@x1a0f3n9/dsh-host-frontend-static 0.1.5-rc.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/host/frontend-static/README.md
+README.md: e616c048119fc1ce75ad29b002c3298b84169af9
+README.zh.md: 6cf55bb6d82f665754767f0a8c5b9cc68d8236d6

package/README.md

@@ -0,0 +1,117 @@
+---
+description: "SPA dist server for the Web shell: claims the webserver fallback seat and serves the built frontend with traversal rejection and SPA index fallback."
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-host-frontend-static
+
+English | [中文](README.zh.md)
+
+## 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](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 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
+
+```yaml
+- name: '@x1a0f3n9/dsh-host-frontend-static'
+  config:
+    distIndex: /absolute/path/to/dist/index.html
+```
+
+`distIndex` is an assembly fact of the composing application: [`dsh-web-app`](../../bundle/web-app/README.md) 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. Every successful index response is rendered through the webserver's `renderIndex`, so the boot manifest reaches the page on `/` and on the configured index path.
+
+Root and configured-index responses 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.
+
+### 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.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+### Design concept
+
+The package is one function plugin around `serveStatic`: `apply` resolves the dist root from `distIndex`, builds a `renderIndex` closure that runs `ctx.webServer.renderIndex` over the raw `index.html`, and registers the fallback handler under an effect scope. 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`](src/index.ts) | `serveStatic` and `apply`: fallback claim, traversal rejection, index rendering, MIME table |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 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](../webserver/README.md) — the fallback seat this plugin claims and the index taps it runs.
+- [dsh-web-app bundle](../../bundle/web-app/README.md) — the application that resolves `distIndex` and mounts this plugin.
+- [HTTP server subsystem](../../../docs/subsystems/web-server.md) — how the fallback seat fits the route tables.
+- [Generated configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-host-frontend-static) — every accepted config field and its source declaration.
+
+-----
+
+<a id="model-experience"></a>
+## 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
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+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-stream` until 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.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
+
+**Runtime invariant:** No companion is published. The only owned relation is the single fallback seat, which cannot be probed from the teardown stream — `internal/plugin` fires before the disposing fiber's effects run, so the legitimate owner still holds the seat at notification time and any claim probe would false-positive on every correct disposal (unlike the webserver companion, whose reserved-path probes never collide with a live registration). The seat's register/release symmetry is covered by the package's real-composition HMR-safety test instead.

package/README.zh.md

@@ -0,0 +1,117 @@
+---
+description: "Web 壳的 SPA dist 服务器：占据 webserver 回退席位，以遍历拒绝与 SPA index 回退服务已构建的前端。"
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-host-frontend-static
+
+[English](README.md) | 中文
+
+## 概述
+
+从配置的发布目录向浏览器提供已构建的 Web 壳。根路径与配置的 index 路径渲染包含启动信息的 index；已有资产直接提供，而缺失或非文件路径返回 404、路径遍历返回 403、不支持的方法返回 405。访问 index 需要有效的进程 token 或浏览器 cookie，但静态资产仍可公开访问。同一时间只能有一个实例处理未匹配的路由；第二个实例启动失败，卸载活动实例后，未匹配的请求返回 404。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在服务已构建 Web 壳的浏览器宿主中组合本插件：它占据 webserver 的回退席位，并应答所有未被具名路由命中的请求。它只需要一个配置值——已构建前端的 `index.html` 位于何处。
+
+### 最小配置
+
+```yaml
+- name: '@x1a0f3n9/dsh-host-frontend-static'
+  config:
+    distIndex: /absolute/path/to/dist/index.html
+```
+
+`distIndex` 是组合应用的组装事实：[`dsh-web-app`](../../bundle/web-app/README.zh.md) 通过前端包的 exports 解析它并挂载本插件；部署绝不硬编码它。
+
+### 服务器实施的约束
+
+请求从 dist 根目录（包含 `distIndex` 的目录）提供。dist 根目录与配置的 index 路径以 HTTP 200 渲染 `index.html`；任何其他已有文件按自身 MIME 类型直接提供，未知扩展名按 `application/octet-stream` 提供。解析到根目录之外的路径以 403 拒绝，因此精心构造的路径无法读取 dist 之上的文件。dist 根目录内不存在或不是文件的目标——文件缺失、目录或配置的 index 缺失——返回空 404。没有匹配具名路由的非 GET／HEAD 请求返回 405。每个成功的 index 响应都经 webserver 的 `renderIndex` 渲染，因此启动 manifest（元数据清单）会通过 `/` 与配置的 index 路径送达页面。
+
+根路径与配置的 index 响应会在读取 HTML 前调用 `ctx.connection.authorizeIndex`。有效进程 token 会得到 303 重定向与持久浏览器 cookie；已有有效 cookie 时直接提供 index；其他 index 请求得到 Connection 所有的 401 响应。非 index 文件仍是公开静态资源。Token、cookie、过期时间与签名记录语义都归 Connection 所有。
+
+### 可观察的失败
+
+遍历返回 403 而不是错误页。dist 根目录内不存在或不是文件的目标返回空 404，因此失效链接或拼错的 pathname 是显式失败，而不是静默的 SPA 回退。第二次占据席位会抛错，而席位无人占据时 webserver 返回 404——本插件的 fiber 被 dispose（资源释放）后，浏览器看到的就是该响应。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+### 设计理念
+
+本包是围绕 `serveStatic` 的一个函数插件：`apply` 从 `distIndex` 解析出 dist 根目录，构建一个对原始 `index.html` 运行 `ctx.webServer.renderIndex` 的 `renderIndex` 闭包，并在 effect 作用域下注册回退 handler。按 webserver 的约定，席位只有单一所有者——第二次注册会抛错——且受 effect 作用域约束，因此 dispose fiber 即释放席位。
+
+### 遍历栅栏
+
+`serveStatic` 规范化请求的 pathname 并拼接到 dist 根目录，然后要求目标就是根目录本身或保持在它之下。检查使用 `sep` 而非 `/`，因为 `resolve()` 在 Windows 上输出反斜杠路径，此时 `/` 后缀会把每个合法子路径都当作遍历拒绝。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `serveStatic` 与 `apply`：回退占据、遍历拒绝、index 渲染、MIME 表 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当服务约定不够用时阅读以下内容：先看席位所有者的约定，再看解析 dist 的组合与子系统参考。
+
+- [Webserver](../webserver/README.zh.md)——本插件占据的回退席位与它运行的 index 转换器。
+- [dsh-web-app 组合包](../../bundle/web-app/README.zh.md)——解析 `distIndex` 并挂载本插件的应用。
+- [HTTP 服务器子系统](../../../docs/subsystems/web-server.zh.md)——回退席位如何融入路由表。
+- [生成配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-host-frontend-static)——每个受支持配置字段及其源声明。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无。该 SPA dist 服务器只应答浏览器资产请求，不注册任何面向模型的内容。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明某个资产类别何时尚未被覆盖。它们是当前包约束，不是任务积压。
+
+- **初始 MIME 表很精简**：它覆盖 Vite 输出的资产集合及实际交付的 PWA manifest；其他扩展名在相应资产类别发布前都会回退到 `application/octet-stream`。
+- **Pathname 路由是显式声明**——当前客户端从根目录或配置的 index 路径进入，没有 History API pathname 路由。新增一条需要显式服务器规则与真实组合覆盖，而不是对每次未命中做宽泛回退。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>
+
+**运行时不变式：** 不发布伴生入口。唯一受本包所有的关系是单个回退席位，但无法从 teardown 流中探测它：`internal/plugin` 在正在释放的 fiber 执行 effect disposer 前触发，因此通知发出时合法所有者仍占据席位，任何占位探测都会把每次正确释放误报为失败；这不同于 webserver companion 对保留路径的探测，后者不会与存活注册冲突。席位的注册／释放对称性由本包真实组合的 HMR（热模块替换）安全测试覆盖。

package/lib/index.js

@@ -0,0 +1,99 @@
+import { readFile } from "node:fs/promises";
+import { dirname, extname, join, normalize, resolve, sep } from "node:path";
+import z from "@deepseek-ai/schemastery";
+//#region lib/types/index.js
+/**
+* @x1a0f3n9/dsh-host-frontend-static — SPA dist server over the webserver
+* fallback seat: serves the built frontend directory with explicit index
+* entry points. A readable index renders at the dist root and configured index
+* path; missing paths return 404, traversal outside the dist root is 403,
+* unknown extensions ship as octet-stream, and non-GET/HEAD is 405. Every
+* index response first passes Connection's browser authentication, then the
+* webserver's index render (structured injection rows, then raw taps).
+* Non-index assets stay public. The dist location is workspace knowledge of
+* the composing application, so `distIndex` is typically supplied through a
+* `!!js` expression, never hardcoded by a deployment.
+* @module @x1a0f3n9/dsh-host-frontend-static
+*/
+/** Stable Cordis plugin name. */
+const name = "frontend-static";
+/** Services required before the authenticated fallback seat can be claimed. */
+const inject = ["webServer", "connection"];
+const Config = z.object({ distIndex: z.string().required() });
+const HTML_MIME = "text/html; charset=utf-8";
+const MIME = {
+	".html": HTML_MIME,
+	".js": "text/javascript; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".svg": "image/svg+xml",
+	".json": "application/json",
+	".map": "application/json",
+	".webmanifest": "application/manifest+json",
+	".gz": "application/gzip"
+};
+const STATIC_MISS_CODES = new Set([
+	"ENOENT",
+	"EISDIR",
+	"ENOTDIR"
+]);
+/**
+* Serve one GET/HEAD static request from the dist root.
+* @param pathname - decoded URL pathname of the request.
+* @param res - the node:http response to write.
+* @param distRoot - absolute dist root directory (resolved by the caller).
+* @param distIndex - absolute path of index.html inside distRoot.
+* @param authorizeIndex - authenticates an index response before its bytes are read.
+* @param renderIndex - produces the index.html body (structured injection
+* rendering) for the dist root and configured index path.
+*/
+async function serveStatic(pathname, res, distRoot, distIndex, authorizeIndex, renderIndex) {
+	const target = resolve(normalize(join(distRoot, pathname)));
+	if (target !== distRoot && !target.startsWith(distRoot + sep)) {
+		res.writeHead(403);
+		res.end();
+		return;
+	}
+	let body;
+	let type;
+	try {
+		if (target === distRoot || target === distIndex) {
+			if (!authorizeIndex()) return;
+			body = await renderIndex();
+			type = HTML_MIME;
+		} else {
+			body = await readFile(target);
+			type = MIME[extname(target)] ?? "application/octet-stream";
+		}
+	} catch (error) {
+		if (!STATIC_MISS_CODES.has(error.code)) throw error;
+		res.writeHead(404);
+		res.end();
+		return;
+	}
+	res.writeHead(200, { "content-type": type });
+	res.end(body);
+}
+/**
+* Claim the webserver fallback seat and serve the dist.
+* @param ctx - plugin context carrying the webServer service.
+* @param config - validated {@link Config}.
+*/
+function apply(ctx, config) {
+	const distIndex = config.distIndex;
+	const distRoot = dirname(distIndex);
+	const renderIndex = async () => {
+		return ctx.webServer.renderIndex(await readFile(distIndex, "utf8")).replace(/<head(?:\s[^>]*)?>/i, (open) => `${open}<base href="/">`);
+	};
+	ctx.effect(() => ctx.webServer.registerFallback(async (req, res) => {
+		if (req.method !== "GET" && req.method !== "HEAD") {
+			res.writeHead(405);
+			res.end();
+			return;
+		}
+		/* v8 ignore next -- node:http always sets url on server requests */
+		const rawPath = new URL(req.url ?? "/", "http://x").pathname;
+		await serveStatic(decodeURIComponent(rawPath), res, distRoot, distIndex, () => ctx.connection.authorizeIndex(req, res), renderIndex);
+	}), "frontend-static: fallback seat");
+}
+//#endregion
+export { Config, apply, inject, name, serveStatic };

package/lib/types/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @x1a0f3n9/dsh-host-frontend-static — SPA dist server over the webserver
+ * fallback seat: serves the built frontend directory with explicit index
+ * entry points. A readable index renders at the dist root and configured index
+ * path; missing paths return 404, traversal outside the dist root is 403,
+ * unknown extensions ship as octet-stream, and non-GET/HEAD is 405. Every
+ * index response first passes Connection's browser authentication, then the
+ * webserver's index render (structured injection rows, then raw taps).
+ * Non-index assets stay public. The dist location is workspace knowledge of
+ * the composing application, so `distIndex` is typically supplied through a
+ * `!!js` expression, never hardcoded by a deployment.
+ * @module @x1a0f3n9/dsh-host-frontend-static
+ */
+import type { ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Stable Cordis plugin name. */
+export declare const name = "frontend-static";
+/** Services required before the authenticated fallback seat can be claimed. */
+export declare const inject: string[];
+/** Plugin config: the dist anchor. */
+export interface Config {
+    /** Absolute path of index.html inside the dist root. */
+    distIndex: string;
+}
+export declare const Config: z<Config>;
+/**
+ * Serve one GET/HEAD static request from the dist root.
+ * @param pathname - decoded URL pathname of the request.
+ * @param res - the node:http response to write.
+ * @param distRoot - absolute dist root directory (resolved by the caller).
+ * @param distIndex - absolute path of index.html inside distRoot.
+ * @param authorizeIndex - authenticates an index response before its bytes are read.
+ * @param renderIndex - produces the index.html body (structured injection
+ * rendering) for the dist root and configured index path.
+ */
+export declare function serveStatic(pathname: string, res: ServerResponse, distRoot: string, distIndex: string, authorizeIndex: () => boolean, renderIndex: () => Promise<string>): Promise<void>;
+/**
+ * Claim the webserver fallback seat and serve the dist.
+ * @param ctx - plugin context carrying the webServer service.
+ * @param config - validated {@link Config}.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@x1a0f3n9/dsh-host-frontend-static",
+  "description": "SPA dist server for the Web shell: owns the webserver fallback seat, serving explicit index entries and static assets with traversal rejection and 404 misses",
+  "version": "0.1.5-rc.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/host/frontend-static"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@x1a0f3n9/dsh-host-webserver": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-client-connection": "^0.1.5-rc.3",
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@x1a0f3n9/dsh-client-connection": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-credentials-local": "^0.1.5-rc.3",
+    "@x1a0f3n9/dsh-host-webserver": "^0.1.5-rc.3",
+    "@deepseek-ai/cordis": "^4.0.2"
+  }
+}