@waica/cli 0.5.0 → 0.6.0

package/dist/mcp/project-component-loader.js

@@ -1,287 +1,553 @@
-import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
+import { execFile, fork, } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, rmSync } from 'node:fs';
+import { copyFile, cp, mkdir, mkdtemp } from 'node:fs/promises';
 import * as nodeModule from 'node:module';
+import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { classDefaults, objectRecord } from './component-metadata.js';
-import { causeText, PackageResolver, projectAnchoredRequire } from './package-resolver.js';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
 import { directFiles } from './project-path.js';
-const { createRequire } = nodeModule;
-// Two independent identifiers travel on every module URL this loader hands
-// out: PROJECT_PARAM routes a resolve-hook call back to the validation run
-// that started it (an ephemeral, in-memory lookup, cleaned up per run), and
-// LOAD_PARAM is a content hash that only changes when the file's own bytes
-// change. Splitting them is what lets re-validating unchanged files reuse
-// Node's module cache instead of pinning a fresh entry on every run (see
-// loadProjectComponents below).
-const PROJECT_PARAM = 'waica-component-project';
-const LOAD_PARAM = 'waica-component-load';
-const hookContexts = new Map();
-// Loading this tiny CommonJS trampoline through Node keeps Vitest from
-// rewriting fixture imports. The build copies the same file byte-for-byte.
-const nativeImport = createRequire(import.meta.url)('./native-import.cjs');
+export const PROJECT_COMPONENT_PROTOCOL_VERSION = 1;
+export const PROJECT_COMPONENT_DEADLINE_MS = 5_000;
+export const PROJECT_COMPONENT_DIAGNOSTIC_BYTES = 64 * 1_024;
 const MODULE_HOOKS_MIN_NODE = '22.15';
-/** Pure so it can be exercised directly, independent of the running Node. */
+const REF_KINDS = new Set(['prefab', 'clip', 'action', 'stat']);
+const FALLBACK_PACKAGE_DIRECTORIES = [
+    ['@waica/engine', 'engine'],
+    ['@waica/behaviors', 'behaviors'],
+    ['@waica/archetype-platformer', 'archetype-platformer'],
+];
+const execFileAsync = promisify(execFile);
+let sourceFallbackEntries;
+export class ProjectComponentRunnerUnavailableError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'ProjectComponentRunnerUnavailableError';
+    }
+}
+/** Pure feature probe retained for callers that report the native Node capability. */
 export function nodeSupportsModuleHooks(moduleApi = nodeModule) {
     return typeof moduleApi.registerHooks === 'function';
 }
-/**
- * `node:module`'s `registerHooks` landed in Node 22.15; this MCP server is
- * still expected to start (and serve every other tool) on the older Node
- * hosts an agent may be running. A static named import of `registerHooks`
- * would fail ESM linking on those hosts before the transport ever connects
- * (see workspace-runtime.ts for the same guard on the same API), so this is
- * a namespace import feature-checked at runtime instead.
- */
-const hooksSupported = nodeSupportsModuleHooks();
-/** The single finding emitted in place of real component loading on a host too old for module hooks. */
+/** Compatibility diagnostic for hosts below the package's declared Node floor. */
 export function unsupportedNodeFailure(nodeVersion = process.version) {
     return {
         code: 'component-load-unsupported',
         file: 'src',
         message: `Deep component validation requires Node >= ${MODULE_HOOKS_MIN_NODE} (node:module registerHooks) ` +
-            `to run project components, roles and states in-process; this host runs Node ${nodeVersion}. ` +
-            'Skipping in-process module loading: component params and instance defaults from project code ' +
-            'will not appear in validate_project or list_components until the host upgrades.',
+            `to run isolated project-entry children; this host runs Node ${nodeVersion}. ` +
+            'Skipping validate_project component metadata loading until the host upgrades.',
     };
 }
-function runFromParent(parentURL) {
-    if (!parentURL)
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function exactKeys(value, required, optional = []) {
+    const allowed = new Set([...required, ...optional]);
+    return (required.every((key) => Object.hasOwn(value, key)) &&
+        Object.keys(value).every((key) => allowed.has(key)));
+}
+function validReady(value) {
+    const candidate = record(value);
+    return (candidate !== undefined &&
+        exactKeys(candidate, ['kind', 'version']) &&
+        candidate.kind === 'project-entry-ready' &&
+        candidate.version === PROJECT_COMPONENT_PROTOCOL_VERSION);
+}
+function parseParam(value) {
+    const candidate = record(value);
+    if (!candidate ||
+        !exactKeys(candidate, ['name', 'ref', 'hasOptions'], ['default']) ||
+        typeof candidate.name !== 'string' ||
+        candidate.name.length === 0 ||
+        typeof candidate.ref !== 'string' ||
+        !REF_KINDS.has(candidate.ref) ||
+        typeof candidate.hasOptions !== 'boolean' ||
+        (Object.hasOwn(candidate, 'default') && typeof candidate.default !== 'string')) {
         return undefined;
-    try {
-        const token = new URL(parentURL).searchParams.get(PROJECT_PARAM);
-        const context = token ? hookContexts.get(token) : undefined;
-        return token && context ? { token, context } : undefined;
     }
-    catch {
+    return {
+        name: candidate.name,
+        ref: candidate.ref,
+        hasOptions: candidate.hasOptions,
+        ...(Object.hasOwn(candidate, 'default')
+            ? { default: candidate.default }
+            : {}),
+    };
+}
+function parseComponent(value, expectedFile) {
+    const candidate = record(value);
+    if (!candidate ||
+        !exactKeys(candidate, [
+            'name',
+            'file',
+            'params',
+            'hasOnUpdate',
+            'hasUpdateAfter',
+            'updateAfter',
+        ]) ||
+        typeof candidate.name !== 'string' ||
+        candidate.name.length === 0 ||
+        candidate.file !== expectedFile ||
+        !Array.isArray(candidate.params) ||
+        typeof candidate.hasOnUpdate !== 'boolean' ||
+        typeof candidate.hasUpdateAfter !== 'boolean' ||
+        !Array.isArray(candidate.updateAfter) ||
+        candidate.updateAfter.some((target) => typeof target !== 'string') ||
+        (!candidate.hasUpdateAfter && candidate.updateAfter.length > 0)) {
         return undefined;
     }
+    const params = candidate.params.map(parseParam);
+    if (params.some((param) => param === undefined))
+        return undefined;
+    return {
+        name: candidate.name,
+        file: expectedFile,
+        params: params,
+        hasOnUpdate: candidate.hasOnUpdate,
+        hasUpdateAfter: candidate.hasUpdateAfter,
+        updateAfter: [...candidate.updateAfter],
+    };
 }
-function versioned(url, token, content) {
-    url.searchParams.set(PROJECT_PARAM, token);
-    url.searchParams.set(LOAD_PARAM, content);
-    return url.href;
-}
-function projectToken(projectPath) {
-    return createHash('sha1').update(path.resolve(projectPath)).digest('hex').slice(0, 16);
-}
-/** Content identity for cache-busting: stable across runs, changes only when the file's bytes do. */
-function contentToken(filePath) {
-    try {
-        return createHash('sha1').update(readFileSync(filePath)).digest('hex').slice(0, 16);
+function parseTerminal(value, token, expectedFile) {
+    const candidate = record(value);
+    if (!candidate ||
+        candidate.kind !== 'project-entry-result' ||
+        candidate.version !== PROJECT_COMPONENT_PROTOCOL_VERSION ||
+        candidate.token !== token ||
+        typeof candidate.ok !== 'boolean') {
+        return undefined;
     }
-    catch {
-        // The subsequent import attempt reports the real read/import error; this
-        // token only needs to exist so versioned() has something to stamp.
-        return 'unreadable';
+    if (candidate.ok) {
+        if (!exactKeys(candidate, ['kind', 'version', 'token', 'ok', 'components'])) {
+            return undefined;
+        }
+        if (!Array.isArray(candidate.components))
+            return undefined;
+        const components = candidate.components.map((row) => parseComponent(row, expectedFile));
+        if (components.some((row) => row === undefined))
+            return undefined;
+        return { ok: true, components: components };
     }
+    if (!exactKeys(candidate, ['kind', 'version', 'token', 'ok', 'code', 'message']) ||
+        (candidate.code !== 'component-load-failed' &&
+            candidate.code !== 'component-load-unsupported') ||
+        typeof candidate.message !== 'string') {
+        return undefined;
+    }
+    return {
+        ok: false,
+        code: candidate.code,
+        message: candidate.message,
+    };
 }
-const RELATIVE_EXTENSIONS = ['.ts', '.tsx', '.js'];
-/** Mirrors the editor's resolveProjectImport (play-code.ts): direct, direct+ext, direct/index+ext. */
-function relativeCandidates(unresolvedPath) {
-    const candidates = [
-        ...RELATIVE_EXTENSIONS.map((extension) => `${unresolvedPath}${extension}`),
-        ...RELATIVE_EXTENSIONS.map((extension) => path.join(unresolvedPath, `index${extension}`)),
-    ];
-    if (unresolvedPath.endsWith('.js')) {
-        const withoutJs = unresolvedPath.slice(0, -'.js'.length);
-        candidates.unshift(`${withoutJs}.ts`, `${withoutJs}.tsx`);
+function appendTail(current, chunk) {
+    const next = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    if (next.length >= PROJECT_COMPONENT_DIAGNOSTIC_BYTES) {
+        return next.subarray(next.length - PROJECT_COMPONENT_DIAGNOSTIC_BYTES);
     }
-    return candidates;
+    const combined = Buffer.concat([current, next]);
+    return combined.length <= PROJECT_COMPONENT_DIAGNOSTIC_BYTES
+        ? combined
+        : combined.subarray(combined.length - PROJECT_COMPONENT_DIAGNOSTIC_BYTES);
 }
-function resolveRelativeCandidate(unresolvedPath) {
-    return relativeCandidates(unresolvedPath).find((candidate) => existsSync(candidate));
+function diagnosticMessage(base, stdout, stderr) {
+    const diagnostics = [];
+    if (stdout.length > 0)
+        diagnostics.push(`stdout tail:\n${stdout.toString('utf8')}`);
+    if (stderr.length > 0)
+        diagnostics.push(`stderr tail:\n${stderr.toString('utf8')}`);
+    return diagnostics.length > 0 ? `${base}\n${diagnostics.join('\n')}` : base;
 }
-// The synchronous hook is process-wide, but it is inert for imports that were
-// not initiated by this loader. The PROJECT_PARAM token selects the project
-// resolver for a given run; nextResolve is always tried first so real Node
-// resolution (package "exports" maps, symlinks, literal existing paths) stays
-// authoritative, and our TypeScript-project conventions are only a fallback.
-if (hooksSupported) {
-    nodeModule.registerHooks({
-        resolve(specifier, context, nextResolve) {
-            const run = runFromParent(context.parentURL);
-            if (!run)
-                return nextResolve(specifier, context);
-            if (specifier.startsWith('@waica/')) {
-                const bridge = run.context.packageBridges.get(specifier);
-                if (bridge)
-                    return { url: bridge, shortCircuit: true };
-                const resolved = run.context.projectRequire.resolve(specifier);
-                const url = pathToFileURL(resolved);
-                return {
-                    url: /\.tsx?$/.test(resolved)
-                        ? versioned(url, run.token, contentToken(resolved))
-                        : url.href,
-                    shortCircuit: true,
-                };
-            }
-            if (specifier.startsWith('.')) {
-                const unresolved = new URL(specifier, context.parentURL);
-                let resolvedURL;
-                try {
-                    resolvedURL = new URL(nextResolve(specifier, context).url);
-                }
-                catch (error) {
-                    // Directory imports (./lib -> ./lib/index.ts) and multi-dot
-                    // specifiers (./foo.helper -> ./foo.helper.ts) are valid under the
-                    // project's moduleResolution "bundler" and run fine in Vite, but
-                    // Node's default resolver rejects both — fall back to the same
-                    // candidates the editor tries before giving up.
-                    const fallback = resolveRelativeCandidate(fileURLToPath(unresolved));
-                    if (!fallback)
-                        throw error;
-                    resolvedURL = pathToFileURL(fallback);
-                }
-                const resolvedPath = fileURLToPath(resolvedURL);
-                return {
-                    url: versioned(resolvedURL, run.token, contentToken(resolvedPath)),
-                    shortCircuit: true,
-                };
-            }
-            return nextResolve(specifier, context);
-        },
-    });
-}
-function componentDescriptions(module, file) {
-    const descriptions = {};
-    for (const value of Object.values(module)) {
-        if (typeof value !== 'function' || !Object.hasOwn(value, 'componentName'))
-            continue;
-        const Class = value;
-        if (typeof Class.componentName !== 'string' || !Class.componentName)
-            continue;
-        descriptions[Class.componentName] = {
-            file,
-            params: objectRecord(Class.params),
-            defaults: classDefaults(Class),
-        };
+function schedulingAdapter(row) {
+    class SchedulingAdapter {
     }
-    return descriptions;
-}
-function errorChain(error) {
-    const errors = [];
-    let current = error;
-    const seen = new Set();
-    while (current instanceof Error && !seen.has(current)) {
-        errors.push(current);
-        seen.add(current);
-        current = current.cause;
+    Object.defineProperty(SchedulingAdapter, 'componentName', { value: row.name });
+    if (row.hasUpdateAfter) {
+        Object.defineProperty(SchedulingAdapter, 'updateAfter', {
+            value: Object.freeze([...row.updateAfter]),
+        });
     }
-    return errors;
-}
-function unsupportedByNode(error) {
-    for (const candidate of errorChain(error)) {
-        const code = candidate.code;
-        if (code === 'ERR_UNKNOWN_FILE_EXTENSION' ||
-            code === 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX') {
-            return true;
-        }
-        if (/not supported in strip-only mode|unsupported TypeScript syntax|unknown file extension/i.test(candidate.message)) {
-            return true;
-        }
+    if (row.hasOnUpdate) {
+        Object.defineProperty(SchedulingAdapter.prototype, 'onUpdate', {
+            value: () => undefined,
+        });
     }
-    return false;
+    return SchedulingAdapter;
 }
-function bridgeModule(token, specifier, module) {
-    const key = `waica.project-component.${process.pid}.${token}.${specifier}`;
-    Reflect.set(process, Symbol.for(key), module);
-    const exports = Object.keys(module).filter((name) => /^[$A-Z_a-z][$\w]*$/.test(name));
-    const lines = [
-        `const value = process[Symbol.for(${JSON.stringify(key)})]`,
-        `if (!value) throw new Error(${JSON.stringify(`Missing package bridge for ${specifier}`)})`,
-    ];
-    let index = 0;
-    for (const name of exports) {
-        if (name === 'default') {
-            lines.push('export default value.default');
-            continue;
-        }
-        const binding = `binding${index++}`;
-        lines.push(`const ${binding} = value[${JSON.stringify(name)}]`, `export { ${binding} as ${name} }`);
+function description(row) {
+    const params = {};
+    const defaults = {};
+    for (const param of row.params) {
+        params[param.name] = {
+            ref: param.ref,
+            ...(param.hasOptions ? { options: [] } : {}),
+        };
+        if (param.default !== undefined)
+            defaults[param.name] = param.default;
     }
     return {
-        key,
-        url: `data:text/javascript;charset=utf-8,${encodeURIComponent(lines.join('\n'))}`,
+        file: row.file,
+        Class: schedulingAdapter(row),
+        params,
+        defaults,
     };
 }
-const BRIDGED_SPECIFIERS = ['@waica/engine', '@waica/behaviors', '@waica/archetype-platformer'];
-async function packageBridges(projectPath, token, 
-// Defaults to a fresh resolver for standalone callers (e.g. tests); the
-// real loadProjectComponents call site reuses validateProject's resolver
-// so these packages are not re-resolved from scratch a second time.
-resolver = new PackageResolver(projectPath)) {
-    // @waica/archetype-platformer joins engine/behaviors here (not just the
-    // separate projectRequire.resolve path below) so a freshly created,
-    // not-yet-installed project still gets the MCP-bundled copy the same way
-    // it already does for engine/behaviors, instead of a bare MODULE_NOT_FOUND.
-    // The three packages are independent, so they load concurrently.
-    const bridges = await Promise.all(BRIDGED_SPECIFIERS.map(async (specifier) => {
-        try {
-            const loaded = await resolver.load(specifier);
-            // Keyed by the resolved package's own version rather than a per-run
-            // counter, so re-validating without a dependency bump reuses the exact
-            // same data: URL — and therefore Node's already-cached module for it —
-            // instead of pinning a fresh, functionally identical one every run.
-            const bridge = bridgeModule(`${token}:${loaded.provenance.version}`, specifier, loaded.module);
-            return { specifier, bridge };
-        }
-        catch {
-            // The importing project file receives the anchored resolver's real error.
-            return undefined;
+function runnerFromModule() {
+    const javascript = fileURLToPath(new URL('./project-component-runner.js', import.meta.url));
+    if (existsSync(javascript))
+        return javascript;
+    const typescript = fileURLToPath(new URL('./project-component-runner.ts', import.meta.url));
+    if (existsSync(typescript))
+        return typescript;
+    throw new ProjectComponentRunnerUnavailableError(`Project component runner is missing beside ${fileURLToPath(import.meta.url)}.`);
+}
+function checkoutPackagesRoot() {
+    const candidate = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+    return FALLBACK_PACKAGE_DIRECTORIES.every(([, directory]) => existsSync(path.join(candidate, directory, 'package.json')))
+        ? candidate
+        : undefined;
+}
+async function compileSourceFallbacks(packagesRoot) {
+    const repositoryRoot = path.dirname(packagesRoot);
+    const requireFromLoader = nodeModule.createRequire(import.meta.url);
+    const typescriptRoot = path.dirname(requireFromLoader.resolve('typescript/package.json'));
+    const compiler = path.join(typescriptRoot, 'bin', 'tsc');
+    const outputRoot = await mkdtemp(path.join(tmpdir(), 'waica-mcp-fallback-'));
+    try {
+        await Promise.all(FALLBACK_PACKAGE_DIRECTORIES.map(async ([, directory]) => {
+            const sourceRoot = path.join(packagesRoot, directory);
+            const destinationRoot = path.join(outputRoot, directory);
+            await mkdir(destinationRoot, { recursive: true });
+            await Promise.all([
+                execFileAsync(process.execPath, [
+                    compiler,
+                    '-p',
+                    path.join(sourceRoot, 'tsconfig.build.json'),
+                    '--outDir',
+                    path.join(destinationRoot, 'dist'),
+                    '--declaration',
+                    'false',
+                ], { cwd: repositoryRoot }),
+                copyFile(path.join(sourceRoot, 'package.json'), path.join(destinationRoot, 'package.json')),
+                ...(existsSync(path.join(sourceRoot, 'assets'))
+                    ? [
+                        cp(path.join(sourceRoot, 'assets'), path.join(destinationRoot, 'assets'), {
+                            recursive: true,
+                        }),
+                    ]
+                    : []),
+            ]);
+        }));
+        const entries = Object.fromEntries(FALLBACK_PACKAGE_DIRECTORIES.map(([specifier, directory]) => [
+            specifier,
+            path.join(outputRoot, directory, 'dist', 'index.js'),
+        ]));
+        entries.three = nodeModule
+            .createRequire(path.join(packagesRoot, 'engine', 'package.json'))
+            .resolve('three');
+        if (Object.values(entries).some((entry) => !existsSync(entry))) {
+            throw new Error('TypeScript fallback compilation did not emit every package entry.');
         }
-    }));
-    const urls = new Map();
-    const keys = [];
-    for (const entry of bridges) {
-        if (!entry)
-            continue;
-        urls.set(entry.specifier, entry.bridge.url);
-        keys.push(entry.bridge.key);
+        process.once('exit', () => rmSync(outputRoot, { recursive: true, force: true }));
+        return entries;
+    }
+    catch (error) {
+        rmSync(outputRoot, { recursive: true, force: true });
+        throw error;
     }
-    return { urls, keys };
+}
+async function fallbackEntriesFor(runnerPath) {
+    const packagesRoot = checkoutPackagesRoot();
+    if (!packagesRoot)
+        return {};
+    const built = Object.fromEntries(FALLBACK_PACKAGE_DIRECTORIES.map(([specifier, directory]) => [
+        specifier,
+        path.join(packagesRoot, directory, 'dist', 'index.js'),
+    ]));
+    built.three = nodeModule
+        .createRequire(path.join(packagesRoot, 'engine', 'package.json'))
+        .resolve('three');
+    if (Object.values(built).every((entry) => existsSync(entry)))
+        return built;
+    if (!runnerPath.endsWith('.ts'))
+        return {};
+    sourceFallbackEntries ??= compileSourceFallbacks(packagesRoot);
+    return sourceFallbackEntries;
 }
 async function projectModuleFiles(projectPath) {
     const groups = await Promise.all(['components', 'roles', 'states'].map(async (directory) => (await directFiles(path.join(projectPath, 'src', directory), '.ts')).map((file) => `src/${directory}/${file}`)));
     return groups.flat();
 }
-/**
- * Executes every project-owned component/role/state module independently.
- * Failures are returned as data so one bad file cannot abort validation.
- */
-export async function loadProjectComponents(projectPath, resolver) {
-    if (!hooksSupported) {
-        return { components: {}, failures: [unsupportedNodeFailure()] };
+function cancellationReason(signal) {
+    return signal.reason ?? new DOMException('The operation was aborted.', 'AbortError');
+}
+function unavailable(message, cause) {
+    return new ProjectComponentRunnerUnavailableError(message, cause === undefined ? undefined : { cause });
+}
+export class ProjectComponentLoader {
+    active = new Set();
+    defaults;
+    closed = false;
+    constructor(options = {}) {
+        this.defaults = options;
     }
-    const token = projectToken(projectPath);
-    const bridges = await packageBridges(projectPath, token, resolver);
-    hookContexts.set(token, {
-        projectRequire: projectAnchoredRequire(projectPath),
-        packageBridges: bridges.urls,
-    });
-    const components = {};
-    const failures = [];
-    try {
-        for (const relative of await projectModuleFiles(projectPath)) {
-            const file = path.join(projectPath, relative);
-            try {
-                const entryHref = versioned(pathToFileURL(file), token, contentToken(file));
-                const module = await nativeImport(entryHref);
-                Object.assign(components, componentDescriptions(module, relative));
+    async load(projectPath, _resolver, options = {}) {
+        this.assertOpen();
+        options.signal?.throwIfAborted();
+        const files = await projectModuleFiles(projectPath);
+        this.assertOpen();
+        options.signal?.throwIfAborted();
+        if (files.length === 0)
+            return { components: {}, failures: [] };
+        const runnerPath = options.runnerPath ?? this.defaults.runnerPath ?? runnerFromModule();
+        if (!existsSync(runnerPath)) {
+            throw unavailable(`Project component runner is missing: ${runnerPath}`);
+        }
+        const deadlineMs = options.deadlineMs ?? this.defaults.deadlineMs ?? PROJECT_COMPONENT_DEADLINE_MS;
+        let fallbackEntries;
+        try {
+            fallbackEntries = await fallbackEntriesFor(runnerPath);
+        }
+        catch (error) {
+            throw unavailable('Cannot prepare source fallback packages for the project component runner.', error);
+        }
+        this.assertOpen();
+        options.signal?.throwIfAborted();
+        const components = {};
+        const failures = [];
+        for (const relativeFile of files) {
+            this.assertOpen();
+            options.signal?.throwIfAborted();
+            const outcome = await this.runEntry({
+                projectPath,
+                relativeFile,
+                runnerPath,
+                deadlineMs,
+                fallbackEntries,
+                signal: options.signal,
+            });
+            if ('failure' in outcome) {
+                failures.push(outcome.failure);
             }
-            catch (error) {
-                failures.push({
-                    code: unsupportedByNode(error) ? 'component-load-unsupported' : 'component-load-failed',
-                    file: relative,
-                    message: causeText(error),
-                });
+            else {
+                for (const row of outcome.components)
+                    components[row.name] = description(row);
             }
         }
+        return { components, failures };
     }
-    finally {
-        hookContexts.delete(token);
-        for (const key of bridges.keys)
-            Reflect.deleteProperty(process, Symbol.for(key));
+    assertOpen() {
+        if (this.closed) {
+            throw unavailable('Project component runner is unavailable because its owner is closed.');
+        }
+    }
+    async close() {
+        if (this.closed && this.active.size === 0)
+            return;
+        this.closed = true;
+        const reason = new DOMException('The MCP server is closing.', 'AbortError');
+        await Promise.all([...this.active].map((execution) => execution.terminate(reason)));
     }
-    return { components, failures };
+    runEntry(input) {
+        const token = randomUUID();
+        let child;
+        try {
+            child = (this.defaults.launcher ?? fork)(input.runnerPath, [], {
+                stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+                serialization: 'json',
+                execArgv: [],
+            });
+        }
+        catch (error) {
+            return Promise.reject(unavailable(`Cannot launch project component runner ${input.runnerPath}.`, error));
+        }
+        let stdout = Buffer.alloc(0);
+        let stderr = Buffer.alloc(0);
+        let ready = false;
+        let terminalCount = 0;
+        let terminal;
+        let protocolFailure;
+        let infrastructureFailure;
+        let timeout = false;
+        let aborted;
+        let terminationFailure;
+        let closeObservedResolve;
+        const closeObserved = new Promise((resolve) => {
+            closeObservedResolve = resolve;
+        });
+        const forceTerminate = () => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            try {
+                if (!child.kill('SIGKILL')) {
+                    terminationFailure ??= new Error(`Could not force-terminate validation child ${child.pid ?? '(unknown pid)'}.`);
+                }
+            }
+            catch (error) {
+                terminationFailure ??= error instanceof Error ? error : new Error(String(error));
+            }
+        };
+        const execution = {
+            terminate: async (reason) => {
+                aborted ??= reason;
+                forceTerminate();
+                await closeObserved;
+                if (terminationFailure)
+                    throw terminationFailure;
+            },
+        };
+        this.active.add(execution);
+        return new Promise((resolve, reject) => {
+            const clear = () => {
+                clearTimeout(timer);
+                input.signal?.removeEventListener('abort', onAbort);
+                this.active.delete(execution);
+                closeObservedResolve();
+            };
+            const onAbort = () => {
+                aborted ??= cancellationReason(input.signal);
+                forceTerminate();
+            };
+            if (input.signal)
+                input.signal.addEventListener('abort', onAbort, { once: true });
+            child.stdout?.on('data', (chunk) => {
+                stdout = appendTail(stdout, chunk);
+            });
+            child.stderr?.on('data', (chunk) => {
+                stderr = appendTail(stderr, chunk);
+            });
+            child.on('error', (error) => {
+                infrastructureFailure ??= unavailable(`Project component runner failed to launch for ${input.relativeFile}.`, error);
+                forceTerminate();
+            });
+            child.on('message', (message) => {
+                if (!ready) {
+                    if (!validReady(message)) {
+                        infrastructureFailure ??= unavailable(`Project component runner handshake is incompatible for ${input.relativeFile}.`);
+                        forceTerminate();
+                        return;
+                    }
+                    ready = true;
+                    child.send({
+                        kind: 'load-project-entry',
+                        version: PROJECT_COMPONENT_PROTOCOL_VERSION,
+                        token,
+                        projectPath: input.projectPath,
+                        entryFile: path.join(input.projectPath, input.relativeFile),
+                        relativeFile: input.relativeFile,
+                        fallbackEntries: input.fallbackEntries,
+                    }, (error) => {
+                        if (!error)
+                            return;
+                        infrastructureFailure ??= unavailable(`Cannot send a request to the project component runner for ${input.relativeFile}.`, error);
+                        forceTerminate();
+                    });
+                    return;
+                }
+                const candidate = record(message);
+                if (candidate?.kind === 'project-entry-result')
+                    terminalCount += 1;
+                if (terminalCount > 1) {
+                    protocolFailure = 'Runner sent more than one terminal message.';
+                    forceTerminate();
+                    return;
+                }
+                const parsed = parseTerminal(message, token, input.relativeFile);
+                if (!parsed) {
+                    protocolFailure = 'Runner returned a malformed or unbound terminal payload.';
+                    forceTerminate();
+                    return;
+                }
+                terminal = parsed;
+            });
+            child.once('close', (code, signal) => {
+                clear();
+                if (aborted !== undefined) {
+                    reject(aborted);
+                    return;
+                }
+                if (terminationFailure) {
+                    reject(terminationFailure);
+                    return;
+                }
+                if (infrastructureFailure) {
+                    reject(infrastructureFailure);
+                    return;
+                }
+                if (!ready) {
+                    reject(unavailable(`Project component runner exited before its handshake for ${input.relativeFile}.`));
+                    return;
+                }
+                if (timeout) {
+                    resolve({
+                        failure: {
+                            code: 'component-load-failed',
+                            file: input.relativeFile,
+                            message: diagnosticMessage(`Timed out after ${input.deadlineMs} ms; the direct child was force-terminated and its close was observed.`, stdout, stderr),
+                        },
+                    });
+                    return;
+                }
+                if (protocolFailure || terminalCount !== 1 || !terminal) {
+                    const outcome = signal
+                        ? `signal ${signal}`
+                        : code === null
+                            ? 'without an exit status'
+                            : `exit ${code}`;
+                    resolve({
+                        failure: {
+                            code: 'component-load-failed',
+                            file: input.relativeFile,
+                            message: diagnosticMessage(protocolFailure ?? `Child ended with ${outcome} before one terminal payload.`, stdout, stderr),
+                        },
+                    });
+                    return;
+                }
+                if (signal || code !== 0) {
+                    resolve({
+                        failure: {
+                            code: 'component-load-failed',
+                            file: input.relativeFile,
+                            message: diagnosticMessage(signal
+                                ? `Child exited with signal ${signal} after returning metadata.`
+                                : `Child exited with status ${code} after returning metadata.`, stdout, stderr),
+                        },
+                    });
+                    return;
+                }
+                if (!terminal.ok) {
+                    resolve({
+                        failure: {
+                            code: terminal.code,
+                            file: input.relativeFile,
+                            message: diagnosticMessage(terminal.message, stdout, stderr),
+                        },
+                    });
+                    return;
+                }
+                resolve({ components: terminal.components });
+            });
+            const timer = setTimeout(() => {
+                if (!ready) {
+                    infrastructureFailure ??= unavailable(`Project component runner did not complete its handshake within ${input.deadlineMs} ms for ${input.relativeFile}.`);
+                }
+                else {
+                    timeout = true;
+                }
+                forceTerminate();
+            }, input.deadlineMs);
+        });
+    }
+}
+const defaultLoader = new ProjectComponentLoader();
+/**
+ * Executes every direct Project component, role and state entry in its own
+ * short-lived child. File-attributable failures remain result data.
+ */
+export function loadProjectComponents(projectPath, resolver, options) {
+    return defaultLoader.load(projectPath, resolver, options);
 }