Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Remove deprecated remote-access flags and config keys (PRD-7777) (#3666)

omar-inkeep8663424dff2e
diff --git a/.changeset/remove-deprecated-remote-flags-and-keys.md b/.changeset/remove-deprecated-remote-flags-and-keys.md
new file mode 100644
index 000000000..a6956c503
--- /dev/null
+++ b/.changeset/remove-deprecated-remote-flags-and-keys.md
@@ -0,0 +1,18 @@
+---
+"@inkeep/open-knowledge": minor
+---
+
+Removed the deprecated remote-access CLI flags, config keys, and environment variable that were superseded by the ratified `server.*` surface. These were kept as thin back-compat aliases through their deprecation window; that window has closed.
+
+**Breaking changes:**
+
+- **`ok start --remote [url]`** is removed. Use `--external-url <url>` with exposure consent instead: `OK_ALLOW_EXTERNAL=1 OK_IDLE_SHUTDOWN=off ok start --external-url https://<your-tunnel-host>` (add `--bind` to serve a non-loopback address). The server reaches the same exposure posture through the `server.*` keys. Note: `--remote` also pinned a fixed port (24550) so the tunnel's port mapping survived restarts; the successor does not, so pass `--port 24550` (or set `server.port`) if you need a stable port.
+- **`ok start --public-url <url>`** is removed. Use `--external-url <url>` (same value and semantics).
+- **`ok start -H, --host <host>`** is removed. Use `--bind <address>`. The platform `HOST` environment variable is still honored.
+- **`ok start --open`** is removed. Interactive loopback starts open the editor by default; suppress with `--no-open-browser`. Note: `--open`'s one distinctive capability — force-opening the browser from a **non-TTY** context (CI, spawned, containerized) — has no successor; the browser now opens only when stdout is a TTY.
+- **`remote.url`** config key is removed. Use `server.externalUrl`.
+- **`remote.port`** config key is removed. Use `server.port`.
+- **`server.publicUrl`** config key is removed. Use `server.externalUrl` (its current name).
+- **`OK_PUBLIC_URL`** environment variable is removed. Use `OK_EXTERNAL_URL`.
+
+A stale `remote.url`, `remote.port`, or `server.publicUrl` key left in a config file now surfaces a loud `REMOVED_KEY` error naming its replacement (run `ok config migrate` to strip it) rather than being silently discarded.
diff --git a/docs/content/features/share.mdx b/docs/content/features/share.mdx
index 4e60697a8..cbd05213b 100644
--- a/docs/content/features/share.mdx
+++ b/docs/content/features/share.mdx
@@ -6,7 +6,7 @@ description: Copy a link to any doc or folder and send it to a teammate. OpenKno
OpenKnowledge has a Share button in the editor toolbar. Click it and the app copies a `https://openknowledge.ai/d/…` URL to your clipboard. Anyone you send it to lands on a splash page that knows the project and target, and a single click opens it in their copy of OpenKnowledge.
-Share links give each recipient their own copy, kept in sync through GitHub. For real-time editing where everyone works on one live server instead, see the [self-hosting overview](/docs/self-hosting/overview).
+Share links give each recipient their own copy, kept in sync through GitHub. For real-time editing where everyone works on one live server instead, see the [Remote Control overview](/docs/remote-control/overview).
## Sending a share link
diff --git a/docs/content/get-started/overview.mdx b/docs/content/get-started/overview.mdx
index 6e26899e8..94f68a838 100644
--- a/docs/content/get-started/overview.mdx
+++ b/docs/content/get-started/overview.mdx
@@ -22,7 +22,7 @@ OpenKnowledge is three layers working together: a WYSIWYG editor for you, MCP an
- Annotate your knowledge base with **[comments](../features/comments.mdx)**, then resolve them with AI.
- **[Auto-sync](../features/github-sync.mdx)** knowledge base changes with your team using Git.
- Explore your knowledge base through **[graph and wiki-link visualizations](../reference/core-concepts.md#links-and-backlinks)**.
-- [Connect to OpenKnowledge](../self-hosting/connecting-agents.mdx) remotely from local agents, remote agents, or other devices.
+- [Connect to OpenKnowledge](../remote-control/connecting-agents.mdx) remotely from local agents, remote agents, or other devices.
## Where to start
diff --git a/docs/content/meta.json b/docs/content/meta.json
index 737d94760..2aa3283b2 100644
--- a/docs/content/meta.json
+++ b/docs/content/meta.json
@@ -12,8 +12,8 @@
"...features",
"---PLUGINS---",
"...plugins",
- "---SELF-HOSTING---",
- "...self-hosting",
+ "---REMOTE CONTROL---",
+ "...remote-control",
"---ADVANCED---",
"...advanced",
"---IMPORT & TRY---",
diff --git a/docs/content/reference/cli.mdx b/docs/content/reference/cli.mdx
index d9bdfbb7b..3af749046 100644
--- a/docs/content/reference/cli.mdx
+++ b/docs/content/reference/cli.mdx
@@ -117,14 +117,13 @@ Each project runs its own local server. These commands let you see and stop them
| `ok stop` | Stop the server for the current directory — or pass a port, path, or PID to stop a specific server, or `all` to stop every server |
| `ok clean` | Remove stale lock files left behind by a crash (never touches live servers) |
-## Remote control
+## Remote Control
-Serve this project's web UI and `/mcp` endpoint to your other devices through any HTTPS tunnel, both on one URL. See the [self-hosting overview](/docs/self-hosting/overview) for the full setup and access-control model. Use [Connect remote agents](/docs/self-hosting/connecting-agents) to point agents at the URL.
+Serve this project's web UI and `/mcp` endpoint to your other devices through any HTTPS tunnel, both on one URL. See the [Remote Control overview](/docs/remote-control/overview) for the full setup and access-control model. Use [Connect remote agents](/docs/remote-control/connecting-agents) to point agents at the URL.
| Command | What it does |
| --- | --- |
-| `ok start --external-url <url>` | Declare the canonical external origin clients dial (sets `server.externalUrl` for this run) — its host joins the Host/Origin allowlists and issued URLs. External exposure additionally requires consent (`OK_ALLOW_EXTERNAL=1` or `server.allowExternal`). For remote MCP use also set `OK_IDLE_SHUTDOWN=off` — the idle timer only counts editor (WS) connections and would stop the server under a live remote agent. `--public-url` (the flag's former name) remains a deprecated alias |
-| `ok start --remote [url]` | Deprecated alias for `--external-url <url>` plus `OK_ALLOW_EXTERNAL` consent on a loopback bind. Starts the server admitting requests from the tunnel URL (no server-side auth; restrict reach at the tunnel). Bare `--remote` uses `remote.url` from `.ok/config.yml` |
+| `ok start --external-url <url>` | Declare the canonical external origin clients dial (sets `server.externalUrl` for this run) — its host joins the Host/Origin allowlists and issued URLs. External exposure additionally requires consent (`OK_ALLOW_EXTERNAL=1` or `server.allowExternal`). For remote MCP use also set `OK_IDLE_SHUTDOWN=off` — the idle timer only counts editor (WS) connections and would stop the server under a live remote agent. Add `--bind <address>` to serve a non-loopback listen address. |
## More commands
diff --git a/docs/content/reference/configuration.mdx b/docs/content/reference/configuration.mdx
index b21382bad..b9dac0689 100644
--- a/docs/content/reference/configuration.mdx
+++ b/docs/content/reference/configuration.mdx
@@ -48,14 +48,11 @@ A key set in a file more specific than its scope (a user-scope key in `.ok/confi
| `autoSync.enabled` | `boolean \| null` | `null` | project-local | Legacy per-machine auto-sync toggle, superseded by `autoSync.mode`. Read only when `mode` is absent (`true` = full, `false` = off). `null` means "unanswered". |
| `autoSync.default` | `"off" \| "follow" \| "full" \| boolean \| null` | `null` | project | Committed seed for each machine's first-open sync mode: `off` / `follow` / `full`, or the legacy boolean (`true` = full, `false` = off). `null` = ask. Lets a maintainer pre-answer the onboarding prompt for everyone who clones; a per-machine `autoSync.mode` overrides it. Compatibility note: a committed string value (`off` / `follow` / `full`) is rejected by app versions released before `autoSync.mode` existed, resetting that machine to config defaults until it updates (it never silently syncs). The legacy boolean seed (`true` / `false`) stays readable by older apps — commit `follow` only once collaborators are on a current version. |
| `server.bind` | list of addresses | `["127.0.0.1"]` | project-local | Addresses the server binds, e.g. `[127.0.0.1]` or `[0.0.0.0]`. The loopback default keeps everything off-machine out. A non-loopback bind additionally requires the `server.allowExternal` consent interlock. Per-machine — a value committed to `.ok/config.yml` is ignored (the exposing host would otherwise refuse to boot for every teammate who clones and runs locally, since the interlock needs per-machine consent that is never committed). Set it where the server is exposed: `OK_BIND` (space-separated), `ok start --bind <address>`, or `.ok/local/config.yml`. Lists replace, never merge. Read at server start. |
-| `server.port` | number | (unset) | project | TCP port the server listens on. Unset = a local start picks a free port dynamically (deployment platforms inject `PORT` instead). Supersedes `remote.port`, which is still read while this key is absent. Read at server start. |
-| `server.externalUrl` | string | (unset) | project | Canonical external origin the server is reached at, e.g. `https://kb.example.com` — its host joins the Host/Origin allowlists and issued URLs. Setting it declares external exposure, which additionally requires the `server.allowExternal` consent interlock. Supersedes `server.publicUrl` (the key's former name — still read as a deprecated alias while this key is absent) and `remote.url`. Env: `OK_EXTERNAL_URL` (`OK_PUBLIC_URL` remains a deprecated alias); flag: `ok start --external-url <url>`. Read at server start. Compatibility note: app versions from before this key existed read only `server.publicUrl` and silently ignore `server.externalUrl` (config is open-shape), so committing only the new key drops the declared host from those versions' Host/Origin allowlists and external requests 403. While collaborators are still on older versions, commit **both** keys with the same value — current versions prefer `server.externalUrl` (no deprecation notice when both are set) and older versions keep reading `server.publicUrl`; drop the old key once everyone has upgraded. |
-| `server.publicUrl` | string | (unset) | project | Deprecated alias of `server.externalUrl` (the key's former name) — read only while that key is absent, with identical semantics; the CLI prints a rename notice when it is the one in effect. Env alias: `OK_PUBLIC_URL`; flag alias: `ok start --public-url <url>`. May be committed alongside `server.externalUrl` during a mixed-version window (see that key's compatibility note). Slated for removal after a deprecation window. |
+| `server.port` | number | (unset) | project | TCP port the server listens on. Unset = a local start picks a free port dynamically (deployment platforms inject `PORT` instead). Read at server start. |
+| `server.externalUrl` | string | (unset) | project | Canonical external origin the server is reached at, e.g. `https://kb.example.com` — its host joins the Host/Origin allowlists and issued URLs. Setting it declares external exposure, which additionally requires the `server.allowExternal` consent interlock. Env: `OK_EXTERNAL_URL`; flag: `ok start --external-url <url>`. Read at server start. |
| `server.allowExternal` | boolean | `false` | project-local | Exposure consent interlock: a non-loopback `server.bind` (or external requests behind a proxy declared via `server.externalUrl`) is refused without it. Per-machine — consent never travels via git, clone, or share; containers consent via `OK_ALLOW_EXTERNAL=1` instead. There is no server-side auth: restrict who can reach the server at the edge. |
| `server.openBrowser` | boolean | derived: `true` loopback-only, `false` otherwise | project-local | Open the editor in a browser once at start. The derived default means a laptop start pops the UI and an exposed or containerized server stays headless. Env: `OK_OPEN_BROWSER`; flag: `--no-open-browser`. |
| `server.idleShutdown` | `"off"` or duration (`90s`, `30m`, `2h`) | derived: `30m` loopback-only, `off` otherwise | project-local | Shut the server down after this long with no connected editor (WebSocket) clients. Remote MCP sessions are plain HTTP the timer cannot see — set `off` (or `OK_IDLE_SHUTDOWN=off`) when remote agents use the server, or it tears down under them mid-session. |
-| `remote.url` | string | (unset) | project | Superseded by `server.externalUrl` (read only while that key is absent). Public tunnel URL remote clients connect to (e.g. `https://myproject.ngrok.app`); its host is admitted through the Host-header allowlist. Used only when the server is started with the deprecated `ok start --remote` (config alone never enables remote control, and there is no server-side auth). See the [self-hosting overview](/docs/self-hosting/overview). |
-| `remote.port` | number | `24550` | project | Superseded by `server.port` (read only while that key is absent). Fixed TCP port the server binds when remote control is enabled, so the tunnel's port mapping survives restarts. See the [self-hosting overview](/docs/self-hosting/overview). |
| `editor.wordWrap` | boolean | `true` | user | Soft-wrap long lines in the source-mode CodeMirror editor. A personal preference, not project-shared. Toggle from the Settings pane. |
| `editor.previewTabs` | boolean | `true` | user | Reuse one replaceable preview tab for single clicks in the Files tree and Skills sidebar, so browsing does not accumulate tabs. Double-click the tab title, pin it, or choose **Keep open** from its context menu to make it permanent. Set `false` to open every click in its own tab. Rename transitions still reuse the current tab; back/forward navigation focuses the target's existing tab, or opens a permanent one when it is no longer open. A personal preference; toggle it from **Settings → Preferences → Preview tabs**. |
| `appearance.preview.autoOpen` | boolean | `true` | user | Whether the agent should open or refresh the OpenKnowledge preview when it edits a doc through the MCP. Default `true` lets the agent route the preview by host capability: the host's in-app browser (Cursor preview pane, Codex's built-in browser, Claude Code Desktop) when one exists, the system browser otherwise. Set `false` to keep the agent's hands off your preview window. This is useful when you're already viewing the doc in OK Desktop, a browser tab on a second display, a non-default browser, or any flow where your extensions / accessibility tooling only work in your own browser. The agent then surfaces the URL on request but does not navigate. The change takes effect on the next preview-related tool call. Toggle from **Settings → Preferences → "Open preview when agent edits"**. |
@@ -101,7 +98,7 @@ Most users never set these — the schema settings above cover the common cases.
| Variable | Sets |
| --- | --- |
-| `HOST` | Server bind host. The `--host` flag wins over this. |
+| `HOST` | Server bind host. The `--bind` flag wins over this. |
| `PORT` | Server bind port. The `--port` flag wins over this. |
| `OK_MCP_AUTOSTART` | Set to `0` to stop MCP tool calls from auto-starting the project's OpenKnowledge server; tools error until you run `ok start` |
| `OK_LOG_LEVEL` | Log verbosity (`info`, `debug`, `trace`). Falls back to `LOG_LEVEL` if unset. |
diff --git a/docs/content/reference/mcp.mdx b/docs/content/reference/mcp.mdx
index f258c6450..bd6ec995b 100644
--- a/docs/content/reference/mcp.mdx
+++ b/docs/content/reference/mcp.mdx
@@ -10,7 +10,7 @@ Every other read tool (`search`, `links`, `history`, etc.) and all write tools r
The surface is **21 tools**. The four write verbs — `write`, `edit`, `delete`, `move` — are native CRUD operations polymorphic over a target. `write`, `edit`, and `delete` nest per-target fields inside the address key (`write({ document: { path, content } })`) and take exactly one target per call: `document`, `folder`, `template`, or `skill` — plus `asset` for `write` and `delete`, and a `documents` batch on `write` that writes several docs in order, each entry carrying its own `summary`. `move` takes flat `from`/`to` paths and auto-detects a document, folder, or asset, with nested `template` and `skill` targets for those two.
-To point an MCP client at this server, locally or over a tunnel from another machine, see [Connect remote agents](/docs/self-hosting/connecting-agents).
+To point an MCP client at this server, locally or over a tunnel from another machine, see [Connect remote agents](/docs/remote-control/connecting-agents).
## Tools
diff --git a/docs/content/self-hosting/authentication.mdx b/docs/content/remote-control/authentication.mdx
similarity index 94%
rename from docs/content/self-hosting/authentication.mdx
rename to docs/content/remote-control/authentication.mdx
index b15fda105..990dba8d4 100644
--- a/docs/content/self-hosting/authentication.mdx
+++ b/docs/content/remote-control/authentication.mdx
@@ -12,7 +12,7 @@ Add access control in front of the server. The browser and MCP clients use diffe
For a public deployment, protect the editor with a browser login. Protect `/mcp` with a token or MCP-compatible OAuth.
-Add access control to the tunnel, private network, or proxy in front of the server. Use a tunnel or private network with the [CLI method](/docs/self-hosting/methods/cli). Use a proxy with the [Docker method](/docs/self-hosting/methods/docker). A container can also run behind a protected tunnel.
+Add access control to the tunnel, private network, or proxy in front of the server. Use a tunnel or private network with the [CLI method](/docs/remote-control/methods/cli). Use a proxy with the [Docker method](/docs/remote-control/methods/docker). A container can also run behind a protected tunnel.
## Tunnels and private networks
@@ -40,7 +40,7 @@ on_http_request:
config: { provider: google }
```
-Run the tunnel with `--traffic-policy-file policy.yaml`. Browsers get the Google login. An agent connects by sending the Basic credential as a header. See [Connect remote agents](/docs/self-hosting/connecting-agents). Replace `CHANGE_ME` with a strong secret from `openssl rand -hex 24`. For SSO, ngrok's `--oidc` supports Okta, Azure AD, and Google Workspace.
+Run the tunnel with `--traffic-policy-file policy.yaml`. Browsers get the Google login. An agent connects by sending the Basic credential as a header. See [Connect remote agents](/docs/remote-control/connecting-agents). Replace `CHANGE_ME` with a strong secret from `openssl rand -hex 24`. For SSO, ngrok's `--oidc` supports Okta, Azure AD, and Google Workspace.
### Cloudflare Tunnel
@@ -127,7 +127,7 @@ Four settings decide whether this boots the first time:
- **`OAUTH2_PROXY_WHITELIST_DOMAINS` must list your public domain.** Behind Caddy, oauth2-proxy builds its post-login redirect from the forwarded host and refuses any host not on this list, so without it the login silently loops back to itself.
- **`OAUTH2_PROXY_COOKIE_SECRET` must decode to 16, 24, or 32 bytes.** Use `openssl rand -hex 16` to create a valid 32-character value. Do not use `openssl rand -base64 32` because it creates 44 characters and oauth2-proxy will not start.
-- **Caddy must send `X-Forwarded-Proto: https`** using the two `header_up` lines above. TLS ends at the platform edge, so Caddy uses plain HTTP between the edge and the server. Without this header, the server gives the editor a `ws://` connection. The browser blocks it as mixed content on an `https` page and the editor does not load. oauth2-proxy forwards the header automatically. Set `OAUTH2_PROXY_REVERSE_PROXY=true` so oauth2-proxy trusts forwarded headers for client IP addresses and post-login redirects. Set `FLUSH_INTERVAL=100ms` to follow the [never-buffer rule](/docs/self-hosting/methods/docker#rules-for-anything-in-front-of-the-server).
+- **Caddy must send `X-Forwarded-Proto: https`** using the two `header_up` lines above. TLS ends at the platform edge, so Caddy uses plain HTTP between the edge and the server. Without this header, the server gives the editor a `ws://` connection. The browser blocks it as mixed content on an `https` page and the editor does not load. oauth2-proxy forwards the header automatically. Set `OAUTH2_PROXY_REVERSE_PROXY=true` so oauth2-proxy trusts forwarded headers for client IP addresses and post-login redirects. Set `FLUSH_INTERVAL=100ms` to follow the [never-buffer rule](/docs/remote-control/methods/docker#rules-for-anything-in-front-of-the-server).
- **Bind to IPv6 where the platform's private network requires it.** Railway's is IPv6-only, so `OK_BIND=::` and `HTTP_ADDRESS=[::]:4180`, and Caddy dials the `*.railway.internal` names.
### Example: Pomerium
@@ -241,7 +241,7 @@ tailscale funnel --bg --https=443 https+insecure://127.0.0.1:8085
tailscale funnel --bg --https=8443 https+insecure://127.0.0.1:8085
```
-Then point a custom MCP connector in Claude (iOS or Desktop) or Cursor at `https://<host>/mcp` and complete the Google login. [Connect remote agents](/docs/self-hosting/connecting-agents) has the per-client steps.
+Then point a custom MCP connector in Claude (iOS or Desktop) or Cursor at `https://<host>/mcp` and complete the Google login. [Connect remote agents](/docs/remote-control/connecting-agents) has the per-client steps.
The settings that are easy to miss:
@@ -262,9 +262,9 @@ Alternatives to the Pomerium recipe above, as pointers rather than full recipes:
Common symptoms and their fixes:
- **The editor loads but never syncs, and the browser console shows a `ws://` "Mixed Content" error.** The proxy terminates TLS but reports the request to the server as plain HTTP, so the server hands the editor an insecure `ws://` socket. Make the proxy forward `X-Forwarded-Proto: https` (Caddy: `header_up X-Forwarded-Proto https`).
-- **Every request returns `403`.** The request `Host` does not match `OK_EXTERNAL_URL`. Configure the proxy to preserve the client's `Host`. For Caddy, use `header_up Host {host}`. Set `OK_EXTERNAL_URL` to the public origin. See the full [proxy rules](/docs/self-hosting/methods/docker#rules-for-anything-in-front-of-the-server).
+- **Every request returns `403`.** The request `Host` does not match `OK_EXTERNAL_URL`. Configure the proxy to preserve the client's `Host`. For Caddy, use `header_up Host {host}`. Set `OK_EXTERNAL_URL` to the public origin. See the full [proxy rules](/docs/remote-control/methods/docker#rules-for-anything-in-front-of-the-server).
- **The browser login returns to the login page.** oauth2-proxy is rejecting the post-login redirect because the domain is not allowed. Add the public domain to `OAUTH2_PROXY_WHITELIST_DOMAINS`.
-- **An agent gets an HTML login page back from `/mcp`.** The `/mcp` path is behind the browser login instead of a token. Route `/mcp` around the login proxy and gate it with a token, or if you use an MCP-OAuth edge, confirm the client supports it (see [Connect remote agents](/docs/self-hosting/connecting-agents)).
+- **An agent gets an HTML login page back from `/mcp`.** The `/mcp` path is behind the browser login instead of a token. Route `/mcp` around the login proxy and gate it with a token, or if you use an MCP-OAuth edge, confirm the client supports it (see [Connect remote agents](/docs/remote-control/connecting-agents)).
- **`/mcp` hangs or times out.** A proxy is buffering the streamed response. Turn off buffering for `/mcp`. In nginx, set `proxy_buffering` to `off`. For oauth2-proxy, set `FLUSH_INTERVAL=100ms`. Caddy streams by default.
-Once auth is in place, [Connect remote agents](/docs/self-hosting/connecting-agents) covers how each client presents its credential.
+Once auth is in place, [Connect remote agents](/docs/remote-control/connecting-agents) covers how each client presents its credential.
diff --git a/docs/content/self-hosting/connecting-agents.mdx b/docs/content/remote-control/connecting-agents.mdx
similarity index 73%
rename from docs/content/self-hosting/connecting-agents.mdx
rename to docs/content/remote-control/connecting-agents.mdx
index e10c9c3b3..aa24c0dc1 100644
--- a/docs/content/self-hosting/connecting-agents.mdx
+++ b/docs/content/remote-control/connecting-agents.mdx
@@ -11,9 +11,9 @@ If the agent runs on the same machine as your OpenKnowledge project, follow the
## Before you start
-Set up a running server with [remote control](/docs/self-hosting/overview). Every remote agent connects to the same address, `https://<your-external-url>/mcp`, whether the server runs on your laptop, a VPS, or in a container.
+Set up a running server with [remote control](/docs/remote-control/overview). Every remote agent connects to the same address, `https://<your-external-url>/mcp`, whether the server runs on your laptop, a VPS, or in a container.
-OpenKnowledge does not authenticate callers. The tunnel, private network, or proxy in front of the server controls access. Configure it first. Then give the agent any required network access or credentials. See [Authentication](/docs/self-hosting/authentication).
+OpenKnowledge does not authenticate callers. The tunnel, private network, or proxy in front of the server controls access. Configure it first. Then give the agent any required network access or credentials. See [Authentication](/docs/remote-control/authentication).
## Connect agents on another machine
@@ -23,7 +23,7 @@ Run this on the machine where the agents are installed. [`add-mcp`](https://gith
npx add-mcp https://<your-external-url>/mcp --name ok-remote
```
-If your `/mcp` endpoint is behind a token at the edge (a **bearer token** or **Basic Auth** from your [Authentication](/docs/self-hosting/authentication) setup), pass it as a header so the agent connects with no browser step:
+If your `/mcp` endpoint is behind a token at the edge (a **bearer token** or **Basic Auth** from your [Authentication](/docs/remote-control/authentication) setup), pass it as a header so the agent connects with no browser step:
```bash
npx add-mcp https://<your-external-url>/mcp --name ok-remote \
@@ -32,11 +32,11 @@ npx add-mcp https://<your-external-url>/mcp --name ok-remote \
For Basic Auth, the header is `Authorization: Basic $(printf 'user:pass' | base64)` instead.
-A headless agent cannot complete a standard browser login. Protect `/mcp` with a token, a [path-specific access policy](/docs/self-hosting/authentication#tunnels-and-private-networks), or Tailscale.
+A headless agent cannot complete a standard browser login. Protect `/mcp` with a token, a [path-specific access policy](/docs/remote-control/authentication#tunnels-and-private-networks), or Tailscale.
-The exception is an [MCP-native edge](/docs/self-hosting/authentication#mcp-native-edges), such as Pomerium. It lets the agent sign in through its own browser popup with no token to set. Pomerium serves CIMD by default for Claude. Enable `mcp_dynamic_client_registration` to add DCR support for Cursor and `mcp-remote`. The [Pomerium recipe](/docs/self-hosting/authentication#example-pomerium) turns both on.
+The exception is an [MCP-native edge](/docs/remote-control/authentication#mcp-native-edges), such as Pomerium. It lets the agent sign in through its own browser popup with no token to set. Pomerium serves CIMD by default for Claude. Enable `mcp_dynamic_client_registration` to add DCR support for Cursor and `mcp-remote`. The [Pomerium recipe](/docs/remote-control/authentication#example-pomerium) turns both on.
-The per-client setups below use a plain `/mcp` URL. If yours is behind a token, add the same `Authorization` header shown above (details in [Authentication](/docs/self-hosting/authentication)).
+The per-client setups below use a plain `/mcp` URL. If yours is behind a token, add the same `Authorization` header shown above (details in [Authentication](/docs/remote-control/authentication)).
## Claude Code
@@ -88,7 +88,7 @@ Add the `/mcp` URL to your harness's MCP server config, the same way as above. I
## Cloud-hosted agents and connectors (Claude.ai, ChatGPT, etc.)
-Cloud-hosted agents and connectors reach the MCP endpoint from the provider's cloud. The URL must be publicly reachable over HTTPS. The Claude and ChatGPT connectors require an MCP-aware OAuth service in front of `/mcp`. The [Pomerium recipe](/docs/self-hosting/authentication#example-pomerium) has been verified with the Claude connector on iOS and Desktop and with Cursor's cloud agents. Support varies by provider.
+Cloud-hosted agents and connectors reach the MCP endpoint from the provider's cloud. The URL must be publicly reachable over HTTPS. The Claude and ChatGPT connectors require an MCP-aware OAuth service in front of `/mcp`. The [Pomerium recipe](/docs/remote-control/authentication#example-pomerium) has been verified with the Claude connector on iOS and Desktop and with Cursor's cloud agents. Support varies by provider.
Connectors that accept a bearer token or API key can use a token enforced at the edge. This includes Microsoft Copilot Studio and Perplexity. Protect `/mcp` with a static bearer token, then add that token to the connector's settings.
diff --git a/docs/content/self-hosting/meta.json b/docs/content/remote-control/meta.json
similarity index 77%
rename from docs/content/self-hosting/meta.json
rename to docs/content/remote-control/meta.json
index 131ab405f..f04978ce2 100644
--- a/docs/content/self-hosting/meta.json
+++ b/docs/content/remote-control/meta.json
@@ -1,5 +1,5 @@
{
- "title": "Self-hosting",
+ "title": "Remote Control",
"icon": "LuServer",
"pages": ["overview", "methods", "authentication", "connecting-agents"]
}
diff --git a/docs/content/self-hosting/methods/cli.mdx b/docs/content/remote-control/methods/cli.mdx
similarity index 85%
rename from docs/content/self-hosting/methods/cli.mdx
rename to docs/content/remote-control/methods/cli.mdx
index 2416fffdf..fcb4588ff 100644
--- a/docs/content/self-hosting/methods/cli.mdx
+++ b/docs/content/remote-control/methods/cli.mdx
@@ -9,11 +9,11 @@ Install OpenKnowledge from npm, then run the server yourself:
npm install -g @inkeep/open-knowledge
```
-Run OpenKnowledge on a laptop or an always-on server. Use a private network, tunnel, or reverse proxy to make it reachable. See the [self-hosting overview](/docs/self-hosting/overview) to choose an access method.
+Run OpenKnowledge on a laptop or an always-on server. Use a private network, tunnel, or reverse proxy to make it reachable. See the [Remote Control overview](/docs/remote-control/overview) to choose an access method.
## Your laptop, behind a tunnel
-A tunnel gives the OpenKnowledge server on your laptop an HTTPS URL. The server is available only while the laptop is awake. For continuous access, use [an always-on server](#a-server-you-manage) or the [Docker method](/docs/self-hosting/methods/docker).
+A tunnel gives the OpenKnowledge server on your laptop an HTTPS URL. The server is available only while the laptop is awake. For continuous access, use [an always-on server](#a-server-you-manage) or the [Docker method](/docs/remote-control/methods/docker).
### 1. Pin a port and open a tunnel
@@ -31,7 +31,7 @@ Install the tunnel client on the machine before continuing.
</Callout>
<Callout type="warn">
-Tailscale Serve stays inside your tailnet. Before starting ngrok or Cloudflare Tunnel, [set up authentication](/docs/self-hosting/authentication) at that edge. Do not open an unprotected public URL.
+Tailscale Serve stays inside your tailnet. Before starting ngrok or Cloudflare Tunnel, [set up authentication](/docs/remote-control/authentication) at that edge. Do not open an unprotected public URL.
</Callout>
<Tabs groupId="ok-tunnel" persist items={['Tailscale', 'ngrok', 'Cloudflare Tunnel']}>
@@ -51,7 +51,7 @@ If `serve` says Tailscale is stopped, run `tailscale up` first (on a Linux serve
<Tab>
-Public URL. Add access control at the edge. See [Authentication](/docs/self-hosting/authentication).
+Public URL. Add access control at the edge. See [Authentication](/docs/remote-control/authentication).
```bash
ngrok http 8080
@@ -62,7 +62,7 @@ ngrok http 8080
<Tab>
-A quick public URL on a `*.trycloudflare.com` address, fresh each run. For a stable URL on your own domain, and to pair with [Cloudflare Access](/docs/self-hosting/authentication), set up a [named tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) instead.
+A quick public URL on a `*.trycloudflare.com` address, fresh each run. For a stable URL on your own domain, and to pair with [Cloudflare Access](/docs/remote-control/authentication), set up a [named tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) instead.
```bash
cloudflared tunnel --url http://localhost:8080
@@ -110,7 +110,7 @@ The server prints a warning banner naming the public origin on every exposed sta
OK_ALLOW_EXTERNAL=1 OK_IDLE_SHUTDOWN=off ok start --external-url https://<your-tunnel-url> --port 8080
```
-If the URL is public, [add access control](/docs/self-hosting/authentication) before opening it. Tailscale Serve already limits access to your tailnet. Once the route is protected, [try it out](/docs/self-hosting/overview#try-it-out).
+If the URL is public, [add access control](/docs/remote-control/authentication) before opening it. Tailscale Serve already limits access to your tailnet. Once the route is protected, [try it out](/docs/remote-control/overview#try-it-out).
## A server you manage
@@ -154,7 +154,7 @@ Choose one of these access methods:
externalUrl: https://notes.example.com
```
- Caddy automatically handles the [proxy rules](/docs/self-hosting/methods/docker#rules-for-anything-in-front-of-the-server), including Host preservation, `X-Forwarded-Proto`, and no buffering on `/mcp`. Do not add an `encode` directive on `/mcp`. Configure these rules yourself when using another proxy such as nginx. Without them, requests may return `403` and the editor's WebSocket may fail.
+ Caddy automatically handles the [proxy rules](/docs/remote-control/methods/docker#rules-for-anything-in-front-of-the-server), including Host preservation, `X-Forwarded-Proto`, and no buffering on `/mcp`. Do not add an `encode` directive on `/mcp`. Configure these rules yourself when using another proxy such as nginx. Without them, requests may return `403` and the editor's WebSocket may fail.
For either option, allow external access in `.ok/local/config.yml` by setting `allowExternal: true` and `idleShutdown: "off"`. Use the same [configuration and start steps](#2-configure-and-start) as the laptop setup.
@@ -189,7 +189,7 @@ sudo systemctl enable --now openknowledge
**macOS and Windows do not use systemd.** Run `ok start` in a terminal and disable sleep. For automatic restarts, use launchd on macOS, or Task Scheduler or a Windows service on Windows.
</Callout>
-If the URL is public, [add access control](/docs/self-hosting/authentication) before opening it. Once the route is protected, [try it out](/docs/self-hosting/overview#try-it-out).
+If the URL is public, [add access control](/docs/remote-control/authentication) before opening it. Once the route is protected, [try it out](/docs/remote-control/overview#try-it-out).
## Back up to a git remote
diff --git a/docs/content/self-hosting/methods/docker.mdx b/docs/content/remote-control/methods/docker.mdx
similarity index 93%
rename from docs/content/self-hosting/methods/docker.mdx
rename to docs/content/remote-control/methods/docker.mdx
index b516d1085..e35cd44ac 100644
--- a/docs/content/self-hosting/methods/docker.mdx
+++ b/docs/content/remote-control/methods/docker.mdx
@@ -3,7 +3,7 @@ title: Docker
icon: custom/Docker
description: Build the OpenKnowledge container image and run it on Railway, Fly.io, or any Docker host.
---
-For an always-on knowledge base without managing a box, run the server as a container on a hosting platform (Railway, Fly.io, or your own Docker host). The platform provides the domain and TLS. A volume holds the project. The `OK_*` environment variables carry the same declarations as every other path. Start with the [self-hosting overview](/docs/self-hosting/overview) if you have not chosen an access path yet.
+For an always-on knowledge base without managing a box, run the server as a container on a hosting platform (Railway, Fly.io, or your own Docker host). The platform provides the domain and TLS. A volume holds the project. The `OK_*` environment variables carry the same declarations as every other path. Start with the [Remote Control overview](/docs/remote-control/overview) if you have not chosen an access path yet.
## What any host must provide
@@ -126,7 +126,7 @@ The same image runs anywhere Docker is available. On Fly.io, mount a volume at `
With Docker Compose, you can add a `cloudflared` sidecar as the only ingress. This works on a hosting platform or your own VPS. You do not need a separate public domain. Set `OK_EXTERNAL_URL` to the tunnel hostname.
-AWS, Google Cloud, and Azure can run the image on a virtual machine with Docker. You can also use the [CLI method](/docs/self-hosting/methods/cli#a-server-you-manage) on a virtual machine. Serverless container services must provide persistent storage and support one always-on replica. Vercel and Netlify cannot host OpenKnowledge because they run request-based functions instead of one long-lived stateful process.
+AWS, Google Cloud, and Azure can run the image on a virtual machine with Docker. You can also use the [CLI method](/docs/remote-control/methods/cli#a-server-you-manage) on a virtual machine. Serverless container services must provide persistent storage and support one always-on replica. Vercel and Netlify cannot host OpenKnowledge because they run request-based functions instead of one long-lived stateful process.
## Upgrading
@@ -147,4 +147,4 @@ Three rules apply to any proxy you place between clients and the container (an a
## Next steps
-The platform domain has no login of its own, so anyone who finds the URL has full read and write access. [Add authentication](/docs/self-hosting/authentication) before opening the public domain. Once the route is protected, [try it out](/docs/self-hosting/overview#try-it-out), then [Connect remote agents](/docs/self-hosting/connecting-agents).
+The platform domain has no login of its own, so anyone who finds the URL has full read and write access. [Add authentication](/docs/remote-control/authentication) before opening the public domain. Once the route is protected, [try it out](/docs/remote-control/overview#try-it-out), then [Connect remote agents](/docs/remote-control/connecting-agents).
diff --git a/docs/content/self-hosting/methods/meta.json b/docs/content/remote-control/methods/meta.json
similarity index 100%
rename from docs/content/self-hosting/methods/meta.json
rename to docs/content/remote-control/methods/meta.json
diff --git a/docs/content/self-hosting/overview.mdx b/docs/content/remote-control/overview.mdx
similarity index 75%
rename from docs/content/self-hosting/overview.mdx
rename to docs/content/remote-control/overview.mdx
index ee25893a3..6fb2de349 100644
--- a/docs/content/self-hosting/overview.mdx
+++ b/docs/content/remote-control/overview.mdx
@@ -12,8 +12,8 @@ The setup has four parts: run the server, make it reachable, add access control,
There are three ways to run an OpenKnowledge server:
- [**Desktop**](/docs/get-started/quickstart#install-the-desktop-app-macos-windows-linux)
-- [**CLI**](/docs/self-hosting/methods/cli)
-- [**Docker**](/docs/self-hosting/methods/docker)
+- [**CLI**](/docs/remote-control/methods/cli)
+- [**Docker**](/docs/remote-control/methods/docker)
## Make the server reachable
@@ -21,9 +21,9 @@ Choose the instructions that match where your server runs:
| Your setup | What to follow |
| --- | --- |
-| Desktop or CLI on your computer | [Connect the computer through a private network or tunnel](/docs/self-hosting/methods/cli#your-laptop-behind-a-tunnel). If Desktop already runs the project, skip the CLI installation step. The networking settings are the same. |
-| CLI on an always-on machine | [Set up a server you manage](/docs/self-hosting/methods/cli#a-server-you-manage). |
-| Docker | [Deploy the container](/docs/self-hosting/methods/docker). |
+| Desktop or CLI on your computer | [Connect the computer through a private network or tunnel](/docs/remote-control/methods/cli#your-laptop-behind-a-tunnel). If Desktop already runs the project, skip the CLI installation step. The networking settings are the same. |
+| CLI on an always-on machine | [Set up a server you manage](/docs/remote-control/methods/cli#a-server-you-manage). |
+| Docker | [Deploy the container](/docs/remote-control/methods/docker). |
Each method provides an HTTPS URL and the required configuration. See the [configuration reference](/docs/reference/configuration) for all available settings.
@@ -35,7 +35,7 @@ Each method provides an HTTPS URL and the required configuration. See the [confi
OpenKnowledge does not have built-in user accounts yet. Everyone who can reach the server has full read and write access as the same owner.
-A private network such as Tailscale can be the access-control layer. A public URL needs an authentication edge or proxy in front of it. Follow [Authentication](/docs/self-hosting/authentication) before continuing.
+A private network such as Tailscale can be the access-control layer. A public URL needs an authentication edge or proxy in front of it. Follow [Authentication](/docs/remote-control/authentication) before continuing.
## Try it out
@@ -53,7 +53,7 @@ Connect agents to the MCP endpoint:
https://<your-external-url>/mcp
```
-Open the browser URL first to confirm the editor loads. Then follow [Connect remote agents](/docs/self-hosting/connecting-agents) for Claude, Cursor, Codex, and other MCP clients. Give teammates the browser URL plus any network access or credential required by your access-control setup.
+Open the browser URL first to confirm the editor loads. Then follow [Connect remote agents](/docs/remote-control/connecting-agents) for Claude, Cursor, Codex, and other MCP clients. Give teammates the browser URL plus any network access or credential required by your access-control setup.
## Turn off remote access
diff --git a/docs/next.config.ts b/docs/next.config.ts
index f5694f78c..c3fdad85a 100644
--- a/docs/next.config.ts
+++ b/docs/next.config.ts
@@ -113,32 +113,99 @@ const nextConfig: NextConfig = {
},
{
source: '/docs/deploy/remote-access',
- destination: '/docs/self-hosting/overview',
+ destination: '/docs/remote-control/overview',
permanent: true,
},
{
source: '/docs/deploy/remote-access/',
- destination: '/docs/self-hosting/overview',
+ destination: '/docs/remote-control/overview',
permanent: true,
},
{
source: '/docs/self-hosting/methods/npm',
- destination: '/docs/self-hosting/methods/cli',
+ destination: '/docs/remote-control/methods/cli',
permanent: true,
},
{
source: '/docs/self-hosting/methods/npm/',
- destination: '/docs/self-hosting/methods/cli',
+ destination: '/docs/remote-control/methods/cli',
permanent: true,
},
{
source: '/docs/deploy/connecting-agents',
- destination: '/docs/self-hosting/connecting-agents',
+ destination: '/docs/remote-control/connecting-agents',
permanent: true,
},
{
source: '/docs/deploy/connecting-agents/',
- destination: '/docs/self-hosting/connecting-agents',
+ destination: '/docs/remote-control/connecting-agents',
+ permanent: true,
+ },
+ // The Self-hosting section was renamed to Remote Control (folder + URL),
+ // so every prior /docs/self-hosting/* link forwards to its
+ // /docs/remote-control/* counterpart. Both slash variants are listed
+ // because skipTrailingSlashRedirect (above) disables Next's automatic
+ // `/path/` → `/path` normalization. The bare section root forwards to the
+ // overview page (the section has no index route of its own); the former
+ // `methods/npm` path is covered by the npm→cli redirect above.
+ {
+ source: '/docs/self-hosting',
+ destination: '/docs/remote-control/overview',
+ permanent: true,
+ },
+ {
+ source: '/docs/self-hosting/',
+ destination: '/docs/remote-control/overview',
+ permanent: true,
+ },
+ {
+ source: '/docs/self-hosting/overview',
+ destination: '/docs/remote-control/overview',
+ permanent: true,
+ },
+ {
+ source: '/docs/self-hosting/overview/',
+ destination: '/docs/remote-control/overview',
+ permanent: true,
+ },
+ {
+ source: '/docs/self-hosting/authentication',
+ destination: '/docs/remote-control/authentication',
+ permanent: true,
+ },
+ {
+ source: '/docs/self-hosting/authentication/',
+ destination: '/docs/remote-control/authentication',
+ permanent: true,
+ },
+ {
+ source: '/docs/self-hosting/connecting-agents',
+ destination: '/docs/remote-control/connecting-agents',
+ permanent: true,
+ },
+ {
+ source: '/docs/self-hosting/connecting-agents/',
+ destination: '/docs/remote-control/connecting-agents',
+ permanent: true,
+ },
+ {
+ source: '/docs/self-hosting/methods/cli',
+ destination: '/docs/remote-control/methods/cli',
+ permanent: true,
+ },
+ {
+ source: '/docs/self-hosting/methods/cli/',
+ destination: '/docs/remote-control/methods/cli',
+ permanent: true,
+ },
+ {
+ source: '/docs/self-hosting/methods/docker',
+ destination: '/docs/remote-control/methods/docker',
+ permanent: true,
+ },
+ {
+ source: '/docs/self-hosting/methods/docker/',
+ destination: '/docs/remote-control/methods/docker',
permanent: true,
},
{
diff --git a/knip.config.ts b/knip.config.ts
index 78162ec09..f9179f2d4 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -123,7 +123,9 @@ export default {
'packages/server': {
entry: ['src/**/*.test.ts', 'src/parse-worker.ts'],
project: 'src/**',
- ignoreDependencies: ['@types/shell-quote'],
+ ignoreDependencies: [
+ '@types/shell-quote',
+ ],
},
'packages/cli': {
entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts', 'src/parse-worker.ts'],
diff --git a/packages/app/src/components/settings/NetworkAccessSection.tsx b/packages/app/src/components/settings/NetworkAccessSection.tsx
index c35715021..914b1f7ae 100644
--- a/packages/app/src/components/settings/NetworkAccessSection.tsx
+++ b/packages/app/src/components/settings/NetworkAccessSection.tsx
@@ -25,7 +25,7 @@
* project-local, origin + port are committed project scope (inert without the
* local consent).
*/
-import { DEFAULT_REMOTE_PORT, humanFormat } from '@inkeep/open-knowledge-core';
+import { DEFAULT_TUNNEL_PORT, humanFormat } from '@inkeep/open-knowledge-core';
import { useLingui } from '@lingui/react/macro';
import { useEffect, useState } from 'react';
import { toast } from 'sonner';
@@ -73,7 +73,7 @@ export function NetworkAccessSection() {
const [origin, setOrigin] = useState(configuredOrigin);
const [portMode, setPortMode] = useState<PortMode>(configuredPort != null ? 'fixed' : 'auto');
const [portDraft, setPortDraft] = useState(
- configuredPort != null ? String(configuredPort) : String(DEFAULT_REMOTE_PORT),
+ configuredPort != null ? String(configuredPort) : String(DEFAULT_TUNNEL_PORT),
);
const [originError, setOriginError] = useState<string | null>(null);
const [portError, setPortError] = useState<string | null>(null);
@@ -100,7 +100,7 @@ export function NetworkAccessSection() {
setExpose(configuredAllow);
setOrigin(configuredOrigin);
setPortMode(configuredPort != null ? 'fixed' : 'auto');
- setPortDraft(configuredPort != null ? String(configuredPort) : String(DEFAULT_REMOTE_PORT));
+ setPortDraft(configuredPort != null ? String(configuredPort) : String(DEFAULT_TUNNEL_PORT));
setOriginError(null);
setPortError(null);
// Drop the stale probe verdict too — it was measured against the old draft.
diff --git a/packages/cli/src/commands/config.test.ts b/packages/cli/src/commands/config.test.ts
index 074561e3d..00af24f65 100644
--- a/packages/cli/src/commands/config.test.ts
+++ b/packages/cli/src/commands/config.test.ts
@@ -168,9 +168,42 @@ describe('runValidate', () => {
expect(outcome.ok).toBe(true);
const joined = out.join('\n');
expect(joined).toContain('✓ Configuration valid');
- // Names the dead key and surfaces its replacement guidance.
+ // Names the dead key and surfaces its replacement guidance — both the
+ // successor config key and the flag the redirect text now points at.
expect(joined).toContain('server.host');
- expect(joined).toContain('--host');
+ expect(joined).toContain('server.bind');
+ expect(joined).toContain('--bind');
+ } finally {
+ project.cleanup();
+ }
+ });
+
+ test('removed remote-access keys → valid with each finding + successor reported', () => {
+ // Parallels the server.host coverage above for the remote-access key
+ // removal: remote.url / remote.port / server.publicUrl are removed keys, so
+ // a committed config carrying them still validates (removed keys never
+ // block) and each is reported with the server.* key that replaced it.
+ const project = makeTempProject();
+ try {
+ writeConfigYaml(
+ projectConfigPath(project.cwd),
+ 'content:\n dir: docs\nremote:\n url: https://kb.example.com\n port: 24550\nserver:\n publicUrl: https://kb.example.com\n',
+ );
+ const out: string[] = [];
+ const outcome = runValidate({
+ cwd: project.cwd,
+ log: (msg) => out.push(msg),
+ error: (msg) => out.push(msg),
+ });
+ expect(outcome.ok).toBe(true);
+ const joined = out.join('\n');
+ expect(joined).toContain('✓ Configuration valid');
+ // Each dead key is named and points at its server.* successor.
+ expect(joined).toContain('remote.url');
+ expect(joined).toContain('remote.port');
+ expect(joined).toContain('server.publicUrl');
+ expect(joined).toContain('server.externalUrl');
+ expect(joined).toContain('server.port');
} finally {
project.cleanup();
}
@@ -371,6 +404,38 @@ describe('runMigrate', () => {
);
});
+ test('removes remote.* and server.publicUrl while preserving live server.* keys (project)', async () => {
+ const wsPath = projectConfigPath(project.cwd);
+ // The removed remote-access keys (remote.url, remote.port — an entire
+ // top-level `remote:` section — plus server.publicUrl) are stripped; the
+ // live successors (server.externalUrl, server.port) must survive. A codemod
+ // that touched them would destroy config on the exact command the removed-key
+ // redirects tell users to run.
+ const original = `content:\n dir: docs\nremote:\n url: https://old-remote.example.com\n port: 24550\nserver:\n port: 8080\n externalUrl: https://kb.example.com\n publicUrl: https://old-public.example.com\n`;
+ writeConfigYaml(wsPath, original);
+ const outcome = await runMigrate({
+ cwd: project.cwd,
+ scope: 'project',
+ homedirOverride: project.userHome,
+ log: () => {},
+ });
+ expect(outcome.ok).toBe(true);
+ const migrated = readFileSync(wsPath, 'utf-8');
+ // Deprecated keys and their values are gone.
+ expect(migrated).not.toContain('publicUrl');
+ expect(migrated).not.toContain('old-remote.example.com');
+ expect(migrated).not.toContain('old-public.example.com');
+ expect(migrated).not.toContain('24550');
+ // Live successors survive untouched.
+ expect(migrated).toContain('port: 8080');
+ expect(migrated).toContain('externalUrl: https://kb.example.com');
+ expect(migrated).toContain('dir: docs');
+ const wsOutcome = outcome.outcomes.find((o) => o.scope === 'project');
+ expect(wsOutcome?.removed.sort()).toEqual(
+ ['remote.port', 'remote.url', 'server.publicUrl'].sort(),
+ );
+ });
+
test('removes content.{include,exclude} leaf fields (project)', async () => {
const wsPath = projectConfigPath(project.cwd);
const original = `content:\n dir: .\n include:\n - "**/*.md"\n exclude:\n - drafts/**\n`;
diff --git a/packages/cli/src/commands/start.test.ts b/packages/cli/src/commands/start.test.ts
index 9bfcd678e..65a56d95c 100644
--- a/packages/cli/src/commands/start.test.ts
+++ b/packages/cli/src/commands/start.test.ts
@@ -5,21 +5,13 @@ import { request as httpRequest } from 'node:http';
import { tmpdir } from 'node:os';
import { join, resolve } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
-import {
- applyConfigOverlay,
- idleShutdownToMs,
- requiresExternalConsent,
- resolveEnvConfigLayer,
- resolveServerRuntimeConfig,
-} from '@inkeep/open-knowledge-core';
+import { idleShutdownToMs } from '@inkeep/open-knowledge-core';
import { type Config, ConfigSchema } from '@inkeep/open-knowledge-server';
-import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import {
type BootedStartServer,
bootStartServer,
- coerceRemoteBindHost,
deriveServerProcessTitle,
- expandRemoteAlias,
formatServerReuseNotice,
formatShutdownNotice,
isLoopbackHost,
@@ -28,15 +20,11 @@ import {
parseExternalUrlFlag,
parseIdleShutdownFlag,
parseOnlyModule,
- parsePublicUrlFlag,
resolveBundledReactShellDir,
- resolveCollabPort,
- resolveFlagExternalUrl,
resolveHost,
resolveServerReuse,
resolveStartConsoleLevel,
resolveStartShellDir,
- scopeRemoteAliasConsentToBind,
shouldOpenBrowser,
shouldWarnHostOverridesMultiBind,
startCommand,
@@ -46,11 +34,7 @@ import {
} from './start.ts';
describe('resolveHost', () => {
- test('returns --host flag when --bind is absent (second priority, after --bind)', () => {
- expect(resolveHost({ host: '0.0.0.0' }, { HOST: '127.0.0.2' })).toBe('0.0.0.0');
- });
-
- test('falls back to HOST env when --host is absent', () => {
+ test('falls back to HOST env when --bind is absent', () => {
expect(resolveHost({}, { HOST: '0.0.0.0' })).toBe('0.0.0.0');
});
@@ -61,153 +45,6 @@ describe('resolveHost', () => {
// skips DNS and binds the same family on every platform.
expect(resolveHost({}, {})).toBe('127.0.0.1');
});
-
- test('explicit undefined --host falls through to env (precedence: flag > env > default)', () => {
- expect(resolveHost({ host: undefined }, { HOST: '0.0.0.0' })).toBe('0.0.0.0');
- });
-});
-
-describe('coerceRemoteBindHost', () => {
- test('no-op when remote access is disabled', () => {
- expect(coerceRemoteBindHost('::1', false)).toEqual({ host: '::1', coerced: false });
- expect(coerceRemoteBindHost('localhost', false)).toEqual({
- host: 'localhost',
- coerced: false,
- });
- });
-
- test('coerces IPv6/hostname binds to 127.0.0.1 in remote mode (tunnel proxy target)', () => {
- for (const host of ['::', '::1', '[::1]', 'localhost']) {
- expect(coerceRemoteBindHost(host, true)).toEqual({ host: '127.0.0.1', coerced: true });
- }
- });
-
- test('leaves loopback binds alone in remote mode', () => {
- expect(coerceRemoteBindHost('127.0.0.1', true)).toEqual({
- host: '127.0.0.1',
- coerced: false,
- });
- });
-
- test('coerces all-interfaces binds to loopback in remote mode', () => {
- expect(coerceRemoteBindHost('0.0.0.0', true)).toEqual({ host: '127.0.0.1', coerced: true });
- });
-});
-
-describe('expandRemoteAlias — --remote is a thin alias over the server.* keys', () => {
- const TUNNEL_URL = 'https://myproject.ngrok.app';
-
- /** Narrow to the ok:true arm or fail the test with a useful message. */
- function expectExpanded(alias: ReturnType<typeof expandRemoteAlias>) {
- if (alias === null || !alias.ok) {
- throw new Error(`expected a successful expansion, got ${JSON.stringify(alias)}`);
- }
- return alias;
- }
-
- test('expands to exactly the ratified keys — externalUrl + allowExternal + idleShutdown off', () => {
- expect(expandRemoteAlias(TUNNEL_URL, undefined)).toEqual({
- ok: true,
- url: TUNNEL_URL,
- serverOverlay: { externalUrl: TUNNEL_URL, allowExternal: true, idleShutdown: 'off' },
- });
- });
-
- test('resolves an identical server runtime to the equivalent --external-url invocation', () => {
- const config = makeTestConfig();
- const alias = expectExpanded(expandRemoteAlias(TUNNEL_URL, undefined));
- // What runStartCommand overlays for `ok start --remote <url>` …
- const aliasRuntime = resolveServerRuntimeConfig(
- applyConfigOverlay(config, {
- server: { bind: ['127.0.0.1'], ...alias.serverOverlay },
- }) as Config,
- );
- // … versus the ratified spelling of the same deployment:
- // `OK_ALLOW_EXTERNAL=1 OK_IDLE_SHUTDOWN=off ok start --external-url <url> --bind 127.0.0.1`.
- const env = resolveEnvConfigLayer({ OK_ALLOW_EXTERNAL: '1', OK_IDLE_SHUTDOWN: 'off' });
- const explicitRuntime = resolveServerRuntimeConfig(
- applyConfigOverlay(applyConfigOverlay(config, env.layer), {
- server: { bind: ['127.0.0.1'], externalUrl: TUNNEL_URL },
- }) as Config,
- );
- expect(aliasRuntime).toEqual(explicitRuntime);
- // The load-bearing shape: successor-key externalUrl (drives the ingress
- // policy + issued URLs), consent armed, loopback-only bind.
- expect(aliasRuntime.externalUrlSource).toBe('server');
- expect(aliasRuntime.allowExternal).toBe(true);
- expect(aliasRuntime.loopbackOnly).toBe(true);
- expect(aliasRuntime.idleShutdown).toBe('off');
- });
-
- test('a dormant remote.url in config does NOT arm anything without the flag', () => {
- expect(expandRemoteAlias(undefined, TUNNEL_URL)).toBeNull();
- expect(expandRemoteAlias(false, TUNNEL_URL)).toBeNull();
- });
-
- test('bare --remote pulls the url from config; an inline url wins over config', () => {
- expect(expectExpanded(expandRemoteAlias(true, TUNNEL_URL)).url).toBe(TUNNEL_URL);
- expect(expectExpanded(expandRemoteAlias('https://inline.example.com', TUNNEL_URL)).url).toBe(
- 'https://inline.example.com',
- );
- });
-
- test('trailing slashes are stripped, matching the legacy resolver', () => {
- const alias = expectExpanded(expandRemoteAlias(`${TUNNEL_URL}/`, undefined));
- expect(alias.url).toBe(TUNNEL_URL);
- expect(alias.serverOverlay.externalUrl).toBe(TUNNEL_URL);
- });
-
- test('missing url anywhere refuses with the fix instruction', () => {
- const alias = expandRemoteAlias(true, undefined);
- expect(alias?.ok).toBe(false);
- if (alias === null || alias.ok) throw new Error('expected refusal');
- expect(alias.errorMessage).toContain('--remote requires a public tunnel URL');
- });
-
- test('non-URL and plain-http urls refuse — the legacy https-only rule is preserved', () => {
- const garbage = expandRemoteAlias('not a url', undefined);
- if (garbage === null || garbage.ok) throw new Error('expected refusal');
- expect(garbage.errorMessage).toContain('not a valid URL');
- const http = expandRemoteAlias('http://myproject.ngrok.app', undefined);
- if (http === null || http.ok) throw new Error('expected refusal');
- expect(http.errorMessage).toContain('must be https');
- });
-});
-
-describe('scopeRemoteAliasConsentToBind — self-consent is loopback-scoped', () => {
- const overlay = {
- externalUrl: 'https://myproject.ngrok.app',
- allowExternal: true,
- idleShutdown: 'off',
- } as const;
-
- test('a loopback bind keeps the alias self-consent', () => {
- expect(scopeRemoteAliasConsentToBind(overlay, ['127.0.0.1'])).toEqual(overlay);
- expect(scopeRemoteAliasConsentToBind(overlay, ['::1'])).toEqual(overlay);
- });
-
- test('a non-loopback bind drops allowExternal so the interlock refuses as it did pre-alias', () => {
- // `ok start --remote <url>` on a project with `server.bind: [<lan-ip>]`
- // exited 78 before the alias (the flag never consented to a bind that is
- // reachable AROUND the tunnel). The scoped overlay must not smuggle that
- // consent in.
- const scoped = scopeRemoteAliasConsentToBind(overlay, ['192.168.1.5']);
- expect('allowExternal' in scoped).toBe(false);
- expect(scoped.externalUrl).toBe(overlay.externalUrl);
- const runtime = resolveServerRuntimeConfig(
- applyConfigOverlay(makeTestConfig(), {
- server: { bind: ['192.168.1.5'], ...scoped },
- }) as Config,
- );
- expect(runtime.allowExternal).toBe(false);
- expect(requiresExternalConsent(runtime)).toBe(true);
- });
-
- test('a mixed loopback + non-loopback bind list also drops allowExternal (every, not some)', () => {
- expect(
- 'allowExternal' in scopeRemoteAliasConsentToBind(overlay, ['127.0.0.1', '192.168.1.5']),
- ).toBe(false);
- });
});
describe('parseExternalUrlFlag', () => {
@@ -223,55 +60,6 @@ describe('parseExternalUrlFlag', () => {
test('flag errors name the flag the user typed', () => {
expect(() => parseExternalUrlFlag('not a url')).toThrow(/--external-url/);
- expect(() => parsePublicUrlFlag('not a url')).toThrow(/--public-url/);
- });
-});
-
-describe('parsePublicUrlFlag (deprecated --public-url alias)', () => {
- test('validates with the same http(s)-origin shape as --external-url', () => {
- expect(parsePublicUrlFlag('https://kb.example.com')).toBe('https://kb.example.com');
- expect(parsePublicUrlFlag('http://laptop.tail:55222')).toBe('http://laptop.tail:55222');
- expect(() => parsePublicUrlFlag('ftp://kb.example.com')).toThrow(/http\(s\) origin/);
- });
-});
-
-describe('resolveFlagExternalUrl (the flag-layer fold)', () => {
- test('the deprecated --public-url spelling still sets the value when it is the only flag given', () => {
- // The regression this pins: dropping the publicUrl fallback would leave a
- // --public-url-only start with externalUrl undefined — no CORS/Host
- // admission for the declared host and no issued URLs, with no parse error
- // to signal it during the deprecation window.
- expect(resolveFlagExternalUrl({ publicUrl: 'https://kb.example.com' })).toBe(
- 'https://kb.example.com',
- );
- expect(resolveFlagExternalUrl({ externalUrl: 'https://kb.example.com' })).toBe(
- 'https://kb.example.com',
- );
- expect(resolveFlagExternalUrl({})).toBeUndefined();
- });
-
- test('a --public-url-only invocation resolves the identical runtime to --external-url', () => {
- // Mirrors the expandRemoteAlias parity test above: apply exactly what
- // runStartCommand overlays for each spelling and compare the resolved
- // runtimes end to end.
- const url = 'https://kb.example.com';
- const config = makeTestConfig();
- const viaDeprecated = resolveServerRuntimeConfig(
- applyConfigOverlay(config, {
- server: { bind: ['127.0.0.1'], externalUrl: resolveFlagExternalUrl({ publicUrl: url }) },
- }) as Config,
- );
- const viaCanonical = resolveServerRuntimeConfig(
- applyConfigOverlay(config, {
- server: { bind: ['127.0.0.1'], externalUrl: resolveFlagExternalUrl({ externalUrl: url }) },
- }) as Config,
- );
- expect(viaDeprecated).toEqual(viaCanonical);
- expect(viaDeprecated.externalUrl).toBe(url);
- // Both spellings write the successor key, so the runtime reads as the
- // canonical server-section origin with no deprecated-config-key signal.
- expect(viaDeprecated.externalUrlSource).toBe('server');
- expect(viaDeprecated.externalUrlFromDeprecatedKey).toBe(false);
});
});
@@ -401,21 +189,6 @@ function fetchText(
});
}
-describe('resolveCollabPort (env PORT suppression)', () => {
- test('explicit --port always wins', () => {
- expect(resolveCollabPort(4111, 5555, true)).toBe(4111);
- expect(resolveCollabPort(4111, 5555, false)).toBe(4111);
- });
-
- test('env PORT flows through for a plain local start', () => {
- expect(resolveCollabPort(undefined, 5555, false)).toBe(5555);
- });
-
- test('remote mode drops env PORT (PaaS edge-proxy injection)', () => {
- expect(resolveCollabPort(undefined, 5555, true)).toBeUndefined();
- });
-});
-
describe('withIdleShutdownProcessExit (idle-path zombie prevention)', () => {
test('exits 0 after the handler completes, logging an open-handle summary', async () => {
const order: string[] = [];
@@ -1193,8 +966,7 @@ describe('bootStartServer — rejects with init-required when .ok/config.yml is
// startCommand --mode flag.
// These exercise the Commander wiring at the public CLI surface — the
-// validator (parseStartMode), the --mode=app + --open mutual-exclusion
-// guard (→ exit 2), and the --mode=app + no-bundle error path
+// validator (parseStartMode) and the --mode=app + no-bundle error path
// (→ exit 1). The launch-when-detected path is covered by
// desktop-dispatch.test.ts (detectDesktop matrix + launchDesktop spawn
// shape); replicating it here would require monkey-patching the
@@ -1238,36 +1010,6 @@ describe('startCommand — --mode flag wiring', () => {
expect(helpDisplayed).toBe(true);
});
- test('--mode=app + --open exits with code 2 (FR6 mutual exclusion)', async () => {
- const cmd = quietCommand();
-
- let capturedExitCode: number | undefined;
- let capturedStderr = '';
- const originalExit = process.exit;
- const originalStderrWrite = process.stderr.write.bind(process.stderr);
- process.exit = ((code?: number) => {
- capturedExitCode = code;
- throw new Error('exit-stub');
- }) as never;
- process.stderr.write = ((chunk: unknown) => {
- capturedStderr += String(chunk);
- return true;
- }) as never;
-
- try {
- await cmd.parseAsync(['--mode', 'app', '--open'], { from: 'user' });
- } catch (err) {
- if ((err as Error).message !== 'exit-stub') throw err;
- } finally {
- process.exit = originalExit;
- process.stderr.write = originalStderrWrite;
- }
-
- expect(capturedExitCode).toBe(2);
- expect(capturedStderr).toContain('--mode=app');
- expect(capturedStderr).toContain('--open');
- });
-
test('--mode=app with detection unavailable exits 1 + emits a contextual notFoundMessage (FR5)', async () => {
// OK_FORCE_BROWSER=1 makes detectDesktop deterministically return false
// with reason='force-browser'. The contextual notFoundMessage(reason)
@@ -1440,14 +1182,12 @@ describe('withEphemeralTempDirReap', () => {
});
describe('resolveHost — --bind precedence', () => {
- test('--bind wins over the deprecated --host alias and env', () => {
- expect(resolveHost({ bind: ['0.0.0.0'], host: '127.0.0.2' }, { HOST: '127.0.0.3' })).toBe(
- '0.0.0.0',
- );
+ test('--bind wins over env', () => {
+ expect(resolveHost({ bind: ['0.0.0.0'] }, { HOST: '127.0.0.3' })).toBe('0.0.0.0');
});
- test('empty bind list falls through to --host', () => {
- expect(resolveHost({ bind: [], host: '127.0.0.2' }, {})).toBe('127.0.0.2');
+ test('empty bind list falls through to env', () => {
+ expect(resolveHost({ bind: [] }, { HOST: '127.0.0.2' })).toBe('127.0.0.2');
});
});
@@ -1541,7 +1281,6 @@ describe('shouldOpenBrowser (interactive-loopback default open)', () => {
const base = {
openBrowser: true,
explicitOn: false,
- legacyOpen: false,
host: '127.0.0.1',
isTTY: true,
ephemeral: false,
@@ -1565,10 +1304,6 @@ describe('shouldOpenBrowser (interactive-loopback default open)', () => {
expect(shouldOpenBrowser({ ...base, openBrowser: false })).toBe(false);
});
- test('deprecated --open force-opens even without a TTY (pre-flip contract)', () => {
- expect(shouldOpenBrowser({ ...base, legacyOpen: true, isTTY: false })).toBe(true);
- });
-
test('no TTY (spawned/CI) stays quiet', () => {
expect(shouldOpenBrowser({ ...base, isTTY: false })).toBe(false);
});
@@ -1577,10 +1312,6 @@ describe('shouldOpenBrowser (interactive-loopback default open)', () => {
expect(shouldOpenBrowser({ ...base, host: '0.0.0.0' })).toBe(false);
});
- test('remote mode stays quiet', () => {
- expect(shouldOpenBrowser({ ...base, remoteEnabled: true })).toBe(false);
- });
-
test('ephemeral single-file stays quiet (owns its own open flow)', () => {
expect(shouldOpenBrowser({ ...base, ephemeral: true })).toBe(false);
});
@@ -1592,22 +1323,6 @@ describe('shouldOpenBrowser (interactive-loopback default open)', () => {
test('a start that ended up serving no shell stays quiet', () => {
expect(shouldOpenBrowser({ ...base, servesUi: false })).toBe(false);
});
-
- // Guard-ordering regressions: --open must not override the "nothing to open"
- // or "explicit no" suppressions (only the TTY / loopback gates).
- test('--open does NOT open a dead tab at a shell-less --only server', () => {
- expect(shouldOpenBrowser({ ...base, legacyOpen: true, only: 'server', servesUi: false })).toBe(
- false,
- );
- });
-
- test('--open does NOT open when no shell was served', () => {
- expect(shouldOpenBrowser({ ...base, legacyOpen: true, servesUi: false })).toBe(false);
- });
-
- test('--no-open-browser wins over --open (explicit no)', () => {
- expect(shouldOpenBrowser({ ...base, legacyOpen: true, openBrowser: false })).toBe(false);
- });
});
describe('resolveServerReuse (spawn-or-reuse)', () => {
@@ -1871,189 +1586,4 @@ describe('startCommand — flag-conflict guards (exit 2)', () => {
expect(code).toBe(2);
expect(stderr).toContain('--react-shell-dist-dir');
});
-
- test('--single-file + --remote exits 2 (no consented root to expose)', async () => {
- const { code, stderr } = await captureGuard([
- '--single-file',
- '/tmp/note.md',
- '--remote',
- 'https://tunnel.example.com',
- ]);
- expect(code).toBe(2);
- expect(stderr).toContain('--single-file');
- });
-
- test('--remote + --external-url exits 2 (the alias IS an external-url; one must win)', async () => {
- const { code, stderr } = await captureGuard([
- '--remote',
- 'https://tunnel.example.com',
- '--external-url',
- 'https://kb.example.com',
- ]);
- expect(code).toBe(2);
- expect(stderr).toContain('--external-url');
- });
-
- test('--remote + deprecated --public-url exits 2 with the alias named', async () => {
- const { code, stderr } = await captureGuard([
- '--remote',
- 'https://tunnel.example.com',
- '--public-url',
- 'https://kb.example.com',
- ]);
- expect(code).toBe(2);
- expect(stderr).toContain('--public-url');
- });
-
- test('--external-url + deprecated --public-url exits 2 (same flag under two names)', async () => {
- const { code, stderr } = await captureGuard([
- '--external-url',
- 'https://new.example.com',
- '--public-url',
- 'https://old.example.com',
- ]);
- expect(code).toBe(2);
- expect(stderr).toContain('deprecated alias');
- });
-
- /**
- * The pre-boot `--remote` refusals print via console.warn/console.error
- * (vitest intercepts the console, so `captureGuard`'s stderr stub never
- * sees them) — collect both streams via spies alongside the exit code.
- */
- async function captureRemoteRefusal(
- argv: string[],
- config?: Config,
- ): Promise<{ code: number | undefined; output: string }> {
- const lines: string[] = [];
- const record = (...args: unknown[]) => {
- lines.push(args.map(String).join(' '));
- };
- const warnSpy = vi.spyOn(console, 'warn').mockImplementation(record);
- const errorSpy = vi.spyOn(console, 'error').mockImplementation(record);
- try {
- const { code, stderr } = await captureGuard(argv, config);
- return { code, output: `${stderr}\n${lines.join('\n')}` };
- } finally {
- warnSpy.mockRestore();
- errorSpy.mockRestore();
- }
- }
-
- test('--remote without a url anywhere exits 78 and names the successor keys in the deprecation notice', async () => {
- const { code, output } = await captureRemoteRefusal(['--remote']);
- expect(code).toBe(78);
- expect(output).toContain('--remote requires a public tunnel URL');
- // The deprecation notice fires even on the refusal path — EXACTLY once —
- // and names every key the alias pins (--external-url / --bind /
- // OK_ALLOW_EXTERNAL / OK_IDLE_SHUTDOWN=off), so an operator learns the
- // full ratified spelling from the same run that errors. Omitting the
- // idle-shutdown key would hand migrators a server that tears itself down
- // after 30 idle minutes under a live remote MCP client.
- expect(output.split('--remote is deprecated').length - 1).toBe(1);
- expect(output).toContain('--external-url');
- expect(output).toContain('--bind');
- expect(output).toContain('OK_ALLOW_EXTERNAL');
- expect(output).toContain('OK_IDLE_SHUTDOWN=off');
- });
-
- test('--remote with a plain-http url exits 78 (legacy https-only rule preserved)', async () => {
- const { code, output } = await captureRemoteRefusal(['--remote', 'http://tunnel.example.com']);
- expect(code).toBe(78);
- expect(output).toContain('must be https');
- });
-
- // The rename notices share the --remote ordering contract: they print
- // BEFORE the env layer parses, so pairing the deprecated spelling with a
- // malformed env var proves the notice survives a refusal path without
- // booting a server (env refusal = exit 78).
- test('deprecated --public-url still parses and prints the rename notice (refusal path)', async () => {
- const prior = process.env.OK_OPEN_BROWSER;
- process.env.OK_OPEN_BROWSER = 'not-a-boolean';
- try {
- const { code, output } = await captureRemoteRefusal([
- '--public-url',
- 'https://kb.example.com',
- ]);
- expect(code).toBe(78);
- expect(output.split('--public-url is deprecated').length - 1).toBe(1);
- expect(output).toContain('--external-url');
- } finally {
- if (prior === undefined) delete process.env.OK_OPEN_BROWSER;
- else process.env.OK_OPEN_BROWSER = prior;
- }
- });
-
- test('a config-file server.publicUrl prints the rename notice (refusal path)', async () => {
- const prior = process.env.OK_OPEN_BROWSER;
- process.env.OK_OPEN_BROWSER = 'not-a-boolean';
- try {
- const config = ConfigSchema.parse({
- server: { publicUrl: 'https://kb.example.com' },
- });
- const { code, output } = await captureRemoteRefusal([], config);
- expect(code).toBe(78);
- expect(output.split('server.publicUrl is deprecated').length - 1).toBe(1);
- expect(output).toContain('server.externalUrl');
- } finally {
- if (prior === undefined) delete process.env.OK_OPEN_BROWSER;
- else process.env.OK_OPEN_BROWSER = prior;
- }
- });
-
- test('the config-file notice still fires when a flag or env override masks the value', async () => {
- // The notice is keyed off the FILE layers before the env/flag overlay: a
- // masking override changes which value wins for this run, but the stale
- // committed key still needs renaming, so suppressing the notice would
- // hide exactly the config the operator has to fix.
- const prior = process.env.OK_OPEN_BROWSER;
- process.env.OK_OPEN_BROWSER = 'not-a-boolean';
- try {
- const config = ConfigSchema.parse({
- server: { publicUrl: 'https://committed.example.com' },
- });
- const flagMasked = await captureRemoteRefusal(
- ['--external-url', 'https://flag.example.com'],
- config,
- );
- expect(flagMasked.code).toBe(78);
- expect(flagMasked.output.split('server.publicUrl is deprecated').length - 1).toBe(1);
- } finally {
- if (prior === undefined) delete process.env.OK_OPEN_BROWSER;
- else process.env.OK_OPEN_BROWSER = prior;
- }
-
- const priorEnv = process.env.OK_EXTERNAL_URL;
- const priorOpen = process.env.OK_OPEN_BROWSER;
- process.env.OK_EXTERNAL_URL = 'https://env.example.com';
- process.env.OK_OPEN_BROWSER = 'not-a-boolean';
- try {
- const config = ConfigSchema.parse({
- server: { publicUrl: 'https://committed.example.com' },
- });
- const envMasked = await captureRemoteRefusal([], config);
- expect(envMasked.code).toBe(78);
- expect(envMasked.output.split('server.publicUrl is deprecated').length - 1).toBe(1);
- } finally {
- if (priorEnv === undefined) delete process.env.OK_EXTERNAL_URL;
- else process.env.OK_EXTERNAL_URL = priorEnv;
- if (priorOpen === undefined) delete process.env.OK_OPEN_BROWSER;
- else process.env.OK_OPEN_BROWSER = priorOpen;
- }
- });
-
- test('a config-file server.externalUrl (successor) prints no rename notice', async () => {
- const prior = process.env.OK_OPEN_BROWSER;
- process.env.OK_OPEN_BROWSER = 'not-a-boolean';
- try {
- const config = ConfigSchema.parse({
- server: { externalUrl: 'https://kb.example.com' },
- });
- const { output } = await captureRemoteRefusal([], config);
- expect(output).not.toContain('server.publicUrl is deprecated');
- } finally {
- if (prior === undefined) delete process.env.OK_OPEN_BROWSER;
- else process.env.OK_OPEN_BROWSER = prior;
- }
- });
});
diff --git a/packages/cli/src/commands/start.ts b/packages/cli/src/commands/start.ts
index bd1011ec6..e75d5c0c5 100644
--- a/packages/cli/src/commands/start.ts
+++ b/packages/cli/src/commands/start.ts
@@ -27,13 +27,11 @@ import { basename, resolve as pathResolve } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import {
applyConfigOverlay,
- DEFAULT_REMOTE_PORT,
DEFAULT_SERVER_HOST,
type EnvConfigLayer,
EnvVarError,
IDLE_SHUTDOWN_DURATION_RE,
idleShutdownToMs,
- isLoopbackOnlyBind,
resolveEnvConfigLayer,
resolveServerRuntimeConfig,
type ServerRuntimeConfig,
@@ -46,7 +44,7 @@ import {
type PinoLogger,
prepareSingleFileOpen,
} from '@inkeep/open-knowledge-server';
-import { Command, InvalidArgumentError, Option } from 'commander';
+import { Command, InvalidArgumentError } from 'commander';
import { makeLazyEmbeddingsKeyStore } from '../auth/embeddings-key-store.ts';
import { detectGh } from '../auth/gh-detect.ts';
import { makeLazyProbeTokenStore } from '../auth/token-store.ts';
@@ -64,17 +62,17 @@ import {
const DEFAULT_IDLE_THRESHOLD_MS = 30 * 60 * 1000;
/**
- * Resolve a single bind host with `--bind` flag > deprecated `--host` alias >
- * `HOST` env > application default precedence. Pure helper — no side effects,
- * no `process.env` access inside (env passed in) so tests can pin all
- * branches. Used by the ephemeral single-file path; `ok start` proper
- * resolves the full bind LIST (config/env layers included) inline.
+ * Resolve a single bind host with `--bind` flag > `HOST` env > application
+ * default precedence. Pure helper — no side effects, no `process.env` access
+ * inside (env passed in) so tests can pin all branches. Used by the ephemeral
+ * single-file path; `ok start` proper resolves the full bind LIST (config/env
+ * layers included) inline.
*/
export function resolveHost(
- opts: { host?: string; bind?: string[] },
+ opts: { bind?: string[] },
env: { HOST?: string | undefined; [key: string]: string | undefined },
): string {
- return opts.bind?.[0] ?? opts.host ?? env.HOST ?? DEFAULT_SERVER_HOST;
+ return opts.bind?.[0] ?? env.HOST ?? DEFAULT_SERVER_HOST;
}
/** Modules selectable via `--only` — explicit operator module selection. */
@@ -94,8 +92,8 @@ export function parseOnlyModule(value: string): OnlyModule {
/**
* Resolve the bundled React shell `dist` directory — published `dist/public`
* first, then the monorepo `app/dist`. One resolver shared by plain
- * `ok start`, remote mode, and the ephemeral single-file browser fallback so
- * dev and published builds can never disagree on where the shell lives.
+ * `ok start` and the ephemeral single-file browser fallback so dev and
+ * published builds can never disagree on where the shell lives.
*/
export function resolveBundledReactShellDir(
existsFn: (path: string) => boolean = fsExistsSync,
@@ -109,8 +107,8 @@ export function resolveBundledReactShellDir(
}
/**
- * Decide which React-shell directory the composed server serves — the Wave 3
- * default-flip decision, pure so every branch is unit-tested:
+ * Decide which React-shell directory the composed server serves — pure so
+ * every branch is unit-tested:
*
* - an explicit `--react-shell-dist-dir` always wins;
* - `--only server` opts out of the UI module entirely;
@@ -157,7 +155,7 @@ export function isLoopbackHost(host: string): boolean {
/**
* Should a `HOST`-driven bind warn that it is silently dropping a multi-element
* `server.bind`? `HOST` is a single-address platform-injection variable
- * (Heroku/Railway); when it — and neither `--bind`/`--host` nor `OK_BIND` —
+ * (Heroku/Railway); when it — and neither `--bind` nor `OK_BIND` —
* drives the bind, it REPLACES the whole file-layer list, halving a dual-stack
* config with no record the way `OK_BIND` overrides carry. Pure so the boundary
* (`> 1`, not `>= 1`) is unit-tested independent of the boot path.
@@ -174,18 +172,12 @@ export function shouldWarnHostOverridesMultiBind(input: {
/**
* Should this start open the browser? Interactive loopback starts open by
* default (suppress with `--no-open-browser`); everything non-interactive or
- * non-local stays quiet. Pure so the whole decision table is unit-tested:
+ * non-local stays quiet. Pure so the whole decision table is unit-tested. The
+ * suppression conditions, in order:
*
- * Guard order matters. The "nothing to open" and "explicit no" checks run
- * BEFORE the deprecated `--open` force-open, so `--open` can override the TTY
- * and loopback gates (its pre-flip contract) but can never pop a dead tab at
- * a shell-less server or fight an explicit `--no-open-browser`:
- *
- * - `--no-open-browser` always suppresses, even against `--open`;
- * - remote mode, ephemeral single-file (owns its own open flow), `--only
- * server`, and a start that ended up serving no shell never open;
- * - `--open` (deprecated) then forces open, preserving its pre-flip contract
- * for scripts that relied on it in non-TTY contexts;
+ * - `--no-open-browser` always suppresses;
+ * - ephemeral single-file (owns its own open flow), `--only server`, and a
+ * start that ended up serving no shell never open;
* - otherwise: open iff the bind is loopback AND stdout is a TTY (a spawned
* or CI invocation must not pop a browser). An EXPLICIT
* `server.openBrowser: true` / `OK_OPEN_BROWSER=1` (`explicitOn`) lifts
@@ -195,137 +187,22 @@ export function shouldWarnHostOverridesMultiBind(input: {
export function shouldOpenBrowser(input: {
openBrowser: boolean;
explicitOn: boolean;
- legacyOpen: boolean;
host: string;
isTTY: boolean;
- remoteEnabled: boolean;
ephemeral: boolean;
only: OnlyModule | undefined;
servesUi: boolean;
}): boolean {
if (!input.openBrowser) return false;
- if (input.remoteEnabled || input.ephemeral || input.only === 'server') return false;
+ if (input.ephemeral || input.only === 'server') return false;
if (!input.servesUi) return false;
- if (input.legacyOpen) return true;
return (input.explicitOn || isLoopbackHost(input.host)) && input.isTTY;
}
/**
- * Bind-family guard for remote mode. Tunnel agents (ngrok, cloudflared,
- * tailscaled, …) proxy to an IPv4 loopback target (`127.0.0.1:<port>`), so an
- * IPv6-only bind (`::`, `::1`, or `localhost` resolving to `::1` first)
- * leaves the tunnel dialing a port nobody answers on — hit in practice during
- * the MVP. When remote access is enabled and the resolved host is one of
- * those shapes, coerce to `127.0.0.1` and tell the operator. Pure — returns
- * the corrected host and whether a coercion happened; caller logs.
- */
-export function coerceRemoteBindHost(
- host: string,
- remoteEnabled: boolean,
-): { host: string; coerced: boolean } {
- if (!remoteEnabled) return { host, coerced: false };
- if (
- host === '::' ||
- host === '::1' ||
- host === '[::1]' ||
- host === 'localhost' ||
- // 0.0.0.0 binds every interface; in remote mode the tunnel agent only
- // needs loopback, and an all-interfaces bind would let a LAN peer reach
- // the admitted surface directly, bypassing the tunnel's edge auth.
- host === '0.0.0.0'
- ) {
- return { host: '127.0.0.1', coerced: true };
- }
- return { host, coerced: false };
-}
-
-/** The `server.*` keys `--remote` expands into — nothing beyond the ratified surface. */
-interface RemoteAliasServerOverlay {
- externalUrl: string;
- allowExternal: true;
- idleShutdown: 'off';
-}
-
-export type RemoteAliasExpansion =
- | { ok: true; url: string; serverOverlay: RemoteAliasServerOverlay }
- | { ok: false; errorMessage: string };
-
-/**
- * Scope the alias's self-consent to the topology it promises: a loopback
- * bind where the tunnel's edge auth is the only ingress. A non-loopback bind
- * (a tailnet/LAN address from `server.bind`, `OK_BIND`, `HOST`, or a `--bind`
- * shape `coerceRemoteBindHost` does not recognize) is reachable AROUND the
- * tunnel, so `--remote` must not consent to it on the operator's behalf —
- * without this, the exposure interlock that refused `--remote` + a
- * non-loopback bind before the alias would be silently satisfied. Dropping
- * `allowExternal` here lets the interlock refuse exactly as before;
- * `OK_ALLOW_EXTERNAL=1` remains the sanctioned override.
- */
-export function scopeRemoteAliasConsentToBind(
- serverOverlay: RemoteAliasServerOverlay,
- bindList: readonly string[],
-): { externalUrl: string; idleShutdown: 'off'; allowExternal?: true } {
- if (isLoopbackOnlyBind(bindList)) return serverOverlay;
- return { externalUrl: serverOverlay.externalUrl, idleShutdown: serverOverlay.idleShutdown };
-}
-
-/**
- * `--remote [url]` is a deprecated thin alias over the ratified `server.*`
- * networking keys: it expands to `server.externalUrl` = the tunnel url (its
- * host joins the Host/Origin allowlists), a loopback bind (tunnels proxy to
- * `127.0.0.1` — the deployer's tunnel agent covers ingress, see
- * `coerceRemoteBindHost`), and `server.allowExternal` consent, which
- * satisfies the exposure interlock and the forwarded-header tripwire. Plus
- * `server.idleShutdown: 'off'`: remote MCP sessions arrive as plain HTTP,
- * and the idle timer counts /collab WS clients only — it would tear the
- * server down under a live remote client. Networking-only — the alias
- * carries no auth semantics; restricting who reaches the URL stays the
- * tunnel's job (edge auth).
- *
- * Returns `null` when the flag is absent. `ok: false` carries the exit-78
- * message: a missing url is unusable, and the legacy https-only rule is kept
- * through the deprecation window (a tunnel URL over plain http would be
- * credentials-in-the-clear).
- */
-export function expandRemoteAlias(
- remoteFlag: string | boolean | undefined,
- configRemoteUrl: string | undefined,
-): RemoteAliasExpansion | null {
- if (remoteFlag === undefined || remoteFlag === false) return null;
- const url = typeof remoteFlag === 'string' ? remoteFlag : configRemoteUrl;
- if (url === undefined || url === '') {
- return {
- ok: false,
- errorMessage:
- '--remote requires a public tunnel URL — pass it (`ok start --remote https://<your-tunnel-host>`) or set remote.url in .ok/config.yml.',
- };
- }
- let parsed: URL;
- try {
- parsed = new URL(url);
- } catch {
- return { ok: false, errorMessage: `remote.url is not a valid URL: ${url}` };
- }
- if (parsed.protocol !== 'https:') {
- return {
- ok: false,
- errorMessage: `remote.url must be https — it is the public tunnel URL remote clients connect to (got: ${url})`,
- };
- }
- const normalizedUrl = url.replace(/\/+$/, '');
- return {
- ok: true,
- url: normalizedUrl,
- serverOverlay: { externalUrl: normalizedUrl, allowExternal: true, idleShutdown: 'off' },
- };
-}
-
-/**
- * Validator shared by the `--external-url` parser and its deprecated
- * `--public-url` spelling — the flag-layer setter for `server.externalUrl`,
- * matching the schema leaf's http(s)-origin shape so a flag value can never
- * smuggle in what the config file would reject. `flagName` keeps the error
- * text naming the flag the user actually typed.
+ * Validator for the `--external-url` flag — the flag-layer setter for
+ * `server.externalUrl`, matching the schema leaf's http(s)-origin shape so a
+ * flag value can never smuggle in what the config file would reject.
*/
function parseHttpOriginFlag(flagName: string, value: string): string {
let parsed: URL;
@@ -344,27 +221,6 @@ export function parseExternalUrlFlag(value: string): string {
return parseHttpOriginFlag('--external-url', value);
}
-/**
- * The flag-layer external-URL fold: `--external-url` wins, the deprecated
- * `--public-url` spelling fills in when it is the only one given (the two
- * flags cannot legally co-occur — the action guard exits 2 — so the `??` is
- * precedence bookkeeping, not conflict resolution). Extracted so a test pins
- * that the deprecated flag keeps setting `server.externalUrl` through its
- * removal window: dropping the fallback would silently strand `--public-url`
- * operators on `externalUrl: undefined` (no CORS/Host admission) with no parse
- * error to signal it.
- */
-export function resolveFlagExternalUrl(
- opts: Pick<StartCommandOptions, 'externalUrl' | 'publicUrl'>,
-): string | undefined {
- return opts.externalUrl ?? opts.publicUrl;
-}
-
-/** Parser for the deprecated `--public-url` alias of `--external-url`. */
-export function parsePublicUrlFlag(value: string): string {
- return parseHttpOriginFlag('--public-url', value);
-}
-
/** Hard cap on the project-name suffix in `process.title` to keep `ps`/Activity Monitor lines readable. */
const PROCESS_TITLE_PROJECT_NAME_MAX = 64;
@@ -411,23 +267,6 @@ export class OkDirMissingError extends Error {
}
}
-/**
- * Resolve the collab server's port from the three sources, for `runStartCommand`.
- * An explicit `--port` always wins. Otherwise env `PORT` is dropped when
- * remote access is enabled, because PaaS platforms (Railway, Fly, Render)
- * inject `PORT` for their own edge proxy — honoring it would silently move
- * the server off the stable `remote.port` the tunnel's port mapping targets,
- * leaving the tunnel dialing a dead port. Pure so the suppression rule is
- * tested directly.
- */
-export function resolveCollabPort(
- portFromCli: number | undefined,
- portFromEnv: number | undefined,
- remoteEnabled = false,
-): number | undefined {
- return portFromCli ?? (remoteEnabled ? undefined : portFromEnv);
-}
-
/**
* Wrap an idle-shutdown handler so that, after the server is destroyed, the
* ephemeral session's throwaway temp projectDir is removed. Without this an
@@ -543,7 +382,7 @@ interface BootStartServerOptions {
config: Config;
cwd: string;
/**
- * Server bind host. Source ordering at the call site is `--host` flag →
+ * Server bind host. Source ordering at the call site is `--bind` flag →
* `HOST` env → `DEFAULT_SERVER_HOST`. Resolved at the start command,
* not via config — `server.host` is no longer a schema field.
*/
@@ -932,10 +771,6 @@ interface StartCommandOptions {
port?: string | number;
/** From repeatable `--bind <address>`. First value wins today; >1 rejected at the action layer. */
bind?: string[];
- /** From the deprecated `-H, --host` alias of `--bind`. */
- host?: string;
- /** From deprecated `--open`: force-open the browser (pre-flip contract, honored even non-TTY). */
- open?: boolean;
/**
* From `--no-open-browser` (Commander negation: absent → `true`). Interactive
* loopback starts open the browser by default; this is the suppression
@@ -970,18 +805,8 @@ interface StartCommandOptions {
/** From `--project-dir <dir>`. See `BootStartServerOptions.projectDir` — the
* throwaway temp project root for the ephemeral single-file shape. */
projectDir?: string;
- /**
- * From `--remote [url]`: deprecated alias over the `server.*` keys — see
- * `expandRemoteAlias`. `true` when the flag is bare (url comes from
- * `remote.url` in config); a string when the url is supplied inline (used
- * for this run, not persisted). Absent → loopback-only, regardless of any
- * `remote.url` in config.
- */
- remote?: string | boolean;
/** From `--external-url <url>`: flag-layer `server.externalUrl` for this run. */
externalUrl?: string;
- /** From the deprecated `--public-url` alias of `--external-url`. */
- publicUrl?: string;
}
/**
@@ -1055,12 +880,6 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)
const { accent, dim, error, warning } = await import('../ui/colors.ts');
const cwd = process.cwd();
- // Remote access is an explicit `--remote [url]` opt-in. A `remote.url` left
- // in `.ok/config.yml` does NOT arm it by itself — the flag decides; the
- // config url fills in when the flag is bare, and a flag-supplied url wins
- // for this run without persisting. The flag is a deprecated thin alias over
- // the ratified `server.*` keys — `expandRemoteAlias` holds the expansion.
- const remoteFlagSet = opts.remote !== undefined && opts.remote !== false;
// Set the process title as early as possible so Activity Monitor and
// `ps -ax | grep open-knowledge-server` show each running server by
@@ -1069,73 +888,6 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)
// action; the OS process list is the discovery path.
process.title = deriveServerProcessTitle(cwd);
- // Deprecation notice first, even when the expansion below refuses — the
- // operator should learn the successor spelling from the same run that
- // errors. Networking-only alias; removal ships separately after a soak.
- if (remoteFlagSet) {
- console.warn(
- warning(
- '--remote is deprecated — use `OK_IDLE_SHUTDOWN=off OK_ALLOW_EXTERNAL=1 ok start --external-url <url>` instead (add --bind to serve a non-loopback address; keep OK_IDLE_SHUTDOWN=off — the idle timer only counts WS clients and would tear the server down under a live remote MCP client). The flag now just expands to those server.* keys and will be removed in a later release.',
- ),
- );
- }
-
- // Same ordering contract as the --remote notice above: the rename notices
- // print even when a later step refuses, so the operator learns the
- // successor spelling from the same run.
- if (opts.publicUrl !== undefined) {
- console.warn(
- warning(
- '--public-url is deprecated — use --external-url <url> (same value and semantics; the key was renamed to server.externalUrl). The old spelling will be removed in a later release.',
- ),
- );
- }
-
- // Config-file rename notice, keyed off the FILE layers (before the env/flag
- // overlay — those spellings write the successor key and warn on their own,
- // and a masking override doesn't make the stale file key any less stale).
- if (resolveServerRuntimeConfig(config).externalUrlFromDeprecatedKey) {
- // "Use X instead", not "rename it": in a committed shared config, keeping
- // BOTH keys is the sanctioned mixed-version state — older app versions
- // read only server.publicUrl and silently ignore server.externalUrl, so
- // a literal rename would 403 collaborators who have not upgraded.
- console.warn(
- warning(
- '[config] server.publicUrl is deprecated — use server.externalUrl instead (same value and semantics). If this config is committed and shared, keep both keys until every collaborator has upgraded — older versions read only server.publicUrl; see https://openknowledge.ai/docs/reference/configuration. The old key will be removed in a later release.',
- ),
- );
- }
-
- // Fail loud BEFORE booting: --remote with no url anywhere (or a non-https
- // url) is unusable, and the error message is the fix instruction.
- const aliasResult = expandRemoteAlias(opts.remote, config.remote?.url);
- if (aliasResult !== null && !aliasResult.ok) {
- console.error(error(aliasResult.errorMessage));
- process.exit(78);
- }
- const remoteAlias = aliasResult?.ok ? aliasResult : null;
- const remoteEnabled = remoteAlias !== null;
-
- // The trust-the-tunnel warning. Deliberately unmissable: with --remote there
- // is NO server-side authentication — access control is entirely the
- // tunnel's job (edge auth), and every admitted caller has the full owner
- // surface. Printed on every remote start so the trade is never implicit.
- if (remoteAlias !== null) {
- console.warn(
- warning(
- [
- '',
- '⚠ REMOTE ACCESS ENABLED — no server-side authentication.',
- ` Anyone who can reach ${remoteAlias.url} has FULL control of this`,
- ' knowledge base, including sync, publishing, credentials, and local operations.',
- ' Restrict who can reach it at the tunnel: ngrok OAuth, Cloudflare Access,',
- ' Tailscale ACLs, or equivalent edge auth.',
- '',
- ].join('\n'),
- ),
- );
- }
-
// The env config layer (the mechanical OK_* surface + platform PORT):
// parsed once, leaf-validated, fail-loud on a malformed value with the
// variable named. Did-you-mean observations surface as warnings.
@@ -1154,18 +906,13 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)
}
const envConfig = applyConfigOverlay(config, envLayer.layer) as Config;
- // Bind precedence: --bind / deprecated --host flags > ratified OK_BIND >
- // legacy HOST env > server.bind file layer > loopback default. The resolved
- // LIST is what the derived defaults key off (openBrowser/idleShutdown
- // derive from loopback-only-ness); the listener binds every entry in the
- // list (multi-address bind), each on the same port.
+ // Bind precedence: --bind flag > ratified OK_BIND > legacy HOST env >
+ // server.bind file layer > loopback default. The resolved LIST is what the
+ // derived defaults key off (openBrowser/idleShutdown derive from
+ // loopback-only-ness); the listener binds every entry in the list
+ // (multi-address bind), each on the same port.
const okBindSet = envLayer.overrides.some((o) => o.envVar === 'OK_BIND');
- const flagBind =
- opts.bind !== undefined && opts.bind.length > 0
- ? opts.bind
- : opts.host !== undefined
- ? [opts.host]
- : undefined;
+ const flagBind = opts.bind !== undefined && opts.bind.length > 0 ? opts.bind : undefined;
// Empty/whitespace `HOST` reads as unset, matching the env layer's
// `PORT=''` handling — a platform that exports an empty `HOST` must not
// produce a `['']` bind list (`''` is non-loopback, so it would trip the
@@ -1193,59 +940,29 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)
);
}
- const resolvedHost = requestedBind[0] ?? DEFAULT_SERVER_HOST;
- const hostCoercion = coerceRemoteBindHost(resolvedHost, remoteEnabled);
- if (hostCoercion.coerced) {
- console.warn(
- `remote access is enabled and ${resolvedHost} is not an IPv4 loopback bind — tunnels proxy to 127.0.0.1, so binding ${resolvedHost} would leave the tunnel dialing a dead port. Using 127.0.0.1.`,
- );
- }
- const host = hostCoercion.host;
- // The EFFECTIVE bind list — remote mode collapses to the coerced loopback
- // host (the tunnel is the only ingress there), so the interlock and the
- // ingress policy see what the server actually binds, not the pre-coercion
- // request. Without this, `HOST=0.0.0.0 ok start --remote` coerces to
- // loopback yet still trips ExposureConsentError off the uncoerced list.
- const bindList = remoteEnabled ? [host] : requestedBind;
+ const host = requestedBind[0] ?? DEFAULT_SERVER_HOST;
+ const bindList = requestedBind;
// The flag-layer overlay, applied ABOVE the env layer: the resolved bind
- // list, the `--remote` alias expansion (externalUrl + allowExternal +
- // idleShutdown 'off' — the SAME server.* resolution path any other exposure
- // route uses), and `--external-url` (or its deprecated `--public-url`
- // spelling — both write the successor key so the flag layer keeps its
- // precedence over env and file layers). Nothing here is remote-specific
- // machinery; the alias is only these keys. Self-consent is loopback-scoped
- // (see scopeRemoteAliasConsentToBind) — a non-loopback bind under --remote
- // still needs explicit consent, so the interlock refusal below matches the
- // pre-alias behavior.
- const aliasOverlay =
- remoteAlias !== null ? scopeRemoteAliasConsentToBind(remoteAlias.serverOverlay, bindList) : {};
- if (remoteAlias !== null && !('allowExternal' in aliasOverlay)) {
- console.warn(
- warning(
- `--remote does not consent to exposing a non-loopback bind (${bindList.join(', ')}) — the tunnel is the only ingress the alias vouches for. Consent explicitly with OK_ALLOW_EXTERNAL=1 (or server.allowExternal in .ok/local/config.yml), or drop the non-loopback bind.`,
- ),
- );
- }
- const flagExternalUrl = resolveFlagExternalUrl(opts);
+ // list plus `--external-url` (which writes server.externalUrl so the flag
+ // layer keeps its precedence over env and file layers).
+ const flagExternalUrl = opts.externalUrl;
const runtime: ServerRuntimeConfig = resolveServerRuntimeConfig(
applyConfigOverlay(envConfig, {
server: {
bind: bindList,
- ...aliasOverlay,
...(flagExternalUrl !== undefined ? { externalUrl: flagExternalUrl } : {}),
},
}) as Config,
);
- // The consent warning, sibling to the --remote banner above. `allowExternal`
- // is the sanctioned relaxation, but its blast radius is easy to under-read:
- // it exposes not just the editor/collab/API surface but the local-op owner
- // surface (clone, GitHub sign-in, PAT storage, repo spawn) to every external
- // peer, with NO server-side auth. Fire whenever consent is armed AND there is
- // a real exposure vector — a non-loopback bind (direct) or a declared
- // externalUrl (a same-host reverse proxy forwards to a loopback bind). The
- // --remote flow prints its own warning, so skip the duplicate there.
- if (!remoteEnabled && runtime.allowExternal && (!runtime.loopbackOnly || runtime.externalUrl)) {
+ // The exposure consent warning. `allowExternal` is the sanctioned
+ // relaxation, but its blast radius is easy to under-read: it exposes not
+ // just the editor/collab/API surface but the local-op owner surface (clone,
+ // GitHub sign-in, PAT storage, repo spawn) to every external peer, with NO
+ // server-side auth. Fire whenever consent is armed AND there is a real
+ // exposure vector — a non-loopback bind (direct) or a declared externalUrl
+ // (a same-host reverse proxy forwards to a loopback bind).
+ if (runtime.allowExternal && (!runtime.loopbackOnly || runtime.externalUrl)) {
const reach = runtime.externalUrl ?? runtime.bind.join(', ');
console.warn(
warning(
@@ -1267,35 +984,16 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)
const portFromEnv = envLayer.overrides.find((o) => o.envVar === 'PORT')?.value as
| number
| undefined;
- // An explicit --port wins everywhere; in remote mode the config port fills
- // the default slot and env PORT is suppressed (see resolveCollabPort).
- // A stable port matters in remote mode because the tailscale serve/funnel
- // mapping names a fixed target port — a kernel-assigned ephemeral port would
- // break the tunnel on every restart.
- // File-layer ports, split by consumer:
- // - `remotePort` follows the resolver's `server.port ?? remote.port` alias
- // — remote mode wants the stable tunnel-target port from either key.
- // - `localPort` is the SUCCESSOR key ONLY. A plain local start must not
- // inherit a dormant `remote.port` (set long ago for tunnel use); doing so
- // pins every local boot to that fixed port instead of a free dynamic one,
- // and two projects both carrying `remote.port` could never run at once.
- const remotePort = resolveServerRuntimeConfig(config).port;
- const localPort = config.server?.port;
- if (remoteEnabled && portFromCli === undefined && portFromEnv !== undefined) {
- console.warn(
- `remote access is enabled — ignoring env PORT=${process.env.PORT}; the tunnel's port mapping targets the stable remote port (${remotePort ?? DEFAULT_REMOTE_PORT}). Pass --port to override deliberately.`,
- );
- }
- const port =
- resolveCollabPort(portFromCli, portFromEnv, remoteEnabled) ??
- (remoteEnabled ? (remotePort ?? DEFAULT_REMOTE_PORT) : localPort);
+ // An explicit --port wins; otherwise the platform-injected PORT env, then a
+ // configured server.port. Unset → the caller picks a free dynamic port.
+ const port = portFromCli ?? portFromEnv ?? config.server?.port;
// The default composition serves the SPA from the server's own port (`/` =
// UI, `/api`, `/mcp`, `/collab` — one listener, one origin).
// `resolveStartShellDir` holds the decision table (explicit dir wins;
- // `--only server` opts out; everything else — remote included — serves the
- // shell by default). A missing bundle degrades to API/MCP-only with a
- // warning rather than failing the start.
+ // `--only server` opts out; everything else serves the shell by default).
+ // A missing bundle degrades to API/MCP-only with a warning rather than
+ // failing the start.
const shell = resolveStartShellDir({
explicitDir: opts.reactShellDistDir,
only: opts.only,
@@ -1304,9 +1002,7 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)
const reactShellDistDir = shell.dir;
if (shell.missingBundle) {
console.warn(
- remoteEnabled
- ? 'remote access: bundled web UI not found — serving /mcp and /api only over the tunnel.'
- : 'bundled web UI not found — serving /api and /mcp only. Reinstall @inkeep/open-knowledge, or build packages/app in a source checkout.',
+ 'bundled web UI not found — serving /api and /mcp only. Reinstall @inkeep/open-knowledge, or build packages/app in a source checkout.',
);
}
@@ -1317,8 +1013,7 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)
cwd,
host,
port,
- // Full bind list for the multi-listener bind — already collapsed to the
- // coerced loopback host in remote mode (see `bindList` above).
+ // Full bind list for the multi-listener bind (see `bindList` above).
bind: bindList,
...(opts.serveContentAssets !== undefined
? { serveContentAssets: opts.serveContentAssets }
@@ -1329,13 +1024,8 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)
// the resolver's covers OK_IDLE_SHUTDOWN, the config leaf, and the
// bind-derived default ('30m' loopback-only, 'off' exposed). Converted to
// ms (null for 'off') at this single boundary. The flag stays a string
- // through Commander on purpose — see parseIdleShutdownFlag. Under
- // --remote the alias overlay pins 'off' and the flag is ignored — the
- // legacy remote flow always disabled the idle timer, and a remote MCP
- // client is plain HTTP the /collab-counting timer can't see.
- idleThresholdMs: idleShutdownToMs(
- (remoteEnabled ? undefined : opts.idleShutdown) ?? runtime.idleShutdown,
- ),
+ // through Commander on purpose — see parseIdleShutdownFlag.
+ idleThresholdMs: idleShutdownToMs(opts.idleShutdown ?? runtime.idleShutdown),
serverRuntime: runtime,
...(opts.singleFile ? { singleFile: opts.singleFile } : {}),
...(opts.projectDir ? { projectDir: opts.projectDir } : {}),
@@ -1505,17 +1195,15 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)
}
// Interactive loopback starts open the browser by default now that the
- // banner URL is the full editor (suppress with --no-open-browser; the
- // deprecated --open force-opens). Decision table: `shouldOpenBrowser`.
+ // banner URL is the full editor (suppress with --no-open-browser).
+ // Decision table: `shouldOpenBrowser`.
const openDecision = shouldOpenBrowser({
// Flag suppression wins; otherwise the resolver's openBrowser covers
// OK_OPEN_BROWSER, the config leaf, and the bind-derived default.
openBrowser: opts.openBrowser !== false && runtime.openBrowser,
explicitOn: opts.openBrowser !== false && envConfig.server?.openBrowser === true,
- legacyOpen: opts.open === true,
host,
isTTY: process.stdout.isTTY === true,
- remoteEnabled,
ephemeral: opts.singleFile !== undefined,
only: opts.only,
servesUi: reactShellDistDir !== undefined,
@@ -1677,17 +1365,10 @@ export function startCommand(getConfig: () => Config): Command {
'Bind address (repeatable; default 127.0.0.1 — loopback only)',
(value: string, prev: string[] | undefined) => [...(prev ?? []), value],
)
- // Deprecated alias of --bind — kept working for the skew window, hidden
- // from --help so new scripts reach for the locked name.
- .addOption(new Option('-H, --host <host>', 'Deprecated alias of --bind').hideHelp())
.option(
'--no-open-browser',
'Do not open the browser after start (interactive loopback starts open it by default)',
)
- // Deprecated: pre-flip opt-in, now the default for interactive loopback
- // starts. Kept as a force-open for scripts that relied on it (it opens
- // even without a TTY). Hidden from --help.
- .addOption(new Option('--open', 'Deprecated: force-open the browser after start').hideHelp())
.option(
'--only <module>',
"Serve one module: 'server' (API + MCP only, no shell or browser)",
@@ -1717,54 +1398,9 @@ export function startCommand(getConfig: () => Config): Command {
'Canonical external origin clients dial (sets server.externalUrl for this run) — its host joins the Host/Origin allowlists (CORS + external-Host admission). External exposure additionally requires consent (OK_ALLOW_EXTERNAL=1 or server.allowExternal).',
parseExternalUrlFlag,
)
- .option(
- '--public-url <url>',
- 'Deprecated alias of --external-url (the former name of that flag) — same value and semantics.',
- parsePublicUrlFlag,
- )
- .option(
- '--remote [url]',
- 'Deprecated alias: expands to --external-url <url> + OK_ALLOW_EXTERNAL consent on a loopback bind. Serves through a tunnel with NO server-side auth (anyone who can reach the URL has full control — restrict access at the tunnel with edge auth). Bare --remote uses remote.url from .ok/config.yml; --remote <url> supplies it for this run.',
- )
.action(async (opts: StartCommandOptions) => {
const config = getConfig();
- // `--external-url` and its deprecated `--public-url` spelling are the
- // same flag under two names — combining them would make one silently
- // win. Fail loud; pass one.
- if (opts.externalUrl !== undefined && opts.publicUrl !== undefined) {
- process.stderr.write(
- "error: option '--public-url' cannot be combined with '--external-url' (--public-url is a deprecated alias of --external-url)\n",
- );
- process.exit(2);
- }
-
- // `--remote` IS an `--external-url` (plus consent) — combining them
- // would make one silently win. Fail loud; pass one.
- if (
- (opts.externalUrl !== undefined || opts.publicUrl !== undefined) &&
- opts.remote !== undefined &&
- opts.remote !== false
- ) {
- const conflicting = opts.externalUrl !== undefined ? '--external-url' : '--public-url';
- process.stderr.write(
- `error: option '--remote' cannot be combined with '${conflicting}' (--remote is a deprecated alias that sets server.externalUrl)\n`,
- );
- process.exit(2);
- }
-
- // Ephemeral single-file mode has no project and no consented root — the
- // legacy remote flow refused to arm there (while still printing an
- // "enabled" banner). Now that --remote expands into real exposure
- // consent, refuse the combination loudly instead of exposing a
- // throwaway root.
- if (opts.singleFile !== undefined && opts.remote !== undefined && opts.remote !== false) {
- process.stderr.write(
- "error: option '--single-file' cannot be combined with '--remote' — ephemeral single-file mode has no project and no consented root to serve remotely\n",
- );
- process.exit(2);
- }
-
// `--only server` promises "no UI module" — an explicit shell dir
// contradicts it. Fail loud rather than pick a winner silently.
if (opts.only === 'server' && opts.reactShellDistDir !== undefined) {
@@ -1775,35 +1411,18 @@ export function startCommand(getConfig: () => Config): Command {
}
// `--mode=app` shortcuts the server boot and hands off to the
- // desktop app. Mutually exclusive with --open (which opens a
- // browser tab against the local server, which app mode does not
- // boot).
+ // desktop app.
if (opts.mode === 'app') {
- if (opts.open) {
- // Don't throw InvalidArgumentError from an async action — Commander
- // catches it on synchronous validators (parser fns) but a thrown
- // error inside the action surfaces as an unhandled rejection with
- // a stack trace. Exit cleanly via process.exit(2) instead, matching
- // Commander's own conventional exit code for argument errors.
- process.stderr.write(
- "error: option '--mode=app' cannot be combined with '--open' (--open opens a browser tab against the local server, which app mode does not boot)\n",
- );
- process.exit(2);
- }
-
// Non-mode start flags are silently ignored under --mode=app,
// with a debug-level diagnostic so a confused user / CI script
// can grep for it without crashing.
const ignored: string[] = [];
if (opts.port !== undefined) ignored.push('--port');
if (opts.bind !== undefined) ignored.push('--bind');
- if (opts.host !== undefined) ignored.push('--host');
if (opts.only !== undefined) ignored.push('--only');
if (opts.idleShutdown !== undefined) ignored.push('--idle-shutdown');
if (opts.openBrowser === false) ignored.push('--no-open-browser');
if (opts.externalUrl !== undefined) ignored.push('--external-url');
- if (opts.publicUrl !== undefined) ignored.push('--public-url');
- if (opts.remote !== undefined && opts.remote !== false) ignored.push('--remote');
if (ignored.length > 0) {
// Debug-level surface; reuse the existing program log-level
// gate (--log-level=debug). Inline check to avoid a logger dep.
diff --git a/packages/cli/src/config/loader.test.ts b/packages/cli/src/config/loader.test.ts
index 8ad3e430e..50e2f238f 100644
--- a/packages/cli/src/config/loader.test.ts
+++ b/packages/cli/src/config/loader.test.ts
@@ -159,7 +159,7 @@ describe('loadConfig', () => {
}
// Each redirect names the replacement knob.
const joined = removed.map((r) => r.redirect).join('\n');
- expect(joined).toContain('--host');
+ expect(joined).toContain('--bind');
expect(joined).toContain('HOST');
expect(joined).toContain('OPEN_KNOWLEDGE_GITHUB_CLIENT_ID');
expect(joined).toContain('OK_MCP_AUTOSTART');
diff --git a/packages/cli/src/utils/open-browser.ts b/packages/cli/src/utils/open-browser.ts
index cefb32581..85fc3fd2c 100644
--- a/packages/cli/src/utils/open-browser.ts
+++ b/packages/cli/src/utils/open-browser.ts
@@ -1,5 +1,6 @@
/**
- * Cross-platform browser launcher used by `open-knowledge start --open`.
+ * Cross-platform browser launcher used by `open-knowledge start` to open the
+ * editor after boot.
*
* Picks the platform-native launcher (`open` on macOS, `xdg-open` on Linux,
* `cmd /c start` on Windows) and shells out via `execFile`. Failure is
@@ -9,7 +10,7 @@
* **URL validation is mandatory** before passing the value to any launcher.
* On Windows the launcher path goes through `cmd.exe`, which interprets
* `&`, `|`, `<`, `>`, `^`, `(`, `)`, and quote characters as control
- * tokens — a host or port string smuggled in via `--host`, `HOST`, or
+ * tokens — a host or port string smuggled in via `--bind`, `HOST`, or
* `.ok/config.yml` could otherwise be parsed as additional commands. The
* URL parser alone does not reject these (e.g. `http://localhost&calc:3000`
* parses cleanly with host `localhost&calc`), so we apply an explicit
diff --git a/packages/core/src/bridge/bind-frontmatter-doc.ts b/packages/core/src/bridge/bind-frontmatter-doc.ts
index d7a845280..dfd95ef49 100644
--- a/packages/core/src/bridge/bind-frontmatter-doc.ts
+++ b/packages/core/src/bridge/bind-frontmatter-doc.ts
@@ -1,3 +1,4 @@
+
import type * as Y from 'yjs';
import type { Err, Ok, Result } from '../config/result.ts';
import { type FrontmatterValidationError, toFrontmatterIssue } from '../frontmatter/errors.ts';
diff --git a/packages/core/src/bridge/bridge-invariant.ts b/packages/core/src/bridge/bridge-invariant.ts
index 005627195..8bfdb40cd 100644
--- a/packages/core/src/bridge/bridge-invariant.ts
+++ b/packages/core/src/bridge/bridge-invariant.ts
@@ -1,3 +1,4 @@
+
import { fnv1aDigest } from './hash-util.ts';
export type BridgeInvariantSite = 'observer-b' | 'persistence' | 'test-harness';
diff --git a/packages/core/src/bridge/compose.ts b/packages/core/src/bridge/compose.ts
index f4cc8a286..2a597ec3d 100644
--- a/packages/core/src/bridge/compose.ts
+++ b/packages/core/src/bridge/compose.ts
@@ -1,3 +1,4 @@
+
import { prependFrontmatter, stripFrontmatter } from '../extensions/frontmatter.ts';
export type ComposeAdjustment = 'none' | 'body' | 'frontmatter' | 'unresolved';
diff --git a/packages/core/src/bridge/divergence-locate.ts b/packages/core/src/bridge/divergence-locate.ts
index 6b505314d..d979f4b39 100644
--- a/packages/core/src/bridge/divergence-locate.ts
+++ b/packages/core/src/bridge/divergence-locate.ts
@@ -1,3 +1,4 @@
+
import { findFirstDivergenceIndex } from './tolerance-telemetry.ts';
export const BRIDGE_LINE_KINDS = [
diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.ts
index 8fb428b90..01ef76a9f 100644
--- a/packages/core/src/bridge/doc-boundary-space.ts
+++ b/packages/core/src/bridge/doc-boundary-space.ts
@@ -1,3 +1,4 @@
+
import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';
import { carriedEdgeEmpties, type DocEdgeEmpties } from '../markdown/doc-edge-blank-runs.ts';
diff --git a/packages/core/src/bridge/growth-detect.ts b/packages/core/src/bridge/growth-detect.ts
index 9d9c244b0..463e89595 100644
--- a/packages/core/src/bridge/growth-detect.ts
+++ b/packages/core/src/bridge/growth-detect.ts
@@ -1,3 +1,4 @@
+
const DEFAULT_MIN_SUBSTANTIVE_LINE_LENGTH = 16;
export const DUPLICATION_GATE_MIN_LINE_LENGTH = 8;
diff --git a/packages/core/src/bridge/intraline-predicate.ts b/packages/core/src/bridge/intraline-predicate.ts
index c43fdd7e7..0939885bb 100644
--- a/packages/core/src/bridge/intraline-predicate.ts
+++ b/packages/core/src/bridge/intraline-predicate.ts
@@ -1,3 +1,4 @@
+
export function rawLineCounts(doc: string): Map<string, number> {
const counts = new Map<string, number>();
for (const line of doc.split('\n')) {
diff --git a/packages/core/src/bridge/merge-three-way.ts b/packages/core/src/bridge/merge-three-way.ts
index 251560a35..c0dc65705 100644
--- a/packages/core/src/bridge/merge-three-way.ts
+++ b/packages/core/src/bridge/merge-three-way.ts
@@ -65,6 +65,7 @@ export function tryLineLevelCombine(
return { clean: true, merged };
}
+
export type BridgeMergeContentLossSide = 'user' | 'agent';
export type BridgeMergeContentLossWhich = 'substring' | 'order' | 'growth';
diff --git a/packages/core/src/bridge/normalize.ts b/packages/core/src/bridge/normalize.ts
index 01ac80099..dcc5b0690 100644
--- a/packages/core/src/bridge/normalize.ts
+++ b/packages/core/src/bridge/normalize.ts
@@ -1,3 +1,4 @@
+
import { stripFrontmatter } from '../extensions/frontmatter.ts';
import { bodyEdgeEmpties } from './doc-boundary-space.ts';
diff --git a/packages/core/src/bridge/pm-structural-equivalence.ts b/packages/core/src/bridge/pm-structural-equivalence.ts
index 754dc5cc2..0be5203e4 100644
--- a/packages/core/src/bridge/pm-structural-equivalence.ts
+++ b/packages/core/src/bridge/pm-structural-equivalence.ts
@@ -32,6 +32,7 @@ const BR_SENTINEL: PmStructuralNode = { type: '__br__' };
const BR_LITERAL_RE = /^<br\s*\/?>$/i;
+
interface DegradeEntry {
readonly label: string;
readonly severity: ToleranceClassSeverity;
@@ -127,6 +128,7 @@ export interface ComparePmStructuralOptions {
ignoreAttrs?: (attrKey: string) => boolean;
}
+
/** Rebuild a node with `fn` applied to each child; identity when childless.
* Shared by the degrade canonicalizers so none re-implements the walk. */
function mapChildren(
@@ -248,6 +250,7 @@ function applyDegrades(tree: PmStructuralNode): {
return { normalized: current, fired };
}
+
export function comparePmStructural(
expected: PmStructuralNode,
actual: PmStructuralNode,
diff --git a/packages/core/src/bridge/subsequence.ts b/packages/core/src/bridge/subsequence.ts
index af20de1e2..dca644141 100644
--- a/packages/core/src/bridge/subsequence.ts
+++ b/packages/core/src/bridge/subsequence.ts
@@ -1,3 +1,4 @@
+
/** True when `needle` is a subsequence of `haystack` (two-pointer, O(n+m)):
* insertions in `haystack` are free; any dropped or substituted `needle` byte
* fails. */
diff --git a/packages/core/src/config/env-layer.test.ts b/packages/core/src/config/env-layer.test.ts
index 64f02e330..16e0a20f9 100644
--- a/packages/core/src/config/env-layer.test.ts
+++ b/packages/core/src/config/env-layer.test.ts
@@ -1,6 +1,5 @@
import { describe, expect, it } from 'vitest';
import {
- DEPRECATED_ENV_ALIASES,
EnvVarError,
listConfigLeafPaths,
mechanicalEnvName,
@@ -48,17 +47,6 @@ describe('recognized surface pin', () => {
]),
);
});
-
- // Same name-lock reasoning for the deprecated set: entries leave only when
- // their removal window closes, and each must target the SUCCESSOR path so
- // the env layer keeps its precedence over the file layers.
- it('deprecated aliases are exactly OK_PUBLIC_URL → server.externalUrl', () => {
- expect(new Map(DEPRECATED_ENV_ALIASES)).toEqual(
- new Map([
- ['OK_PUBLIC_URL', { successor: 'OK_EXTERNAL_URL', path: ['server', 'externalUrl'] }],
- ]),
- );
- });
});
describe('resolveEnvConfigLayer', () => {
@@ -143,64 +131,6 @@ describe('resolveEnvConfigLayer', () => {
expect(diagnostics[0]?.message).toContain('OK_BIND');
});
- it('a near-miss of a deprecated alias still hints, steering to the successor', () => {
- // OK_PUBLIC_URL left the recognized set for the deprecated table; its
- // typos are nowhere near OK_EXTERNAL_URL by edit distance, so they must
- // keep matching the old name — silently dropping the hint would regress
- // the pre-rename diagnostic.
- const { diagnostics, overrides } = resolveEnvConfigLayer({
- OK_PUBLI_URL: 'https://kb.example.com',
- });
- expect(overrides).toEqual([]);
- expect(diagnostics).toHaveLength(1);
- expect(diagnostics[0]?.message).toContain('OK_PUBLIC_URL');
- expect(diagnostics[0]?.message).toContain('OK_EXTERNAL_URL');
- expect(diagnostics[0]?.message).toContain('deprecated');
- });
-
- it('deprecated OK_PUBLIC_URL still resolves — to the successor path — and warns', () => {
- const { layer, overrides, diagnostics } = resolveEnvConfigLayer({
- OK_PUBLIC_URL: 'https://kb.example.com',
- });
- // Successor path, NOT ['server', 'publicUrl'] — writing the deprecated
- // config leaf would let a config-file server.externalUrl outrank the env
- // var, breaking env > file precedence for 0.51.x deployments.
- expect(layer).toEqual({ server: { externalUrl: 'https://kb.example.com' } });
- expect(overrides).toEqual([
- {
- path: ['server', 'externalUrl'],
- envVar: 'OK_PUBLIC_URL',
- value: 'https://kb.example.com',
- },
- ]);
- expect(diagnostics).toHaveLength(1);
- expect(diagnostics[0]?.message).toContain('deprecated');
- expect(diagnostics[0]?.message).toContain('OK_EXTERNAL_URL');
- });
-
- it('OK_EXTERNAL_URL wins when both spellings are set, with an ignored-var warning', () => {
- const { layer, overrides, diagnostics } = resolveEnvConfigLayer({
- OK_EXTERNAL_URL: 'https://new.example.com',
- OK_PUBLIC_URL: 'https://old.example.com',
- });
- expect(layer).toEqual({ server: { externalUrl: 'https://new.example.com' } });
- expect(overrides).toHaveLength(1);
- expect(diagnostics).toHaveLength(1);
- expect(diagnostics[0]?.envVar).toBe('OK_PUBLIC_URL');
- expect(diagnostics[0]?.message).toContain('ignored');
- });
-
- it('deprecated OK_PUBLIC_URL keeps the fail-loud validation of the recognized set', () => {
- expect(() => resolveEnvConfigLayer({ OK_PUBLIC_URL: 'not a url' })).toThrow(/OK_PUBLIC_URL/);
- expect(() => resolveEnvConfigLayer({ OK_PUBLIC_URL: 'ftp://kb.example.com' })).toThrow(
- EnvVarError,
- );
- // Empty/whitespace reads as unset — and unset never warns.
- const { overrides, diagnostics } = resolveEnvConfigLayer({ OK_PUBLIC_URL: ' ' });
- expect(overrides).toEqual([]);
- expect(diagnostics).toEqual([]);
- });
-
it('stays silent on legitimate operational OK_* vars and non-OK vars', () => {
const { diagnostics, overrides } = resolveEnvConfigLayer({
OK_LOCK_KIND: 'mcp-spawned',
diff --git a/packages/core/src/config/env-layer.ts b/packages/core/src/config/env-layer.ts
index d99a61407..ce79c651a 100644
--- a/packages/core/src/config/env-layer.ts
+++ b/packages/core/src/config/env-layer.ts
@@ -87,19 +87,6 @@ export const RECOGNIZED_ENV_VARS: ReadonlyMap<string, readonly string[]> = new M
['OK_IDLE_SHUTDOWN', ['server', 'idleShutdown']],
]);
-/**
- * Deprecated env spellings kept through their removal window. Each maps to
- * the SUCCESSOR config path — not the deprecated config leaf — so the env
- * layer keeps its precedence over the file layers (an old `OK_PUBLIC_URL`
- * must still beat a config-file `server.externalUrl`, exactly as it beat
- * `server.publicUrl` before the rename). The successor env var wins when both
- * are set. Every use emits a deprecation diagnostic naming the new spelling.
- */
-export const DEPRECATED_ENV_ALIASES: ReadonlyMap<
- string,
- { successor: string; path: readonly string[] }
-> = new Map([['OK_PUBLIC_URL', { successor: 'OK_EXTERNAL_URL', path: ['server', 'externalUrl'] }]]);
-
function camelToScreamingSnake(segment: string): string {
return segment.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase();
}
@@ -218,16 +205,10 @@ function diagnoseUnknownOkVar(
message: `${envVar} maps to config key ${mapped.join('.')}, which is not env-configurable — set it in the config file instead.`,
};
}
- // Deprecated aliases stay in the near-miss pool: a typo of OK_PUBLIC_URL is
- // nowhere near OK_EXTERNAL_URL by edit distance, so dropping the old names
- // here would turn a once-hinted typo into silence. The hint steers the user
- // to the successor spelling rather than the deprecated one it matched.
- for (const known of [...RECOGNIZED_ENV_VARS.keys(), ...DEPRECATED_ENV_ALIASES.keys()]) {
+ // Did-you-mean for a near-miss typo of a recognized env var.
+ for (const known of RECOGNIZED_ENV_VARS.keys()) {
if (known !== 'PORT' && levenshtein(envVar, known) <= 2) {
- const alias = DEPRECATED_ENV_ALIASES.get(known);
- const hint =
- alias === undefined ? known : `${known} (deprecated — use ${alias.successor} instead)`;
- return { envVar, message: `Unknown variable ${envVar} — did you mean ${hint}?` };
+ return { envVar, message: `Unknown variable ${envVar} — did you mean ${known}?` };
}
}
return null;
@@ -288,40 +269,8 @@ export function resolveEnvConfigLayer(env: Record<string, string | undefined>):
overrides.push({ path, envVar, value: checked.data });
}
- // Deprecated spellings: parsed with the same fail-loud validation as the
- // recognized set, but only while the successor is unset — the successor
- // always wins, and every use (honored or shadowed) warns with the rename.
- for (const [envVar, { successor, path }] of DEPRECATED_ENV_ALIASES) {
- const raw = env[envVar];
- if (raw === undefined || raw.trim() === '') continue;
- const successorRaw = env[successor];
- if (successorRaw !== undefined && successorRaw.trim() !== '') {
- diagnostics.push({
- envVar,
- message: `${envVar} is deprecated and ignored because ${successor} is also set — remove ${envVar}.`,
- });
- continue;
- }
- diagnostics.push({
- envVar,
- message: `${envVar} is deprecated — use ${successor} instead.`,
- });
- const leaf = resolveLeafSchema(ConfigSchema, path);
- if (leaf === undefined) {
- throw new EnvVarError(envVar, `internal: config path ${path.join('.')} does not resolve`);
- }
- const parsed = parseByLeafType(envVar, raw.trim(), leaf);
- const checked = leaf.safeParse(parsed);
- if (!checked.success) {
- const detail = checked.error.issues.map((i) => i.message).join('; ') || 'invalid value';
- throw new EnvVarError(envVar, `${detail} (got ${JSON.stringify(raw)})`);
- }
- overrides.push({ path, envVar, value: checked.data });
- }
-
for (const envVar of Object.keys(env)) {
if (!envVar.startsWith('OK_') || RECOGNIZED_ENV_VARS.has(envVar)) continue;
- if (DEPRECATED_ENV_ALIASES.has(envVar)) continue;
if (env[envVar] === undefined) continue;
const diagnostic = diagnoseUnknownOkVar(envVar, mechanicalTable);
if (diagnostic !== null) diagnostics.push(diagnostic);
diff --git a/packages/core/src/config/field-registry.test.ts b/packages/core/src/config/field-registry.test.ts
index 87f0c1b22..58cabc678 100644
--- a/packages/core/src/config/field-registry.test.ts
+++ b/packages/core/src/config/field-registry.test.ts
@@ -245,11 +245,6 @@ describe('ConfigSchema coverage (NR3 — every leaf has fieldRegistry metadata)'
.filter((l) => getFieldMeta(l.schema)?.scope === 'project')
.map((l) => l.path.join('.'))
.sort();
- // `remote.*` is the project's remote-access posture — the tunnel URL the
- // Host allowlist admits (armed only by `ok start --remote`) and the stable
- // port the tunnel targets. Project scope (committed) and never
- // agent-settable: an agent setting these would be widening its own
- // network exposure.
expect(projectStrict).toEqual([
'autoSync.default',
'bridge.backgroundThrottle.enabled',
@@ -268,15 +263,13 @@ describe('ConfigSchema coverage (NR3 — every leaf has fieldRegistry metadata)'
'contentRules.okf.rules',
'lossCapture.enabled',
'lossCapture.maxBytes',
- 'remote.port',
- 'remote.url',
// `server.{port,externalUrl}` are the committed, reviewed shape of this
- // knowledge base's server — project scope, like the `remote.*` keys they
- // supersede. `server.bind` and the rest of the listener's consent/workflow
- // siblings are project-local (below).
+ // knowledge base's server — project scope. `server.bind` and the rest of
+ // the listener's consent/workflow siblings are project-local (below).
+ // Both are never agent-settable: an agent setting these would be widening
+ // its own network exposure.
'server.externalUrl',
'server.port',
- 'server.publicUrl',
'telemetry.localSink.attributeDenylist',
'telemetry.localSink.enabled',
'telemetry.localSink.logs.maxBytes',
@@ -368,11 +361,8 @@ describe('ConfigSchema coverage (NR3 — every leaf has fieldRegistry metadata)'
test("boot-only leaves are exactly content.dir + the listener/exposure keys — everything else is 'live'", () => {
// `content.dir` re-roots the whole index (watcher, Y.Doc registry, link
- // graph); the `server.*` keys and the superseded `remote.*` aliases shape
- // the listener and its exposure — none can change under a running server.
- // `remote.*` are consumed at start via the alias-read in
- // `resolveServerRuntimeConfig`, so they carry the same 'boot' class as the
- // `server.*` successors they map onto. `server.idleShutdown` is the one
+ // graph); the `server.*` keys shape the listener and its exposure — none
+ // can change under a running server. `server.idleShutdown` is the one
// listener leaf that CAN re-arm live.
const leaves: { path: string[]; schema: unknown }[] = [];
walkLeaves(ConfigSchema, [], leaves);
@@ -382,14 +372,11 @@ describe('ConfigSchema coverage (NR3 — every leaf has fieldRegistry metadata)'
.sort();
expect(bootOnly).toEqual([
'content.dir',
- 'remote.port',
- 'remote.url',
'server.allowExternal',
'server.bind',
'server.externalUrl',
'server.openBrowser',
'server.port',
- 'server.publicUrl',
]);
});
});
diff --git a/packages/core/src/config/removed-keys.ts b/packages/core/src/config/removed-keys.ts
index 61604e1a0..488047632 100644
--- a/packages/core/src/config/removed-keys.ts
+++ b/packages/core/src/config/removed-keys.ts
@@ -104,10 +104,39 @@ export const REMOVED_KEYS: readonly RemovedKey[] = [
path: ['server', 'host'],
// Rewritten when `server.bind` returned as a live config key — the old
// "use --host / HOST" text pointed away from the file at the exact moment
- // a file key existed again.
+ // a file key existed again. The `--host` CLI flag no longer exists; the
+ // HOST environment variable is still honored.
redirect: [
'Use server.bind in .ok/config.yml instead — a list of bind addresses, e.g. [127.0.0.1]; a non-loopback bind additionally requires server.allowExternal.',
- 'The --host CLI flag and HOST environment variable also remain available.',
+ 'The --bind CLI flag and HOST environment variable also remain available.',
+ MIGRATE_HINT,
+ ].join(' '),
+ },
+ {
+ // `remote.url` was the former way to declare the public tunnel origin,
+ // superseded by `server.externalUrl`; it was alias-read while the
+ // successor was absent through a deprecation window, now closed.
+ path: ['remote', 'url'],
+ redirect: [
+ 'remote.url has been removed. Use server.externalUrl in .ok/config.yml instead (the public origin your tunnel serves).',
+ MIGRATE_HINT,
+ ].join(' '),
+ },
+ {
+ // `remote.port` was the former fixed listen port for a tunneled
+ // deployment, superseded by `server.port`.
+ path: ['remote', 'port'],
+ redirect: [
+ 'remote.port has been removed. Use server.port in .ok/config.yml instead.',
+ MIGRATE_HINT,
+ ].join(' '),
+ },
+ {
+ // `server.publicUrl` was the former name of `server.externalUrl`, kept as
+ // a deprecated alias through a deprecation window, now closed.
+ path: ['server', 'publicUrl'],
+ redirect: [
+ 'server.publicUrl has been removed. Use server.externalUrl in .ok/config.yml instead (the same key under its current name).',
MIGRATE_HINT,
].join(' '),
},
diff --git a/packages/core/src/config/resolve-server-config.test.ts b/packages/core/src/config/resolve-server-config.test.ts
index 235535c2c..352a2f109 100644
--- a/packages/core/src/config/resolve-server-config.test.ts
+++ b/packages/core/src/config/resolve-server-config.test.ts
@@ -94,81 +94,17 @@ describe('resolveServerRuntimeConfig — defaults', () => {
});
});
-describe('resolveServerRuntimeConfig — remote.* alias-reads', () => {
- test('remote.port fills server.port only while it is absent', () => {
- expect(resolveServerRuntimeConfig(parse({ remote: { port: 24550 } })).port).toBe(24550);
- expect(
- resolveServerRuntimeConfig(parse({ server: { port: 8080 }, remote: { port: 24550 } })).port,
- ).toBe(8080);
- });
-
- test('remote.url fills server.externalUrl only while it is absent', () => {
- const legacyOnly = resolveServerRuntimeConfig(
- parse({ remote: { url: 'https://kb.example.com' } }),
- );
- expect(legacyOnly.externalUrl).toBe('https://kb.example.com');
-
- const both = resolveServerRuntimeConfig(
- parse({
- server: { externalUrl: 'https://new.example.com' },
- remote: { url: 'https://old.example.com' },
- }),
- );
- expect(both.externalUrl).toBe('https://new.example.com');
- });
-
- test('an empty-string remote.url reads as unset', () => {
- const resolved = resolveServerRuntimeConfig(parse({ remote: { url: '' } }));
- expect(resolved.externalUrl).toBeUndefined();
- expect(requiresExternalConsent(resolved)).toBe(false);
- });
-});
-
-describe('resolveServerRuntimeConfig — deprecated server.publicUrl spelling', () => {
- test('server.publicUrl fills externalUrl with full successor semantics (source stays server)', () => {
- // The old spelling is the SAME key, not the remote.* legacy flow: consumers
- // keying exposure decisions off `externalUrlSource === 'server'` (interlock,
- // issued URLs, Host/Origin admission) must see a 0.51.x config behave
- // exactly as it did before the rename.
+describe('resolveServerRuntimeConfig — externalUrl', () => {
+ test('server.externalUrl sets externalUrl', () => {
const resolved = resolveServerRuntimeConfig(
- parse({ server: { publicUrl: 'https://kb.example.com' } }),
+ parse({ server: { externalUrl: 'https://kb.example.com' } }),
);
expect(resolved.externalUrl).toBe('https://kb.example.com');
- expect(resolved.externalUrlSource).toBe('server');
- expect(resolved.externalUrlFromDeprecatedKey).toBe(true);
});
- test('server.externalUrl wins over the deprecated spelling when both are set', () => {
- const resolved = resolveServerRuntimeConfig(
- parse({
- server: {
- externalUrl: 'https://new.example.com',
- publicUrl: 'https://old.example.com',
- },
- }),
- );
- expect(resolved.externalUrl).toBe('https://new.example.com');
- expect(resolved.externalUrlSource).toBe('server');
- expect(resolved.externalUrlFromDeprecatedKey).toBe(false);
- });
-
- test('the deprecated spelling still wins over the remote.url legacy alias', () => {
- const resolved = resolveServerRuntimeConfig(
- parse({
- server: { publicUrl: 'https://renamed.example.com' },
- remote: { url: 'https://legacy.example.com' },
- }),
- );
- expect(resolved.externalUrl).toBe('https://renamed.example.com');
- expect(resolved.externalUrlSource).toBe('server');
- });
-
- test('externalUrlFromDeprecatedKey is false for unset and for the remote.url alias', () => {
- expect(resolveServerRuntimeConfig(parse({})).externalUrlFromDeprecatedKey).toBe(false);
- const aliased = resolveServerRuntimeConfig(
- parse({ remote: { url: 'https://kb.example.com' } }),
- );
- expect(aliased.externalUrlFromDeprecatedKey).toBe(false);
+ test('an unset externalUrl stays undefined', () => {
+ const resolved = resolveServerRuntimeConfig(parse({}));
+ expect(resolved.externalUrl).toBeUndefined();
});
});
@@ -193,7 +129,6 @@ describe('requiresExternalConsent', () => {
const explicit = resolveServerRuntimeConfig(
parse({ server: { externalUrl: 'https://kb.example.com' } }),
);
- expect(explicit.externalUrlSource).toBe('server');
expect(explicit.loopbackOnly).toBe(true);
expect(requiresExternalConsent(explicit)).toBe(false);
@@ -202,13 +137,6 @@ describe('requiresExternalConsent', () => {
parse({ server: { bind: ['0.0.0.0'], externalUrl: 'https://kb.example.com' } }),
);
expect(requiresExternalConsent(exposedWithUrl)).toBe(true);
-
- // A remote.url alias-read likewise never trips it (loopback bind).
- const aliased = resolveServerRuntimeConfig(
- parse({ remote: { url: 'https://kb.example.com' } }),
- );
- expect(aliased.externalUrlSource).toBe('remote-alias');
- expect(requiresExternalConsent(aliased)).toBe(false);
});
test('consent state itself does not change whether consent is required', () => {
diff --git a/packages/core/src/config/resolve-server-config.ts b/packages/core/src/config/resolve-server-config.ts
index 96438565d..1fcbc3b47 100644
--- a/packages/core/src/config/resolve-server-config.ts
+++ b/packages/core/src/config/resolve-server-config.ts
@@ -1,21 +1,11 @@
/**
* Resolve the effective `server.*` runtime settings from a merged `Config`.
*
- * Two jobs no zod `.default()` can do:
- *
- * 1. **Alias-read of the superseded keys.** `server.publicUrl` (the former
- * name of `server.externalUrl`) is read only while `server.externalUrl`
- * is absent; `remote.url` only while both are absent; `remote.port` only
- * while `server.port` is absent — the same shape as the
- * `autoSync.enabled` → `autoSync.mode` alias. This resolver is the single
- * alias-read point; no other reader should consult `remote.*` or
- * `server.publicUrl` for these values.
- *
- * 2. **Derived defaults.** `openBrowser` and `idleShutdown` default off the
- * resolved bind: a loopback-only server pops the UI and idles out after
- * {@link DEFAULT_LOOPBACK_IDLE_SHUTDOWN}; an exposed or containerized
- * server is headless and stays up. The local/hosted split is emergent
- * from these values — there is deliberately no mode key to branch on.
+ * The one job no zod `.default()` can do: **derived defaults.** `openBrowser`
+ * and `idleShutdown` default off the resolved bind: a loopback-only server pops
+ * the UI and idles out after {@link DEFAULT_LOOPBACK_IDLE_SHUTDOWN}; an exposed
+ * or containerized server is headless and stays up. The local/hosted split is
+ * emergent from these values — there is deliberately no mode key to branch on.
*
* Enforcing the exposure interlock (refusing to boot when
* {@link requiresExternalConsent} is true and `allowExternal` is not) is the
@@ -42,25 +32,6 @@ export interface ServerRuntimeConfig {
* `http://localhost:<port>` for a loopback server.
*/
externalUrl: string | undefined;
- /**
- * Where `externalUrl` came from: the `server.*` section (`'server'` — the
- * canonical `server.externalUrl` key or its deprecated `server.publicUrl`
- * spelling, which are the same key under two names) or the superseded
- * `remote.url` alias (`'remote-alias'`); `undefined` when unset.
- * Load-bearing distinction: a `remote.url` left in config does NOT arm
- * anything by itself (`ok start --remote` is the explicit opt-in), so
- * consumers that treat a declared external origin as an exposure signal —
- * the consent interlock, Host/Origin admission — must key off `'server'`
- * only and leave the alias to the legacy remote flow.
- */
- externalUrlSource: 'server' | 'remote-alias' | undefined;
- /**
- * True when `externalUrl` was read from the deprecated `server.publicUrl`
- * spelling (i.e. `server.externalUrl` itself was absent) — the CLI's signal
- * to print the rename notice. Never true for the `remote.url` alias, which
- * carries its own deprecation flow (`--remote`).
- */
- externalUrlFromDeprecatedKey: boolean;
/** Exposure consent interlock (see `requiresExternalConsent`). */
allowExternal: boolean;
/** Open the UI in a browser at start. Derived when not set explicitly. */
@@ -147,32 +118,18 @@ export function idleShutdownToMs(value: string): number | null {
export function resolveServerRuntimeConfig(config: Config | undefined): ServerRuntimeConfig {
const server = config?.server;
- const remote = config?.remote;
const bind =
server?.bind === undefined || server.bind.length === 0 ? DEFAULT_SERVER_BIND : server.bind;
const loopbackOnly = isLoopbackOnlyBind(bind);
- // Alias-reads: the successor key wins whenever present; an empty-string
- // `remote.url` reads as unset (matching the CLI's `expandRemoteAlias`).
- const port = server?.port ?? remote?.port;
- const legacyUrl = remote?.url === '' ? undefined : remote?.url;
- const externalUrl = server?.externalUrl ?? server?.publicUrl ?? legacyUrl;
- const externalUrlSource =
- server?.externalUrl !== undefined || server?.publicUrl !== undefined
- ? ('server' as const)
- : legacyUrl !== undefined
- ? ('remote-alias' as const)
- : undefined;
- const externalUrlFromDeprecatedKey =
- server?.externalUrl === undefined && server?.publicUrl !== undefined;
+ const port = server?.port;
+ const externalUrl = server?.externalUrl;
return {
port,
bind,
externalUrl,
- externalUrlSource,
- externalUrlFromDeprecatedKey,
allowExternal: server?.allowExternal ?? false,
openBrowser: server?.openBrowser ?? loopbackOnly,
idleShutdown: server?.idleShutdown ?? (loopbackOnly ? DEFAULT_LOOPBACK_IDLE_SHUTDOWN : 'off'),
diff --git a/packages/core/src/config/schema.test.ts b/packages/core/src/config/schema.test.ts
index 76310c8ac..cdcec9b36 100644
--- a/packages/core/src/config/schema.test.ts
+++ b/packages/core/src/config/schema.test.ts
@@ -395,7 +395,7 @@ describe('server.* (canonical listener/exposure surface)', () => {
expect(config.server.bind).toEqual(['127.0.0.1']);
expect(config.server.allowExternal).toBe(false);
// No schema default: unset means dynamic locally / platform PORT env in
- // images, and keeps the remote.port alias-read detectable.
+ // images.
expect(config.server.port).toBeUndefined();
expect(config.server.externalUrl).toBeUndefined();
// Derived defaults resolve in resolveServerRuntimeConfig, not here.
@@ -430,16 +430,6 @@ describe('server.* (canonical listener/exposure surface)', () => {
expect(meta?.defaultScope).toBe('project-local');
});
- test('the deprecated publicUrl spelling still validates with the same URL shape', () => {
- expect(
- ConfigSchema.parse({ server: { publicUrl: 'https://kb.example.com' } }).server.publicUrl,
- ).toBe('https://kb.example.com');
- expect(ConfigSchema.safeParse({ server: { publicUrl: 'not a url' } }).success).toBe(false);
- expect(ConfigSchema.safeParse({ server: { publicUrl: 'ftp://kb.example.com' } }).success).toBe(
- false,
- );
- });
-
test('externalUrl accepts http(s) URLs and rejects other schemes or non-URLs', () => {
expect(
ConfigSchema.parse({ server: { externalUrl: 'https://kb.example.com' } }).server.externalUrl,
@@ -461,9 +451,4 @@ describe('server.* (canonical listener/exposure surface)', () => {
expect(ConfigSchema.safeParse({ server: { idleShutdown: bad } }).success).toBe(false);
}
});
-
- test('remote.port no longer bakes a schema default (alias-read needs absence to be detectable)', () => {
- expect(ConfigSchema.parse({}).remote.port).toBeUndefined();
- expect(ConfigSchema.parse({ remote: { port: 24550 } }).remote.port).toBe(24550);
- });
});
diff --git a/packages/core/src/config/schema.ts b/packages/core/src/config/schema.ts
index 122dcc77c..03b773b12 100644
--- a/packages/core/src/config/schema.ts
+++ b/packages/core/src/config/schema.ts
@@ -102,13 +102,13 @@ export const IDLE_SHUTDOWN_DURATION_RE = /^[1-9]\d*(s|m|h)$/;
const HTTP_URL_SCHEME_RE = /^https?:\/\//;
/**
- * Fallback listen port when remote access is enabled but `remote.port` is
- * unset. Lives in the READER (the CLI's remote-mode port resolution), not as
- * a zod `.default()` — the successor `server.port` is
- * alias-read from `remote.port` only when unset, and a schema-baked default
- * would make "unset" undetectable in a parsed config.
+ * The conventional fixed port for a tunneled/exposed deployment, offered as the
+ * placeholder default in the Network Access settings pane when `server.port` is
+ * unset. Not a zod `.default()` on `server.port` — a schema-baked default would
+ * make "unset" (dynamic free-port selection for a local start) undetectable in a
+ * parsed config.
*/
-export const DEFAULT_REMOTE_PORT = 24550;
+export const DEFAULT_TUNNEL_PORT = 24550;
/** Why an embeddings base URL is rejected: unparseable, or a plaintext scheme. */
export type EmbeddingsBaseUrlProblem = 'invalid-url' | 'insecure-scheme';
@@ -1259,52 +1259,6 @@ export const ConfigSchema = z.looseObject({
.default(true),
})
.default({ enabled: true }),
- // Remote access through any HTTPS tunnel. Config alone never enables it —
- // the `ok start --remote` flag does. Trust-the-tunnel: no server-side auth
- // and no access-level knob; restricting reach is the tunnel's job.
- // `agentSettable: false` everywhere so an agent can't self-expose the box.
- //
- // SUPERSEDED by the `server.*` section below: `remote.url` by
- // `server.externalUrl`, `remote.port` by `server.port`. Each is alias-read
- // only while its successor is absent (`resolveServerRuntimeConfig` — the
- // same shape as the `autoSync.enabled` → `autoSync.mode` alias). The keys
- // stay readable so existing configs keep working; removal (REMOVED_KEYS +
- // `ok config migrate`) comes only after the successors have shipped and
- // soaked. `remote.port` deliberately has no zod `.default()` — see
- // `DEFAULT_REMOTE_PORT`.
- //
- // Reload class `'boot'`, matching their `server.*` successors: both are
- // listener/exposure config consumed at server start (via the alias-read in
- // `resolveServerRuntimeConfig`), so a change takes effect only on restart.
- remote: z
- .looseObject({
- url: z
- .string()
- .register(fieldRegistry, {
- scope: 'project',
- agentSettable: false,
- reload: 'boot',
- defaultScope: 'project',
- description:
- 'Superseded by server.externalUrl — read only while server.externalUrl (and its deprecated server.publicUrl spelling) is absent. Public URL your tunnel gives you, e.g. https://myproject.ngrok.app. Used only with `ok start --remote` (config alone never enables remote access); its host is admitted through the Host-header allowlist. There is no server-side auth, so restrict access at the tunnel (ngrok OAuth, Cloudflare Access, Tailscale ACLs).',
- })
- .optional(),
- port: z
- .number()
- .int()
- .min(1)
- .max(65535)
- .register(fieldRegistry, {
- scope: 'project',
- agentSettable: false,
- reload: 'boot',
- defaultScope: 'project',
- description:
- "Superseded by server.port — read only while server.port is absent. TCP port the server binds when remote access is enabled (default 24550). Fixed so the tunnel's port mapping survives restarts. Set it only on a conflict. An explicit --port still wins; the PORT env var is ignored in remote mode.",
- })
- .optional(),
- })
- .default({}),
// The canonical server surface: one listener whose local vs hosted posture
// is EMERGENT from the values set here — there is deliberately no
// `server.mode` / profile discriminator key. A mode key becomes a branch
@@ -1328,15 +1282,14 @@ export const ConfigSchema = z.looseObject({
// / `idleShutdown` are PROJECT-LOCAL personal workflow, like the sidebar
// toggles.
//
- // `agentSettable: false` on every leaf, same reasoning as `remote.*`: an
- // agent must never widen its own network exposure.
+ // `agentSettable: false` on every leaf: an agent must never widen its own
+ // network exposure.
//
// `openBrowser` and `idleShutdown` have DERIVED defaults (they depend on
// whether the resolved `bind` is loopback-only), so those leaves stay
// optional here — a schema-time `.default()` cannot see `bind`. The
// derivation lives in `resolveServerRuntimeConfig`
- // (`resolve-server-config.ts`), which is also the single alias-read point
- // for the superseded `remote.*` keys.
+ // (`resolve-server-config.ts`).
server: z
.looseObject({
port: z
@@ -1350,7 +1303,7 @@ export const ConfigSchema = z.looseObject({
reload: 'boot',
defaultScope: 'project',
description:
- 'TCP port the server listens on. Unset by default: a local start picks a free port dynamically, and deployment platforms inject the PORT environment variable instead. Supersedes remote.port (still read while this key is absent). Read at server start; changing it requires a restart.',
+ 'TCP port the server listens on. Unset by default: a local start picks a free port dynamically, and deployment platforms inject the PORT environment variable instead. Read at server start; changing it requires a restart.',
})
.optional(),
bind: z
@@ -1377,22 +1330,7 @@ export const ConfigSchema = z.looseObject({
reload: 'boot',
defaultScope: 'project',
description:
- 'Canonical external origin the server is reached at, e.g. https://kb.example.com — its host joins the Host/Origin allowlists (external-Host + CORS admission). Unset by default: the server admits only loopback Hosts. Setting it declares external exposure, which additionally requires the server.allowExternal consent interlock. Supersedes server.publicUrl (its former name) and remote.url — both still read while this key is absent. Read at server start; changing it requires a restart.',
- })
- .optional(),
- // The former name of `server.externalUrl`, shipped in stable 0.51.x —
- // kept as a deprecated alias (alias-read in `resolveServerRuntimeConfig`,
- // same shape as `remote.url`), removed only after a deprecation window.
- publicUrl: z
- .url({ protocol: /^https?$/ })
- .regex(HTTP_URL_SCHEME_RE)
- .register(fieldRegistry, {
- scope: 'project',
- agentSettable: false,
- reload: 'boot',
- defaultScope: 'project',
- description:
- 'Deprecated alias of server.externalUrl (the former name of that key) — read only while server.externalUrl is absent, with identical semantics. Use server.externalUrl instead; if this config is committed and shared, keep both keys until every collaborator has upgraded (older versions read only server.publicUrl).',
+ 'Canonical external origin the server is reached at, e.g. https://kb.example.com — its host joins the Host/Origin allowlists (external-Host + CORS admission). Unset by default: the server admits only loopback Hosts. Setting it declares external exposure, which additionally requires the server.allowExternal consent interlock. Read at server start; changing it requires a restart.',
})
.optional(),
allowExternal: z
diff --git a/packages/core/src/constants/server.ts b/packages/core/src/constants/server.ts
index 428819091..96969dd15 100644
--- a/packages/core/src/constants/server.ts
+++ b/packages/core/src/constants/server.ts
@@ -1,6 +1,6 @@
/**
* Default bind host for `ok start`. Overridable at runtime via the
- * `--host` CLI flag or the `HOST` environment variable; resolved at
+ * `--bind` CLI flag or the `HOST` environment variable; resolved at
* the start command, not via config.
*
* Numeric IPv4 loopback — NOT the `localhost` hostname — on purpose. On
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 66f5c79e6..cacd12616 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -241,10 +241,10 @@ export {
DEFAULT_EMBEDDINGS_BASE_URL,
DEFAULT_EMBEDDINGS_MODEL,
DEFAULT_LOGS_MAX_BYTES,
- DEFAULT_REMOTE_PORT,
DEFAULT_SERVER_BIND,
DEFAULT_SPANS_MAX_BYTES,
DEFAULT_TELEMETRY_ATTRIBUTE_DENYLIST,
+ DEFAULT_TUNNEL_PORT,
IDLE_SHUTDOWN_DURATION_RE,
isLoopbackEmbeddingsUrl,
isValidAttachmentFolderPath,
diff --git a/packages/core/src/markdown/callout-transformer.ts b/packages/core/src/markdown/callout-transformer.ts
index 83d47404a..a363dfd54 100644
--- a/packages/core/src/markdown/callout-transformer.ts
+++ b/packages/core/src/markdown/callout-transformer.ts
@@ -1,3 +1,4 @@
+
import type { Blockquote, Paragraph, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/code-fence.ts b/packages/core/src/markdown/code-fence.ts
index 9807a7e82..4499dbc92 100644
--- a/packages/core/src/markdown/code-fence.ts
+++ b/packages/core/src/markdown/code-fence.ts
@@ -1,3 +1,4 @@
+
export function selectFenceChar(info: string): '`' | '~' {
return info.includes('`') ? '~' : '`';
}
diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.ts
index 7415c474a..34704165b 100644
--- a/packages/core/src/markdown/comment-promoter.ts
+++ b/packages/core/src/markdown/comment-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/dedent-block-jsx-close.ts b/packages/core/src/markdown/dedent-block-jsx-close.ts
index ece5c02a1..b6299a948 100644
--- a/packages/core/src/markdown/dedent-block-jsx-close.ts
+++ b/packages/core/src/markdown/dedent-block-jsx-close.ts
@@ -1,3 +1,4 @@
+
import { findFencedRegions, isInsideFence } from './fence-regions.ts';
const INDENTED_BLOCK_JSX_CLOSE_RE = /^([ ]{1,3})(<\/[A-Z][A-Za-z0-9_]*\s*>)([ \t]*)$/gm;
diff --git a/packages/core/src/markdown/details-accordion-promoter.ts b/packages/core/src/markdown/details-accordion-promoter.ts
index 54774764a..acd398aa6 100644
--- a/packages/core/src/markdown/details-accordion-promoter.ts
+++ b/packages/core/src/markdown/details-accordion-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/div-align-promoter.ts b/packages/core/src/markdown/div-align-promoter.ts
index 43ecdc709..ba9b56384 100644
--- a/packages/core/src/markdown/div-align-promoter.ts
+++ b/packages/core/src/markdown/div-align-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';
import type { MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/fence-regions.ts b/packages/core/src/markdown/fence-regions.ts
index 6d3f3643e..4513da9bb 100644
--- a/packages/core/src/markdown/fence-regions.ts
+++ b/packages/core/src/markdown/fence-regions.ts
@@ -1,3 +1,4 @@
+
const FENCE_RE = /^(`{3,}|~{3,})/gm;
export function findFencedRegions(src: string): Array<[number, number]> {
diff --git a/packages/core/src/markdown/fixtures/index.ts b/packages/core/src/markdown/fixtures/index.ts
index 00f5771ee..6931623c7 100644
--- a/packages/core/src/markdown/fixtures/index.ts
+++ b/packages/core/src/markdown/fixtures/index.ts
@@ -1,3 +1,4 @@
+
import { readFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -8,6 +9,7 @@ function fixturePath(...segments: string[]): string {
return resolve(FIXTURES_DIR, ...segments);
}
+
interface GfmExample {
section: string;
markdown: string;
@@ -17,6 +19,7 @@ export function loadGfmExamples(): GfmExample[] {
return JSON.parse(readFileSync(fixturePath('gfm', 'examples.json'), 'utf8')) as GfmExample[];
}
+
interface MdxCrashEntry {
id: string;
input: string;
@@ -68,6 +71,7 @@ export function loadLargeEmbedFixtures(): LargeEmbedFixture[] {
) as LargeEmbedFixture[];
}
+
export function loadPrd6955Before(): string {
return readFileSync(fixturePath('regression', 'prd-6955-before.md'), 'utf8');
}
@@ -76,6 +80,7 @@ export function loadPrd6955CorruptedTriplicated(): string {
return readFileSync(fixturePath('regression', 'prd-6955-corrupted-triplicated.md'), 'utf8');
}
+
export interface NgPinnedCase {
id: string;
name: string;
@@ -92,6 +97,7 @@ export function loadNgPinnedCases(): NgPinnedCase[] {
) as NgPinnedCase[];
}
+
export function loadLargeRealistic(): string {
return readFileSync(fixturePath('perf', 'large-realistic.md'), 'utf8');
}
diff --git a/packages/core/src/markdown/fixtures/perf/generate.ts b/packages/core/src/markdown/fixtures/perf/generate.ts
index 8b1eb8519..daa3ef82b 100644
--- a/packages/core/src/markdown/fixtures/perf/generate.ts
+++ b/packages/core/src/markdown/fixtures/perf/generate.ts
@@ -1,3 +1,4 @@
+
import { writeFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -10,6 +11,7 @@ const BASELINE_ONLY_COUNTS = [500, 2500] as const;
const SEED = 0xf1de1117;
+
function mulberry32(seed: number): () => number {
let a = seed >>> 0;
return () => {
@@ -36,6 +38,7 @@ function pickWeighted<T>(rand: () => number, items: readonly [T, number][]): T {
return items[items.length - 1][0];
}
+
const WORDS = [
'lorem',
'ipsum',
@@ -153,6 +156,7 @@ function mdxBlock(rand: () => number): string {
return `<${name}>\n\n${sentence(rand)}\n\n</${name}>`;
}
+
type BlockKind = 'paragraph' | 'heading' | 'list' | 'code' | 'table' | 'mdx';
const MIX: readonly [BlockKind, number][] = [
@@ -191,6 +195,7 @@ function generateDocument(blockCount: number, seed: number): string {
return `${blocks.join('\n\n')}\n`;
}
+
function main(): void {
for (const count of [...BLOCK_COUNTS, ...BASELINE_ONLY_COUNTS]) {
const doc = generateDocument(count, SEED);
diff --git a/packages/core/src/markdown/guard-flanking-matrix.ts b/packages/core/src/markdown/guard-flanking-matrix.ts
index 420dc0fe5..32c055c5b 100644
--- a/packages/core/src/markdown/guard-flanking-matrix.ts
+++ b/packages/core/src/markdown/guard-flanking-matrix.ts
@@ -7,6 +7,7 @@ import {
import { BACKSLASH_GUARD_SUBSTITUTIONS, encodeBackslashEscapes } from './backslash-escape-guard.ts';
import { ENTITY_REF_GUARD_SUBSTITUTIONS, encodeEntityRefs } from './entity-ref-guard.ts';
+
export const ATTENTION_DELIMITERS = ['*', '_', '**', '~~', '=='] as const;
export type FlankClass = 'whitespace' | 'punctuation' | 'other';
diff --git a/packages/core/src/markdown/handler-shadow-audit.ts b/packages/core/src/markdown/handler-shadow-audit.ts
index 2653473da..283913255 100644
--- a/packages/core/src/markdown/handler-shadow-audit.ts
+++ b/packages/core/src/markdown/handler-shadow-audit.ts
@@ -1,3 +1,4 @@
+
export interface HandlerShadowWitness {
input: string;
expect: 'byte' | 'byte-and-reparse-type';
diff --git a/packages/core/src/markdown/highlight-promoter.ts b/packages/core/src/markdown/highlight-promoter.ts
index da0a81d23..5d1000cc4 100644
--- a/packages/core/src/markdown/highlight-promoter.ts
+++ b/packages/core/src/markdown/highlight-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, PhrasingContent, Root, Text } from 'mdast';
import type { MdxJsxTextElement } from 'mdast-util-mdx';
import { SKIP, visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/html-to-mdast.ts b/packages/core/src/markdown/html-to-mdast.ts
index 787315157..9681c0056 100644
--- a/packages/core/src/markdown/html-to-mdast.ts
+++ b/packages/core/src/markdown/html-to-mdast.ts
@@ -1,3 +1,4 @@
+
import type { Element as HastElement, Root as HastRoot } from 'hast';
import type { List, Nodes as MdastNodes, Root as MdastRoot } from 'mdast';
import rehypeParse from 'rehype-parse';
@@ -128,7 +129,8 @@ export function htmlToMdast(html: string, options?: HtmlToMdastOptions): MdastRo
throw new HtmlPayloadTooLargeError(html.length, maxBytes);
}
- const processor = unified().use(rehypeParse, { fragment: true });
+ const processor = unified()
+ .use(rehypeParse, { fragment: true });
for (const plugin of cleanupPlugins) {
processor.use(plugin);
diff --git a/packages/core/src/markdown/image-promoter.ts b/packages/core/src/markdown/image-promoter.ts
index 706fa9afb..994eb6917 100644
--- a/packages/core/src/markdown/image-promoter.ts
+++ b/packages/core/src/markdown/image-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Image, Paragraph, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/index.ts b/packages/core/src/markdown/index.ts
index 779e27500..ec1ac1b7e 100644
--- a/packages/core/src/markdown/index.ts
+++ b/packages/core/src/markdown/index.ts
@@ -1,3 +1,4 @@
+
import {
type FromProseMirrorOptions,
fromPmMark,
@@ -206,6 +207,7 @@ export class MarkdownManager {
}
}
+
const registry = createRegistry();
function destructureAttrs(
@@ -254,6 +256,7 @@ function destructureAttrs(
return result;
}
+
function hasDirtyDescendant(node: PmNode): boolean {
let found = false;
node.descendants((child) => {
@@ -276,6 +279,7 @@ function effectiveDirty(node: PmNode, freshnessChecker?: StructuralFreshnessChec
return freshnessChecker ? freshnessChecker.isDiverged(node.toJSON()) : false;
}
+
function isEmptyMdastParagraph(node: MdastNodes): boolean {
if (node.type !== 'paragraph') return false;
const children = node.children ?? [];
@@ -344,6 +348,7 @@ function extractTextFromMdastNodes(nodes: MdastNodes[]): string {
return out;
}
+
import {
AUDIO_EXTENSIONS,
FILE_ATTACHMENT_EXTENSIONS,
@@ -596,6 +601,7 @@ function buildMdastToPmHandlers(
}));
}
+
if (m.emphasis) {
handlers.emphasis = toPmMark(m.emphasis, (node: Emphasis) => ({
sourceDelimiter: node.data?.sourceDelimiter ?? '*',
@@ -676,6 +682,7 @@ function buildMdastToPmHandlers(
}));
}
+
if (m.link) {
const sourceLiteralMark = m.sourceLiteral;
handlers.link = (node: Link, _parent: MdastParent, state: MdastToPmState) => {
@@ -973,6 +980,7 @@ function buildMdastToPmHandlers(
};
}
+
const blockUnknownHandler = (node: {
type: string;
position?: { start: { offset: number }; end: { offset: number } };
@@ -1098,6 +1106,7 @@ function buildMdastToPmHandlers(
return handlers as RemarkProseMirrorOptions['handlers'];
}
+
function buildPmToMdastHandlers(
schema: Schema,
freshness: FreshnessCheckerHolder,
diff --git a/packages/core/src/markdown/lint/applies-to.ts b/packages/core/src/markdown/lint/applies-to.ts
index fa0be9e86..b79e9aef7 100644
--- a/packages/core/src/markdown/lint/applies-to.ts
+++ b/packages/core/src/markdown/lint/applies-to.ts
@@ -1,3 +1,4 @@
+
import picomatch from 'picomatch';
import { SUPPORTED_DOC_EXTENSIONS } from '../../constants/doc-extensions.ts';
diff --git a/packages/core/src/markdown/lint/config-files.ts b/packages/core/src/markdown/lint/config-files.ts
index 312c9c74b..94b34dee1 100644
--- a/packages/core/src/markdown/lint/config-files.ts
+++ b/packages/core/src/markdown/lint/config-files.ts
@@ -1,3 +1,4 @@
+
const MARKDOWNLINT_JSON_CONFIG_FILES: ReadonlySet<string> = new Set([
'.markdownlint.json',
'.markdownlint.jsonc',
diff --git a/packages/core/src/markdown/lint/config-schemas.ts b/packages/core/src/markdown/lint/config-schemas.ts
index 3d4814597..7d97004fb 100644
--- a/packages/core/src/markdown/lint/config-schemas.ts
+++ b/packages/core/src/markdown/lint/config-schemas.ts
@@ -51,6 +51,7 @@ const fullPluginShape = Object.fromEntries(
LINT_PLUGINS.map((plugin) => [plugin.id, plugin.sliceSchema]),
) as z.ZodRawShape;
+
export const LinterConfigSchema = z.object({
enabled: z.boolean(),
plugins: z.object(fullPluginShape),
diff --git a/packages/core/src/markdown/lint/default-config.ts b/packages/core/src/markdown/lint/default-config.ts
index d48eea5e4..a51f2ffb0 100644
--- a/packages/core/src/markdown/lint/default-config.ts
+++ b/packages/core/src/markdown/lint/default-config.ts
@@ -6,6 +6,7 @@ export const DEFAULT_MARKDOWNLINT_CONFIG: Record<string, MarkdownlintRuleSetting
MD013: false,
};
+
export function resolveMarkdownlintConfig(
rules: Record<string, MarkdownlintRuleSetting> | undefined,
): Configuration {
diff --git a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
index ef478e268..9c9542661 100644
--- a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
+++ b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts
@@ -1,3 +1,4 @@
+
import { CANONICAL_SCHEMA_DIALECT_URIS, DEFAULT_SCHEMA_DIALECT } from './frontmatter-validate.ts';
export interface FrontmatterFieldConstraint {
diff --git a/packages/core/src/markdown/lint/frontmatter-validate.ts b/packages/core/src/markdown/lint/frontmatter-validate.ts
index eba37cee7..ca6eed91c 100644
--- a/packages/core/src/markdown/lint/frontmatter-validate.ts
+++ b/packages/core/src/markdown/lint/frontmatter-validate.ts
@@ -1,3 +1,4 @@
+
import Ajv, { type ValidateFunction } from 'ajv';
import Ajv2019 from 'ajv/dist/2019.js';
import Ajv2020 from 'ajv/dist/2020.js';
diff --git a/packages/core/src/markdown/lint/index.ts b/packages/core/src/markdown/lint/index.ts
index ae5ff2924..9c2a0875e 100644
--- a/packages/core/src/markdown/lint/index.ts
+++ b/packages/core/src/markdown/lint/index.ts
@@ -1,3 +1,4 @@
+
import { LINT_PLUGINS, type LinterConfig } from './plugins.ts';
import type { LintDiagnostic } from './types.ts';
diff --git a/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts b/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts
index 7a5af097e..f438f1b16 100644
--- a/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts
+++ b/packages/core/src/markdown/lint/okf-frontmatter/materialize.ts
@@ -1,3 +1,4 @@
+
import type { OkfRuleId } from '../okf-rule-meta.ts';
import { fileNameFor, OKF_SCHEMA_DIR, okfSchemaPathFor } from './paths.ts';
import { OKF_FRONTMATTER_REGISTRY } from './registry.ts';
diff --git a/packages/core/src/markdown/lint/okf-frontmatter/paths.ts b/packages/core/src/markdown/lint/okf-frontmatter/paths.ts
index 1ee913527..c290b6878 100644
--- a/packages/core/src/markdown/lint/okf-frontmatter/paths.ts
+++ b/packages/core/src/markdown/lint/okf-frontmatter/paths.ts
@@ -1,3 +1,4 @@
+
import type { OkfRuleId } from '../okf-rule-meta.ts';
export const OKF_SCHEMA_DIR = '.ok/okf';
diff --git a/packages/core/src/markdown/lint/okf-frontmatter/registry.ts b/packages/core/src/markdown/lint/okf-frontmatter/registry.ts
index de09740c5..5168602d5 100644
--- a/packages/core/src/markdown/lint/okf-frontmatter/registry.ts
+++ b/packages/core/src/markdown/lint/okf-frontmatter/registry.ts
@@ -1,3 +1,4 @@
+
import { compileAppliesTo } from '../applies-to.ts';
import { validateFrontmatterSource } from '../frontmatter-validate.ts';
import { isOkfRuleEnabled, type OkfRuleId, type OkfRuleToggles } from '../okf-rule-meta.ts';
diff --git a/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts b/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts
index f1c37671b..89845d3d5 100644
--- a/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts
+++ b/packages/core/src/markdown/lint/okf-frontmatter/schemas.ts
@@ -1,3 +1,4 @@
+
// file-level form is deliberate: the sibling `biome-ignore` must sit on the line
// oxlint-disable unicorn/no-thenable
diff --git a/packages/core/src/markdown/lint/okf-project/rules.ts b/packages/core/src/markdown/lint/okf-project/rules.ts
index 6d691ae2b..8b476332e 100644
--- a/packages/core/src/markdown/lint/okf-project/rules.ts
+++ b/packages/core/src/markdown/lint/okf-project/rules.ts
@@ -1,3 +1,4 @@
+
import { SUPPORTED_DOC_EXTENSIONS } from '../../../constants/doc-extensions.ts';
import { isOkfRuleEnabled, type OkfRuleId, type OkfRuleToggles } from '../okf-rule-meta.ts';
diff --git a/packages/core/src/markdown/lint/okf-rule-meta.ts b/packages/core/src/markdown/lint/okf-rule-meta.ts
index 4de50d79f..44913a9dc 100644
--- a/packages/core/src/markdown/lint/okf-rule-meta.ts
+++ b/packages/core/src/markdown/lint/okf-rule-meta.ts
@@ -1,3 +1,4 @@
+
export const OKF_RULE_IDS = [
'no-wiki-links',
'log-shape',
diff --git a/packages/core/src/markdown/lint/okf-rules.ts b/packages/core/src/markdown/lint/okf-rules.ts
index 1d5538421..d0999b62e 100644
--- a/packages/core/src/markdown/lint/okf-rules.ts
+++ b/packages/core/src/markdown/lint/okf-rules.ts
@@ -1,3 +1,4 @@
+
import { isOkfRuleEnabled, type OkfRuleId, type OkfRuleToggles } from './okf-rule-meta.ts';
import type { OkfRule } from './okf-runner.ts';
import { indexShape } from './rules/index-shape.ts';
diff --git a/packages/core/src/markdown/lint/okf-runner.ts b/packages/core/src/markdown/lint/okf-runner.ts
index de130e3f4..fabb08d6e 100644
--- a/packages/core/src/markdown/lint/okf-runner.ts
+++ b/packages/core/src/markdown/lint/okf-runner.ts
@@ -1,3 +1,4 @@
+
import type { Root } from 'mdast';
import remarkFrontmatter from 'remark-frontmatter';
import remarkGfm from 'remark-gfm';
diff --git a/packages/core/src/markdown/lint/plugins.ts b/packages/core/src/markdown/lint/plugins.ts
index 4b9df9c56..03efcf66c 100644
--- a/packages/core/src/markdown/lint/plugins.ts
+++ b/packages/core/src/markdown/lint/plugins.ts
@@ -1,3 +1,4 @@
+
import { z } from 'zod';
import { DEFAULT_MARKDOWNLINT_CONFIG, resolveMarkdownlintConfig } from './default-config.ts';
import {
@@ -17,6 +18,7 @@ import {
type OkfSlice,
} from './types.ts';
+
const MarkdownlintRuleSettingSchema = z.union([
z.boolean(),
z.enum(MARKDOWNLINT_RULE_SEVERITIES),
diff --git a/packages/core/src/markdown/lint/rules/index-shape.ts b/packages/core/src/markdown/lint/rules/index-shape.ts
index 59fe9b87d..fcbb1b56c 100644
--- a/packages/core/src/markdown/lint/rules/index-shape.ts
+++ b/packages/core/src/markdown/lint/rules/index-shape.ts
@@ -1,3 +1,4 @@
+
import type { List, ListItem } from 'mdast';
import { EXIT, visit } from 'unist-util-visit';
import { defineScopedOkfRule } from '../okf-runner.ts';
diff --git a/packages/core/src/markdown/lint/rules/log-shape.ts b/packages/core/src/markdown/lint/rules/log-shape.ts
index e0159519f..431e4e9c8 100644
--- a/packages/core/src/markdown/lint/rules/log-shape.ts
+++ b/packages/core/src/markdown/lint/rules/log-shape.ts
@@ -1,3 +1,4 @@
+
import type { Heading } from 'mdast';
import { toString as headingText } from 'mdast-util-to-string';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/lint/rules/no-wiki-links.ts b/packages/core/src/markdown/lint/rules/no-wiki-links.ts
index 2123e977f..f75a04d15 100644
--- a/packages/core/src/markdown/lint/rules/no-wiki-links.ts
+++ b/packages/core/src/markdown/lint/rules/no-wiki-links.ts
@@ -1,3 +1,4 @@
+
import type { Point } from 'unist';
import { visit } from 'unist-util-visit';
import { defineOkfRule } from '../okf-runner.ts';
diff --git a/packages/core/src/markdown/lint/rules/reserved-casing.ts b/packages/core/src/markdown/lint/rules/reserved-casing.ts
index 89ef3e4a9..c8b4d8f28 100644
--- a/packages/core/src/markdown/lint/rules/reserved-casing.ts
+++ b/packages/core/src/markdown/lint/rules/reserved-casing.ts
@@ -1,3 +1,4 @@
+
import { SUPPORTED_DOC_EXTENSIONS } from '../../../constants/doc-extensions.ts';
import { defineOkfRule } from '../okf-runner.ts';
diff --git a/packages/core/src/markdown/lint/types.ts b/packages/core/src/markdown/lint/types.ts
index 2a8f4a279..4fa9a5a27 100644
--- a/packages/core/src/markdown/lint/types.ts
+++ b/packages/core/src/markdown/lint/types.ts
@@ -1,3 +1,4 @@
+
import type { BrokenLinkReason } from '../../schemas/api/agent-write.ts';
import type { OkfRuleId } from './okf-rule-meta.ts';
@@ -105,6 +106,7 @@ export interface OkfSlice {
generate?: { index?: boolean };
}
+
interface RuleOptionSpecBase {
key: string;
description: string;
diff --git a/packages/core/src/markdown/lint/validation-counts.ts b/packages/core/src/markdown/lint/validation-counts.ts
index 98238656e..437cc539a 100644
--- a/packages/core/src/markdown/lint/validation-counts.ts
+++ b/packages/core/src/markdown/lint/validation-counts.ts
@@ -1,3 +1,4 @@
+
export interface ValidationSourceCounts {
errorCount: number;
warningCount: number;
diff --git a/packages/core/src/markdown/math-promoter.ts b/packages/core/src/markdown/math-promoter.ts
index a5b511f25..bd79424c7 100644
--- a/packages/core/src/markdown/math-promoter.ts
+++ b/packages/core/src/markdown/math-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Code, Root } from 'mdast';
import type { Math as MdastMath } from 'mdast-util-math';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
diff --git a/packages/core/src/markdown/mdast-to-hast-handlers.ts b/packages/core/src/markdown/mdast-to-hast-handlers.ts
index ed89371d0..00fbc0035 100644
--- a/packages/core/src/markdown/mdast-to-hast-handlers.ts
+++ b/packages/core/src/markdown/mdast-to-hast-handlers.ts
@@ -1,3 +1,4 @@
+
import type { Comment, Element, ElementContent, Properties } from 'hast';
import type { FootnoteDefinition, FootnoteReference } from 'mdast';
import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';
diff --git a/packages/core/src/markdown/mdast-to-html.ts b/packages/core/src/markdown/mdast-to-html.ts
index 8ce2b2492..df788a80d 100644
--- a/packages/core/src/markdown/mdast-to-html.ts
+++ b/packages/core/src/markdown/mdast-to-html.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root as HastRoot, Text as HastText } from 'hast';
import type { Root as MdastRoot, Text as MdastText } from 'mdast';
import type { Handler } from 'mdast-util-to-hast';
diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.ts
index bfd7e3109..fa3cfcd86 100644
--- a/packages/core/src/markdown/merged-walker.ts
+++ b/packages/core/src/markdown/merged-walker.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, Root } from 'mdast';
import { SKIP, visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/mermaid-promoter.ts b/packages/core/src/markdown/mermaid-promoter.ts
index 1a897fca8..17ed2b829 100644
--- a/packages/core/src/markdown/mermaid-promoter.ts
+++ b/packages/core/src/markdown/mermaid-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Code, Root } from 'mdast';
import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/parse-with-fallback.ts b/packages/core/src/markdown/parse-with-fallback.ts
index d988f4b8b..4aa0490c4 100644
--- a/packages/core/src/markdown/parse-with-fallback.ts
+++ b/packages/core/src/markdown/parse-with-fallback.ts
@@ -168,6 +168,7 @@ export function parseRecursive(
}
}
+
interface VFilePlace {
offset?: number;
start?: { offset?: number };
@@ -186,6 +187,7 @@ function extractErrorOffset(err: unknown): number | undefined {
return undefined;
}
+
interface Region {
start: number;
end: number;
@@ -209,6 +211,7 @@ function nearestBlankLineAfter(src: string, offset: number): number | null {
return null;
}
+
export interface TagEvent {
kind: 'open' | 'close' | 'self-close';
name: string;
@@ -355,6 +358,7 @@ function findFallbackRegion(src: string, errorOffset: number): Region {
return { start: blockStart, end: blockEnd };
}
+
interface SourceBlock {
src: string;
start: number;
@@ -452,6 +456,7 @@ function tryPerBlockFallback(
};
}
+
function wholeDocRawText(source: string): JSONContent {
return {
type: 'doc',
diff --git a/packages/core/src/markdown/parser-drop-closure.ts b/packages/core/src/markdown/parser-drop-closure.ts
index e6ab4fd57..43d420187 100644
--- a/packages/core/src/markdown/parser-drop-closure.ts
+++ b/packages/core/src/markdown/parser-drop-closure.ts
@@ -1,3 +1,4 @@
+
export type DroppedTokenAdjudication =
| {
kind: 'format-dof-axis';
diff --git a/packages/core/src/markdown/pipeline.ts b/packages/core/src/markdown/pipeline.ts
index 0e3224206..55736041c 100644
--- a/packages/core/src/markdown/pipeline.ts
+++ b/packages/core/src/markdown/pipeline.ts
@@ -1,3 +1,4 @@
+
import {
type FromProseMirrorOptions,
fromProseMirror,
diff --git a/packages/core/src/markdown/position-aware-join.ts b/packages/core/src/markdown/position-aware-join.ts
index 91cdf658f..ccf06e94d 100644
--- a/packages/core/src/markdown/position-aware-join.ts
+++ b/packages/core/src/markdown/position-aware-join.ts
@@ -1,3 +1,4 @@
+
import type { Join } from 'mdast-util-to-markdown';
import type { Position } from 'unist';
import { isBlankLineParagraph } from './zero-emission-blocks.ts';
diff --git a/packages/core/src/markdown/position-slice.ts b/packages/core/src/markdown/position-slice.ts
index 0f399d34c..e5b4c9eba 100644
--- a/packages/core/src/markdown/position-slice.ts
+++ b/packages/core/src/markdown/position-slice.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Root } from 'mdast';
import { visit } from 'unist-util-visit';
import type { VFile } from 'vfile';
@@ -476,7 +477,8 @@ export function applyPositionSliceToNode(
const first = source[startOff];
if (first !== '[' && first !== '<' && !node.title) {
node.data.sourceStyle = 'gfm-autolink';
- } else if (first === '[') {
+ }
+ else if (first === '[') {
const slice = source.slice(startOff, endOff);
const closeBracketIdx = slice.lastIndexOf('](');
if (closeBracketIdx !== -1) {
diff --git a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
index db10fa54b..ca225ce9b 100644
--- a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
+++ b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts
@@ -1,3 +1,4 @@
+
import type { Comment, Element, Root, Text } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
index 34068d103..3a2524a9a 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts
@@ -1,3 +1,4 @@
+
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
index 93151d43b..2279a0189 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
index 188f02d83..a0f467c42 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
index 4ba2c3418..4e8542a21 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
index 1a74b1272..a3c96b24a 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts
@@ -1,3 +1,4 @@
+
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
index de35e7b79..e95cf43d6 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts
@@ -1,3 +1,4 @@
+
import type { Comment, Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
index b4be1b2ea..ffdb4d5b5 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts
@@ -1,3 +1,4 @@
+
import type { Element, ElementContent, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
index 3c8d88b7c..e2a96d1a7 100644
--- a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
+++ b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts
@@ -1,3 +1,4 @@
+
import type { Element, Root } from 'hast';
import type { Plugin } from 'unified';
diff --git a/packages/core/src/markdown/resolve-image-url.ts b/packages/core/src/markdown/resolve-image-url.ts
index cf2c9da8e..0389575ac 100644
--- a/packages/core/src/markdown/resolve-image-url.ts
+++ b/packages/core/src/markdown/resolve-image-url.ts
@@ -1,3 +1,4 @@
+
import { isRelativeUrl } from './safe-url.ts';
function isDevDiagnosticContext(): boolean {
diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.ts
index 4d3250d3a..8be632ba4 100644
--- a/packages/core/src/markdown/safe-url.ts
+++ b/packages/core/src/markdown/safe-url.ts
@@ -1,3 +1,4 @@
+
export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;
const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');
diff --git a/packages/core/src/markdown/serialize-fidelity.test-helper.ts b/packages/core/src/markdown/serialize-fidelity.test-helper.ts
index 0dd54070e..96304e7a5 100644
--- a/packages/core/src/markdown/serialize-fidelity.test-helper.ts
+++ b/packages/core/src/markdown/serialize-fidelity.test-helper.ts
@@ -1,3 +1,4 @@
+
import type { JSONContent } from '@tiptap/core';
import type { Nodes } from 'mdast';
import { expect } from 'vitest';
diff --git a/packages/core/src/markdown/serialize-helpers.ts b/packages/core/src/markdown/serialize-helpers.ts
index 7cac5b042..93798cf83 100644
--- a/packages/core/src/markdown/serialize-helpers.ts
+++ b/packages/core/src/markdown/serialize-helpers.ts
@@ -1,3 +1,4 @@
+
import type { Node as PmNode } from '@tiptap/pm/model';
import type {
MdxJsxAttribute,
diff --git a/packages/core/src/markdown/single-dollar-math-promoter.ts b/packages/core/src/markdown/single-dollar-math-promoter.ts
index b012a5aff..8c08b7a04 100644
--- a/packages/core/src/markdown/single-dollar-math-promoter.ts
+++ b/packages/core/src/markdown/single-dollar-math-promoter.ts
@@ -1,3 +1,4 @@
+
import type { PhrasingContent, Root, Text } from 'mdast';
import type { InlineMath } from 'mdast-util-math';
import { SKIP, visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/to-markdown-handlers.ts b/packages/core/src/markdown/to-markdown-handlers.ts
index 3e79f8cb6..959cc0bd2 100644
--- a/packages/core/src/markdown/to-markdown-handlers.ts
+++ b/packages/core/src/markdown/to-markdown-handlers.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parents } from 'mdast';
import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';
import type { Handle, Info, State } from 'mdast-util-to-markdown';
diff --git a/packages/core/src/markdown/underline-promoter.ts b/packages/core/src/markdown/underline-promoter.ts
index 0f1b0f27d..6e6d73400 100644
--- a/packages/core/src/markdown/underline-promoter.ts
+++ b/packages/core/src/markdown/underline-promoter.ts
@@ -1,3 +1,4 @@
+
import type { Nodes, Parent, Root } from 'mdast';
import type { MdxJsxTextElement } from 'mdast-util-mdx';
import { visit } from 'unist-util-visit';
diff --git a/packages/core/src/markdown/unknown-mdast-guard.ts b/packages/core/src/markdown/unknown-mdast-guard.ts
index 1a082bda7..932d7d2a8 100644
--- a/packages/core/src/markdown/unknown-mdast-guard.ts
+++ b/packages/core/src/markdown/unknown-mdast-guard.ts
@@ -1,3 +1,4 @@
+
import type { Root as MdastRoot } from 'mdast';
import type { VFile } from 'vfile';
diff --git a/packages/core/src/markdown/whitespace-char-ref.ts b/packages/core/src/markdown/whitespace-char-ref.ts
index d578476a7..ac9f5239b 100644
--- a/packages/core/src/markdown/whitespace-char-ref.ts
+++ b/packages/core/src/markdown/whitespace-char-ref.ts
@@ -1,3 +1,4 @@
+
const INLINE_WHITESPACE_BY_CODE: ReadonlyMap<number, string> = new Map([
[0x20, ' '],
[0x09, '\t'],
diff --git a/packages/core/src/markdown/wiki-link-micromark.ts b/packages/core/src/markdown/wiki-link-micromark.ts
index 6dad26200..afd9936fe 100644
--- a/packages/core/src/markdown/wiki-link-micromark.ts
+++ b/packages/core/src/markdown/wiki-link-micromark.ts
@@ -17,6 +17,7 @@ declare module 'micromark-util-types' {
}
}
+
const CODE_BANG = 33; // !
const CODE_LBRACKET = 91; // [
const CODE_RBRACKET = 93; // ]
@@ -260,6 +261,7 @@ export function wikiLinkSyntax(): Extension {
};
}
+
function enterWikiLink(this: CompileContext, token: Token) {
this.enter(
{
@@ -385,6 +387,7 @@ export const wikiLinkToMarkdown: {
unsafe: [{ character: '[', inConstruct: ['phrasing'] }],
};
+
const MICROMARK_EXT = wikiLinkSyntax();
export function remarkWikiLink(this: Processor) {
diff --git a/packages/desktop/src/utility/server-entry.test.ts b/packages/desktop/src/utility/server-entry.test.ts
index a0a8d6504..f79cafe49 100644
--- a/packages/desktop/src/utility/server-entry.test.ts
+++ b/packages/desktop/src/utility/server-entry.test.ts
@@ -78,7 +78,6 @@ describe('resolveDesktopServerRuntime — scope-correct three-layer load', () =>
writeProjectConfig('server:\n externalUrl: https://box.tailnet.ts.net\n port: 24550\n');
const { serverRuntime } = resolveDesktopServerRuntime(testDir);
expect(serverRuntime.externalUrl).toBe('https://box.tailnet.ts.net');
- expect(serverRuntime.externalUrlSource).toBe('server');
expect(serverRuntime.port).toBe(24550);
});
@@ -118,8 +117,6 @@ function makeServerRuntime(port: number | undefined): ServerRuntimeConfig {
port,
bind: ['127.0.0.1'],
externalUrl: undefined,
- externalUrlSource: undefined,
- externalUrlFromDeprecatedKey: false,
allowExternal: false,
openBrowser: false,
idleShutdown: '30m',
diff --git a/packages/desktop/tests/integration/ephemeral-lifecycle.test.ts b/packages/desktop/tests/integration/ephemeral-lifecycle.test.ts
index 269bd5292..ba7e3f441 100644
--- a/packages/desktop/tests/integration/ephemeral-lifecycle.test.ts
+++ b/packages/desktop/tests/integration/ephemeral-lifecycle.test.ts
@@ -119,7 +119,7 @@ describe('ephemeral single-file lifecycle (real CLI)', () => {
// Pin IPv4 so the `/api/config` probe below isn't subject to the
// macOS `localhost` IPv6-first resolution (the production desktop uses
// the `localhost` default; the host is irrelevant to G4 / teardown).
- '--host',
+ '--bind',
'127.0.0.1',
// No `--serve-content-assets` — mirrors the production spawn shape;
// content-asset serving is the CLI default on every boot path.
diff --git a/packages/server/src/boot.test.ts b/packages/server/src/boot.test.ts
index af72b9533..fda7c0889 100644
--- a/packages/server/src/boot.test.ts
+++ b/packages/server/src/boot.test.ts
@@ -1111,11 +1111,10 @@ describeEvenOnCI('bootServer — exposure consent interlock', () => {
expect((err as Error | null)?.constructor.name).not.toBe('ExposureConsentError');
});
- test('the --remote alias shape (externalUrl + consent on a loopback bind) boots outright', async () => {
- // `ok start --remote <url>` expands to exactly this runtime with NO
- // OK_ALLOW_EXTERNAL in the environment — the alias carries its own
- // consent. Historically the flag WAS the consent; if this shape ever
- // trips the interlock, every existing --remote user breaks at boot.
+ test('an externalUrl + consent on a loopback bind boots outright', async () => {
+ // A tunneled deployment sets server.externalUrl + server.allowExternal on a
+ // loopback bind (the tunnel is the only ingress). This shape must boot
+ // without tripping the exposure interlock — the consent is explicit.
const err = await tryBoot(
{ externalUrl: 'https://myproject.ngrok.app', allowExternal: true },
true,
diff --git a/packages/server/src/boot.ts b/packages/server/src/boot.ts
index 68aab7add..57139d44d 100644
--- a/packages/server/src/boot.ts
+++ b/packages/server/src/boot.ts
@@ -597,8 +597,7 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {
// ONE ingress policy for the whole listener — HTTP gates, WS upgrade
// admission, config-doc admission, and the local-op checks all consult this
// object. Built from the resolved server.* runtime (consent, declared bind
- // literals, externalUrl); `ok start --remote` reaches here through the same
- // runtime, expanded by the CLI into these keys.
+ // literals, externalUrl).
//
// The policy's admitted Host names come from `serverRuntime.bind` — the
// DECLARED bind (which Host headers to accept) — NOT the physical
@@ -615,7 +614,7 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {
if (
serverRuntime.allowExternal &&
!serverRuntime.loopbackOnly &&
- serverRuntime.externalUrlSource !== 'server'
+ serverRuntime.externalUrl === undefined
) {
if (ingressPolicy.bindLiterals.length === 0) {
// Wildcard bind (0.0.0.0 / ::) contributes NO admissible Host name, and
diff --git a/packages/server/src/collaboration-host.test.ts b/packages/server/src/collaboration-host.test.ts
index 4c95a3a5a..727775966 100644
--- a/packages/server/src/collaboration-host.test.ts
+++ b/packages/server/src/collaboration-host.test.ts
@@ -168,12 +168,11 @@ describe('createCollaborationHost', () => {
expect(host.handleUpgrade(forwardedRequest as never, raw as never, Buffer.alloc(0))).toBe(true);
expect(raw.destroy).toHaveBeenCalledOnce();
expect(hocuspocus.handleConnection).not.toHaveBeenCalled();
- // Posture flip: the tripwire hint names the consent surface
- // (OK_ALLOW_EXTERNAL + OK_EXTERNAL_URL) now that it exists, with the
- // legacy --remote flow as the alternative.
+ // The tripwire hint names the consent surface (OK_ALLOW_EXTERNAL +
+ // OK_EXTERNAL_URL, or the server.* config equivalents).
expect(log.warn).toHaveBeenCalledWith(
{ url: '/collab', host: 'localhost' },
- '[remote] refused proxied WS upgrade; consent with OK_ALLOW_EXTERNAL=1 + OK_EXTERNAL_URL, or start with `ok start --remote <url>`',
+ '[remote] refused proxied WS upgrade; consent with OK_ALLOW_EXTERNAL=1 + OK_EXTERNAL_URL (or server.allowExternal + server.externalUrl in config)',
);
});
@@ -183,15 +182,13 @@ describe('createCollaborationHost', () => {
const host = createCollaborationHost({
hocuspocus,
log,
- // The `ok start --remote` alias shape: declared public origin + consent
- // on a loopback bind.
+ // A tunneled exposure shape: declared public origin + consent on a
+ // loopback bind.
ingressPolicy: buildIngressPolicy({
serverRuntime: {
port: undefined,
bind: ['127.0.0.1'],
externalUrl: 'https://myproject.ngrok.app',
- externalUrlSource: 'server',
- externalUrlFromDeprecatedKey: false,
allowExternal: true,
openBrowser: false,
idleShutdown: 'off',
@@ -220,10 +217,10 @@ describe('createCollaborationHost', () => {
});
test('under allowExternal consent, plain /collab validates Host (foreign refused, admitted names pass)', () => {
- // The #5 gap: before, plain /collab was gated only under legacy --remote,
- // so consented exposure (allowExternal, no --remote) left it ungated and
- // any Host reached full CRDT read/write. It now runs the consolidated
- // admit gate — loopback + bind literals + externalUrl — under consent too.
+ // Before, plain /collab was gated only under the old remote-access flow, so
+ // consented exposure (allowExternal) left it ungated and any Host reached
+ // full CRDT read/write. It now runs the consolidated admit gate — loopback
+ // + bind literals + externalUrl — under consent too.
const log = createLog();
const hocuspocus = createHocuspocus();
const host = createCollaborationHost({
@@ -234,8 +231,6 @@ describe('createCollaborationHost', () => {
port: undefined,
bind: ['127.0.0.1', '100.64.0.7'],
externalUrl: undefined,
- externalUrlSource: undefined,
- externalUrlFromDeprecatedKey: false,
allowExternal: true,
openBrowser: false,
idleShutdown: 'off',
@@ -293,8 +288,6 @@ describe('createCollaborationHost', () => {
port: undefined,
bind: ['127.0.0.1', '100.64.0.7'],
externalUrl: 'https://kb.example.com',
- externalUrlSource: 'server',
- externalUrlFromDeprecatedKey: false,
allowExternal: true,
openBrowser: false,
idleShutdown: 'off',
@@ -405,8 +398,6 @@ describe('createCollaborationHost', () => {
port: undefined,
bind: ['127.0.0.1', '100.64.0.7'],
externalUrl: 'https://kb.example.com',
- externalUrlSource: 'server',
- externalUrlFromDeprecatedKey: false,
allowExternal: true,
openBrowser: false,
idleShutdown: 'off',
@@ -457,8 +448,6 @@ describe('createCollaborationHost', () => {
port: undefined,
bind: ['127.0.0.1', '100.64.0.7'],
externalUrl: 'https://kb.example.com',
- externalUrlSource: 'server',
- externalUrlFromDeprecatedKey: false,
allowExternal: true,
openBrowser: false,
idleShutdown: 'off',
diff --git a/packages/server/src/collaboration-host.ts b/packages/server/src/collaboration-host.ts
index 1c46294f3..b8d1b71bc 100644
--- a/packages/server/src/collaboration-host.ts
+++ b/packages/server/src/collaboration-host.ts
@@ -287,7 +287,7 @@ export function createCollaborationHost(options: CollaborationHostOptions): Coll
if (tripsForwardedHeaderTripwire(req, ingressPolicy)) {
log.warn(
{ url: req.url, host: req.headers.host },
- '[remote] refused proxied WS upgrade; consent with OK_ALLOW_EXTERNAL=1 + OK_EXTERNAL_URL, or start with `ok start --remote <url>`',
+ '[remote] refused proxied WS upgrade; consent with OK_ALLOW_EXTERNAL=1 + OK_EXTERNAL_URL (or server.allowExternal + server.externalUrl in config)',
);
socket.destroy();
return true;
@@ -330,7 +330,7 @@ export function createCollaborationHost(options: CollaborationHostOptions): Coll
// admitted — those are not CSWSH vectors and legitimately carry none.
//
// (2) Peer + Host admission (`admitted()`) — only when EXPOSED
- // (`allowExternal` consent, which `ok start --remote` expands into).
+ // (`allowExternal` consent).
// Pure-local keeps its historical ungated posture on this axis — a
// deliberate carve-out from the read-posture hardening that
// Host-gates `/api` reads and content-asset serving in every mode: WS
diff --git a/packages/server/src/embed-probe.ts b/packages/server/src/embed-probe.ts
index cb9503455..d78e2cd91 100644
--- a/packages/server/src/embed-probe.ts
+++ b/packages/server/src/embed-probe.ts
@@ -17,7 +17,7 @@
* (`handlePrincipal`, `handleMetricsAgentPresence`). The buffer is
* populated unconditionally from `onRequest`, so the gate has to live
* on the read side — readers see only loopback traffic in practice,
- * but a misconfigured `--host 0.0.0.0` deployment would route LAN
+ * but a misconfigured `--bind 0.0.0.0` deployment would route LAN
* peers through here too.
*/
diff --git a/packages/server/src/handoff-api.test.ts b/packages/server/src/handoff-api.test.ts
index a7d41b8e7..d5647d3e9 100644
--- a/packages/server/src/handoff-api.test.ts
+++ b/packages/server/src/handoff-api.test.ts
@@ -485,8 +485,6 @@ describe('GET /api/installed-agents (integration — real HTTP + real createApiE
port: undefined,
bind: ['127.0.0.1', '192.168.1.100'],
externalUrl: 'http://example.com:5173',
- externalUrlSource: 'server',
- externalUrlFromDeprecatedKey: false,
allowExternal: true,
openBrowser: false,
idleShutdown: 'off',
diff --git a/packages/server/src/http/admit-request-surface.test.ts b/packages/server/src/http/admit-request-surface.test.ts
index 6783e95f5..798d2da6f 100644
--- a/packages/server/src/http/admit-request-surface.test.ts
+++ b/packages/server/src/http/admit-request-surface.test.ts
@@ -6,10 +6,10 @@ import { admitRequestSurface } from './http-app.ts';
// admitRequestSurface is the surface-wide admission prelude the mount runs
// BEFORE dispatch for EVERY request — /mcp, /api, the static SPA shell, and
-// project content assets. These pin the #6 fix: under `allowExternal` consent
-// (no legacy --remote), it validates Host with the consolidated predicate
-// (loopback + bind literals + externalUrl), so a rebound / foreign Host cannot
-// read the static shell or content while the peer is admitted.
+// project content assets. Under `allowExternal` consent it validates Host with
+// the consolidated predicate (loopback + bind literals + externalUrl), so a
+// rebound / foreign Host cannot read the static shell or content while the
+// peer is admitted.
function req(
host: string | undefined,
@@ -45,8 +45,6 @@ const consentPolicy = buildIngressPolicy({
port: undefined,
bind: ['127.0.0.1', '100.64.0.7'],
externalUrl: 'http://laptop.tail:55222',
- externalUrlSource: 'server',
- externalUrlFromDeprecatedKey: false,
allowExternal: true,
openBrowser: false,
idleShutdown: 'off',
diff --git a/packages/server/src/http/http-app.ts b/packages/server/src/http/http-app.ts
index 5a167ff86..6c754b16e 100644
--- a/packages/server/src/http/http-app.ts
+++ b/packages/server/src/http/http-app.ts
@@ -66,10 +66,10 @@ export interface NativeApiHandle {
* public tunnel with full local trust, decided by whether the tunnel
* rewrites Host.
*
- * Gate 2 — with the surface EXPOSED (`server.allowExternal` consent, which
- * `ok start --remote` also expands into), ONE admit decision covers every
- * surface: an admitted peer + Host on the allowlist. Refusals are wrong-Host
- * callers (DNS-rebound pages), not auth failures.
+ * Gate 2 — with the surface EXPOSED (`server.allowExternal` consent), ONE
+ * admit decision covers every surface: an admitted peer + Host on the
+ * allowlist. Refusals are wrong-Host callers (DNS-rebound pages), not auth
+ * failures.
*
* `handler` is the caller's tag on the `ok.api.error.count` counter for
* rejections ('mcp-mount' for the legacy dispatch, 'native-api-surface' for
@@ -87,7 +87,7 @@ export function admitRequestSurface(
res,
403,
'urn:ok:error:host-not-allowed',
- 'Proxied request refused: this server has not consented to external exposure. Set OK_EXTERNAL_URL to the public origin and OK_ALLOW_EXTERNAL=1 (or server.externalUrl + server.allowExternal in config), or restart with `ok start --remote <url>`.',
+ 'Proxied request refused: this server has not consented to external exposure. Set OK_EXTERNAL_URL to the public origin and OK_ALLOW_EXTERNAL=1 (or server.externalUrl + server.allowExternal in config), then restart the server.',
{ handler },
);
return false;
diff --git a/packages/server/src/http/metrics-routes.ts b/packages/server/src/http/metrics-routes.ts
index 6573e97a8..752a80dc2 100644
--- a/packages/server/src/http/metrics-routes.ts
+++ b/packages/server/src/http/metrics-routes.ts
@@ -1,10 +1,8 @@
/**
* The metrics read family — `metrics-reconciliation`, `metrics-parse-health`,
* `metrics-agent-presence`, `metrics-agent-effects`, `metrics-watcher-recent`
- * — lifted out of `api-extension.ts` as the second natively-routed Wave 2
- * group. Same lift shape as `link-graph-routes.ts`: what the handlers closed
- * over in the extension arrives as {@link MetricsRouteDeps}, and the handler
- * bodies are unchanged.
+ * — the second natively-routed group. What the handlers close over arrives as
+ * {@link MetricsRouteDeps}.
*
* Being the SECOND group is the point: the extension aggregates every group
* into one `nativeApi` handle (paths concatenated, per-group pipeline
@@ -17,8 +15,9 @@
* from the pipeline's `isMutating` mechanism, which gates before dispatch but
* ALSO before the per-route 404/405 machinery for mutating writes — so these
* gates deliberately stay in the handler bodies and `isMutating` stays false.
- * The Host predicate arrives as a dep because the extension widens it in
- * remote mode (the tunnel's public Host is as legitimate as loopback).
+ * The Host predicate arrives as a dep because the extension widens it when
+ * the server is exposed (server.allowExternal + server.externalUrl) — the
+ * tunnel's public Host is as legitimate as loopback.
*/
import type { IncomingMessage, ServerResponse } from 'node:http';
@@ -51,8 +50,9 @@ export interface MetricsRouteDeps {
hocuspocus: Hocuspocus;
agentPresenceBroadcaster: AgentPresenceBroadcaster | undefined;
/**
- * The extension's remote-widened workspace-Host predicate — in remote mode
- * the tunnel's public Host passes alongside the loopback names.
+ * The extension's exposure-widened workspace-Host predicate — when the
+ * server is exposed, the tunnel's public Host passes alongside the loopback
+ * names.
*/
isAllowedWorkspaceHostHeader: (host: string | undefined) => boolean;
log: PinoLogger;
diff --git a/packages/server/src/ingress-policy.test.ts b/packages/server/src/ingress-policy.test.ts
index be65f645d..9f2c3288a 100644
--- a/packages/server/src/ingress-policy.test.ts
+++ b/packages/server/src/ingress-policy.test.ts
@@ -18,8 +18,6 @@ function runtime(overrides: Partial<ServerRuntimeConfig> = {}): ServerRuntimeCon
port: undefined,
bind: ['127.0.0.1'],
externalUrl: undefined,
- externalUrlSource: undefined,
- externalUrlFromDeprecatedKey: false,
allowExternal: false,
openBrowser: true,
idleShutdown: '30m',
@@ -29,12 +27,11 @@ function runtime(overrides: Partial<ServerRuntimeConfig> = {}): ServerRuntimeCon
}
/**
- * The runtime shape `ok start --remote <url>` expands to: declared public
- * origin + consent on a loopback bind — no dedicated tunnel shape.
+ * A tunneled deployment's runtime shape: declared public origin + consent on a
+ * loopback bind — there is no dedicated tunnel policy shape.
*/
-const REMOTE_ALIAS_RUNTIME: Partial<ServerRuntimeConfig> = {
+const TUNNEL_EXPOSURE_RUNTIME: Partial<ServerRuntimeConfig> = {
externalUrl: 'https://myproject.ngrok.app',
- externalUrlSource: 'server',
allowExternal: true,
idleShutdown: 'off',
openBrowser: false,
@@ -59,35 +56,29 @@ describe('buildIngressPolicy', () => {
expect(policy.bindLiterals).toEqual(['100.64.0.7', '2001:db8::1']);
});
- test('externalOrigin comes from the successor key only, never the remote alias', () => {
+ test('externalOrigin comes from a server-sourced externalUrl', () => {
const explicit = buildIngressPolicy({
serverRuntime: runtime({
externalUrl: 'http://laptop.tail:55222',
- externalUrlSource: 'server',
}),
});
expect(explicit.externalOrigin).toEqual({ host: 'laptop.tail:55222', protocol: 'http:' });
- const aliased = buildIngressPolicy({
- serverRuntime: runtime({
- externalUrl: 'https://kb.example.com',
- externalUrlSource: 'remote-alias',
- }),
- });
- expect(aliased.externalOrigin).toBeUndefined();
+ // No externalUrl → no external origin.
+ const none = buildIngressPolicy({ serverRuntime: runtime({}) });
+ expect(none.externalOrigin).toBeUndefined();
});
test('forwarded headers are tolerated only under consent + declared externalUrl', () => {
- // The --remote alias lands exactly here: its expansion carries both keys.
+ // A tunneled deployment lands exactly here: its config carries both keys.
expect(
- buildIngressPolicy({ serverRuntime: runtime(REMOTE_ALIAS_RUNTIME) }).tolerateForwardedHeaders,
+ buildIngressPolicy({ serverRuntime: runtime(TUNNEL_EXPOSURE_RUNTIME) })
+ .tolerateForwardedHeaders,
).toBe(true);
expect(
buildIngressPolicy({
serverRuntime: runtime({
allowExternal: true,
externalUrl: 'https://kb.example.com',
- externalUrlSource: 'server',
- externalUrlFromDeprecatedKey: false,
}),
}).tolerateForwardedHeaders,
).toBe(true);
@@ -104,7 +95,6 @@ describe('buildIngressPolicy', () => {
buildIngressPolicy({
serverRuntime: runtime({
externalUrl: 'https://kb.example.com',
- externalUrlSource: 'server',
}),
}).tolerateForwardedHeaders,
).toBe(false);
@@ -140,7 +130,6 @@ describe('isHostAdmitted — names validate in every mode, never widened by cons
loopbackOnly: false,
allowExternal: true,
externalUrl: 'http://laptop.tail:55222',
- externalUrlSource: 'server',
}),
});
@@ -188,7 +177,6 @@ describe('isOriginAdmitted — if present, must match; scheme-matched for extern
serverRuntime: runtime({
allowExternal: true,
externalUrl: 'https://notes.example.com',
- externalUrlSource: 'server',
}),
});
@@ -203,7 +191,6 @@ describe('isOriginAdmitted — if present, must match; scheme-matched for extern
serverRuntime: runtime({
allowExternal: true,
externalUrl: 'http://laptop.tail:55222',
- externalUrlSource: 'server',
}),
});
expect(isOriginAdmitted('http://laptop.tail:55222', httpPublic)).toBe(true);
@@ -242,11 +229,11 @@ describe('isOriginAdmitted — if present, must match; scheme-matched for extern
});
});
-describe('the --remote alias shape — tunnel admission via the ratified keys', () => {
- // Behavior-preservation pins for the legacy `--remote` contract, expressed
- // through the ONE policy: the tunnel's public Host is admitted, its https
- // origin is admitted, foreign names stay refused.
- const tunnel = buildIngressPolicy({ serverRuntime: runtime(REMOTE_ALIAS_RUNTIME) });
+describe('tunnel admission via the ratified keys', () => {
+ // Behavior pins for a tunneled deployment, expressed through the ONE policy:
+ // the tunnel's public Host is admitted, its https origin is admitted,
+ // foreign names stay refused.
+ const tunnel = buildIngressPolicy({ serverRuntime: runtime(TUNNEL_EXPOSURE_RUNTIME) });
test('the tunnel public Host is admitted, with or without default-port suffix', () => {
expect(isHostAdmitted('myproject.ngrok.app', tunnel)).toBe(true);
@@ -303,7 +290,6 @@ describe('tripsForwardedHeaderTripwire', () => {
serverRuntime: runtime({
allowExternal: true,
externalUrl: 'https://notes.example.com',
- externalUrlSource: 'server',
}),
});
expect(tripsForwardedHeaderTripwire(req, consented)).toBe(false);
diff --git a/packages/server/src/ingress-policy.ts b/packages/server/src/ingress-policy.ts
index 94c522ead..9e501608d 100644
--- a/packages/server/src/ingress-policy.ts
+++ b/packages/server/src/ingress-policy.ts
@@ -7,9 +7,9 @@
* local-op security checks. One policy, one set of predicates — the HTTP and
* WS halves of the server can never disagree about who is admitted.
*
- * The `ok start --remote <url>` flag is CLI sugar over the same keys (it
- * expands to `server.externalUrl` + loopback `server.bind` +
- * `server.allowExternal`) — there is no separate tunnel policy shape.
+ * Exposing the server is just these keys — `server.externalUrl` + a
+ * `server.bind` + `server.allowExternal` consent — there is no separate
+ * tunnel policy shape.
*
* The three predicates and what governs each:
*
@@ -101,10 +101,10 @@ export interface IngressPolicy {
*/
bindLiterals: readonly string[];
/**
- * The declared canonical origin — the EXPLICIT `server.externalUrl` only
- * (`externalUrlSource === 'server'`). `host` is `host[:port]` with default
- * ports stripped; `protocol` is `http:`/`https:`, matched exactly for
- * Origin checks since the key admits http for tailnet/LAN deployments.
+ * The declared canonical origin — the EXPLICIT `server.externalUrl`;
+ * `host` is `host[:port]` with default ports stripped, `protocol` is
+ * `http:`/`https:`, matched exactly for Origin checks since the key
+ * admits http for tailnet/LAN deployments.
*/
externalOrigin: { host: string; protocol: string } | undefined;
/**
@@ -151,7 +151,7 @@ export function buildIngressPolicy(input: BuildIngressPolicyInput): IngressPolic
.filter((addr) => !NON_NAMEABLE_BINDS.has(addr) && !addr.startsWith('127.'));
let externalOrigin: IngressPolicy['externalOrigin'];
- if (runtime?.externalUrlSource === 'server' && runtime.externalUrl !== undefined) {
+ if (runtime?.externalUrl !== undefined) {
// The schema guarantees a parseable http(s) URL; a throw here would be a
// schema/resolver drift bug, so let it propagate loudly at boot.
const parsed = new URL(runtime.externalUrl);
diff --git a/packages/server/src/init-project.ts b/packages/server/src/init-project.ts
index ae77460cc..dd70eae71 100644
--- a/packages/server/src/init-project.ts
+++ b/packages/server/src/init-project.ts
@@ -158,10 +158,10 @@ export function buildConfigYmlContent(_version: string, options?: BuildConfigYml
# --- Server ----------------------------------------------------------------
-# Host: set via \`--host\` flag or \`HOST\` env var (default: localhost; use
-# \`0.0.0.0\` to bind LAN-visible). Port: set via \`--port\` flag or \`PORT\`
-# env var (auto-allocated if unset). Both are per-process runtime knobs —
-# no \`server:\` schema field exists.
+# Bind host: \`--bind\` flag, \`HOST\` env var, or the \`server.bind\` config key
+# (default: 127.0.0.1; \`0.0.0.0\` binds LAN-visible and also needs
+# \`server.allowExternal\`). Port: \`--port\` flag, \`PORT\` env var, or
+# \`server.port\` (auto-allocated if unset). See the Configuration reference.
# --- Appearance ------------------------------------------------------------
diff --git a/packages/server/src/local-op-security.test.ts b/packages/server/src/local-op-security.test.ts
index 4c8caf1d5..2106f2658 100644
--- a/packages/server/src/local-op-security.test.ts
+++ b/packages/server/src/local-op-security.test.ts
@@ -719,16 +719,14 @@ describe('hasValidLocalOpOrigin with a remote public host', () => {
const reqWithOrigin = (origin: string) =>
({ headers: { origin }, socket: { remoteAddress: '127.0.0.1' } }) as never;
- // The `ok start --remote` alias shape: declared public origin + consent on
- // a loopback bind.
+ // A tunneled exposure shape: declared public origin + consent on a loopback
+ // bind.
const tunnelPolicy = () =>
buildIngressPolicy({
serverRuntime: {
port: undefined,
bind: ['127.0.0.1'],
externalUrl: 'https://myproject.ngrok.app',
- externalUrlSource: 'server',
- externalUrlFromDeprecatedKey: false,
allowExternal: true,
openBrowser: false,
idleShutdown: 'off',
@@ -761,8 +759,6 @@ describe('hasValidLocalOpOrigin with a remote public host', () => {
port: undefined,
bind: ['100.64.0.7'],
externalUrl: undefined,
- externalUrlSource: undefined,
- externalUrlFromDeprecatedKey: false,
allowExternal: true,
openBrowser: false,
idleShutdown: 'off',
diff --git a/packages/server/src/mcp-mount.ts b/packages/server/src/mcp-mount.ts
index b447afe83..dff15ed63 100644
--- a/packages/server/src/mcp-mount.ts
+++ b/packages/server/src/mcp-mount.ts
@@ -447,7 +447,7 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
if (tripsForwardedHeaderTripwire(req, ingressPolicy)) {
log.warn(
{ url: req.url, host: req.headers.host },
- '[remote] refused proxied WS upgrade; consent with OK_ALLOW_EXTERNAL=1 + OK_EXTERNAL_URL, or start with `ok start --remote <url>`',
+ '[remote] refused proxied WS upgrade; consent with OK_ALLOW_EXTERNAL=1 + OK_EXTERNAL_URL (or server.allowExternal + server.externalUrl in config)',
);
}
socket.destroy();
diff --git a/packages/server/src/perf-measurement.ts b/packages/server/src/perf-measurement.ts
index 8104f6158..e4a3c21ed 100644
--- a/packages/server/src/perf-measurement.ts
+++ b/packages/server/src/perf-measurement.ts
@@ -151,7 +151,7 @@ export function installPerfMeasurementHttpRoute(server: Hocuspocus): void {
// gate api-extension.ts applies to /api/principal + /api/workspace
// keeps the route's posture consistent with the rest of the package
// — engineers don't have to remember which DEV-only routes are
- // safe under `--host 0.0.0.0`.
+ // safe under `--bind 0.0.0.0`.
if (!isLoopbackAddress(request.socket?.remoteAddress)) {
writeJsonResponse(response, 403, JSON.stringify({ error: 'loopback required' }));
return;
diff --git a/packages/server/src/remote-mcp.test.ts b/packages/server/src/remote-mcp.test.ts
index c56b587d2..e139230b0 100644
--- a/packages/server/src/remote-mcp.test.ts
+++ b/packages/server/src/remote-mcp.test.ts
@@ -8,11 +8,10 @@
* server sees behind a real ngrok / cloudflared / tailscale tunnel — the
* transport itself is the only untested hop.
*
- * The ingress policy is built from the SAME `server.*` runtime shape the
- * `ok start --remote <url>` alias expands to (`server.externalUrl` + consent
- * on a loopback bind); these tests are the behavior-preservation pins for
- * the legacy tunnel contract now that the dedicated remote topology is
- * gone. With the tunnel shape armed there is ONE gate: Host on the
+ * The ingress policy is built from the `server.*` runtime shape a tunneled
+ * deployment declares (`server.externalUrl` + consent on a loopback bind);
+ * these tests are the behavior pins for the tunnel contract. With the tunnel
+ * shape armed there is ONE gate: Host on the
* allowlist (loopback names or the tunnel's public host). Admitted callers
* get the full surface; there is no per-origin tiering and no server-side
* auth — restricting WHO can reach the tunnel is the tunnel's job (edge
@@ -91,9 +90,8 @@ async function bootRemoteRig(externalUrl: string | null, extras: RigExtras = {})
const contentDir = mkdtempSync(join(tmpdir(), 'ok-remote-mcp-'));
const localDir = join(contentDir, '.ok', 'local');
mkdirSync(localDir, { recursive: true });
- // Exactly the keys `ok start --remote <url>` expands to: declared public
- // origin + consent; the rig's listener stays loopback like the coerced
- // remote bind.
+ // A tunneled deployment's keys: declared public origin + consent; the rig's
+ // listener stays loopback (the tunnel is the only ingress).
const config = ConfigSchema.parse(
externalUrl === null ? {} : { server: { externalUrl, allowExternal: true } },
);
@@ -404,14 +402,14 @@ describe('remote enabled — trust-the-tunnel admission', () => {
});
describe('remote disabled — the forwarding-header tripwire', () => {
- test('proxied requests are refused with the --remote hint', async () => {
+ test('proxied requests are refused with the exposure-consent hint', async () => {
const rig = await bootRemoteRig(null);
const res = await raw(rig.port, {
path: '/api/pages',
headers: { host: `127.0.0.1:${rig.port}`, 'x-forwarded-for': '203.0.113.7' },
});
expect(res.status).toBe(403);
- expect(res.body).toContain('ok start --remote');
+ expect(res.body).toContain('OK_ALLOW_EXTERNAL');
});
test('vendor proxy headers (X-Real-IP, CF-Connecting-IP, True-Client-IP) also trip the wire', async () => {
@@ -422,7 +420,7 @@ describe('remote disabled — the forwarding-header tripwire', () => {
headers: { host: `127.0.0.1:${rig.port}`, [header]: '203.0.113.7' },
});
expect(res.status, `${header} should trip the wire`).toBe(403);
- expect(res.body).toContain('ok start --remote');
+ expect(res.body).toContain('OK_ALLOW_EXTERNAL');
}
});
diff --git a/packages/server/src/server-factory.test.ts b/packages/server/src/server-factory.test.ts
index a227cce41..870166857 100644
--- a/packages/server/src/server-factory.test.ts
+++ b/packages/server/src/server-factory.test.ts
@@ -2758,15 +2758,13 @@ describe('createServer() — config-doc admission guard', () => {
contentDir: tmpDir,
projectDir: tmpDir,
quiet: true,
- // The `ok start --remote` alias shape: declared public origin + consent
- // on a loopback bind.
+ // A tunneled exposure shape: declared public origin + consent on a
+ // loopback bind.
ingressPolicy: buildIngressPolicy({
serverRuntime: {
port: undefined,
bind: ['127.0.0.1'],
externalUrl: 'https://myproject.ngrok.app',
- externalUrlSource: 'server',
- externalUrlFromDeprecatedKey: false,
allowExternal: true,
openBrowser: false,
idleShutdown: 'off',