Files
stack/packages/plugins/src/loader.mjs
T
jason.woltjeandClaude Opus 5.5 eaeb5ebf2b plugins: the plug-in layer, kind registry and loader (row 131, #1626)
packages/plugins holds the kind registry and the loader for in-repo
plug-in modules (REQ-PLUG-1). The first two kinds are usage-source and
limit-check (REQ-LIMIT-4). The business file's plugins key turns modules
on per kind, through plugin-settings.mjs and step 5's write path
(REQ-ROLE-3). A refused load is logged and keeps the kind's old modules.
Any filesystem error other than ENOENT or ENOTDIR refuses as unreadable.
The organization writer validates the bytes it writes as well as the
document. stack-copy ships packages/plugins. Nothing is wired into a
host process yet.

Candidate 466c835f7dce79d20c7ab74c197a52b70e7fdeb0efae0456222dc6d0a633f219,
Dewey packet 80797a539 (round 2), base 0bdd573ff. Filbert approved
round 2 in 28568 and Darkwing in 28570. Landing gate at f7d249634: 24 suites green, 0 failed.
14 package suites passed 1586 tests (plugins 21, business 92,
bus 171, cli 195, webui 112). The 10 script suites passed. Follow-up:
P19 task 293, coded writer refusals.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-15 11:57:54 -05:00

145 lines
5.7 KiB
JavaScript

// The plug-in loader (REQ-PLUG-1). It switches on the modules the
// organization file's `plugins` object names, one key per kind, and loads
// only packages/plugins/<kind>/<name>/index.mjs from the tree this file runs
// from. It takes no path from config and loads nothing outside that tree
// (lead decision 143). A loaded module runs with the host's authority.
//
// A refusal keeps the kind's last good modules and is logged. A kind refused
// on its first load has nothing switched on. `loaded()` reports what each
// kind actually has switched on.
import { lstatSync, realpathSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import { KINDS, PluginError, namesFor } from "./kinds.mjs";
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
const refuse = (code, message, name) => {
throw new PluginError(code, message, name);
};
// Run one filesystem read. Any error becomes a refusal for this path, so load()
// logs it and keeps the kind's old modules (Darkwing N1, Filbert F2, sage-0314).
function fsCall(path, read) {
try {
return read(path);
} catch (e) {
if (e.code === "ENOENT" || e.code === "ENOTDIR") refuse("missing", `${path} is missing`);
refuse("unreadable", `${path} can't be read (${e.code ?? e.message})`);
}
}
// lstat one path component: it must exist, be the expected type, and not be a symlink.
function component(path, directory) {
const st = fsCall(path, lstatSync);
if (st.isSymbolicLink()) refuse("symlink", `${path} is a symlink`);
if (directory ? !st.isDirectory() : !st.isFile()) {
refuse("missing", `${path} is not a ${directory ? "directory" : "regular file"}`);
}
}
async function loadModule(spec, name, barrier) {
const kindDir = join(ROOT, spec.kind);
const nameDir = join(kindDir, name);
const index = join(nameDir, "index.mjs");
component(ROOT, true);
component(kindDir, true);
component(nameDir, true);
component(index, false);
barrier("checked", { kind: spec.kind, name });
// Last check before import: the resolved file is still the one checked
// above. Ancestors of packages/plugins are not checked (sage-0301).
const expected = join(fsCall(ROOT, realpathSync), spec.kind, name, "index.mjs");
const real = fsCall(index, realpathSync);
if (real !== expected) refuse("symlink", `${index} resolves to ${real}`);
let module;
try {
module = await import(pathToFileURL(expected).href);
} catch (e) {
refuse("load-failed", `${spec.kind} ${name} failed to load: ${e.message}`);
}
for (const key of ["interfaceVersion", ...spec.exports]) {
if (!Object.hasOwn(module, key)) refuse("missing-export", `${spec.kind} ${name} doesn't export ${key}`);
}
for (const key of spec.exports) {
if (typeof module[key] !== "function") refuse("missing-export", `${spec.kind} ${name} export ${key} isn't a function`);
}
if (module.interfaceVersion !== spec.interfaceVersion) {
refuse("interface-version",
`${spec.kind} ${name} implements interface ${module.interfaceVersion}, not ${spec.interfaceVersion}`);
}
return Object.freeze({ name, module });
}
export function createLoader({ log, barrier = () => {} }) {
if (typeof log !== "function") throw new TypeError("createLoader needs a log callback");
const current = new Map(Object.keys(KINDS).map(kind => [kind, Object.freeze([])]));
let queue = Promise.resolve();
function refused(kind, name, e, report) {
if (!(e instanceof PluginError)) throw e;
// kept: what stays switched on, for the kind or (whole setting refused) for every kind.
const entry = {
event: "plugin-refused", kind, name: e.plugin ?? name, code: e.code, message: e.message,
kept: kind === null ? loaded() : current.has(kind) ? current.get(kind).map(m => m.name) : [],
};
log(entry);
report.push(entry);
}
async function apply(plugins) {
const report = [];
// A malformed whole setting refuses every kind; an unknown kind refuses only itself.
if (plugins === null || typeof plugins !== "object" || Array.isArray(plugins)) {
refused(null, null, new PluginError("bad-setting", "plugins must be an object with one key per kind"), report);
return { loaded: loaded(), refused: report };
}
for (const kind of Object.keys(plugins)) {
if (!Object.hasOwn(KINDS, kind)) {
refused(kind, null, new PluginError("unknown-kind", `plugins names unknown kind ${JSON.stringify(kind)}`), report);
}
}
for (const [kind, spec] of Object.entries(KINDS)) {
// An absent key switches the kind off.
let names = [];
try {
if (Object.hasOwn(plugins, kind)) names = namesFor(spec, plugins[kind], `plugins.${kind}`, refuse);
} catch (e) {
refused(kind, typeof plugins[kind] === "string" ? plugins[kind] : null, e, report);
continue;
}
const next = [];
let ok = true;
for (const name of names) {
try {
next.push(await loadModule(spec, name, barrier));
} catch (e) {
refused(kind, name, e, report);
ok = false;
break;
}
}
if (ok) current.set(kind, Object.freeze(next));
}
return { loaded: loaded(), refused: report };
}
// Loads run one at a time, so a kind's switch never interleaves.
function load(plugins) {
const run = queue.then(() => apply(plugins));
queue = run.catch(() => {});
return run;
}
function loaded() {
return Object.fromEntries([...current].map(([kind, modules]) => [kind, modules.map(m => m.name)]));
}
function modules(kind) {
if (!current.has(kind)) refuse("unknown-kind", `unknown kind ${JSON.stringify(kind)}`);
return current.get(kind).map(m => m.module);
}
return { load, loaded, modules };
}