@openvcs/sdk 0.2.2 → 0.2.4

package/README.md

@@ -7,7 +7,9 @@
 OpenVCS SDK for npm-based plugin development.
 
 Install this package in plugin projects, scaffold a starter plugin, and package
-plugins into `.ovcsp` bundles.
+plugins into `.ovcsp` bundles. The SDK also exports a Node-only JSON-RPC runtime
+layer and shared protocol/types so plugins do not have to hand-roll stdio
+framing or method dispatch.
 
 ## Install
 
@@ -44,6 +46,7 @@ Run the local CLI through npm scripts:
 
 ```bash
 npm run openvcs -- --help
+npm run openvcs -- build --help
 npm run openvcs -- init --help
 npm run openvcs -- dist --help
 ```
@@ -60,29 +63,93 @@ The generated module template includes TypeScript and Node typings (`@types/node
 Plugin IDs entered during scaffold must not be `.`/`..` and must not contain path
 separators (`/` or `\\`).
 
+Generated module plugins now start with a working SDK runtime entrypoint:
+
+```ts
+import { createPluginRuntime, startPluginRuntime } from '@openvcs/sdk/runtime';
+
+const runtime = createPluginRuntime({
+  plugin: {
+    async 'plugin.init'(_params, context) {
+      context.host.info('OpenVCS plugin started');
+      return null;
+    },
+  },
+});
+
+startPluginRuntime(runtime);
+```
+
+Runtime and protocol imports are exposed as npm subpaths:
+
+```ts
+import { createPluginRuntime, pluginError } from '@openvcs/sdk/runtime';
+import type { PluginDelegates, VcsDelegates } from '@openvcs/sdk/types';
+```
+
+The runtime handles stdio framing, JSON-RPC request dispatch, host notifications,
+default `plugin.*` handlers, and exact-method delegate registration for `vcs.*`.
+
 Interactive theme plugin scaffold:
 
 ```bash
 openvcs init --theme my-theme
 ```
 
+## Build plugin assets
+
+In a generated code plugin folder:
+
+```bash
+npm run build
+```
+
+This runs `openvcs build`, which executes `scripts["build:plugin"]` and verifies
+that `bin/<module.exec>` now exists.
+
+Theme-only plugins can also run `npm run build`; the command exits successfully
+without producing `bin/` output.
+
 ## Build a `.ovcsp` bundle
 
 In a generated plugin folder:
 
 ```bash
-npm run build
+npm run dist
 ```
 
 This produces `dist/<plugin-id>.ovcsp`.
 
+`openvcs dist` runs `openvcs build` first unless `--no-build` is provided.
+Use `--no-build` when packaging prebuilt plugin assets.
+
+Generated code plugin scripts use this split by default:
+
+```json
+{
+  "scripts": {
+    "build:plugin": "tsc -p tsconfig.json",
+    "build": "openvcs build",
+    "dist": "openvcs dist --plugin-dir . --out dist"
+  }
+}
+```
+
 `.ovcsp` is a gzip-compressed tar archive (`tar.gz`) that contains a top-level
 `<plugin-id>/` directory with `openvcs.plugin.json` and plugin runtime assets.
 
+Bundle contents:
+- `openvcs.plugin.json` (required)
+- `icon.*` (optional, first found by extension priority)
+- `bin/` (required for code plugins with `module.exec`)
+- `entry` directory (required for UI plugins with top-level `entry` field; the entire directory containing the entry file is bundled)
+- `themes/` (required for theme plugins)
+- `node_modules/` (if npm dependencies are bundled)
+
 Dependency behavior while packaging:
 
 - npm dependency bundling is enabled by default when `package.json` exists.
-- If `package-lock.json` is missing, SDK generates it in the plugin worktree.
+- If `package-lock.json` is missing, SDK generates it in the staging area (not the plugin worktree).
 - Dependencies are installed into the bundle staging dir with:
   - `npm ci --omit=dev --ignore-scripts --no-bin-links --no-audit --no-fund`
 - Disable npm dependency processing with `--no-npm-deps`.
@@ -93,15 +160,17 @@ Dependency behavior while packaging:
 Package a plugin manually:
 
 ```bash
-openvcs dist --plugin-dir /path/to/plugin --out /path/to/dist
+npx openvcs build --plugin-dir /path/to/plugin
+npx openvcs dist --plugin-dir /path/to/plugin --out /path/to/dist
 ```
 
 Show command help:
 
 ```bash
-openvcs --help
-openvcs dist --help
-openvcs init --help
+npx openvcs --help
+npx openvcs build --help
+npx openvcs dist --help
+npx openvcs init --help
 ```
 
 ## Releases

package/lib/build.d.ts

@@ -0,0 +1,28 @@
+/** 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;
+}
+/** Returns the npm executable name for the current platform. */
+export declare function npmExecutable(): string;
+/** Formats help text for the build command. */
+export declare function buildUsage(commandName?: string): string;
+/** Parses `openvcs build` arguments. */
+export declare function parseBuildArgs(args: string[]): BuildArgs;
+/** Reads and validates the plugin manifest. */
+export declare function readManifest(pluginDir: string): ManifestInfo;
+/** Verifies that a declared module entry resolves to a real file under `bin/`. */
+export declare function validateDeclaredModuleExec(pluginDir: string, moduleExec: string | undefined): void;
+/** Returns whether the plugin repository has a `package.json`. */
+export declare function hasPackageJson(pluginDir: string): boolean;
+/** Runs a command in the given directory with optional verbose logging. */
+export declare function runCommand(program: string, args: string[], cwd: string, verbose: boolean): void;
+/** Builds a plugin's runtime assets when it declares a code module. */
+export declare function buildPluginAssets(parsedArgs: BuildArgs): ManifestInfo;

package/lib/build.js

@@ -0,0 +1,188 @@
+"use strict";
+// Copyright © 2025-2026 OpenVCS Contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.npmExecutable = npmExecutable;
+exports.buildUsage = buildUsage;
+exports.parseBuildArgs = parseBuildArgs;
+exports.readManifest = readManifest;
+exports.validateDeclaredModuleExec = validateDeclaredModuleExec;
+exports.hasPackageJson = hasPackageJson;
+exports.runCommand = runCommand;
+exports.buildPluginAssets = buildPluginAssets;
+const fs = require("node:fs");
+const path = require("node:path");
+const node_child_process_1 = require("node:child_process");
+const fs_utils_1 = require("./fs-utils");
+/** Returns the npm executable name for the current platform. */
+function npmExecutable() {
+    return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+/** Formats help text for the build command. */
+function buildUsage(commandName = "openvcs") {
+    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. */
+function parseBuildArgs(args) {
+    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];
+            continue;
+        }
+        if (arg === "-V" || arg === "--verbose") {
+            verbose = true;
+            continue;
+        }
+        if (arg === "--help") {
+            const error = new Error(buildUsage());
+            error.code = "USAGE";
+            throw error;
+        }
+        throw new Error(`unknown flag: ${arg}`);
+    }
+    return {
+        pluginDir: path.resolve(pluginDir),
+        verbose,
+    };
+}
+/** Reads and validates the plugin manifest. */
+function readManifest(pluginDir) {
+    const manifestPath = path.join(pluginDir, "openvcs.plugin.json");
+    let manifestRaw;
+    let manifestFd;
+    let manifest;
+    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) {
+        if (error.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) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`parse ${manifestPath}: ${detail}`);
+    }
+    const pluginId = typeof manifest.id === "string"
+        ? manifest.id.trim()
+        : "";
+    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.module;
+    const moduleExec = typeof moduleValue?.exec === "string" ? moduleValue.exec.trim() : undefined;
+    const entryValue = manifest.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/`. */
+function validateDeclaredModuleExec(pluginDir, moduleExec) {
+    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 (!(0, fs_utils_1.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`. */
+function hasPackageJson(pluginDir) {
+    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. */
+function runCommand(program, args, cwd, verbose) {
+    if (verbose) {
+        process.stderr.write(`Running command in ${cwd}: ${program} ${args.join(" ")}\n`);
+    }
+    const result = (0, node_child_process_1.spawnSync)(program, args, {
+        cwd,
+        stdio: ["ignore", verbose ? "inherit" : "ignore", "inherit"],
+    });
+    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) {
+    const packageJsonPath = path.join(pluginDir, "package.json");
+    let packageData;
+    try {
+        packageData = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    }
+    catch (error) {
+        if (error.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.scripts;
+    if (typeof scripts !== "object" || scripts === null) {
+        return {};
+    }
+    return scripts;
+}
+/** Builds a plugin's runtime assets when it declares a code module. */
+function buildPluginAssets(parsedArgs) {
+    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/lib/cli.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runCli = runCli;
+const build_1 = require("./build");
 const dist_1 = require("./dist");
 const init_1 = require("./init");
 const packageJson = require("../package.json");
@@ -11,7 +12,7 @@ function hasCode(error, code) {
         error.code === code);
 }
 function usage() {
-    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";
 }
 async function runCli(args) {
     if (args.length === 0) {
@@ -19,7 +20,7 @@ async function runCli(args) {
         process.exitCode = 1;
         return;
     }
-    if (args.includes("-v") || args.includes("--version")) {
+    if (args[0] === "-v" || args[0] === "--version") {
         process.stdout.write(`openvcs ${packageJson.version}\n`);
         return;
     }
@@ -46,6 +47,24 @@ async function runCli(args) {
             throw error;
         }
     }
+    if (command === "build") {
+        if (rest.includes("--help")) {
+            process.stdout.write((0, build_1.buildUsage)());
+            return;
+        }
+        try {
+            const parsed = (0, build_1.parseBuildArgs)(rest);
+            const manifest = (0, build_1.buildPluginAssets)(parsed);
+            process.stdout.write(`${manifest.pluginId}\n`);
+            return;
+        }
+        catch (error) {
+            if (hasCode(error, "USAGE")) {
+                throw new Error((0, build_1.buildUsage)());
+            }
+            throw error;
+        }
+    }
     if (command === "init") {
         if (rest.includes("--help")) {
             process.stdout.write((0, init_1.initUsage)());

package/lib/dist.d.ts

@@ -1,18 +1,14 @@
+import { readManifest, validateDeclaredModuleExec } from "./build";
 interface DistArgs {
     pluginDir: string;
     outDir: string;
     verbose: boolean;
     noNpmDeps: boolean;
-}
-interface ManifestInfo {
-    pluginId: string;
-    moduleExec: string | undefined;
-    manifestPath: string;
+    noBuild: boolean;
 }
 export declare function distUsage(commandName?: string): string;
 export declare function parseDistArgs(args: string[]): DistArgs;
-declare function readManifest(pluginDir: string): ManifestInfo;
-declare function validateDeclaredModuleExec(pluginDir: string, moduleExec: string | undefined): void;
+declare function validateManifestEntry(pluginDir: string, entry: string): void;
 declare function rejectNativeAddonsRecursive(dirPath: string): void;
 declare function copyIcon(pluginDir: string, bundleDir: string): void;
 declare function uniqueStagingDir(outDir: string): string;
@@ -25,6 +21,7 @@ export declare const __private: {
     rejectNativeAddonsRecursive: typeof rejectNativeAddonsRecursive;
     uniqueStagingDir: typeof uniqueStagingDir;
     validateDeclaredModuleExec: typeof validateDeclaredModuleExec;
+    validateManifestEntry: typeof validateManifestEntry;
     writeTarGz: typeof writeTarGz;
 };
 export {};