@openvcs/sdk 0.2.4 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openvcs/sdk",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "OpenVCS SDK CLI for plugin scaffolding and .ovcsp tar.gz packaging",
   "license": "GPL-3.0-or-later",
   "homepage": "https://openvcs.app/",

package/src/lib/build.ts

@@ -32,6 +32,8 @@ interface PackageScripts {
   [scriptName: string]: unknown;
 }
 
+const AUTHORED_PLUGIN_MODULE_BASENAME = "plugin.js";
+
 /** Returns the npm executable name for the current platform. */
 export function npmExecutable(): string {
   return process.platform === "win32" ? "npm.cmd" : "npm";
@@ -137,6 +139,14 @@ export function validateDeclaredModuleExec(pluginDir: string, moduleExec: string
     return;
   }
 
+  const targetPath = resolveDeclaredModuleExecPath(pluginDir, moduleExec);
+  if (!fs.existsSync(targetPath) || !fs.lstatSync(targetPath).isFile()) {
+    throw new Error(`module entrypoint not found at ${targetPath}`);
+  }
+}
+
+/** Resolves `module.exec` to an absolute path under `bin/`, rejecting invalid targets. */
+function resolveDeclaredModuleExecPath(pluginDir: string, moduleExec: string): string {
   const normalizedExec = moduleExec.trim();
   const lowered = normalizedExec.toLowerCase();
   if (!lowered.endsWith(".js") && !lowered.endsWith(".mjs") && !lowered.endsWith(".cjs")) {
@@ -151,9 +161,100 @@ export function validateDeclaredModuleExec(pluginDir: string, moduleExec: string
   if (!isPathInside(binDir, targetPath) || targetPath === binDir) {
     throw new Error(`manifest module.exec must point to a file under bin/: ${moduleExec}`);
   }
-  if (!fs.existsSync(targetPath) || !fs.lstatSync(targetPath).isFile()) {
-    throw new Error(`module entrypoint not found at ${targetPath}`);
+
+  return targetPath;
+}
+
+/** Returns the compiled plugin module path imported by the generated bootstrap. */
+export function authoredPluginModulePath(pluginDir: string): string {
+  return path.resolve(pluginDir, "bin", AUTHORED_PLUGIN_MODULE_BASENAME);
+}
+
+/** Ensures the plugin's authored module and generated bootstrap paths are compatible. */
+export function validateGeneratedBootstrapTargets(
+  pluginDir: string,
+  moduleExec: string | undefined,
+): void {
+  if (!moduleExec) {
+    return;
+  }
+
+  resolveDeclaredModuleExecPath(pluginDir, moduleExec);
+  const normalizedExec = moduleExec.trim().toLowerCase();
+  if (normalizedExec === AUTHORED_PLUGIN_MODULE_BASENAME.toLowerCase()) {
+    throw new Error(
+      `manifest module.exec must not be ${AUTHORED_PLUGIN_MODULE_BASENAME}; SDK reserves bin/${AUTHORED_PLUGIN_MODULE_BASENAME} for the compiled OnPluginStart module`
+    );
+  }
+
+  const authoredModulePath = authoredPluginModulePath(pluginDir);
+  if (!fs.existsSync(authoredModulePath) || !fs.lstatSync(authoredModulePath).isFile()) {
+    throw new Error(
+      `compiled plugin module not found at ${authoredModulePath}; build:plugin must emit bin/${AUTHORED_PLUGIN_MODULE_BASENAME}`
+    );
+  }
+}
+
+/** Returns a normalized import specifier from one bin file to another. */
+function relativeBinImport(fromExecPath: string, toModulePath: string): string {
+  const relativePath = path.relative(path.dirname(fromExecPath), toModulePath).replace(/\\/g, "/");
+  return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+}
+
+/** Validates that a module import path contains only safe characters for code generation. */
+function validateModuleImportPath(importPath: string): void {
+  if (!/^[./a-zA-Z0-9_-]+$/.test(importPath)) {
+    throw new Error(
+      `unsafe module import path: ${importPath}; path must contain only alphanumeric characters, dots, slashes, hyphens, and underscores`
+    );
+  }
+}
+
+/** Renders the generated Node bootstrap that owns runtime startup. */
+export function renderGeneratedBootstrap(
+  pluginModuleImportPath: string,
+  isEsm: boolean,
+): string {
+  validateModuleImportPath(pluginModuleImportPath);
+
+  if (isEsm) {
+    return `#!/usr/bin/env node\n// Copyright © 2025-2026 OpenVCS Contributors\n// SPDX-License-Identifier: GPL-3.0-or-later\n\nimport { bootstrapPluginModule } from '@openvcs/sdk/runtime';\n\nawait bootstrapPluginModule({\n  importPluginModule: async () => import('${pluginModuleImportPath}'),\n  modulePath: '${pluginModuleImportPath}',\n});\n`;
+  }
+
+  return `#!/usr/bin/env node\n// Copyright © 2025-2026 OpenVCS Contributors\n// SPDX-License-Identifier: GPL-3.0-or-later\n\n(async () => {\n  const { bootstrapPluginModule } = require('@openvcs/sdk/runtime');\n  await bootstrapPluginModule({\n    importPluginModule: async () => require('${pluginModuleImportPath}'),\n    modulePath: '${pluginModuleImportPath}',\n  });\n})();\n`;
+}
+
+/** Writes the generated SDK-owned module entrypoint under `bin/<module.exec>`. */
+export function generateModuleBootstrap(pluginDir: string, moduleExec: string | undefined): void {
+  if (!moduleExec) {
+    console.debug(`generateModuleBootstrap: no module.exec defined, skipping bootstrap generation for ${pluginDir}`);
+    return;
+  }
+
+  validateGeneratedBootstrapTargets(pluginDir, moduleExec);
+  const execPath = resolveDeclaredModuleExecPath(pluginDir, moduleExec);
+  const pluginModulePath = authoredPluginModulePath(pluginDir);
+  const pluginModuleImportPath = relativeBinImport(execPath, pluginModulePath);
+  const isEsm = detectEsmMode(pluginDir, moduleExec);
+
+  fs.mkdirSync(path.dirname(execPath), { recursive: true });
+  fs.writeFileSync(execPath, renderGeneratedBootstrap(pluginModuleImportPath, isEsm), "utf8");
+}
+
+/** Detects whether the plugin runs in ESM mode based on package.json or file extension. */
+function detectEsmMode(pluginDir: string, moduleExec: string): boolean {
+  const packageJsonPath = path.join(pluginDir, "package.json");
+  if (fs.existsSync(packageJsonPath) && fs.lstatSync(packageJsonPath).isFile()) {
+    try {
+      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+      if (packageJson.type === "module") {
+        return true;
+      }
+    } catch {
+      // Ignore JSON parse errors
+    }
   }
+  return moduleExec.trim().endsWith(".mjs");
 }
 
 /** Returns whether the plugin repository has a `package.json`. */
@@ -224,6 +325,7 @@ export function buildPluginAssets(parsedArgs: BuildArgs): ManifestInfo {
   }
 
   runCommand(npmExecutable(), ["run", "build:plugin"], parsedArgs.pluginDir, parsedArgs.verbose);
+  generateModuleBootstrap(parsedArgs.pluginDir, manifest.moduleExec);
   validateDeclaredModuleExec(parsedArgs.pluginDir, manifest.moduleExec);
   return manifest;
 }

package/src/lib/dist.ts

@@ -9,6 +9,7 @@ import {
   readManifest,
   runCommand,
   validateDeclaredModuleExec,
+  validateGeneratedBootstrapTargets,
 } from "./build";
 import {
   copyDirectoryRecursiveStrict,
@@ -251,6 +252,7 @@ export async function bundlePlugin(parsedArgs: DistArgs): Promise<string> {
   if (!moduleExec && !hasThemes && !entry) {
     throw new Error("manifest has no module.exec, entry, or themes/");
   }
+  validateGeneratedBootstrapTargets(pluginDir, moduleExec);
   validateDeclaredModuleExec(pluginDir, moduleExec);
 
   ensureDirectory(outDir);

package/src/lib/init.ts

@@ -223,7 +223,7 @@ function writeCommonFiles(answers: InitAnswers): void {
     name: answers.pluginName,
     version: answers.pluginVersion,
     default_enabled: answers.defaultEnabled,
-    ...(answers.kind === "module" ? { module: { exec: "plugin.js" } } : {}),
+    ...(answers.kind === "module" ? { module: { exec: "openvcs-plugin.js" } } : {}),
   });
   writeText(path.join(answers.targetDir, ".gitignore"), "node_modules/\ndist/\n");
 }
@@ -264,7 +264,7 @@ function writeModuleTemplate(answers: InitAnswers): void {
   });
   writeText(
     path.join(answers.targetDir, "src", "plugin.ts"),
-    "// Copyright © 2025-2026 OpenVCS Contributors\n// SPDX-License-Identifier: GPL-3.0-or-later\n\nimport { createPluginRuntime, startPluginRuntime } from '@openvcs/sdk/runtime';\n\nconst runtime = createPluginRuntime({\n  plugin: {\n    async 'plugin.init'(_params, context) {\n      context.host.info('OpenVCS plugin started');\n      return null;\n    },\n  },\n});\n\nstartPluginRuntime(runtime);\n"
+    "// Copyright © 2025-2026 OpenVCS Contributors\n// SPDX-License-Identifier: GPL-3.0-or-later\n\nimport type { PluginModuleDefinition } from '@openvcs/sdk/runtime';\n\nexport const PluginDefinition: PluginModuleDefinition = {\n  plugin: {\n    async 'plugin.init'(_params, context) {\n      context.host.info('OpenVCS plugin started');\n      return null;\n    },\n  },\n};\n\n/** Runs plugin startup work before the generated runtime begins processing requests. */\nexport function OnPluginStart(): void {}\n"
   );
 }
 

package/src/lib/runtime/factory.ts

@@ -0,0 +1,182 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type { JsonRpcId, JsonRpcRequest, RequestParams } from '../types';
+
+import type {
+  CreatePluginRuntimeOptions,
+  PluginRuntime,
+  PluginRuntimeTransport,
+} from './contracts';
+import { createRuntimeDispatcher } from './dispatcher';
+import { createHost } from './host';
+import { parseFramedMessages, writeFramedMessage } from './transport';
+
+/** Creates a reusable stdio JSON-RPC runtime for OpenVCS Node plugins. */
+export function createPluginRuntime(
+  options: CreatePluginRuntimeOptions = {},
+): PluginRuntime {
+  let buffer: Buffer<ArrayBufferLike> = Buffer.alloc(0);
+  let processing: Promise<void> = Promise.resolve();
+  let started = false;
+  let currentTransport: PluginRuntimeTransport | null = null;
+  let chunkLock: Promise<void> = Promise.resolve();
+
+  const runtime: PluginRuntime = {
+    start(transport: PluginRuntimeTransport = defaultTransport()): void {
+      if (started) {
+        return;
+      }
+
+      started = true;
+      currentTransport = transport;
+      transport.stdin.on('data', (chunk: Buffer | string) => {
+        runtime.consumeChunk(chunk);
+      });
+      transport.stdin.on('error', () => {
+        process.exit(1);
+      });
+      options.onStart?.();
+    },
+    stop(): void {
+      if (!started) {
+        return;
+      }
+      started = false;
+      processing = processing
+        .catch(async (error: unknown) => {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          console.error(`[runtime] shutdown error: ${errorMessage}`);
+          const err = error instanceof Error ? error : new Error(errorMessage);
+          await options.onShutdown?.(err);
+        })
+        .then(async () => {
+          await options.onShutdown?.();
+        });
+      currentTransport = null;
+    },
+    consumeChunk(chunk: Buffer | string): void {
+      if (!started) {
+        return;
+      }
+
+      const lock = chunkLock.then(() => {
+        buffer = Buffer.concat([buffer, normalizeChunk(chunk)]);
+        const parsed = parseFramedMessages(buffer);
+        buffer = parsed.remainder;
+
+        for (const request of parsed.messages) {
+          processing = processing
+            .then(async () => {
+              await runtime.dispatchRequest(request);
+            })
+            .catch((error: unknown) => {
+              const message = error instanceof Error ? error.message : String(error || 'unknown plugin processing error');
+              const host = createRuntimeHost(currentTransport, options.logTarget);
+              host.error(message);
+            });
+        }
+      });
+
+      chunkLock = lock;
+    },
+    async dispatchRequest(request: JsonRpcRequest): Promise<void> {
+      const id = request.id;
+      const host = createRuntimeHost(currentTransport, options.logTarget);
+      const method = asTrimmedString(request.method);
+      const validationErrors: string[] = [];
+      if (!method) validationErrors.push('missing method');
+      if (typeof id !== 'number' && typeof id !== 'string') validationErrors.push(`invalid id type: ${typeof id}`);
+      if (validationErrors.length > 0) {
+        host.error(`invalid request: ${validationErrors.join(', ')}`);
+        return;
+      }
+      const dispatcher = createRuntimeDispatcher(options, host, {
+        async sendResult<TResult>(requestId: JsonRpcId, result: TResult): Promise<void> {
+          await sendMessage(currentTransport, {
+            jsonrpc: '2.0',
+            id: requestId,
+            result,
+          });
+        },
+        async sendError(requestId: JsonRpcId, code: number, message: string, data?: unknown): Promise<void> {
+          await sendMessage(currentTransport, {
+            jsonrpc: '2.0',
+            id: requestId,
+            error: {
+              code,
+              message,
+              ...(data == null ? {} : { data }),
+            },
+          });
+        },
+      });
+
+      const methodName = method as string;
+      const params = asRecord(request.params) ?? {};
+      const requestId = id as JsonRpcId;
+      await dispatcher(requestId, methodName, params);
+    },
+  };
+
+  return runtime;
+}
+
+/** Returns the default stdio transport used by the runtime. */
+function defaultTransport(): PluginRuntimeTransport {
+  return {
+    stdin: process.stdin,
+    stdout: process.stdout,
+  };
+}
+
+/** Sends one JSON-RPC response or notification through the active transport. */
+async function sendMessage(
+  transport: PluginRuntimeTransport | null,
+  value: unknown,
+): Promise<void> {
+  await writeFramedMessage((transport ?? defaultTransport()).stdout, value);
+}
+
+/** Builds the host helper for the currently active transport. */
+function createRuntimeHost(
+  transport: PluginRuntimeTransport | null,
+  logTarget: string | undefined,
+) {
+  return createHost(
+    async (method: string, params: unknown) => {
+      await sendMessage(transport, {
+        jsonrpc: '2.0',
+        method,
+        params,
+      });
+    },
+    { logTarget },
+  );
+}
+
+/** Type guard that returns true if the value is a valid RequestParams object. */
+function isRequestParams(value: unknown): value is RequestParams {
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  return true;
+}
+
+/** Coerces unknown request method values into trimmed strings. Returns null for non-strings. */
+function asTrimmedString(value: unknown): string | null {
+  return typeof value === 'string' ? value.trim() : null;
+}
+
+/** Coerces unknown params to a Record, returning null for invalid input. */
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (isRequestParams(value)) {
+    return value as Record<string, unknown>;
+  }
+  return null;
+}
+
+/** Normalizes incoming data chunks to UTF-8 buffers. */
+function normalizeChunk(chunk: Buffer | string): Buffer {
+  return Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, 'utf8');
+}

package/src/lib/runtime/index.ts

@@ -1,17 +1,10 @@
 // Copyright © 2025-2026 OpenVCS Contributors
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-import type { JsonRpcId, JsonRpcRequest, RequestParams } from '../types';
-
 import type {
-  CreatePluginRuntimeOptions,
   PluginRuntime,
-  PluginRuntimeContext,
   PluginRuntimeTransport,
 } from './contracts';
-import { createRuntimeDispatcher } from './dispatcher';
-import { createHost } from './host';
-import { parseFramedMessages, writeFramedMessage } from './transport';
 
 export type {
   CreatePluginRuntimeOptions,
@@ -19,119 +12,20 @@ export type {
   PluginRuntimeContext,
   PluginRuntimeTransport,
 } from './contracts';
-export { createDefaultPluginDelegates } from './dispatcher';
+export type {
+  BootstrapPluginModuleOptions,
+  OnPluginStartHandler,
+  PluginBootstrapModule,
+  PluginModuleDefinition,
+} from './registration';
+export { createDefaultPluginDelegates, createRuntimeDispatcher } from './dispatcher';
 export { isPluginFailure, pluginError } from './errors';
+export { createPluginRuntime } from './factory';
 export { createHost } from './host';
-
-/** Creates a reusable stdio JSON-RPC runtime for OpenVCS Node plugins. */
-export function createPluginRuntime(
-  options: CreatePluginRuntimeOptions = {},
-): PluginRuntime {
-  let buffer: Buffer<ArrayBufferLike> = Buffer.alloc(0);
-  let processing: Promise<void> = Promise.resolve();
-  let started = false;
-  let currentTransport: PluginRuntimeTransport | null = null;
-  let chunkLock: Promise<void> = Promise.resolve();
-
-  const runtime: PluginRuntime = {
-    start(transport: PluginRuntimeTransport = defaultTransport()): void {
-      if (started) {
-        return;
-      }
-
-      started = true;
-      currentTransport = transport;
-      transport.stdin.on('data', (chunk: Buffer | string) => {
-        runtime.consumeChunk(chunk);
-      });
-      transport.stdin.on('error', () => {
-        process.exit(1);
-      });
-      options.onStart?.();
-    },
-    stop(): void {
-      if (!started) {
-        return;
-      }
-      started = false;
-      processing = processing
-        .catch(async (error: unknown) => {
-          const errorMessage = error instanceof Error ? error.message : String(error);
-          console.error(`[runtime] shutdown error: ${errorMessage}`);
-          const err = error instanceof Error ? error : new Error(errorMessage);
-          await options.onShutdown?.(err);
-        })
-        .then(async () => {
-          await options.onShutdown?.();
-        });
-      currentTransport = null;
-    },
-    consumeChunk(chunk: Buffer | string): void {
-      if (!started) {
-        return;
-      }
-
-      const lock = chunkLock.then(() => {
-        buffer = Buffer.concat([buffer, normalizeChunk(chunk)]);
-        const parsed = parseFramedMessages(buffer);
-        buffer = parsed.remainder;
-
-        for (const request of parsed.messages) {
-          processing = processing
-            .then(async () => {
-              await runtime.dispatchRequest(request);
-            })
-            .catch((error: unknown) => {
-              const message = error instanceof Error ? error.message : String(error || 'unknown plugin processing error');
-              const host = createRuntimeHost(currentTransport, options.logTarget);
-              host.error(message);
-            });
-        }
-      });
-
-      chunkLock = lock;
-    },
-    async dispatchRequest(request: JsonRpcRequest): Promise<void> {
-      const id = request.id;
-      const host = createRuntimeHost(currentTransport, options.logTarget);
-      const method = asTrimmedString(request.method);
-      const validationErrors: string[] = [];
-      if (!method) validationErrors.push('missing method');
-      if (typeof id !== 'number' && typeof id !== 'string') validationErrors.push(`invalid id type: ${typeof id}`);
-      if (validationErrors.length > 0) {
-        host.error(`invalid request: ${validationErrors.join(', ')}`);
-        return;
-      }
-      const dispatcher = createRuntimeDispatcher(options, host, {
-        async sendResult<TResult>(requestId: JsonRpcId, result: TResult): Promise<void> {
-          await sendMessage(currentTransport, {
-            jsonrpc: '2.0',
-            id: requestId,
-            result,
-          });
-        },
-        async sendError(requestId: JsonRpcId, code: number, message: string, data?: unknown): Promise<void> {
-          await sendMessage(currentTransport, {
-            jsonrpc: '2.0',
-            id: requestId,
-            error: {
-              code,
-              message,
-              ...(data == null ? {} : { data }),
-            },
-          });
-        },
-      });
-
-      const methodName = method as string;
-      const params = asRecord(request.params) ?? {};
-      const requestId = id as JsonRpcId;
-      await dispatcher(requestId, methodName, params);
-    },
-  };
-
-  return runtime;
-}
+export {
+  bootstrapPluginModule,
+  createRegisteredPluginRuntime,
+} from './registration';
 
 /** Starts a previously created plugin runtime on process stdio. */
 export function startPluginRuntime(
@@ -140,62 +34,3 @@ export function startPluginRuntime(
 ): void {
   runtime.start(transport);
 }
-
-/** Returns the default stdio transport used by the runtime. */
-function defaultTransport(): PluginRuntimeTransport {
-  return {
-    stdin: process.stdin,
-    stdout: process.stdout,
-  };
-}
-
-/** Sends one JSON-RPC response or notification through the active transport. */
-async function sendMessage(
-  transport: PluginRuntimeTransport | null,
-  value: unknown,
-): Promise<void> {
-  await writeFramedMessage((transport ?? defaultTransport()).stdout, value);
-}
-
-/** Builds the host helper for the currently active transport. */
-function createRuntimeHost(
-  transport: PluginRuntimeTransport | null,
-  logTarget: string | undefined,
-) {
-  return createHost(
-    async (method: string, params: unknown) => {
-      await sendMessage(transport, {
-        jsonrpc: '2.0',
-        method,
-        params,
-      });
-    },
-    { logTarget },
-  );
-}
-
-/** Type guard that returns true if the value is a valid RequestParams object. */
-function isRequestParams(value: unknown): value is RequestParams {
-  if (value == null || typeof value !== 'object' || Array.isArray(value)) {
-    return false;
-  }
-  return true;
-}
-
-/** Coerces unknown request method values into trimmed strings. Returns null for non-strings. */
-function asTrimmedString(value: unknown): string | null {
-  return typeof value === 'string' ? value.trim() : null;
-}
-
-/** Coerces unknown params to a Record, returning null for invalid input. */
-function asRecord(value: unknown): Record<string, unknown> | null {
-  if (isRequestParams(value)) {
-    return value as Record<string, unknown>;
-  }
-  return null;
-}
-
-/** Normalizes incoming data chunks to UTF-8 buffers. */
-function normalizeChunk(chunk: Buffer | string): Buffer {
-  return Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, 'utf8');
-}

package/src/lib/runtime/registration.ts

@@ -0,0 +1,93 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type {
+  PluginDelegates,
+  PluginImplements,
+  VcsDelegates,
+} from '../types';
+
+import type {
+  CreatePluginRuntimeOptions,
+  PluginRuntime,
+  PluginRuntimeContext,
+  PluginRuntimeTransport,
+} from './contracts';
+import { createPluginRuntime } from './factory';
+
+/** Describes the plugin module startup hook invoked by the generated bootstrap. */
+export type OnPluginStartHandler = () => void | Promise<void>;
+
+/** Describes runtime-wide options applied by the generated bootstrap. */
+export interface PluginModuleDefinition {
+  /** Stores optional `plugin.*` delegates contributed by the plugin module. */
+  plugin?: PluginDelegates<PluginRuntimeContext>;
+  /** Stores optional `vcs.*` delegates contributed by the plugin module. */
+  vcs?: VcsDelegates<PluginRuntimeContext>;
+  /** Stores optional capability overrides for `plugin.initialize`. */
+  implements?: Partial<PluginImplements>;
+  /** Stores the `host.log` target emitted by the runtime. */
+  logTarget?: string;
+  /** Stores the timeout in milliseconds for request handlers. */
+  timeout?: number;
+  /** Called during stop() after pending operations complete. */
+  onShutdown?: (error?: Error) => void | Promise<void>;
+}
+
+/** Describes one imported plugin module consumed by the generated bootstrap. */
+export interface PluginBootstrapModule {
+  /** Stores the plugin author's declarative runtime definition. */
+  PluginDefinition?: PluginModuleDefinition;
+  /** Stores the plugin author's startup hook. */
+  OnPluginStart?: OnPluginStartHandler;
+}
+
+/** Describes the generated bootstrap inputs used to import and start a plugin. */
+export interface BootstrapPluginModuleOptions {
+  /** Imports the plugin author's compiled runtime module. */
+  importPluginModule: () => Promise<PluginBootstrapModule>;
+  /** Stores the plugin module path for error messages. */
+  modulePath: string;
+  /** Overrides the transport used by the runtime loop. */
+  transport?: PluginRuntimeTransport;
+}
+
+/** Creates a runtime from one declarative plugin module definition. */
+export function createRegisteredPluginRuntime(
+  definition: PluginModuleDefinition = {},
+): PluginRuntime {
+  const options: CreatePluginRuntimeOptions = {
+    plugin: definition.plugin,
+    vcs: definition.vcs,
+    implements: definition.implements,
+    logTarget: definition.logTarget,
+    timeout: definition.timeout,
+    onShutdown: definition.onShutdown,
+  };
+  return createPluginRuntime(options);
+}
+
+/** Imports the author module, applies its definition, runs `OnPluginStart`, and starts the runtime loop. */
+export async function bootstrapPluginModule(
+  options: BootstrapPluginModuleOptions,
+): Promise<PluginRuntime> {
+  const pluginModule = await options.importPluginModule();
+  const onPluginStart = pluginModule.OnPluginStart;
+
+  if (typeof onPluginStart !== 'function') {
+    throw new Error(
+      `plugin module '${options.modulePath}' must export OnPluginStart()`,
+    );
+  }
+
+  try {
+    await onPluginStart();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`plugin startup failed: ${message}`);
+  }
+
+  const runtime = createRegisteredPluginRuntime(pluginModule.PluginDefinition);
+  runtime.start(options.transport);
+  return runtime;
+}