Skip to content

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.mjs
index 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.json
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.yaml
index 936170b0..109d0adf 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -435,6 +435,9 @@ importers:
tar:
specifier: ^7.5.21
version: 7.5.22
+ typescript:
+ specifier: ^5.6.0
+ version: 5.9.3
undici:
specifier: ^7.29.0
version: 7.29.0
@@ -466,9 +469,6 @@ importers:
tsx:
specifier: ^4.20.0
version: 4.22.4
- typescript:
- specifier: ^5.6.0
- version: 5.9.3
vitest:
specifier: ^3.2.6
diff --git a/scripts/deploy.mjs b/scripts/deploy.mjs
index 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 cannot
diff --git a/scripts/gen-ifaces.mjs b/scripts/gen-ifaces.mjs
index 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.mjs
new file mode 100644
index 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),
+ }));
+}