@inharness-ai/claude4spec 1.0.21 → 1.0.23

package/dist/server/core/plugin-host/loader.d.ts

@@ -0,0 +1,107 @@
+/**
+ * M33 plugin loader — the single mechanism that turns workspace-declared npm
+ * packages into registered host capabilities, run identically from every entry
+ * point (server, `c4s`, `c4s-mcp`, `c4s-reader`).
+ *
+ * Four steps, per package, each isolated in its own try/catch so a single bad
+ * plugin is skipped — never crashing the process:
+ *   1. Dynamic import      — `await import(pkg)` (native ESM).
+ *   2. Manifest extraction — `mod.manifest` or `mod.default`.
+ *   3. Validation gate     — hostApiVersion range + engines.node.
+ *   4. Registration        — `registry.registerPlugin(manifest)`.
+ */
+import type { PluginManifest } from '../../../shared/plugin-host/manifest.js';
+import { type PluginMigrationInfo } from '../../../shared/plugin-host/host-api.js';
+import type { PluginRegistry } from './types.js';
+/**
+ * `incompatible` (M33) is distinct from `skipped`: it means the package
+ * was built against an incompatible MAJOR Host API and carries a `migration`
+ * descriptor (a repair path), whereas `skipped` is an environment problem (an
+ * `engines` miss) with no migration path.
+ */
+export type PluginLoadStatus = 'loaded' | 'skipped' | 'incompatible' | 'failed';
+export type PluginLoadCode = 'PLUGIN_HOST_API_MISMATCH' | 'PLUGIN_ENGINE_UNSATISFIED' | 'PLUGIN_IMPORT_FAILED' | 'PLUGIN_INVALID_MANIFEST' | 'PLUGIN_TYPE_CONFLICT' | 'PLUGIN_PROJECT_UNTRUSTED';
+/** Which layer a record belongs to — base (workspace/npm) vs overlay (project-local). */
+export type PluginLayer = 'base' | 'overlay';
+/**
+ * Per-package outcome. Adds `layer` (base/overlay), `trust`, `origin`
+ * (project-local source path), and `shadows`/`shadowedTypes` — all optional so
+ * base records keep their shape.
+ */
+export interface PluginLoadRecord {
+    /** Source identifier: the npm package name, or a synthetic id for built-ins. */
+    package: string;
+    status: PluginLoadStatus;
+    /** Machine code for skipped/failed packages. */
+    code?: PluginLoadCode;
+    /** Human-readable explanation for skipped/failed packages. */
+    reason?: string;
+    manifestName?: string;
+    manifestVersion?: string;
+    /** Entity types this package contributed (only when `loaded`). */
+    contributedTypes?: string[];
+    /** Which layer this record came from (base/overlay). */
+    layer?: PluginLayer;
+    /** Trust state of the project-local layer (overlay only). */
+    trust?: 'trusted' | 'untrusted';
+    /** Source path under `<cwd>/.claude4spec/plugins/` (overlay only). */
+    origin?: string;
+    /**
+     * M33: present on `incompatible` records — the repair path (target
+     * Host API version, applicable migration descriptors, shim availability).
+     */
+    migration?: PluginMigrationInfo;
+}
+export interface PluginLoadResult {
+    records: PluginLoadRecord[];
+}
+/** Module importer — overridable in tests; defaults to native dynamic import. */
+export type PluginImporter = (specifier: string) => Promise<unknown>;
+/** Pull the `PluginManifest` off a freshly-imported module namespace. Shared by
+ * the workspace loader and the project-local overlay loader. */
+export declare function extractManifest(mod: unknown): PluginManifest | null;
+/** A structurally-valid manifest carries at least string `name` + `hostApiVersion`. */
+export declare function isValidManifestShape(manifest: PluginManifest | null): manifest is PluginManifest;
+/**
+ * Outcome of the compatibility gate. `status` lets the caller record an
+ * `incompatible` (major Host API mismatch — carries a `migration` repair path)
+ * distinctly from a `skipped` (host-api same-major miss, or an `engines` miss —
+ * environment problems with no migration path).
+ */
+export interface GateResult {
+    status: 'skipped' | 'incompatible';
+    code: PluginLoadCode;
+    reason: string;
+    migration?: PluginMigrationInfo;
+}
+/**
+ * Compatibility gate shared by all layers: hostApiVersion range + engines.node.
+ * Returns `null` when the manifest may register; otherwise the gate result.
+ * A MAJOR Host API mismatch → `incompatible` + a migration descriptor; an
+ * `engines` miss (or a same-major host-api miss) → `skipped`.
+ */
+export declare function gateManifest(manifest: PluginManifest): GateResult | null;
+/**
+ * Load and register the given workspace plugin packages onto `registry`.
+ * Returns one record per package for the diagnostics route. Never throws.
+ */
+export declare function loadWorkspacePlugins(registry: PluginRegistry, packageNames: string[], importer?: PluginImporter): Promise<PluginLoadResult>;
+/** Seams for `reloadPlugin` — overridable in tests. */
+export interface ReloadPluginOptions {
+    importer?: PluginImporter;
+    resolveEntry?: (pkg: string) => string | null;
+    cacheBust?: (entry: string) => string;
+}
+/**
+ * M33 — hot-reload pipeline for ONE base (workspace/npm) package.
+ *
+ * Atomicity: the failure modes the brief names "old stays" — import failure,
+ * missing manifest export, incompatible major — are all checked BEFORE any
+ * teardown, so the previously-registered version remains registered and the
+ * caller surfaces a warning. Only once a fresh, compatible manifest is in hand
+ * do we tear the old version down (`unregisterPlugin` → its `onUnregister`) and
+ * register the new one — the brief's "onUnregister old, then register new".
+ *
+ * Returns the per-package record (`loaded` / `skipped` / `failed`). Never throws.
+ */
+export declare function reloadPlugin(registry: PluginRegistry, pkg: string, opts?: ReloadPluginOptions): Promise<PluginLoadRecord>;

package/dist/server/core/plugin-host/loader.js

@@ -0,0 +1,196 @@
+/**
+ * M33 plugin loader — the single mechanism that turns workspace-declared npm
+ * packages into registered host capabilities, run identically from every entry
+ * point (server, `c4s`, `c4s-mcp`, `c4s-reader`).
+ *
+ * Four steps, per package, each isolated in its own try/catch so a single bad
+ * plugin is skipped — never crashing the process:
+ *   1. Dynamic import      — `await import(pkg)` (native ESM).
+ *   2. Manifest extraction — `mod.manifest` or `mod.default`.
+ *   3. Validation gate     — hostApiVersion range + engines.node.
+ *   4. Registration        — `registry.registerPlugin(manifest)`.
+ */
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import semver from 'semver';
+import { HOST_API_VERSION } from '../../../shared/plugin-host/manifest.js';
+import { buildMigrationInfo } from '../../../shared/plugin-host/host-api.js';
+import { entryCacheBust } from './cache-bust.js';
+const defaultImporter = (specifier) => import(specifier);
+/** Pull the `PluginManifest` off a freshly-imported module namespace. Shared by
+ * the workspace loader and the project-local overlay loader. */
+export function extractManifest(mod) {
+    if (mod == null || typeof mod !== 'object')
+        return null;
+    const ns = mod;
+    const candidate = (ns.manifest ?? ns.default);
+    if (candidate == null || typeof candidate !== 'object')
+        return null;
+    return candidate;
+}
+/** A structurally-valid manifest carries at least string `name` + `hostApiVersion`. */
+export function isValidManifestShape(manifest) {
+    return (manifest != null &&
+        typeof manifest.name === 'string' &&
+        typeof manifest.hostApiVersion === 'string');
+}
+/** engines.node satisfied by the running node? Missing constraint = satisfied. */
+function enginesSatisfied(manifest) {
+    const node = manifest.engines?.node;
+    if (!node)
+        return true;
+    return semver.satisfies(process.versions.node, node);
+}
+/**
+ * Compatibility gate shared by all layers: hostApiVersion range + engines.node.
+ * Returns `null` when the manifest may register; otherwise the gate result.
+ * A MAJOR Host API mismatch → `incompatible` + a migration descriptor; an
+ * `engines` miss (or a same-major host-api miss) → `skipped`.
+ */
+export function gateManifest(manifest) {
+    if (!semver.satisfies(HOST_API_VERSION, manifest.hostApiVersion)) {
+        const migration = buildMigrationInfo(manifest.hostApiVersion);
+        return {
+            status: migration ? 'incompatible' : 'skipped',
+            code: 'PLUGIN_HOST_API_MISMATCH',
+            reason: `host API ${HOST_API_VERSION} does not satisfy plugin requirement "${manifest.hostApiVersion}"`,
+            migration: migration ?? undefined,
+        };
+    }
+    if (!enginesSatisfied(manifest)) {
+        return {
+            status: 'skipped',
+            code: 'PLUGIN_ENGINE_UNSATISFIED',
+            reason: `node ${process.versions.node} does not satisfy engines.node "${manifest.engines?.node}"`,
+        };
+    }
+    return null;
+}
+/**
+ * Load and register the given workspace plugin packages onto `registry`.
+ * Returns one record per package for the diagnostics route. Never throws.
+ */
+export async function loadWorkspacePlugins(registry, packageNames, importer = defaultImporter) {
+    const records = [];
+    for (const pkg of packageNames) {
+        let mod;
+        try {
+            mod = await importer(pkg);
+        }
+        catch (err) {
+            const reason = err.message;
+            console.warn(`[plugin-loader] PLUGIN_IMPORT_FAILED ${pkg}: ${reason}`);
+            records.push({ package: pkg, status: 'failed', code: 'PLUGIN_IMPORT_FAILED', reason });
+            continue;
+        }
+        const manifest = extractManifest(mod);
+        if (!isValidManifestShape(manifest)) {
+            const reason = 'package does not export a valid PluginManifest (manifest/default)';
+            console.warn(`[plugin-loader] PLUGIN_INVALID_MANIFEST ${pkg}: ${reason}`);
+            records.push({ package: pkg, status: 'failed', code: 'PLUGIN_INVALID_MANIFEST', reason });
+            continue;
+        }
+        const base = {
+            package: pkg,
+            status: 'loaded',
+            layer: 'base',
+            manifestName: manifest.name,
+            manifestVersion: manifest.version,
+        };
+        const gate = gateManifest(manifest);
+        if (gate) {
+            console.warn(`[plugin-loader] ${gate.code} ${pkg}: ${gate.reason}`);
+            records.push({
+                ...base,
+                status: gate.status,
+                code: gate.code,
+                reason: gate.reason,
+                migration: gate.migration,
+            });
+            continue;
+        }
+        try {
+            registry.registerPlugin(manifest);
+        }
+        catch (err) {
+            const reason = err.message;
+            console.warn(`[plugin-loader] PLUGIN_INVALID_MANIFEST ${pkg}: ${reason}`);
+            records.push({ ...base, status: 'failed', code: 'PLUGIN_INVALID_MANIFEST', reason });
+            continue;
+        }
+        records.push({
+            ...base,
+            contributedTypes: (manifest.contributes.entities ?? []).map((e) => e.type),
+        });
+    }
+    return { records };
+}
+/** Resolve a base package's main entry to an absolute path (cache-bust + watch). */
+function resolveBaseEntry(pkg) {
+    try {
+        return createRequire(import.meta.url).resolve(pkg);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * M33 — hot-reload pipeline for ONE base (workspace/npm) package.
+ *
+ * Atomicity: the failure modes the brief names "old stays" — import failure,
+ * missing manifest export, incompatible major — are all checked BEFORE any
+ * teardown, so the previously-registered version remains registered and the
+ * caller surfaces a warning. Only once a fresh, compatible manifest is in hand
+ * do we tear the old version down (`unregisterPlugin` → its `onUnregister`) and
+ * register the new one — the brief's "onUnregister old, then register new".
+ *
+ * Returns the per-package record (`loaded` / `skipped` / `failed`). Never throws.
+ */
+export async function reloadPlugin(registry, pkg, opts = {}) {
+    const importer = opts.importer ?? defaultImporter;
+    const resolveEntry = opts.resolveEntry ?? resolveBaseEntry;
+    const cacheBust = opts.cacheBust ?? entryCacheBust;
+    const base = { package: pkg, status: 'loaded', layer: 'base' };
+    const entry = resolveEntry(pkg);
+    const specifier = entry ? pathToFileURL(entry).href + cacheBust(entry) : pkg;
+    let mod;
+    try {
+        mod = await importer(specifier);
+    }
+    catch (err) {
+        const reason = err.message;
+        console.warn(`[plugin-loader] reload PLUGIN_IMPORT_FAILED ${pkg}: ${reason} (old version retained)`);
+        return { ...base, status: 'failed', code: 'PLUGIN_IMPORT_FAILED', reason };
+    }
+    const manifest = extractManifest(mod);
+    if (!isValidManifestShape(manifest)) {
+        const reason = 'package does not export a valid PluginManifest (manifest/default)';
+        console.warn(`[plugin-loader] reload PLUGIN_INVALID_MANIFEST ${pkg}: ${reason} (old version retained)`);
+        return { ...base, status: 'failed', code: 'PLUGIN_INVALID_MANIFEST', reason };
+    }
+    const named = { ...base, manifestName: manifest.name, manifestVersion: manifest.version };
+    const gate = gateManifest(manifest);
+    if (gate) {
+        console.warn(`[plugin-loader] reload ${gate.code} ${pkg}: ${gate.reason} (old version retained)`);
+        return { ...named, status: gate.status, code: gate.code, reason: gate.reason, migration: gate.migration };
+    }
+    // Atomicity: validate + lower the NEW manifest BEFORE tearing the old one
+    // down, so a structurally-broken new version leaves the old one in place
+    // (parity with the import/gate failures above — "old stays").
+    try {
+        registry.validatePlugin(manifest);
+    }
+    catch (err) {
+        const reason = err.message;
+        console.warn(`[plugin-loader] reload PLUGIN_INVALID_MANIFEST ${pkg}: ${reason} (old version retained)`);
+        return { ...named, status: 'failed', code: 'PLUGIN_INVALID_MANIFEST', reason };
+    }
+    // Fresh, compatible, valid: tear the old version down, then register the new.
+    registry.unregisterPlugin(manifest.name);
+    registry.registerPlugin(manifest);
+    return {
+        ...named,
+        contributedTypes: (manifest.contributes.entities ?? []).map((e) => e.type),
+    };
+}
+//# sourceMappingURL=loader.js.map

package/dist/server/core/plugin-host/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../../../src/server/core/plugin-host/loader.ts"],"names":[],"mappings":"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"}

package/dist/server/core/plugin-host/manifest-adapter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * M33: lower a runtime plugin's authoring shape (`EntityContribution`) into the
+ * internal `BackendModule` the host already understands. This keeps
+ * `mountBackend` / `MountContext` / `ProjectPluginHost` 100% unchanged — the
+ * manifest is purely an authoring envelope, reconciled here.
+ *
+ * Two backend shapes are supported:
+ *  - `backend.mount` (full power)  — passes through as the `BackendModule` mount.
+ *  - `backend.routes` (sugar)      — a pre-built express Router; synthesized into
+ *    `mount = (ctx) => ctx.app.use(pathPrefix, routes)`. No MCP server, no entity
+ *    service, no migrations beyond what is declared.
+ */
+import type { EntityContribution, WritingStyleContribution } from '../../../shared/plugin-host/manifest.js';
+import type { BackendModule } from './types.js';
+/** Thrown when a contribution is structurally invalid. Caught per-package by the loader. */
+export declare class PluginManifestError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validate one writing-style contribution (M15). Mirrors the SKILL.md
+ * frontmatter checks in skill-registry so a plugin style is held to the same
+ * shape as a file-authored one. Throws `PluginManifestError` (caught per-package
+ * by the loader) on any structural problem.
+ */
+export declare function validateWritingStyle(c: WritingStyleContribution): WritingStyleContribution;
+/**
+ * Convert one `EntityContribution` (shared authoring shape with `unknown`
+ * server payloads) into a fully-typed `BackendModule`.
+ */
+export declare function lowerEntityContribution(c: EntityContribution): BackendModule;

package/dist/server/core/plugin-host/manifest-adapter.js

@@ -0,0 +1,119 @@
+/**
+ * M33: lower a runtime plugin's authoring shape (`EntityContribution`) into the
+ * internal `BackendModule` the host already understands. This keeps
+ * `mountBackend` / `MountContext` / `ProjectPluginHost` 100% unchanged — the
+ * manifest is purely an authoring envelope, reconciled here.
+ *
+ * Two backend shapes are supported:
+ *  - `backend.mount` (full power)  — passes through as the `BackendModule` mount.
+ *  - `backend.routes` (sugar)      — a pre-built express Router; synthesized into
+ *    `mount = (ctx) => ctx.app.use(pathPrefix, routes)`. No MCP server, no entity
+ *    service, no migrations beyond what is declared.
+ */
+/** Thrown when a contribution is structurally invalid. Caught per-package by the loader. */
+export class PluginManifestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PluginManifestError';
+    }
+}
+/**
+ * Validate one writing-style contribution (M15). Mirrors the SKILL.md
+ * frontmatter checks in skill-registry so a plugin style is held to the same
+ * shape as a file-authored one. Throws `PluginManifestError` (caught per-package
+ * by the loader) on any structural problem.
+ */
+export function validateWritingStyle(c) {
+    if (!c || typeof c !== 'object') {
+        throw new PluginManifestError('writingStyle contribution must be an object');
+    }
+    if (typeof c.slug !== 'string' || c.slug.length === 0) {
+        throw new PluginManifestError('writingStyle — slug must be a non-empty string');
+    }
+    if (typeof c.title !== 'string' || c.title.length === 0) {
+        throw new PluginManifestError(`writingStyle "${c.slug}" — title must be a non-empty string`);
+    }
+    if (typeof c.description !== 'string' || c.description.length === 0) {
+        throw new PluginManifestError(`writingStyle "${c.slug}" — description must be a non-empty string`);
+    }
+    if (typeof c.version !== 'number' || !Number.isInteger(c.version) || c.version < 1) {
+        throw new PluginManifestError(`writingStyle "${c.slug}" — version must be a positive integer`);
+    }
+    if (c.language !== 'en' && c.language !== 'pl') {
+        throw new PluginManifestError(`writingStyle "${c.slug}" — language must be 'en' or 'pl'`);
+    }
+    if (typeof c.content !== 'string') {
+        throw new PluginManifestError(`writingStyle "${c.slug}" — content must be a string`);
+    }
+    return c;
+}
+const MANIFEST_FIELDS = [
+    'type',
+    'table',
+    'label',
+    'labelPlural',
+    'displayOrder',
+    'slugFrom',
+    'pathPrefix',
+];
+function assertContribution(c) {
+    if (!c || typeof c !== 'object') {
+        throw new PluginManifestError('entity contribution must be an object');
+    }
+    const record = c;
+    for (const f of MANIFEST_FIELDS) {
+        if (record[f] == null) {
+            throw new PluginManifestError(`entity "${c.type ?? '?'}" missing required field "${f}"`);
+        }
+    }
+    if (typeof c.slugFrom !== 'function') {
+        throw new PluginManifestError(`entity "${c.type}" — slugFrom must be a function`);
+    }
+    if (c.serializer == null) {
+        throw new PluginManifestError(`entity "${c.type}" — serializer is required`);
+    }
+    if (c.systemPrompt == null) {
+        throw new PluginManifestError(`entity "${c.type}" — systemPrompt is required`);
+    }
+    const backend = c.backend;
+    if (backend != null && typeof backend !== 'object') {
+        throw new PluginManifestError(`entity "${c.type}" — backend must be an object`);
+    }
+}
+/**
+ * Convert one `EntityContribution` (shared authoring shape with `unknown`
+ * server payloads) into a fully-typed `BackendModule`.
+ */
+export function lowerEntityContribution(c) {
+    assertContribution(c);
+    const backend = c.backend;
+    let backendSlot;
+    if (backend) {
+        const migrations = backend.migrations;
+        let mount = backend.mount;
+        if (!mount && backend.routes != null) {
+            const routes = backend.routes;
+            const pathPrefix = c.pathPrefix;
+            mount = (ctx) => {
+                ctx.app.use(pathPrefix, routes);
+            };
+        }
+        if (mount && typeof mount !== 'function') {
+            throw new PluginManifestError(`entity "${c.type}" — backend.mount must be a function`);
+        }
+        backendSlot = { migrations, mount };
+    }
+    return {
+        type: c.type,
+        table: c.table,
+        label: c.label,
+        labelPlural: c.labelPlural,
+        displayOrder: c.displayOrder,
+        slugFrom: c.slugFrom,
+        pathPrefix: c.pathPrefix,
+        serializer: c.serializer,
+        systemPrompt: c.systemPrompt,
+        backend: backendSlot,
+    };
+}
+//# sourceMappingURL=manifest-adapter.js.map

package/dist/server/core/plugin-host/manifest-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-adapter.js","sourceRoot":"","sources":["../../../../src/server/core/plugin-host/manifest-adapter.ts"],"names":[],"mappings":"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"}

package/dist/server/core/plugin-host/overlay-loader.d.ts

@@ -0,0 +1,60 @@
+/**
+ * M33 — project-local plugin overlay loader.
+ *
+ * The second of the two M33 tracks (the first being the process-global
+ * `loadWorkspacePlugins`). This one loads plugins committed into a repo at
+ * `<cwd>/.claude4spec/plugins/<pkg>/` and builds a per-`ProjectContext`
+ * `ProjectPluginOverlay`. Because a `git clone` brings this code with it,
+ * loading is gated by `trustProjectPlugins` — the CALLER decides trust and only
+ * invokes `loadProjectOverlay` when trusted; `enumerateOverlayPackages` is the
+ * code-free probe used to drive the trust prompt.
+ *
+ * Per package, each step is isolated in its own try/catch so one bad plugin is
+ * skipped — never failing the project build:
+ *   1. Resolve entry  — package.json main/module/exports, else index.{js,mjs}.
+ *   2. Dynamic import — `import(pathToFileURL(entry))` (native ESM).
+ *   3. Validate+gate  — shared with the workspace loader (hostApiVersion+engines).
+ *   4. Lower entities — `lowerEntityContribution`, enforcing within-overlay
+ *      type uniqueness (second duplicate → PLUGIN_TYPE_CONFLICT, rejected).
+ */
+import { type PluginLoadRecord } from './loader.js';
+import type { ProjectPluginOverlay } from './types.js';
+import type { WritingStyleContribution } from '../../../shared/plugin-host/manifest.js';
+/** Importer seam — overridable in tests; defaults to native dynamic import. */
+export type PluginImporter = (specifier: string) => Promise<unknown>;
+export interface ProjectOverlayResult {
+    /** The overlay, or `undefined` when no loadable project-local module exists. */
+    overlay: ProjectPluginOverlay | undefined;
+    /** Per-package diagnostics for the per-project `/_meta/plugins` route. */
+    records: PluginLoadRecord[];
+    /** M15: trusted project-local writing styles, pushed into SkillRegistry. */
+    writingStyles: WritingStyleContribution[];
+    /** Best-effort detach of imported project-local modules (see dispose note). */
+    dispose: () => void;
+}
+/** Absolute path to a project's local plugins directory. */
+export declare function projectPluginsDir(cwd: string): string;
+/**
+ * Package directory names under `<cwd>/.claude4spec/plugins/`. Pure FS read — no
+ * code runs — so it is safe to call before the trust decision (drives the prompt
+ * and the untrusted-layer diagnostics).
+ */
+export declare function enumerateOverlayPackages(cwd: string): string[];
+/** True when the project ships at least one local plugin package. */
+export declare function hasProjectPlugins(cwd: string): boolean;
+/**
+ * Resolve a package.json `exports` field to a relative entry path. Handles the
+ * common shapes: a bare string, the `"."` subpath, and a conditions object
+ * (`{ import, default, require, node }`) at either the top level or under `"."`.
+ * Returns the first string match (preferring ESM `import`/`default`), or
+ * undefined if no string entry is reachable (caller falls back to module/main).
+ * Exported so the workspace-tier frontend resolver reuses the same condition
+ * handling for a plugin's `exports['./frontend']` (see `frontend-assets.ts`).
+ */
+export declare function resolveExportsEntry(exp: unknown): string | undefined;
+/**
+ * Load and validate the trusted project-local overlay for `cwd`. The caller must
+ * have already confirmed `trustProjectPlugins === true`; this function executes
+ * project-committed code.
+ */
+export declare function loadProjectOverlay(cwd: string, importer?: PluginImporter): Promise<ProjectOverlayResult>;