Fail loud on a null package.json and a stray plugins/package.json

src/plugin-host/discovery.test.ts

@@ -60,6 +60,10 @@ const badCases: Array<{ name: string; files: Record<string, string>; match: RegE
   { name: "a plugin shipping its own copy of the barrel", files: { "shadow/node_modules/@plainpages/plugin-api/index.js": `export class GuardError extends Error {}`, "shadow/plugin.ts": full("shadow") }, match: /shadow.*@plainpages\/plugin-api/s },
   { name: "a plugin package.json that forgets type: module", files: { "cjs/package.json": `{ "name": "cjs" }`, "cjs/plugin.ts": full("cjs") }, match: /cjs.*"type": "module"/s },
   { name: "a plugin package.json that is not valid JSON", files: { "bent/package.json": `{`, "bent/plugin.ts": full("bent") }, match: /bent.*package\.json.*JSON/s },
+  { name: "a plugin package.json holding null", files: { "nul/package.json": `null`, "nul/plugin.ts": full("nul") }, match: /nul.*"type": "module"/s },
+  // Written by the documented install command with one path segment dropped — and it would silently
+  // make every plugin below it part of its scope.
+  { name: "a package.json in the scan root itself", files: { "package.json": `{ "name": "oops" }`, "ok/plugin.ts": full("ok") }, match: /plugins\/package\.json must not exist/ },
   { name: "two plugins claim the public home", files: { "a/plugin.ts": `export default { apiVersion: "1.0.0", home: () => ({ html: "a" }) };`, "b/plugin.ts": `export default { apiVersion: "1.0.0", home: () => ({ html: "b" }) };` }, match: /home/ },
   { name: "two plugins claim the gated dashboard", files: { "a/plugin.ts": `export default { apiVersion: "1.0.0", dashboard: () => ({ html: "a" }) };`, "b/plugin.ts": `export default { apiVersion: "1.0.0", dashboard: () => ({ html: "b" }) };` }, match: /dashboard/ },
 ];
@@ -105,8 +109,8 @@ test("a plugin may declare `home` (public /) and `dashboard` (gated /dashboard)
   assert.equal(typeof plugins[0]?.dashboard, "function");
 });
 
-// The barrel still resolves from a folder holding its own package.json because host deps sit at
-// /node_modules, above every plugin scope (README → Plugin dependencies).
+// Host deps sit at /node_modules, above every plugin scope, so the barrel resolves from a folder
+// that has its own package.json (README → Plugin dependencies).
 test("a plugin may carry its own package.json, node_modules and dependencies", async (t) => {
   const dir = scaffold(t, {
     "shop/package.json": `{ "name": "shop", "version": "0.0.0", "type": "module", "dependencies": { "price-tag": "1.0.0" } }`,

src/plugin-host/discovery.ts

@@ -27,6 +27,10 @@ export async function discoverPlugins(options: DiscoverOptions = {}): Promise<Pl
   const errors: string[] = [];
   const plugins: Plugin[] = [];
 
+  if (existsSync(join(dir, "package.json"))) {
+    errors.push(`plugins/package.json must not exist — it becomes the package scope for every plugin below it; install into plugins/<id>, not plugins/`);
+  }
+
   for (const id of pluginFolders(dir)) {
     const fail = (msg: string): void => void errors.push(`plugins/${id}: ${msg}`);
 
@@ -89,9 +93,8 @@ function pluginFolders(dir: string): string[] {
     .sort();
 }
 
-// The two ways a plugin's own packaging breaks it. A barrel copy resolves before the host's, and its
-// GuardError matches no `instanceof` here — the sign-in redirect silently becomes a 500. Without a
-// `type`, which npm never writes, the folder is left CommonJS: a .js helper breaks, every .ts re-parses.
+// A barrel copy resolves before the host's, so its GuardError matches no `instanceof` here and a
+// sign-in redirect becomes a 500. A typeless folder re-parses every file it loads, and warns on each.
 function packagingError(folder: string): string | null {
   if (existsSync(join(folder, "node_modules", "@plainpages", "plugin-api"))) {
     return "ships its own copy of @plainpages/plugin-api — remove it; the host provides the one instance";
@@ -100,15 +103,15 @@ function packagingError(folder: string): string | null {
   const file = join(folder, "package.json");
   if (!existsSync(file)) return null;
 
-  let manifest: { type?: unknown };
+  let manifest: { type?: unknown } | null;
   try {
-    manifest = JSON.parse(readFileSync(file, "utf8")) as { type?: unknown };
+    manifest = JSON.parse(readFileSync(file, "utf8")) as { type?: unknown } | null;
   } catch (err) {
-    return `package.json is not valid JSON — ${messageOf(err)}`;
+    return `package.json could not be read as JSON — ${messageOf(err)}`;
   }
-  return manifest.type === "module"
+  return manifest?.type === "module"
     ? null
-    : `package.json must set "type": "module" — npm writes no type, which leaves the folder CommonJS`;
+    : `package.json must set "type": "module" — npm writes no type, and Node then re-parses every file in the folder`;
 }
 
 function asManifest(value: unknown): PluginManifest | null {

src/plugin-host/plugin-api.test.ts

@@ -5,8 +5,7 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import * as api from "./plugin-api.ts";
 
-// A plugin with its own package.json reaches the barrel only as a package; a second copy landing
-// there would fail every `instanceof GuardError` a handler makes.
+// Both specifiers must reach one module instance; the Dockerfile symlink is what makes them.
 test("the barrel resolves by package name to this same module", async () => {
   const asPackage = await import("@plainpages/plugin-api");