@openvcs/sdk 0.2.2 → 0.2.4

package/src/lib/build.ts

@@ -0,0 +1,229 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawnSync } from "node:child_process";
+
+import { isPathInside } from "./fs-utils";
+
+type UsageError = Error & { code?: string };
+
+/** CLI arguments for `openvcs build`. */
+export interface BuildArgs {
+  pluginDir: string;
+  verbose: boolean;
+}
+
+/** Trimmed manifest details used by build and dist flows. */
+export interface ManifestInfo {
+  pluginId: string;
+  moduleExec: string | undefined;
+  entry: string | undefined;
+  manifestPath: string;
+}
+
+interface CommandResult {
+  status: number | null;
+  error?: Error;
+}
+
+interface PackageScripts {
+  [scriptName: string]: unknown;
+}
+
+/** Returns the npm executable name for the current platform. */
+export function npmExecutable(): string {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
+/** Formats help text for the build command. */
+export function buildUsage(commandName = "openvcs"): string {
+  return `${commandName} build [args]\n\n  --plugin-dir <path>   Plugin repository root (contains openvcs.plugin.json)\n  -V, --verbose         Enable verbose output\n`;
+}
+
+/** Parses `openvcs build` arguments. */
+export function parseBuildArgs(args: string[]): BuildArgs {
+  let pluginDir = process.cwd();
+  let verbose = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--plugin-dir") {
+      index += 1;
+      if (index >= args.length) {
+        throw new Error("missing value for --plugin-dir");
+      }
+      pluginDir = args[index] as string;
+      continue;
+    }
+    if (arg === "-V" || arg === "--verbose") {
+      verbose = true;
+      continue;
+    }
+    if (arg === "--help") {
+      const error = new Error(buildUsage()) as UsageError;
+      error.code = "USAGE";
+      throw error;
+    }
+    throw new Error(`unknown flag: ${arg}`);
+  }
+
+  return {
+    pluginDir: path.resolve(pluginDir),
+    verbose,
+  };
+}
+
+/** Reads and validates the plugin manifest. */
+export function readManifest(pluginDir: string): ManifestInfo {
+  const manifestPath = path.join(pluginDir, "openvcs.plugin.json");
+  let manifestRaw: string;
+  let manifestFd: number | undefined;
+  let manifest: unknown;
+  try {
+    manifestFd = fs.openSync(manifestPath, "r");
+    const manifestStat = fs.fstatSync(manifestFd);
+    if (!manifestStat.isFile()) {
+      throw new Error(`missing openvcs.plugin.json at ${manifestPath}`);
+    }
+    manifestRaw = fs.readFileSync(manifestFd, "utf8");
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(`missing openvcs.plugin.json at ${manifestPath}`);
+    }
+    throw error;
+  } finally {
+    if (typeof manifestFd === "number") {
+      fs.closeSync(manifestFd);
+    }
+  }
+
+  try {
+    manifest = JSON.parse(manifestRaw);
+  } catch (error: unknown) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`parse ${manifestPath}: ${detail}`);
+  }
+
+  const pluginId =
+    typeof (manifest as { id?: unknown }).id === "string"
+      ? ((manifest as { id: string }).id.trim() as string)
+      : "";
+  if (!pluginId) {
+    throw new Error(`manifest ${manifestPath} is missing a string 'id'`);
+  }
+  if (pluginId === "." || pluginId === ".." || pluginId.includes("/") || pluginId.includes("\\")) {
+    throw new Error(`manifest id must not contain path separators: ${pluginId}`);
+  }
+
+  const moduleValue = (manifest as { module?: { exec?: unknown } }).module;
+  const moduleExec = typeof moduleValue?.exec === "string" ? moduleValue.exec.trim() : undefined;
+
+  const entryValue = (manifest as { entry?: unknown }).entry;
+  const entry = typeof entryValue === "string" ? entryValue.trim() : undefined;
+
+  return {
+    pluginId,
+    moduleExec,
+    entry,
+    manifestPath,
+  };
+}
+
+/** Verifies that a declared module entry resolves to a real file under `bin/`. */
+export function validateDeclaredModuleExec(pluginDir: string, moduleExec: string | undefined): void {
+  if (!moduleExec) {
+    return;
+  }
+
+  const normalizedExec = moduleExec.trim();
+  const lowered = normalizedExec.toLowerCase();
+  if (!lowered.endsWith(".js") && !lowered.endsWith(".mjs") && !lowered.endsWith(".cjs")) {
+    throw new Error(`manifest exec must end with .js/.mjs/.cjs (Node runtime): ${moduleExec}`);
+  }
+  if (path.isAbsolute(normalizedExec)) {
+    throw new Error(`manifest module.exec must be a relative path under bin/: ${moduleExec}`);
+  }
+
+  const binDir = path.resolve(pluginDir, "bin");
+  const targetPath = path.resolve(binDir, normalizedExec);
+  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}`);
+  }
+}
+
+/** Returns whether the plugin repository has a `package.json`. */
+export function hasPackageJson(pluginDir: string): boolean {
+  const packageJsonPath = path.join(pluginDir, "package.json");
+  return fs.existsSync(packageJsonPath) && fs.lstatSync(packageJsonPath).isFile();
+}
+
+/** Runs a command in the given directory with optional verbose logging. */
+export function runCommand(program: string, args: string[], cwd: string, verbose: boolean): void {
+  if (verbose) {
+    process.stderr.write(`Running command in ${cwd}: ${program} ${args.join(" ")}\n`);
+  }
+
+  const result = spawnSync(program, args, {
+    cwd,
+    stdio: ["ignore", verbose ? "inherit" : "ignore", "inherit"],
+  }) as CommandResult;
+
+  if (result.error) {
+    throw new Error(`failed to spawn '${program}' in ${cwd}: ${result.error.message}`);
+  }
+  if (result.status === 0) {
+    return;
+  }
+
+  throw new Error(`command failed (${program} ${args.join(" ")}), exit code ${result.status}`);
+}
+
+/** Reads `package.json` scripts for the plugin, if present. */
+function readPackageScripts(pluginDir: string): PackageScripts {
+  const packageJsonPath = path.join(pluginDir, "package.json");
+  let packageData: unknown;
+  try {
+    packageData = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(`code plugins must include package.json: ${packageJsonPath}`);
+    }
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`parse ${packageJsonPath}: ${detail}`);
+  }
+
+  const scripts = (packageData as { scripts?: unknown }).scripts;
+  if (typeof scripts !== "object" || scripts === null) {
+    return {};
+  }
+  return scripts as PackageScripts;
+}
+
+/** Builds a plugin's runtime assets when it declares a code module. */
+export function buildPluginAssets(parsedArgs: BuildArgs): ManifestInfo {
+  const manifest = readManifest(parsedArgs.pluginDir);
+  if (!manifest.moduleExec) {
+    return manifest;
+  }
+
+  if (!hasPackageJson(parsedArgs.pluginDir)) {
+    throw new Error(`code plugins must include package.json: ${path.join(parsedArgs.pluginDir, "package.json")}`);
+  }
+
+  const scripts = readPackageScripts(parsedArgs.pluginDir);
+  const buildScript = scripts["build:plugin"];
+  if (typeof buildScript !== "string" || buildScript.trim() === "") {
+    throw new Error(
+      `code plugins must define scripts[\"build:plugin\"] in ${path.join(parsedArgs.pluginDir, "package.json")}`
+    );
+  }
+
+  runCommand(npmExecutable(), ["run", "build:plugin"], parsedArgs.pluginDir, parsedArgs.verbose);
+  validateDeclaredModuleExec(parsedArgs.pluginDir, manifest.moduleExec);
+  return manifest;
+}

package/src/lib/cli.ts

@@ -1,3 +1,4 @@
+import { buildPluginAssets, buildUsage, parseBuildArgs } from "./build";
 import { bundlePlugin, distUsage, parseDistArgs } from "./dist";
 import { initUsage, runInitCommand } from "./init";
 
@@ -17,7 +18,7 @@ function hasCode(error: unknown, code: string): boolean {
 }
 
 function usage(): string {
-  return "Usage: openvcs <command> [options]\n\nCommands:\n  dist [args]            Package plugin into .ovcsp\n  init [--theme] [dir]   Interactively scaffold a plugin project\n  -v, --version          Show version information\n\nDist args:\n  --plugin-dir <path>    Plugin root containing openvcs.plugin.json\n  --out <path>           Output directory (default: ./dist)\n  --no-npm-deps          Skip npm dependency bundling\n  -V, --verbose          Verbose output\n";
+  return "Usage: openvcs <command> [options]\n\nCommands:\n  build [args]           Build plugin runtime assets\n  dist [args]            Package plugin into .ovcsp\n  init [--theme] [dir]   Interactively scaffold a plugin project\n  -v, --version          Show version information\n\nBuild args:\n  --plugin-dir <path>    Plugin root containing openvcs.plugin.json\n  -V, --verbose          Verbose output\n\nDist args:\n  --plugin-dir <path>    Plugin root containing openvcs.plugin.json\n  --out <path>           Output directory (default: ./dist)\n  --no-build             Skip plugin build before packaging\n  --no-npm-deps          Skip npm dependency bundling\n  -V, --verbose          Verbose output\n";
 }
 
 export async function runCli(args: string[]): Promise<void> {
@@ -27,7 +28,7 @@ export async function runCli(args: string[]): Promise<void> {
     return;
   }
 
-  if (args.includes("-v") || args.includes("--version")) {
+  if (args[0] === "-v" || args[0] === "--version") {
     process.stdout.write(`openvcs ${packageJson.version}\n`);
     return;
   }
@@ -56,6 +57,24 @@ export async function runCli(args: string[]): Promise<void> {
     }
   }
 
+  if (command === "build") {
+    if (rest.includes("--help")) {
+      process.stdout.write(buildUsage());
+      return;
+    }
+    try {
+      const parsed = parseBuildArgs(rest);
+      const manifest = buildPluginAssets(parsed);
+      process.stdout.write(`${manifest.pluginId}\n`);
+      return;
+    } catch (error: unknown) {
+      if (hasCode(error, "USAGE")) {
+        throw new Error(buildUsage());
+      }
+      throw error;
+    }
+  }
+
   if (command === "init") {
     if (rest.includes("--help")) {
       process.stdout.write(initUsage());

package/src/lib/dist.ts

@@ -1,7 +1,15 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { spawnSync } from "node:child_process";
 import tar = require("tar");
+import {
+  buildPluginAssets,
+  hasPackageJson,
+  ManifestInfo,
+  npmExecutable,
+  readManifest,
+  runCommand,
+  validateDeclaredModuleExec,
+} from "./build";
 import {
   copyDirectoryRecursiveStrict,
   copyFileStrict,
@@ -19,25 +27,11 @@ interface DistArgs {
   outDir: string;
   verbose: boolean;
   noNpmDeps: boolean;
-}
-
-interface ManifestInfo {
-  pluginId: string;
-  moduleExec: string | undefined;
-  manifestPath: string;
-}
-
-interface CommandResult {
-  status: number | null;
-  error?: Error;
-}
-
-function npmExecutable(): string {
-  return process.platform === "win32" ? "npm.cmd" : "npm";
+  noBuild: boolean;
 }
 
 export function distUsage(commandName = "openvcs"): string {
-  return `${commandName} dist [args]\n\n  --plugin-dir <path>   Plugin repository root (contains openvcs.plugin.json)\n  --out <path>          Output directory (default: ./dist)\n  --no-npm-deps         Disable npm dependency bundling (enabled by default)\n  -V, --verbose         Enable verbose output\n`;
+  return `${commandName} dist [args]\n\n  --plugin-dir <path>   Plugin repository root (contains openvcs.plugin.json)\n  --out <path>          Output directory (default: ./dist)\n  --no-build            Skip the plugin build step before packaging\n  --no-npm-deps         Disable npm dependency bundling (enabled by default)\n  -V, --verbose         Enable verbose output\n`;
 }
 
 export function parseDistArgs(args: string[]): DistArgs {
@@ -45,6 +39,7 @@ export function parseDistArgs(args: string[]): DistArgs {
   let outDir = "dist";
   let verbose = false;
   let noNpmDeps = false;
+  let noBuild = false;
 
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
@@ -68,6 +63,10 @@ export function parseDistArgs(args: string[]): DistArgs {
       noNpmDeps = true;
       continue;
     }
+    if (arg === "--no-build") {
+      noBuild = true;
+      continue;
+    }
     if (arg === "-V" || arg === "--verbose") {
       verbose = true;
       continue;
@@ -85,110 +84,34 @@ export function parseDistArgs(args: string[]): DistArgs {
     outDir: path.resolve(outDir),
     verbose,
     noNpmDeps,
+    noBuild,
   };
 }
 
-function readManifest(pluginDir: string): ManifestInfo {
-  const manifestPath = path.join(pluginDir, "openvcs.plugin.json");
-  let manifestRaw: string;
-  let manifestFd: number | undefined;
-  let manifest: unknown;
-  try {
-    manifestFd = fs.openSync(manifestPath, "r");
-    const manifestStat = fs.fstatSync(manifestFd);
-    if (!manifestStat.isFile()) {
-      throw new Error(`missing openvcs.plugin.json at ${manifestPath}`);
-    }
-    manifestRaw = fs.readFileSync(manifestFd, "utf8");
-  } catch (error: unknown) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-      throw new Error(`missing openvcs.plugin.json at ${manifestPath}`);
-    }
-    throw error;
-  } finally {
-    if (typeof manifestFd === "number") {
-      fs.closeSync(manifestFd);
-    }
+function validateManifestEntry(pluginDir: string, entry: string): void {
+  const normalized = entry.trim();
+  if (path.isAbsolute(normalized)) {
+    throw new Error(`manifest entry must be a relative path: ${entry}`);
   }
-
-  try {
-    manifest = JSON.parse(manifestRaw);
-  } catch (error: unknown) {
-    const detail = error instanceof Error ? error.message : String(error);
-    throw new Error(`parse ${manifestPath}: ${detail}`);
-  }
-
-  const pluginId =
-    typeof (manifest as { id?: unknown }).id === "string"
-      ? ((manifest as { id: string }).id.trim() as string)
-      : "";
-  if (!pluginId) {
-    throw new Error(`manifest ${manifestPath} is missing a string 'id'`);
-  }
-  if (pluginId === "." || pluginId === ".." || pluginId.includes("/") || pluginId.includes("\\")) {
-    throw new Error(`manifest id must not contain path separators: ${pluginId}`);
-  }
-
-  const moduleValue = (manifest as { module?: { exec?: unknown } }).module;
-  const moduleExec = typeof moduleValue?.exec === "string" ? moduleValue.exec.trim() : undefined;
-
-  return {
-    pluginId,
-    moduleExec,
-    manifestPath,
-  };
-}
-
-function validateDeclaredModuleExec(pluginDir: string, moduleExec: string | undefined): void {
-  if (!moduleExec) {
-    return;
-  }
-
-  const normalizedExec = moduleExec.trim();
-  const lowered = normalizedExec.toLowerCase();
-  if (!lowered.endsWith(".js") && !lowered.endsWith(".mjs") && !lowered.endsWith(".cjs")) {
-    throw new Error(`manifest exec must end with .js/.mjs/.cjs (Node runtime): ${moduleExec}`);
-  }
-  if (path.isAbsolute(normalizedExec)) {
-    throw new Error(`manifest module.exec must be a relative path under bin/: ${moduleExec}`);
-  }
-
-  const binDir = path.resolve(pluginDir, "bin");
-  const targetPath = path.resolve(binDir, normalizedExec);
-  if (!isPathInside(binDir, targetPath) || targetPath === binDir) {
-    throw new Error(`manifest module.exec must point to a file under bin/: ${moduleExec}`);
+  const targetPath = path.resolve(pluginDir, normalized);
+  const pluginDirResolved = path.resolve(pluginDir);
+  if (!isPathInside(pluginDirResolved, targetPath) || targetPath === pluginDirResolved) {
+    throw new Error(`manifest entry must point to a file under the plugin directory: ${entry}`);
   }
   if (!fs.existsSync(targetPath) || !fs.lstatSync(targetPath).isFile()) {
-    throw new Error(`module entrypoint not found at ${targetPath}`);
+    throw new Error(`manifest entry file not found: ${entry}`);
   }
 }
 
-function hasPackageJson(pluginDir: string): boolean {
-  const packageJsonPath = path.join(pluginDir, "package.json");
-  return fs.existsSync(packageJsonPath) && fs.lstatSync(packageJsonPath).isFile();
+function copyEntryDirectory(pluginDir: string, bundleDir: string, entry: string): void {
+  const normalized = entry.trim();
+  const entryDir = path.dirname(normalized);
+  const sourceDir = path.join(pluginDir, entryDir);
+  const destDir = path.join(bundleDir, entryDir);
+  copyDirectoryRecursiveStrict(sourceDir, destDir);
 }
 
-function runCommand(program: string, args: string[], cwd: string, verbose: boolean): void {
-  if (verbose) {
-    process.stderr.write(`Running command in ${cwd}: ${program} ${args.join(" ")}\n`);
-  }
-
-  const result = spawnSync(program, args, {
-    cwd,
-    stdio: ["ignore", verbose ? "inherit" : "ignore", "inherit"],
-  }) as CommandResult;
-
-  if (result.error) {
-    throw new Error(`failed to spawn '${program}' in ${cwd}: ${result.error.message}`);
-  }
-  if (result.status === 0) {
-    return;
-  }
-
-  throw new Error(`command failed (${program} ${args.join(" ")}), exit code ${result.status}`);
-}
-
-function ensurePackageLock(pluginDir: string, verbose: boolean): void {
+function ensurePackageLock(pluginDir: string, bundleDir: string, verbose: boolean): void {
   if (!hasPackageJson(pluginDir)) {
     return;
   }
@@ -197,13 +120,16 @@ function ensurePackageLock(pluginDir: string, verbose: boolean): void {
     return;
   }
 
+  const packageJsonPath = path.join(pluginDir, "package.json");
+  copyFileStrict(packageJsonPath, path.join(bundleDir, "package.json"));
+
   if (verbose) {
-    process.stderr.write(`Generating package-lock.json in ${pluginDir}\n`);
+    process.stderr.write(`Generating package-lock.json in staging\n`);
   }
   runCommand(
     npmExecutable(),
     ["install", "--package-lock-only", "--ignore-scripts", "--no-audit", "--no-fund"],
-    pluginDir,
+    bundleDir,
     verbose
   );
 }
@@ -215,12 +141,17 @@ function copyNpmFilesToStaging(pluginDir: string, bundleDir: string): void {
   if (!fs.existsSync(packageJsonPath) || !fs.lstatSync(packageJsonPath).isFile()) {
     throw new Error(`missing package.json at ${packageJsonPath}`);
   }
-  if (!fs.existsSync(lockPath) || !fs.lstatSync(lockPath).isFile()) {
-    throw new Error(`missing package-lock.json at ${lockPath}`);
-  }
 
   copyFileStrict(packageJsonPath, path.join(bundleDir, "package.json"));
-  copyFileStrict(lockPath, path.join(bundleDir, "package-lock.json"));
+
+  const stagedLockPath = path.join(bundleDir, "package-lock.json");
+  if (fs.existsSync(stagedLockPath) && fs.lstatSync(stagedLockPath).isFile()) {
+    return;
+  }
+
+  if (fs.existsSync(lockPath) && fs.lstatSync(lockPath).isFile()) {
+    copyFileStrict(lockPath, path.join(bundleDir, "package-lock.json"));
+  }
 }
 
 function rejectNativeAddonsRecursive(dirPath: string): void {
@@ -264,14 +195,21 @@ function installNpmDependencies(pluginDir: string, bundleDir: string, verbose: b
 }
 
 function copyIcon(pluginDir: string, bundleDir: string): void {
-  for (const extension of ICON_EXTENSIONS) {
-    const fileName = `icon.${extension}`;
-    const sourcePath = path.join(pluginDir, fileName);
-    if (!fs.existsSync(sourcePath)) {
-      continue;
+  const entries = fs.readdirSync(pluginDir, { withFileTypes: true });
+  const iconEntries = entries.filter((e) => {
+    if (!e.isFile()) return false;
+    const name = e.name.toLowerCase();
+    return name.startsWith("icon.") && ICON_EXTENSIONS.includes(name.slice(5));
+  });
+  for (const ext of ICON_EXTENSIONS) {
+    const found = iconEntries.find((e) => e.name.toLowerCase() === `icon.${ext}`);
+    if (found) {
+      copyFileStrict(
+        path.join(pluginDir, found.name),
+        path.join(bundleDir, found.name)
+      );
+      return;
     }
-    copyFileStrict(sourcePath, path.join(bundleDir, fileName));
-    return;
   }
 }
 
@@ -297,16 +235,21 @@ async function writeTarGz(outPath: string, baseDir: string, folderName: string):
 }
 
 export async function bundlePlugin(parsedArgs: DistArgs): Promise<string> {
-  const { pluginDir, outDir, verbose, noNpmDeps } = parsedArgs;
+  const { pluginDir, outDir, verbose, noNpmDeps, noBuild } = parsedArgs;
   if (verbose) {
     process.stderr.write(`Bundling plugin from: ${pluginDir}\n`);
   }
 
-  const { pluginId, moduleExec, manifestPath } = readManifest(pluginDir);
+  const { pluginId, moduleExec, entry, manifestPath } = noBuild
+    ? readManifest(pluginDir)
+    : buildPluginAssets({ pluginDir, verbose });
   const themesPath = path.join(pluginDir, "themes");
   const hasThemes = fs.existsSync(themesPath) && fs.lstatSync(themesPath).isDirectory();
-  if (!moduleExec && !hasThemes) {
-    throw new Error("manifest has no module.exec or themes/");
+  if (entry) {
+    validateManifestEntry(pluginDir, entry);
+  }
+  if (!moduleExec && !hasThemes && !entry) {
+    throw new Error("manifest has no module.exec, entry, or themes/");
   }
   validateDeclaredModuleExec(pluginDir, moduleExec);
 
@@ -320,6 +263,10 @@ export async function bundlePlugin(parsedArgs: DistArgs): Promise<string> {
     copyFileStrict(manifestPath, path.join(bundleDir, "openvcs.plugin.json"));
     copyIcon(pluginDir, bundleDir);
 
+    if (entry) {
+      copyEntryDirectory(pluginDir, bundleDir, entry);
+    }
+
     const sourceBinDir = path.join(pluginDir, "bin");
     if (fs.existsSync(sourceBinDir) && fs.lstatSync(sourceBinDir).isDirectory()) {
       copyDirectoryRecursiveStrict(sourceBinDir, path.join(bundleDir, "bin"));
@@ -329,7 +276,7 @@ export async function bundlePlugin(parsedArgs: DistArgs): Promise<string> {
     }
 
     if (!noNpmDeps && hasPackageJson(pluginDir)) {
-      ensurePackageLock(pluginDir, verbose);
+      ensurePackageLock(pluginDir, bundleDir, verbose);
       installNpmDependencies(pluginDir, bundleDir, verbose);
     }
 
@@ -352,5 +299,6 @@ export const __private = {
   rejectNativeAddonsRecursive,
   uniqueStagingDir,
   validateDeclaredModuleExec,
+  validateManifestEntry,
   writeTarGz,
 };

package/src/lib/init.ts

@@ -236,12 +236,15 @@ function writeModuleTemplate(answers: InitAnswers): void {
     private: true,
     type: "module",
     scripts: {
-      "build:ts": "tsc -p tsconfig.json",
-      build: "npm run build:ts && openvcs dist --plugin-dir . --out dist",
-      test: "openvcs dist --plugin-dir . --out dist --no-npm-deps",
+      "build:plugin": "tsc -p tsconfig.json",
+      build: "openvcs build",
+      dist: "openvcs dist --plugin-dir . --out dist",
+      test: "openvcs dist --plugin-dir . --out dist --no-build --no-npm-deps",
     },
-    devDependencies: {
+    dependencies: {
       "@openvcs/sdk": `^${packageJson.version}`,
+    },
+    devDependencies: {
       "@types/node": "^22.0.0",
       typescript: "^5.8.2",
     },
@@ -261,7 +264,7 @@ function writeModuleTemplate(answers: InitAnswers): void {
   });
   writeText(
     path.join(answers.targetDir, "src", "plugin.ts"),
-    "const message = \"OpenVCS plugin started\";\nprocess.stderr.write(`${message}\\n`);\n"
+    "// 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"
   );
 }
 
@@ -272,10 +275,11 @@ function writeThemeTemplate(answers: InitAnswers): void {
     version: answers.pluginVersion,
     private: true,
     scripts: {
-      build: "openvcs dist --plugin-dir . --out dist",
-      test: "openvcs dist --plugin-dir . --out dist --no-npm-deps",
+      build: "openvcs build",
+      dist: "openvcs dist --plugin-dir . --out dist",
+      test: "openvcs dist --plugin-dir . --out dist --no-build --no-npm-deps",
     },
-    devDependencies: {
+    dependencies: {
       "@openvcs/sdk": `^${packageJson.version}`,
     },
   });
@@ -361,4 +365,5 @@ export const __private = {
   defaultPluginIdFromDir,
   sanitizeIdToken,
   validatePluginId,
+  writeModuleTemplate,
 };

package/src/lib/runtime/contracts.ts

@@ -0,0 +1,52 @@
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+import type { PluginHost, PluginImplements, PluginDelegates, JsonRpcId, JsonRpcRequest, VcsDelegates } from '../types';
+
+/** Describes the transport endpoints used by the plugin runtime loop. */
+export interface PluginRuntimeTransport {
+  /** Stores the readable stdin-like stream receiving framed messages. */
+  stdin: NodeJS.ReadStream;
+  /** Stores the writable stdout-like stream sending framed messages. */
+  stdout: NodeJS.WritableStream;
+}
+
+/** Describes the context object passed to every SDK delegate handler. */
+export interface PluginRuntimeContext {
+  /** Stores the active host notification helper. */
+  host: PluginHost;
+  /** Stores the request id currently being processed. */
+  requestId: JsonRpcId;
+  /** Stores the current host method name. */
+  method: string;
+}
+
+/** Describes the options accepted by `createPluginRuntime`. */
+export interface CreatePluginRuntimeOptions {
+  /** Stores optional plugin lifecycle and settings delegates. */
+  plugin?: PluginDelegates<PluginRuntimeContext>;
+  /** Stores optional VCS method delegates. */
+  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 when runtime starts and begins processing requests. */
+  onStart?: () => void | Promise<void>;
+  /** Called during stop() after pending operations complete. Called with error if shutdown due to processing error. */
+  onShutdown?: (error?: Error) => void | Promise<void>;
+}
+
+/** Describes one created SDK plugin runtime instance. */
+export interface PluginRuntime {
+  /** Starts listening on stdio for framed JSON-RPC requests. */
+  start(transport?: PluginRuntimeTransport): void;
+  /** Stops the runtime and cleans up pending operations. */
+  stop(): void;
+  /** Consumes one raw stdio chunk and dispatches complete requests. */
+  consumeChunk(chunk: Buffer | string): void;
+  /** Dispatches one already-decoded JSON-RPC request. */
+  dispatchRequest(request: JsonRpcRequest): Promise<void>;
+}