Turtle
38c7a9fbf4
* feat(release): publish package source, declaration maps, and documentation Every release member publishes its TypeScript source and the declaration maps that resolve into it, and @deepseek-ai/dsh publishes the repository Markdown documentation staged from docs/ at prepack time. The ./src/* export most members already declared now resolves for an installed consumer, and a consumer editor follows a declaration to the implementation. Bundled JavaScript maps stay unpublished; the vendored family and the Desktop runtime file policy are unchanged. Rationale: .agents/notes/implemented/process/2026-10-08-published-source-and-docs.md * feat(release): publish JavaScript maps and compress bundles Every emitted JavaScript map ships beside the bundle it describes, and the workspace build and the client preset compress bundles without mangling identifiers. The documentation payload now mirrors the website publication manifest and is removed again by `postpack`; Desktop and the Python executable exclude the published source, documentation, and maps; `clean` removes a staged copy. Typert's publication contract gains the Remote declaration map. * fix(release): keep node bundles readable for the worker image The browser worker image lowers `yield*` only as a whole statement and rewrites `for await` loops by their source layout, so compressed node-side entries either fail that lowering or lower to unparseable code. Only the browser bundles keep compression, which removes about a third of their text. The bundle-purity assertion now matches the module-loader call regardless of the quote style compression picks, and the release-pack fixture exercises the installed package's new documentation requirement. * feat(release): publish the whole documentation tree `@deepseek-ai/dsh` copies `docs/` in full instead of the website's page set: the maintainer documents, the generated migration records, the translation guidelines, and the `*.i18n.yaml` consistency records ship with the installed package, so the documentation's own links resolve without a checkout. * feat(release): publish the upgrade guides with the documentation The staged documentation keeps the website's page set and adds every `docs/upgrade-guide/` document, which is what an installed reader consults when a released change breaks something. The rest of the maintainer tree stays out. * test(release): expect source and maps in master's new payload cases * feat(release): keep installed docs and source readable in Desktop Desktop keeps the published src/ and docs/ trees inside app.asar, and every model shell call receives DSH_INSTALL_DIR and DSH_NODE_EXECUTABLE so an agent can read them through Electron's Node mode. Staging also generates docs/upgrade-guide/README.md, an index of the upgrade guides grouped by the release they upgrade from. Minified client bundles print string literals with backticks: the worker image packer now recognizes those chunk requests, client license banners are prepended after minification so their text survives, and the affected artifact tests accept either quote. * test(desktop): read archived docs through the Windows PowerShell form Regenerate the config catalog for the shifted shell-env source line. * test(desktop): wait for the GUI-subsystem Electron process from PowerShell * build(release): publish source and maps from the message-quotes package * build(release): publish source and maps from packages new on master * build(release): publish source and maps from the tool-office package
description, kind
| description | kind |
|---|---|
| SPA dist server for the Web shell: claims the webserver fallback seat and serves the built frontend with traversal rejection and SPA index fallback. | package-reference |
@deepseek-ai/dsh-host-frontend-static
English | 中文
Summary
Serve the built Web shell to browsers from its configured distribution directory. The root and configured index path render the bootstrapped index; existing assets are served directly, while missing or non-file paths return 404, traversal returns 403, and unsupported methods return 405. Index access requires a valid process token or browser cookie, but static assets remain public. Only one instance can handle unmatched routes at a time; a second activation fails, and unloading the active instance makes unmatched requests return 404.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
Compose this plugin in a browser-facing host that serves the built Web shell: it claims the webserver's fallback seat and answers every request no named route matches. It needs one config value — where the built frontend's index.html lives.
Minimal configuration
- name: '@deepseek-ai/dsh-host-frontend-static'
config:
distIndex: /absolute/path/to/dist/index.html
distIndex is an assembly fact of the composing application: dsh-web-app resolves it through the frontend package's exports and mounts this plugin; a deployment never hardcodes it.
What the server enforces
Requests are served from the dist root (the directory containing distIndex). The dist root and the configured index path render index.html with HTTP 200; any other existing file is served directly with its MIME type, and unknown extensions ship as application/octet-stream. A path that resolves outside the root is rejected with 403, so a crafted path cannot read files above the dist. An absent or non-file target inside the dist root — a missing file, a directory, or a missing configured index — returns an empty 404. Non-GET/HEAD requests without a matching named route are answered 405. The fallback is a webserver resource. Every successful index response is rendered through the webserver's renderIndex — for connection.browserPeer, the Peer Connection's browser authentication admits, over HTTP, and for peer in a webServer.readResource(request, peer) read, which skips browser authentication — so the boot manifest and that Peer's access snapshot reach the page on / and on the configured index path.
The served HTML carries one document base, <base href="./">, ahead of every injected resource row, so it freezes the entry directory the page was loaded from: the shell's own app-directory-relative references and the Host's plugin-resource rows both resolve under the mount that served the page. The same index therefore serves the origin root and whatever mount a prefix-stripping proxy owns; this plugin renders it only for the dist root and the configured index path.
HTTP root and configured-index requests call ctx.connection.authorizeIndex before reading HTML. A valid process token receives a 303 redirect plus the persistent browser cookie; an existing valid cookie serves the index; every other index request receives the Connection-owned 401 response. Non-index files remain public static assets. Connection owns the token, cookie, expiry, and signing-record semantics.
Browsers revalidate every served file except the index. Such a response carries cache-control: no-cache and a weak ETag built from a SHA-1 of the file's bytes, so a file whose content changes gets a new ETag even when its name stays the same; a request whose If-None-Match equals the current ETag receives an empty 304. The rendered index carries no cache headers.
Observable failures
Traversal returns 403 rather than an error page. An absent or non-file target inside the dist root returns an empty 404, so a stale link or a mistyped pathname is an explicit failure rather than a silent SPA fallback. Claiming the seat twice throws, and while the seat is unclaimed the webserver answers 404 — which is what a browser sees if this plugin's fiber is disposed.
Understand the implementation
Implementation internals — click to expand
Design concept
The package is one function plugin around serveStatic, which maps a Fetch Request to a Response: apply resolves the dist root from distIndex and registers a fallback resource under an effect scope. For each request the resource passes serveStatic an authorizeIndex closure, which runs ctx.connection.authorizeIndex only when no Peer came with the request, and a renderIndex closure that runs ctx.webServer.renderIndex over the raw index.html for that Peer or the browser Peer and splices the document base in after the opening head tag (after the raw taps, so it precedes their markup too). The seat is single-owner by the webserver's contract — a second registration throws — and effect-scoped, so disposing the fiber releases the seat.
The traversal fence
serveStatic normalizes the requested pathname and joins it to the dist root, then requires the target to be the root itself or stay under it. The check uses sep rather than / because resolve() emits backslash paths on Windows, where a / suffix would reject every legitimate subpath as traversal.
Source map
| File | Role |
|---|---|
src/index.ts |
serveStatic and apply: fallback resource, traversal rejection, index authorization and rendering, revalidation, MIME table |
Further Exploration
Read these when the serving contract is not enough: the seat owner's contract, then the composition that resolves the dist and the subsystem reference.
- Webserver — the fallback seat this plugin claims and the index taps it runs.
- dsh-web-app bundle — the application that resolves
distIndexand mounts this plugin. - HTTP server subsystem — how the fallback seat fits the route tables.
- Generated configuration catalog — every accepted config field and its source declaration.
Model Experience
None, as the SPA dist server answers browser asset requests and registers nothing model-facing.
KV Cache effect
None; this package neither assembles nor sends a provider request.
Known Limitations and Deferred Work
These limits define when a served asset class is not yet covered. They are current package constraints, not a task backlog.
- The starter MIME table is minimal — it covers the Vite-emitted asset set plus the shipped PWA manifest; other extensions fall back to
application/octet-streamuntil an asset class ships. - Pathname routing is explicit — the current client enters through the root or configured index path and has no History API pathname routes. Adding one requires an explicit server rule and real-composition coverage rather than a broad fallback for every miss.
Dev Note
Working context for maintainers — click to expand
None.