A local-first multi-agent app development platform, built on PenguinHarness
feat(server,desktop,scripts): a plugin's interfaces are compared with the platform's by the TypeScript compiler (#808)
Myriad-Dreamin15defbb6714d
diff --git a/changelog/unreleased/2026-09-20-plugin-interface-check.md b/changelog/unreleased/2026-09-20-plugin-interface-check.mdnew file mode 100644index 00000000..a481f193--- /dev/null+++ b/changelog/unreleased/2026-09-20-plugin-interface-check.md@@ -0,0 +1,18 @@+# A plugin's interfaces are compared with the platform's by the TypeScript compiler++- **Date:** 2026-09-20+- **Type:** feature+- **Scope:** `server`, `desktop`, `scripts`+- **PR:** [#808](https://github.com/Prism-Shadow/penguin-harness/pull/808)++[中文版](2026-09-20-plugin-interface-check.zh.md)++Whether a plugin package still fits the platform it is loaded into used to be answered by looking the interfaces it names up in the platform's own table — which compares a declaration with itself and can never fail. Each side now brings its own: the plugin the `ifaces.json` its package was generated with, the platform this generation's table. Each is rendered as a self-contained `.d.ts`, the questions become assignments in a third file, and the TypeScript compiler answers them, in both directions — the platform's interface must be assignable to what the plugin requires, and what the plugin provides must be assignable to what the platform asks for.++- A member the platform has dropped, or whose signature no longer fits, is a load error naming the module, the alias and the interface; a member the platform has gained breaks nothing.+- The plugin's table is never substituted: an interface either side holds no copy of is logged as *not compared*, never answered from the other's entry — both halves are counted, so the tally is the number of questions that went unanswered. (The generator does not yet copy host interfaces into a plugin's table, so today that is most of them — the log says so rather than reporting a pass.)+- An opaque type is compared by its name, the identity the table records: each side is rendered into its own file, so the brand is a plain property rather than a `unique symbol`, which would be a different symbol per file and would stop the platform fitting itself.+- A table the renderer cannot read costs the comparison, not the package: an unrenderable expression in the plugin's own table is *not compared*, with the reason, while one in the platform's own table is reported.+- Rendering is lossless or it refuses: a table expression with no TypeScript form is reported by name, never widened; a stream carries its return type, so a change to it is not invisible.+- The compiler is a runtime dependency of the server now, loaded the first time a comparison needs it and resolved beside the module, beside the running program, or in the pushed assets. A hot push carries it as `archives/typescript.tgz` (the compiler's entry and default libraries only), because the program on the target may predate the dependency; the desktop build stages it beside the server bundle, which has no `node_modules` of its own. On an installation that has none of the three, plugins load as before and the log says the comparison was not made.+- `gen-ifaces`: an optional member typed `unknown` (or `any`) keeps that type. Stripping `undefined` with `getNonNullableType` turned `unknown` into `{}`, which refuses `null`.diff --git a/changelog/unreleased/2026-09-20-plugin-interface-check.zh.md b/changelog/unreleased/2026-09-20-plugin-interface-check.zh.mdnew file mode 100644index 00000000..904630f4--- /dev/null+++ b/changelog/unreleased/2026-09-20-plugin-interface-check.zh.md@@ -0,0 +1,18 @@+# 插件的接口与平台的接口,交由 TypeScript 编译器比较++- **Date:** 2026-09-20+- **Type:** feature+- **Scope:** `server`, `desktop`, `scripts`+- **PR:** [#808](https://github.com/Prism-Shadow/penguin-harness/pull/808)++[English](2026-09-20-plugin-interface-check.md)++一个插件包是否仍然适配它被加载进去的平台,原先的判断方式是到平台自己的接口表里去查它提到的接口——这等于拿一份声明和它自己比较,永远不会失败。现在双方各带各的:插件带着它的包生成时的 `ifaces.json`,平台带着本代的接口表。两份表各自渲染成一份自包含的 `.d.ts`,要问的问题写成第三个文件里的赋值语句,由 TypeScript 编译器作答,而且是双向的——平台的接口必须能赋给插件所要求的,插件所提供的必须能赋给平台所要求的。++- 平台删掉的成员、或签名已不再匹配的成员,是一个加载错误,并指出模块、别名与接口;平台新增的成员不会破坏任何东西。+- 绝不拿另一侧的条目顶替:任何一侧没有副本的接口都记为**未比较**,两半都计数,所以数出来的就是没能作答的问题数。(生成器目前还不把宿主接口复制进插件的表,所以今天大多数都是这种情况——日志如实说明,而不是报成通过。)+- opaque 类型按名字比较,也就是表里记录的身份:两侧各渲染成一份文件,因此品牌用的是普通属性而非 `unique symbol`——后者每份文件里都是不同的符号,会让平台连自己都判不通过。+- 渲染不出来的表只让比较落空,不牵连包本身:插件自己的表里有无法渲染的表达式记为**未比较**并附原因,平台自己表里的则照常报告。+- 渲染要么无损、要么拒绝:表里无法写成 TypeScript 的表达式按名字报告,绝不放宽;流会带上它的返回类型,因此对它的改动不会不可见。+- 编译器现在是服务端的运行时依赖,在第一次需要比较时加载,依次在模块旁、正在运行的程序旁、推送的 assets 里解析。热推送把它作为 `archives/typescript.tgz` 一并带上(只含编译器入口与默认库),因为目标机器上的程序可能早于这项依赖;桌面构建把它放在服务端 bundle 旁边,因为 bundle 自己没有 `node_modules`。三处都找不到的安装上,插件照旧加载,日志会说明没有进行比较。+- `gen-ifaces`:类型为 `unknown`(或 `any`)的可选成员保持原类型。此前用 `getNonNullableType` 去掉 `undefined` 时,`unknown` 会变成 `{}`,而 `{}` 不接受 `null`。diff --git a/packages/desktop/scripts/build-assets.mjs b/packages/desktop/scripts/build-assets.mjsindex 13cb2203..b38af256 100644--- a/packages/desktop/scripts/build-assets.mjs+++ b/packages/desktop/scripts/build-assets.mjs@@ -113,6 +113,19 @@ if (hostBinding(ptyFiles) === undefined) {process.exit(1);}+// The compiler a plugin's interfaces are checked with, beside the server bundle for the same reason+// node-pty is: the bundle has no node_modules of its own, and the server resolves+// `typescript` from the program that is running.+const { typescriptPayload } = await import(+ pathToFileURL(path.resolve(pkgDir, "..", "..", "scripts", "typescript-payload.mjs")).href+);+const tsDest = path.join(pkgDir, "dist", "node_modules", "typescript");+fs.rmSync(tsDest, { recursive: true, force: true });+for (const { rel, abs } of typescriptPayload(path.resolve(pkgDir, "..", "server"))) {+ fs.mkdirSync(path.dirname(path.join(tsDest, rel)), { recursive: true });+ fs.copyFileSync(abs, path.join(tsDest, rel));+}+const { posixLauncherScript, windowsLauncherScript } = await import(pathToFileURL(launcherModule).href);diff --git a/packages/server/package.json b/packages/server/package.jsonindex 8f6e1048..70f98669 100644--- a/packages/server/package.json+++ b/packages/server/package.json@@ -81,6 +81,7 @@"remark-parse": "^11.0.0","smol-toml": "^1.3.0","tar": "^7.5.21",+ "typescript": "^5.6.0","undici": "^7.29.0","unified": "^11.0.5","ws": "^8.18.3",@@ -93,7 +94,6 @@"@types/ws": "^8.18.1","tsup": "^8.3.0","tsx": "^4.20.0",- "typescript": "^5.6.0","vitest": "^3.2.6"},"files": [diff --git a/packages/server/src/plugin/iface-check.ts b/packages/server/src/plugin/iface-check.tsnew file mode 100644index 00000000..5488103d--- /dev/null+++ b/packages/server/src/plugin/iface-check.ts@@ -0,0 +1,394 @@+/**+ * Do the interfaces a package was written against still fit this platform?+ *+ * A comparison needs two declarations. Looking both sides up in the platform's own table+ * compares a declaration with itself and can never fail, so here each side brings its own:+ * the CONSUMER's is the table the package carries — a plugin's generated `ifaces.json` —+ * and the PLATFORM's is this generation's. Nothing in+ * this module judges assignability itself: each table is rendered as a self-contained+ * `.d.ts`, the questions become assignments in a third file, and the TypeScript compiler+ * answers them —+ *+ * requires the platform's interface must be assignable to the consumer's view of it;+ * provides the consumer's view must be assignable to what the platform asks for.+ *+ * Two rules keep a pass meaningful. The consumer's table is never substituted: an+ * interface it does not carry is reported as uncompared, never answered from the platform's+ * entry. And rendering is lossless or it refuses: an expression this module cannot write as+ * TypeScript is reported by name, never widened to `unknown`.+ */+import os from "node:os";+import path from "node:path";+import type {+ IfaceDecl,+ IfaceTable,+ Manifest,+ Sig,+ TypeExpr,+} from "@prismshadow/penguin-core/kernel";+import type { TypeScript } from "./typescript.js";++export class IfaceRenderError extends Error {}++/** `<package>#<Export>` → its package; null for a reference with no package part. */+export function packageOf(key: string): string | null {+ const at = key.indexOf("#");+ return at <= 0 ? null : key.slice(0, at);+}++// ---- table → .d.ts ------------------------------------------------------------------++const WORDS = new Set([+ ..."string number boolean bigint symbol object null undefined unknown never true false Date".split(+ " ",+ ),+]);+const INFIX = new Set(["|", "&"]);+/** Opaque identities that name a type of TypeScript's own library (`lib#<Name>` in the table). */+const LIB_TYPES = new Set(["lib#Uint8Array"]);+const OPERATORS = new Set(["[]", "|", "&", "?", "=>", ":", "=", "@", "===", "keyof", "instanceof"]);++/** An arktype string expression is written as TypeScript already, for the subset checked here. */+function stringExpression(expr: string, where: string): string {+ const rest = expr+ .replace(/'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"/g, " ")+ .replace(/-?\b\d+(?:\.\d+)?\b/g, " ")+ .replace(/[A-Za-z_][A-Za-z0-9_]*/g, (word) => (WORDS.has(word) ? " " : word));+ if (!/^[\s|&()[\]]*$/.test(rest)) {+ throw new IfaceRenderError(+ `${where}: '${expr}' is not an expression this check can write as TypeScript`,+ );+ }+ return `(${expr})`;+}++/** Whether a parameter's type lets the argument be left out. */+function admitsUndefined(e: TypeExpr): boolean {+ if ("maybe" in e) return true;+ if ("oneOf" in e) return e.oneOf.some(admitsUndefined);+ if (!("data" in e)) return false;+ const inData = (d: unknown): boolean =>+ typeof d === "string"+ ? d.split("|").some((part) => part.trim() === "undefined")+ : Array.isArray(d) && d.length === 3 && d[1] === "|" && (inData(d[0]) || inData(d[2]));+ return inData(e.data);+}++const property = (name: string) => (/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name));++class Renderer {+ private readonly names = new Map<string, string>();+ private readonly taken = new Set<string>();+ private readonly out: string[] = [];+ private readonly done = new Set<string>();++ constructor(private readonly table: IfaceTable) {}++ /**+ * The identifier a table key is declared under: its export name (`…#SessionIndex` →+ * `SessionIndex`), numbered on a clash — so the text reads as a declaration file an author+ * can write against, and a diagnostic names the type the way its source does.+ */+ ident(key: string): string {+ let name = this.names.get(key);+ if (name !== undefined) return name;+ const base = key+ .slice(key.indexOf("#") + 1)+ .replace(/[^A-Za-z0-9]+/g, "_")+ .replace(/^_+|_+$/g, "")+ .replace(/^(\d)/, "_$1");+ name = base;+ for (let n = 2; this.taken.has(name); n++) name = `${base}_${n}`;+ this.taken.add(name);+ this.names.set(key, name);+ return name;+ }++ /** What was rendered, as a table of its own: the declared interfaces and all they reach. */+ readonly slice: IfaceTable = { ifaces: {}, types: {} };++ iface(key: string): string {+ const name = this.ident(`iface ${key}`);+ if (this.done.has(name)) return name;+ this.done.add(name);+ const decl = this.table.ifaces[key];+ if (decl === undefined) throw new IfaceRenderError(`'${key}' is not in the table`);+ this.slice.ifaces[key] = decl;+ this.out.push(this.interfaceText(name, key, decl));+ return name;+ }++ text(): string {+ return [+ // Branded by a plain, string-keyed property — never `unique symbol`. Each side is its+ // own file, and a `unique symbol` declared in each is two different symbols, so the+ // same opaque rendered on both sides would not be assignable to itself. The name is+ // the identity (core/src/kernel/markers.ts), which is what the table records.+ "type Opaque<Name extends string> = { readonly __opaque: Name };",+ ...this.out,+ ].join("\n");+ }++ private namedType(key: string): string {+ const name = this.ident(`type ${key}`);+ if (this.done.has(name)) return name;+ this.done.add(name);+ const def = this.table.types[key];+ if (def === undefined)+ throw new IfaceRenderError(`type '${key}' is referenced but not in the table`);+ this.slice.types[key] = def;+ // Reserve the slot first: a recursive type refers to itself by this name.+ const at = this.out.push("") - 1;+ this.out[at] = `export type ${name} = ${this.data(def, key)};`;+ return name;+ }++ private interfaceText(name: string, key: string, decl: IfaceDecl): string {+ // Members are PROPERTIES of function type: under strictFunctionTypes their parameters+ // are contravariant, the rule the module tree states. Method shorthand is bivariant+ // and would let a narrowed parameter through.+ const methods = Object.entries(decl.methods).map(+ ([m, sig]) => ` ${property(m)}: ${this.sig(sig, `${key}.${m}`)};`,+ );+ const fields = Object.entries(decl.fields ?? {}).map(+ ([f, e]) => ` ${property(f)}${"maybe" in e ? "?" : ""}: ${this.expr(e, `${key}.${f}`)};`,+ );+ return `export interface ${name} {\n${[...methods, ...fields].join("\n")}\n}`;+ }++ private sig(sig: Sig, where: string): string {+ // The table has no "optional parameter", only a type that admits undefined; trailing+ // ones are written back as optional, or `f()` would not type-check against `f(a?: T)`.+ let required = sig.params.length;+ while (required > 0 && admitsUndefined(sig.params[required - 1]!)) required--;+ const params = sig.params.map(+ (p, i) => `a${i}${i >= required ? "?" : ""}: ${this.expr(p, where)}`,+ );+ return `(${params.join(", ")}) => ${this.expr(sig.returns, where)}`;+ }++ private expr(e: TypeExpr, where: string): string {+ if ("data" in e) return this.data(e.data, where);+ if ("iface" in e) return this.iface(e.iface);+ if ("fn" in e) return `(${this.sig(e.fn, where)})`;+ if ("promise" in e) return `Promise<${this.expr(e.promise, where)}>`;+ if ("stream" in e)+ return e.returns === undefined+ ? `AsyncIterable<${this.expr(e.stream, where)}>`+ : `AsyncGenerator<${this.expr(e.stream, where)}, ${this.expr(e.returns, where)}>`;+ if ("void" in e) return "void";+ if ("array" in e) return `Array<${this.expr(e.array, where)}>`;+ if ("object" in e) {+ const optional = new Set(e.optional ?? []);+ const members = Object.entries(e.object).map(+ ([k, v]) => `${property(k)}${optional.has(k) ? "?" : ""}: ${this.expr(v, where)}`,+ );+ return `{ ${members.join("; ")} }`;+ }+ if ("maybe" in e) return `(${this.expr(e.maybe, where)} | null | undefined)`;+ if ("oneOf" in e) return `(${e.oneOf.map((x) => this.expr(x, where)).join(" | ")})`;+ // A type of the language's own library is the same type in every program: it is written+ // as itself, where a host-declared opaque is a brand nobody else can construct.+ if ("opaque" in e && LIB_TYPES.has(e.opaque)) return e.opaque.slice("lib#".length);+ if ("opaque" in e) return `Opaque<${JSON.stringify(e.opaque)}>`;+ throw new IfaceRenderError(+ `${where}: ${JSON.stringify(e).slice(0, 120)} has no TypeScript rendering`,+ );+ }++ /** An arktype definition (string expression, tuple expression or object form). */+ private data(def: unknown, where: string): string {+ if (typeof def === "string") return stringExpression(def, where);+ if (Array.isArray(def)) {+ if (def.length === 2 && def[1] === "[]") return `Array<${this.data(def[0], where)}>`;+ if (def.length === 3 && typeof def[1] === "string" && INFIX.has(def[1])) {+ return `(${this.data(def[0], where)} ${def[1]} ${this.data(def[2], where)})`;+ }+ if (!def.some((x) => typeof x === "string" && OPERATORS.has(x))) {+ return `[${def.map((x) => this.data(x, where)).join(", ")}]`;+ }+ } else if (def !== null && typeof def === "object") {+ const record = def as Record<string, unknown>;+ if (typeof record["$ref"] === "string") return this.namedType(record["$ref"]);+ const members = Object.entries(record).map(([k, v]) => {+ if (k === "[string]") return `[key: string]: ${this.data(v, where)}`;+ if (k === "+" || k === "..." || k.startsWith("[")) {+ throw new IfaceRenderError(`${where}: object key '${k}' has no TypeScript rendering`);+ }+ const optional = k.endsWith("?");+ return `${property(optional ? k.slice(0, -1) : k)}${optional ? "?" : ""}: ${this.data(v, where)}`;+ });+ return `{ ${members.join("; ")} }`;+ }+ throw new IfaceRenderError(+ `${where}: ${JSON.stringify(def).slice(0, 120)} has no TypeScript rendering`,+ );+ }+}++/**+ * A self-contained `.d.ts` declaring `keys` (and everything they reach) out of `table`,+ * with the part of the table it was made from.+ */+export function renderDts(+ table: IfaceTable,+ keys: readonly string[],+): { text: string; names: Map<string, string>; slice: IfaceTable } {+ const renderer = new Renderer(table);+ const names = new Map(keys.map((key) => [key, renderer.iface(key)]));+ return { text: renderer.text(), names, slice: renderer.slice };+}++// ---- the questions --------------------------------------------------------------------++export interface IfaceQuestion {+ /** The module asking, for the message. */+ module: string;+ alias: string;+ direction: "requires" | "provides";+ /** `<package>#<Export>`. */+ key: string;+}++/** The interfaces manifests name with a package part, as questions for the compiler. */+export function ifaceQuestions(manifests: readonly Manifest[]): IfaceQuestion[] {+ const out: IfaceQuestion[] = [];+ for (const m of manifests) {+ for (const [alias, need] of Object.entries(m.requires)) {+ if (packageOf(need.iface) === null) continue;+ out.push({ module: m.name, alias, direction: "requires", key: need.iface });+ }+ for (const [alias, ref] of Object.entries(m.provides)) {+ if (packageOf(ref) === null) continue;+ out.push({ module: m.name, alias, direction: "provides", key: ref });+ }+ }+ return out;+}++export interface IfaceCheckResult {+ /** Why the package does not fit; empty when every comparison passed. */+ problems: string[];+ /** Interfaces that could not be compared: the consumer's table carries no copy of them. */+ uncompared: string[];+}++/**+ * Answers every question with the compiler. A question about an interface this platform+ * does not declare is not one for here (the tree check names it). One the consumer's table+ * does not carry cannot be compared, and is never answered from the platform's own entry:+ * it is reported as `uncompared`, and whether that is a failure is the caller's rule.+ */+export function checkIfaces(+ ts: TypeScript,+ platform: IfaceTable,+ consumer: IfaceTable,+ questions: readonly IfaceQuestion[],+): IfaceCheckResult {+ const problems: string[] = [];+ const uncompared: string[] = [];+ const label = (q: IfaceQuestion) => `${q.module}: ${q.direction}.${q.alias} '${q.key}'`;+ const base = path.join(os.tmpdir(), "penguin-iface-check");+ const files = new Map<string, string>();+ const asked = questions.filter((q) => {+ // Either side missing its copy means there is nothing to compare — and it is recorded,+ // never answered from the other side's entry. Both are counted, so the log's tally is+ // the number of questions that went unanswered rather than half of it.+ if (platform.ifaces[q.key] === undefined || consumer.ifaces[q.key] === undefined) {+ uncompared.push(label(q));+ return false;+ }+ return true;+ });+ if (asked.length === 0) return { problems, uncompared };++ const keys = [...new Set(asked.map((q) => q.key))];+ let ours: ReturnType<typeof renderDts>;+ let theirs: ReturnType<typeof renderDts>;+ try {+ ours = renderDts(platform, keys);+ } catch (err) {+ // The platform's own table: a rendering fault here is ours, and the caller hears it.+ problems.push(`interface check: ${err instanceof Error ? err.message : String(err)}`);+ return { problems, uncompared };+ }+ try {+ theirs = renderDts(consumer, keys);+ } catch (err) {+ // The package's table. A platform must not take a package away from a machine for+ // something the package did not do (plugin/loader.ts), and an expression this renderer+ // cannot write is exactly that: not compared, said out loud, never a refusal.+ const why = err instanceof Error ? err.message : String(err);+ for (const q of asked) uncompared.push(`${label(q)} (${why})`);+ return { problems, uncompared };+ }+ files.set(path.join(base, "platform.d.ts"), ours.text);+ files.set(path.join(base, "consumer.d.ts"), theirs.text);+ const lines = [+ `import type * as P from "./platform.js";`,+ `import type * as C from "./consumer.js";`,+ // One question per line: the diagnostic's line number names the question.+ ...asked.map((q, n) => {+ const [from, to] =+ q.direction === "requires"+ ? [`P.${ours.names.get(q.key)}`, `C.${theirs.names.get(q.key)}`]+ : [`C.${theirs.names.get(q.key)}`, `P.${ours.names.get(q.key)}`];+ return `declare const q${n}: ${from}; export const a${n}: ${to} = q${n};`;+ }),+ ];++ const checkFile = path.join(base, "check.ts");+ files.set(checkFile, lines.join("\n") + "\n");+ const firstQuestionLine = lines.length - asked.length;+ const options: import("typescript").CompilerOptions = {+ strict: true,+ noEmit: true,+ types: [],+ target: ts.ScriptTarget.ES2022,+ // The language's own library without the DOM: the rendered tables use Promise, Array,+ // AsyncIterable and the typed arrays, and parsing lib.dom.d.ts on every check is the+ // largest single cost of one.+ lib: ["lib.es2022.d.ts"],+ module: ts.ModuleKind.NodeNext,+ moduleResolution: ts.ModuleResolutionKind.NodeNext,+ };+ const host = ts.createCompilerHost(options);+ const { fileExists, readFile, getSourceFile } = host;+ const virtual = (file: string) => files.get(path.resolve(file));+ // The files exist only here; the resolver asks about their directory before it asks about them.+ const directoryExists = host.directoryExists;+ host.directoryExists = (dir) =>+ path.resolve(dir) === base || (directoryExists?.call(host, dir) ?? true);+ host.fileExists = (file) => virtual(file) !== undefined || fileExists.call(host, file);+ host.readFile = (file) => virtual(file) ?? readFile.call(host, file);+ host.getSourceFile = (file, languageVersion, ...rest) => {+ const text = virtual(file);+ return text === undefined+ ? getSourceFile.call(host, file, languageVersion, ...rest)+ : ts.createSourceFile(file, text, languageVersion, true);+ };+ const program = ts.createProgram([checkFile], options, host);+ for (const d of ts.getPreEmitDiagnostics(program)) {+ const text = ts+ .flattenDiagnosticMessageText(d.messageText, "\n ")+ .replace(/import\("[^"]*"(?:, \{[^}]*\{[^}]*\} \})?\)\./g, "");+ const line =+ d.file && d.start !== undefined ? d.file.getLineAndCharacterOfPosition(d.start).line : -1;+ const q =+ d.file && path.resolve(d.file.fileName) === checkFile+ ? asked[line - firstQuestionLine]+ : undefined;+ if (q === undefined) {+ problems.push(`interface check: TS${d.code} ${text}`);+ continue;+ }+ problems.push(+ `${label(q)}: ${+ q.direction === "requires"+ ? "this platform's interface does not fit the version the package was written against"+ : "the version the package was written against does not fit what this platform asks for"+ }\n TS${d.code} ${text}`,+ );+ }+ return { problems, uncompared };+}diff --git a/packages/server/src/plugin/loader.ts b/packages/server/src/plugin/loader.tsindex 95a46df7..e47b9740 100644--- a/packages/server/src/plugin/loader.ts+++ b/packages/server/src/plugin/loader.ts@@ -41,6 +41,9 @@ import { readManifest } from "../hmr/manifest.js";import type { Plugin } from "@prismshadow/penguin-core/plugin";import type { LoadedPlugin } from "./host.js";import { PluginHost, pluginHostFrom } from "./host.js";+import platformTable from "../ifaces.json" with { type: "json" };+import { checkIfaces, ifaceQuestions } from "./iface-check.js";+import { loadTypeScript, TypeScriptUnavailable, type TypeScript } from "./typescript.js";/*** Where a Project's list lives, for a surface that has to name the file. The data root's@@ -456,6 +459,46 @@ async function readPackageTable(file: string | null): Promise<{}}+/**+ * Whether the host interfaces this package compiled against — its own table copies them —+ * still fit this platform's, both for what its modules require and for what they provide.+ * The tree check cannot say: it looks a key up in one merged table, where the host's entry+ * stands, so it would compare the platform's declaration with itself.+ *+ * Two things can leave an interface uncompared, and neither fails the load — a pushed+ * platform must not take plugins away from a machine for something the plugin did not do:+ * a table that carries no copy of a host interface (the generator only writes the+ * interfaces a package DECLARES, so today that is every host interface a plugin requires),+ * and an installation whose program predates the compiler being a dependency. Both are+ * logged; an interface the table does carry, and that no longer fits, fails the load.+ */+let compilerMissingLogged = false;+async function interfaceMisfits(+ specifier: string,+ own: IfaceTable,+ defs: readonly ModuleDef[],+ assets: string | null,+): Promise<string[]> {+ const questions = ifaceQuestions(defs.map((d) => d.manifest));+ if (questions.length === 0) return [];+ let ts: TypeScript;+ try {+ ts = await loadTypeScript(assets);+ } catch (err) {+ if (!(err instanceof TypeScriptUnavailable)) throw err;+ if (!compilerMissingLogged) console.warn(`[plugins] interfaces not compared: ${err.message}`);+ compilerMissingLogged = true;+ return [];+ }+ const fit = checkIfaces(ts, platformTable as unknown as IfaceTable, own, questions);+ if (fit.uncompared.length > 0) {+ console.warn(+ `[plugins] ${specifier}: ${fit.uncompared.length} interface(s) not compared — its table carries no copy of them`,+ );+ }+ return fit.problems;+}+/** The package's default export as a Plugin, or null when it is not one. */function asPlugin(module: unknown): Plugin | null {const def = (module as { default?: unknown }).default;@@ -503,10 +546,8 @@ export async function loadPlugins(reuse: ReadonlyMap<string, LoadedPlugin> = new Map(),): Promise<PluginLoadResult> {const failed = new Map<string, string>();- const bases = pluginBases(- root,- assetsDir === undefined ? await committedAssetsDir(root) : assetsDir,- );+ const pushedAssets = assetsDir === undefined ? await committedAssetsDir(root) : assetsDir;+ const bases = pluginBases(root, pushedAssets);// The closure over this root's Projects, and nothing else. A plugin the BUILD ships is// available without a download — that is what `builtin` means — but availability is not// consent: it loads when a Project asks for it, like every other plugin.@@ -568,6 +609,13 @@ export async function loadPlugins(});const modules = pair(plugin.modules);const replaces = pair(plugin.replaces);+ const misfits = await interfaceMisfits(+ specifier,+ read.ifaces,+ [...modules, ...replaces],+ pushedAssets,+ );+ if (misfits.length > 0) throw new Error(misfits.join("\n"));loaded.push({ specifier, file, stamp, modules, replaces, ifaces: read.ifaces });} catch (err) {failed.set(specifier, err instanceof Error ? err.message : String(err));diff --git a/packages/server/src/plugin/typescript.ts b/packages/server/src/plugin/typescript.tsnew file mode 100644index 00000000..04a6e13c--- /dev/null+++ b/packages/server/src/plugin/typescript.ts@@ -0,0 +1,53 @@+/**+ * The TypeScript compiler, loaded when something first needs it.+ *+ * The compiler decides whether the interfaces a package was written against still fit this+ * platform (./iface-check.ts). It is a dependency of this package, but the platform also runs as a single pushed bundle that sits outside any+ * `node_modules`, on machines whose program may predate that dependency — so the specifier+ * is kept out of the bundler's sight and resolved at run time, in three places: beside this+ * module, beside the program that is running, and in the assets the push carried it in+ * (scripts/typescript-payload.mjs), the way node-pty is found.+ */+import { createRequire } from "node:module";+import path from "node:path";+import { pathToFileURL } from "node:url";+import { unpackedAssetsDir } from "../hmr/asset-archives.js";++export type TypeScript = typeof import("typescript");++export class TypeScriptUnavailable extends Error {}++let loading: Promise<TypeScript> | null = null;++async function resolveAndImport(assets: string | null): Promise<TypeScript> {+ // A variable, not a literal: the platform bundle must not inline nine megabytes of compiler.+ const specifier = "typescript";+ const tried: string[] = [];+ const bases = [+ import.meta.url,+ ...(process.argv[1] ? [pathToFileURL(process.argv[1]).href] : []),+ // A push carries the compiler as an archive; it is unpacked before it is resolved.+ ...(assets === null ? [] : [path.join(unpackedAssetsDir(assets), "index.mjs")]),+ ];+ for (const base of bases) {+ try {+ const file = createRequire(base).resolve(specifier);+ const mod = (await import(pathToFileURL(file).href)) as { default?: TypeScript } & TypeScript;+ return mod.default ?? mod;+ } catch (err) {+ tried.push(`${base}: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`);+ }+ }+ throw new TypeScriptUnavailable(+ `the TypeScript compiler is not available in this installation (${tried.join("; ")})`,+ );+}++/** `assets` is the pushed build's assets directory (the hmr capability's `assetsDir()`), when there is one. */+export function loadTypeScript(assets: string | null = null): Promise<TypeScript> {+ loading ??= resolveAndImport(assets).catch((err) => {+ loading = null;+ throw err;+ });+ return loading;+}diff --git a/packages/server/test/iface-check.test.ts b/packages/server/test/iface-check.test.tsnew file mode 100644index 00000000..26b6ff04--- /dev/null+++ b/packages/server/test/iface-check.test.ts@@ -0,0 +1,148 @@+/**+ * The interface comparison a plugin package gets at load: its OWN table against this+ * platform's, decided by the TypeScript compiler, both for what it requires and for what+ * it provides.+ */+import { describe, expect, it } from "vitest";+import ts from "typescript";+import { parseManifest } from "@prismshadow/penguin-core/kernel";+import type { IfaceTable } from "@prismshadow/penguin-core/kernel";+import platformTable from "../src/ifaces.json" with { type: "json" };+import { checkIfaces, ifaceQuestions, renderDts } from "../src/plugin/iface-check.js";++const platform = platformTable as unknown as IfaceTable;+const LOG = "@prismshadow/penguin-server#Log";+const MAIN = "@prismshadow/penguin-server#AgentConfigService";++const manifest = parseManifest({+ name: "Demo",+ requires: { log: { iface: LOG }, local: { iface: "Sibling" } },+ provides: { main: MAIN },+});++/** The platform's table as the package would have copied it when it was compiled. */+function compiledAgainst(edit: (table: IfaceTable) => void): IfaceTable {+ const table = structuredClone(platform);+ edit(table);+ return table;+}++describe("interface check", () => {+ it("asks about the interfaces a manifest names with a package part, in both directions", () => {+ expect(ifaceQuestions([manifest])).toEqual([+ { module: "Demo", alias: "log", direction: "requires", key: LOG },+ { module: "Demo", alias: "main", direction: "provides", key: MAIN },+ ]);+ });++ it("passes a package compiled against this very platform", () => {+ expect(checkIfaces(ts, platform, platform, ifaceQuestions([manifest]))).toEqual({+ problems: [],+ uncompared: [],+ });+ });++ it("names a required interface that no longer fits, and a provided one", () => {+ const own = compiledAgainst((t) => {+ t.ifaces[LOG]!.methods["line"]!.params = [{ data: "number" }];+ t.ifaces[MAIN]!.methods["exists"]!.returns = { promise: { data: "string" } };+ });+ const { problems } = checkIfaces(ts, platform, own, ifaceQuestions([manifest]));+ expect(problems).toHaveLength(2);+ expect(problems[0]).toContain(`Demo: requires.log '${LOG}'`);+ expect(problems[0]).toContain("TS2322");+ expect(problems[1]).toContain(`Demo: provides.main '${MAIN}'`);+ });++ it("lets the platform grow: a member the package never knew breaks nothing", () => {+ const own = compiledAgainst((t) => {+ t.ifaces[LOG]!.methods = { line: t.ifaces[LOG]!.methods["line"]! };+ });+ expect(checkIfaces(ts, platform, own, ifaceQuestions([manifest])).problems).toEqual([]);+ });++ it("never answers from the platform's entry when the package's table lacks one", () => {+ const own = compiledAgainst((t) => {+ delete t.ifaces[LOG];+ });+ // It is reported as uncompared; whether that fails the load is the caller's rule (a+ // plugin's — whose table the generator does not fill yet — does not).+ expect(checkIfaces(ts, platform, own, ifaceQuestions([manifest]))).toEqual({+ problems: [],+ uncompared: [`Demo: requires.log '${LOG}'`],+ });+ });++ it("compares an opaque by its name: the same table on both sides is not a mismatch", () => {+ // Each side is rendered into its own file, so a brand keyed by `unique symbol` would be+ // two different symbols and the platform would stop fitting ITSELF. 43 of the table's+ // interfaces carry a non-library opaque, so this is the common case, not a corner.+ const opaque = "@prismshadow/penguin-server#TerminalSession";+ const withOpaque = compiledAgainst((t) => {+ t.ifaces[LOG]!.methods["line"]!.params = [{ opaque }];+ });+ expect(checkIfaces(ts, withOpaque, withOpaque, ifaceQuestions([manifest]))).toEqual({+ problems: [],+ uncompared: [],+ });+ // …and a DIFFERENT opaque is still a mismatch: the name is the identity.+ const renamed = compiledAgainst((t) => {+ t.ifaces[LOG]!.methods["line"]!.params = [{ opaque: "@prismshadow/penguin-server#Other" }];+ });+ const { problems } = checkIfaces(ts, withOpaque, renamed, ifaceQuestions([manifest]));+ expect(problems).toHaveLength(1);+ expect(problems[0]).toContain(`Demo: requires.log '${LOG}'`);+ });++ it("carries a stream's return type, so a change to it is not invisible", () => {+ const streaming = compiledAgainst((t) => {+ t.ifaces[LOG]!.methods["line"]!.returns = {+ stream: { data: "string" },+ returns: { data: "string" },+ };+ });+ const changed = compiledAgainst((t) => {+ t.ifaces[LOG]!.methods["line"]!.returns = {+ stream: { data: "string" },+ returns: { data: "number" },+ };+ });+ expect(renderDts(streaming, [LOG]).text).toContain("AsyncGenerator<");+ expect(checkIfaces(ts, streaming, changed, ifaceQuestions([manifest])).problems).toHaveLength(+ 1,+ );+ });++ it("records a provided interface this platform does not know, rather than dropping it", () => {+ const own = compiledAgainst(() => undefined);+ const gone = compiledAgainst((t) => {+ delete t.ifaces[MAIN];+ });+ // Both halves are counted, so the caller's tally is the number of questions unanswered.+ expect(checkIfaces(ts, gone, own, ifaceQuestions([manifest]))).toEqual({+ problems: [],+ uncompared: [`Demo: provides.main '${MAIN}'`],+ });+ });++ it("does not refuse a package whose own table this renderer cannot read", () => {+ const odd = compiledAgainst((t) => {+ t.ifaces[LOG]!.methods["line"]!.params = [{ data: "number.integer" }];+ });+ const { problems, uncompared } = checkIfaces(ts, platform, odd, ifaceQuestions([manifest]));+ expect(problems).toEqual([]);+ expect(uncompared.join(" ")).toContain("number.integer");+ });++ it("renders every interface of the platform's table, refusing nothing it carries", () => {+ const keys = Object.keys(platform.ifaces);+ const { text, names } = renderDts(platform, keys);+ expect(names.size).toBe(keys.length);+ expect(text).not.toContain("never");+ // A construct with no TypeScript rendering is refused by name, not widened.+ const odd = compiledAgainst((t) => {+ t.ifaces[LOG]!.methods["line"]!.params = [{ data: "number.integer" }];+ });+ expect(() => renderDts(odd, [LOG])).toThrow(/number\.integer/);+ });+});diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 936170b0..109d0adf 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -435,6 +435,9 @@ importers:tar:specifier: ^7.5.21version: 7.5.22+ typescript:+ specifier: ^5.6.0+ version: 5.9.3undici:specifier: ^7.29.0version: 7.29.0@@ -466,9 +469,6 @@ importers:tsx:specifier: ^4.20.0version: 4.22.4- typescript:- specifier: ^5.6.0- version: 5.9.3vitest:specifier: ^3.2.6version: 3.2.7(@types/[email protected])(@types/[email protected])([email protected])([email protected])([email protected])([email protected])([email protected])diff --git a/scripts/deploy.mjs b/scripts/deploy.mjsindex c95d65f9..66df4608 100644--- a/scripts/deploy.mjs+++ b/scripts/deploy.mjs@@ -32,6 +32,7 @@ import { ESM_CJS_BANNER } from "./esm-cjs-banner.mjs";import { FAR_SIDE_SCRIPTS } from "./far-side-scripts.mjs";import { buildBuiltinPlugins } from "./build-plugins.mjs";import { archiveName, packArchive, prefixPackages } from "./asset-archives.mjs";+import { typescriptPayload } from "./typescript-payload.mjs";import { createHash } from "node:crypto";const require = createRequire(import.meta.url);@@ -256,6 +257,17 @@ async function readNativeAssets() {// small files is hundreds of blobs, probes and transfers, and stalls. The platform unpacks// `archives/*.tgz` before resolving anything from its assets (hmr/asset-archives.ts).files[`archives/${archiveName("", "node-pty")}`] = await packArchive(pty);+ // The compiler a plugin's interfaces are checked with: the target's program may predate it+ // being a dependency (or be a desktop bundle with no node_modules), and a platform that+ // cannot find it makes no comparison. Content-addressed like everything here, so it+ // crosses once.+ files[`archives/${archiveName("", "typescript")}`] = await packArchive(+ typescriptPayload(path.join(ROOT, "packages", "server")).map(({ rel, abs }) => ({+ rel: `node_modules/typescript/${rel}`,+ abs,+ exec: false,+ })),+ );// The scripts that run on the FAR side — the release installers a remote install feeds// over, the one thing that has to arrive before the CLI does. A pushed bundle resolves them// from its own assets directory, so a push that omits one leaves a server that cannotdiff --git a/scripts/gen-ifaces.mjs b/scripts/gen-ifaces.mjsindex 04b52690..3f12fa6d 100644--- a/scripts/gen-ifaces.mjs+++ b/scripts/gen-ifaces.mjs@@ -423,8 +423,14 @@ for (const project of projects) {* undefined must not pass. The checker can only strip both at once, so null is noted* here and put back on the projected definition by `orNull` / `exprOrNull`.*/+ // `getNonNullableType(unknown)` is `{}` — everything that is not null or undefined — so an+ // optional `unknown` member (a JSON body, say) used to be projected as the empty object+ // shape, which refuses `null`. `unknown` and `any` have nothing to strip: keep them.const sansUndefined = (type) => ({- type: checker.getNonNullableType(type),+ type:+ type.flags & (ts.TypeFlags.Unknown | ts.TypeFlags.Any)+ ? type+ : checker.getNonNullableType(type),nullable: type.isUnion() && hasNull(type),});const orNull = (def) =>diff --git a/scripts/typescript-payload.mjs b/scripts/typescript-payload.mjsnew file mode 100644index 00000000..1397b233--- /dev/null+++ b/scripts/typescript-payload.mjs@@ -0,0 +1,34 @@+/**+ * The TypeScript compiler as something a build carries.+ *+ * The server lets the compiler decide whether a package's interfaces still fit the platform+ * (packages/server/src/plugin/typescript.ts). It+ * is a dependency of the server package, which covers an npm install and a checkout — but a+ * hot push lands on machines whose program was installed before that, and the desktop build+ * bundles the server into one file with no `node_modules` of its own. Both therefore carry+ * the compiler themselves, the way they carry node-pty: the push as one archive in its+ * assets, the desktop build staged beside the server bundle.+ *+ * Only what the compiler reads at run time: its entry and the default library files a+ * program is checked against. The language service, the tsc CLI, the locale catalogues and+ * the type declarations of the API itself are most of the package and none of it is loaded.+ */+import { createRequire } from "node:module";+import fs from "node:fs";+import path from "node:path";++/** `[{ rel, abs }]` for the compiler resolved from `serverDir`, `rel` relative to the package. */+export function typescriptPayload(serverDir) {+ const dir = path.dirname(+ createRequire(path.resolve(serverDir, "package.json")).resolve("typescript/package.json"),+ );+ const lib = fs+ .readdirSync(path.join(dir, "lib"))+ .filter((name) => name === "typescript.js" || /^lib\..*\.d\.ts$/.test(name))+ .sort();+ if (!lib.includes("typescript.js")) throw new Error(`${dir}: no lib/typescript.js`);+ return ["package.json", ...lib.map((name) => `lib/${name}`)].map((rel) => ({+ rel,+ abs: path.join(dir, rel),+ }));+}