@monotykamary/dsh-host-frontend-static 0.1.0-rc.10

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: a8cba9233a694c4f257c1d7197d7247e80e066ac
+README.zh.md: 2d2a53a49003896fbf19ca571d05b0af4e2d3eb3

package/README.md

@@ -0,0 +1,19 @@
+# `@monotykamary/dsh-host-frontend-static`
+
+English | [中文](README.zh.md)
+
+SPA dist server for the Web shell: a function plugin (config `{distIndex}`) that claims the [webserver](../webserver/README.md)'s single fallback seat and serves the built frontend directory with the shell's locked semantics — traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), unknown extensions ship as `application/octet-stream`, and non-GET/HEAD without a matching named route is 405. Every index response runs through the webserver's registered index taps (`applyIndexTaps`), which is how the boot manifest reaches the page. `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.
+
+The fallback seat is single-owner (a second claim throws) and effect-scoped: disposing the plugin's fiber releases the seat, after which the unclaimed webserver answers 404.
+
+## Model Experience
+
+None, as the package serves browser assets; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **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 actually ships.

package/README.zh.md

@@ -0,0 +1,19 @@
+# `@monotykamary/dsh-host-frontend-static`
+
+[English](README.md) | 中文
+
+Web 壳的 SPA dist 服务器：一个函数插件（配置为 `{distIndex}`），占据 [webserver](../webserver/README.md) 的唯一回退席位，并按壳层锁定的语义服务已构建的前端目录——越出 dist 根目录的遍历返回 403，任何未命中项都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 `application/octet-stream` 提供，GET／HEAD 之外的方法在没有匹配的具名路由时返回 405。每个 index 响应都会经过 webserver 已注册的 index 转换器（`applyIndexTaps`），启动 manifest（元数据清单）就是经这条路径送达页面的。`distIndex` 是组合应用的组装事实：[`dsh-web-app`](../../bundle/web-app/README.md) 通过前端包的 exports 解析它并挂载本插件；部署绝不硬编码它。
+
+回退席位只有单一所有者（第二次占据会抛错），并受 effect 作用域约束：dispose（资源释放）插件的 fiber 会释放席位，此后无人占据的 webserver 回答 404。
+
+## 模型体验
+
+无。该包只服务浏览器资产；其中没有任何内容会进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+- **初始 MIME 表很精简**：它覆盖 Vite 输出的资产集合及实际交付的 PWA manifest；其他扩展名在相应资产类别实际发布前都会回退到 `application/octet-stream`。

package/lib/index.js

@@ -0,0 +1,85 @@
+import { readFile } from "node:fs/promises";
+import { dirname, extname, join, normalize, resolve, sep } from "node:path";
+import z from "@monotykamary/schemastery";
+//#region lib/types/index.js
+/**
+* @monotykamary/dsh-host-frontend-static — SPA dist server over the webserver
+* fallback seat: serves the built frontend directory with the semantics the
+* Web shell locked at step1 — traversal outside the dist root is 403, any
+* miss falls back to index.html with HTTP 200 (SPA routing), unknown
+* extensions ship as octet-stream, non-GET/HEAD is 405. Every index response
+* runs through the webserver's registered index taps (boot-manifest
+* injection). 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 @monotykamary/dsh-host-frontend-static
+*/
+/** Stable Cordis plugin name. */
+const name = "frontend-static";
+/** Service required before the fallback seat can be claimed. */
+const inject = ["webServer"];
+const Config = z.object({ distIndex: z.string().required() });
+const MIME = {
+	".html": "text/html; charset=utf-8",
+	".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"
+};
+/**
+* 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 renderIndex - produces the index.html body (index-tap injection) for
+* `/` and every SPA fallback.
+*/
+async function serveStatic(pathname, res, distRoot, distIndex, renderIndex) {
+	const target = resolve(normalize(join(distRoot, pathname)));
+	if (target !== distRoot && !target.startsWith(distRoot + sep)) {
+		res.writeHead(403);
+		res.end();
+		return;
+	}
+	const serveIndex = async () => {
+		const body = await renderIndex();
+		res.writeHead(200, { "content-type": MIME[".html"] });
+		res.end(body);
+	};
+	if (target === distRoot || target === distIndex) {
+		await serveIndex();
+		return;
+	}
+	try {
+		const body = await readFile(target);
+		res.writeHead(200, { "content-type": MIME[extname(target)] ?? "application/octet-stream" });
+		res.end(body);
+	} catch {
+		await serveIndex();
+	}
+}
+/**
+* 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 () => ctx.webServer.applyIndexTaps(await readFile(distIndex, "utf8"));
+	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, renderIndex);
+	}), "frontend-static: fallback seat");
+}
+//#endregion
+export { Config, apply, inject, name, serveStatic };

package/lib/invariant.js

@@ -0,0 +1,29 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@monotykamary/dsh-host-frontend-static`.
+* @module @monotykamary/dsh-host-frontend-static/invariant
+*/
+const PACKAGE_NAME = "@monotykamary/dsh-host-frontend-static";
+/** Cordis companion plugin name. */
+const name = "host-frontend-static-invariant";
+/** Service required before the companion can register. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: 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.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @monotykamary/dsh-host-frontend-static — SPA dist server over the webserver
+ * fallback seat: serves the built frontend directory with the semantics the
+ * Web shell locked at step1 — traversal outside the dist root is 403, any
+ * miss falls back to index.html with HTTP 200 (SPA routing), unknown
+ * extensions ship as octet-stream, non-GET/HEAD is 405. Every index response
+ * runs through the webserver's registered index taps (boot-manifest
+ * injection). 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 @monotykamary/dsh-host-frontend-static
+ */
+import type { ServerResponse } from 'node:http';
+import type { Context } from '@monotykamary/cordis';
+import z from '@monotykamary/schemastery';
+/** Stable Cordis plugin name. */
+export declare const name = "frontend-static";
+/** Service required before the 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 renderIndex - produces the index.html body (index-tap injection) for
+ * `/` and every SPA fallback.
+ */
+export declare function serveStatic(pathname: string, res: ServerResponse, distRoot: string, distIndex: string, 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/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@monotykamary/dsh-host-frontend-static`.
+ * @module @monotykamary/dsh-host-frontend-static/invariant
+ */
+import type { Context } from '@monotykamary/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "host-frontend-static-invariant";
+/** Service required before the companion can register. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@monotykamary/dsh-host-frontend-static",
+  "description": "SPA dist server for the Web shell: owns the webserver fallback seat, serving the built frontend with index-tap injection, traversal rejection, and SPA index fallback",
+  "version": "0.1.0-rc.10",
+  "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"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@monotykamary/dsh-host-webserver": "^0.1.0-rc.10",
+    "@monotykamary/dsh-invariants": "^0.1.0-rc.10",
+    "@monotykamary/cordis": "^4.0.1"
+  },
+  "dependencies": {
+    "@monotykamary/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@monotykamary/cordis-plugin-loader": "^1.0.2",
+    "@monotykamary/dsh-host-webserver": "^0.1.0-rc.10",
+    "@monotykamary/dsh-invariants": "^0.1.0-rc.10",
+    "@monotykamary/cordis": "^4.0.1"
+  }
+}