@openvcs/sdk 0.2.4 → 0.2.6

package/test/build.test.js

@@ -3,9 +3,35 @@ const fs = require("node:fs");
 const path = require("node:path");
 const test = require("node:test");
 
-const { buildPluginAssets, parseBuildArgs, readManifest, validateDeclaredModuleExec } = require("../lib/build");
+const {
+  buildPluginAssets,
+  parseBuildArgs,
+  readManifest,
+  validateDeclaredModuleExec,
+  validateGeneratedBootstrapTargets,
+} = require("../lib/build");
 const { cleanupTempDir, makeTempDir, writeJson, writeText } = require("./helpers");
 
+test("renderGeneratedBootstrap creates ESM code", () => {
+  const output = require("../lib/build").renderGeneratedBootstrap("./plugin.js", true);
+  assert.match(output, /^#!/);
+  assert.match(output, /import \{ bootstrapPluginModule \}/);
+  assert.match(output, /import\('\.\/plugin\.js'\)/);
+});
+
+test("renderGeneratedBootstrap creates CJS code", () => {
+  const output = require("../lib/build").renderGeneratedBootstrap("./plugin.js", false);
+  assert.match(output, /^#!/);
+  assert.match(output, /require\('@openvcs\/sdk\/runtime'\)/);
+  assert.match(output, /require\('\.\/plugin\.js'\)/);
+  assert.match(output, /\(\s*async\s*\(\s*\)\s*=>/);
+});
+
+test("renderGeneratedBootstrap handles subdirectory import paths", () => {
+  const output = require("../lib/build").renderGeneratedBootstrap("./subdir/plugin.js", true);
+  assert.match(output, /import\('\.\/subdir\/plugin\.js'\)/);
+});
+
 test("parseBuildArgs uses defaults", () => {
   const parsed = parseBuildArgs([]);
   assert.equal(parsed.pluginDir, process.cwd());
@@ -39,7 +65,7 @@ test("buildPluginAssets requires package.json for code plugins", () => {
 
   writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
     id: "missing-package",
-    module: { exec: "plugin.js" },
+    module: { exec: "openvcs-plugin.js" },
   });
 
   assert.throws(
@@ -56,7 +82,7 @@ test("buildPluginAssets runs build:plugin and validates output", () => {
 
   writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
     id: "builder",
-    module: { exec: "plugin.js" },
+    module: { exec: "openvcs-plugin.js" },
   });
   writeJson(path.join(pluginDir, "package.json"), {
     name: "builder",
@@ -74,6 +100,11 @@ test("buildPluginAssets runs build:plugin and validates output", () => {
 
   assert.equal(manifest.pluginId, "builder");
   assert.equal(fs.existsSync(path.join(pluginDir, "bin", "plugin.js")), true);
+  assert.equal(fs.existsSync(path.join(pluginDir, "bin", "openvcs-plugin.js")), true);
+  assert.match(
+    fs.readFileSync(path.join(pluginDir, "bin", "openvcs-plugin.js"), "utf8"),
+    /bootstrapPluginModule/
+  );
   cleanupTempDir(root);
 });
 
@@ -83,13 +114,123 @@ test("readManifest and validateDeclaredModuleExec stay reusable", () => {
 
   writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
     id: "reusable",
-    module: { exec: "plugin.js" },
+    module: { exec: "openvcs-plugin.js" },
   });
-  writeText(path.join(pluginDir, "bin", "plugin.js"), "export {};\n");
+  writeText(path.join(pluginDir, "bin", "plugin.js"), "export function OnPluginStart() {}\n");
+  writeText(path.join(pluginDir, "bin", "openvcs-plugin.js"), "export {};\n");
 
   const manifest = readManifest(pluginDir);
-  assert.equal(manifest.moduleExec, "plugin.js");
+  assert.equal(manifest.moduleExec, "openvcs-plugin.js");
+  assert.doesNotThrow(() => validateGeneratedBootstrapTargets(pluginDir, manifest.moduleExec));
   assert.doesNotThrow(() => validateDeclaredModuleExec(pluginDir, manifest.moduleExec));
 
   cleanupTempDir(root);
 });
+
+test("validateGeneratedBootstrapTargets rejects module.exec collisions", () => {
+  const root = makeTempDir("openvcs-sdk-test");
+  const pluginDir = path.join(root, "plugin");
+
+  writeText(path.join(pluginDir, "bin", "plugin.js"), "export function OnPluginStart() {}\n");
+
+  assert.throws(
+    () => validateGeneratedBootstrapTargets(pluginDir, "plugin.js"),
+    /must not be plugin\.js/
+  );
+
+  cleanupTempDir(root);
+});
+
+test("validateGeneratedBootstrapTargets rejects case-insensitive collisions", () => {
+  const root = makeTempDir("openvcs-sdk-test");
+  const pluginDir = path.join(root, "plugin");
+
+  writeText(path.join(pluginDir, "bin", "plugin.js"), "export function OnPluginStart() {}\n");
+
+  assert.throws(
+    () => validateGeneratedBootstrapTargets(pluginDir, "Plugin.js"),
+    /must not be plugin\.js/
+  );
+  assert.throws(
+    () => validateGeneratedBootstrapTargets(pluginDir, "PLUGIN.JS"),
+    /must not be plugin\.js/
+  );
+
+  cleanupTempDir(root);
+});
+
+test("generateModuleBootstrap handles subdirectory module.exec paths", () => {
+  const root = makeTempDir("openvcs-sdk-test");
+  const pluginDir = path.join(root, "plugin");
+
+  writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
+    id: "subdir-plugin",
+    module: { exec: "subdir/openvcs-plugin.js" },
+  });
+  writeJson(path.join(pluginDir, "package.json"), {
+    name: "subdir-plugin",
+    type: "module",
+    private: true,
+    scripts: { "build:plugin": "node ./scripts/build.js" },
+  });
+  writeText(path.join(pluginDir, "bin", "plugin.js"), "export function OnPluginStart() {}\n");
+  writeText(path.join(pluginDir, "bin", "subdir", "openvcs-plugin.js"), "export {};\n");
+
+  const { generateModuleBootstrap } = require("../lib/build");
+  generateModuleBootstrap(pluginDir, "subdir/openvcs-plugin.js");
+
+  const bootstrapContent = fs.readFileSync(
+    path.join(pluginDir, "bin", "subdir", "openvcs-plugin.js"),
+    "utf8"
+  );
+  assert.match(bootstrapContent, /\.\.\/plugin\.js/);
+  cleanupTempDir(root);
+});
+
+test("detectEsmMode returns true for package.json type: module", () => {
+  const root = makeTempDir("openvcs-sdk-test");
+  const pluginDir = path.join(root, "plugin");
+
+  writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
+    id: "esm-plugin",
+    module: { exec: "bootstrap.js" },
+  });
+  writeJson(path.join(pluginDir, "package.json"), {
+    name: "esm-plugin",
+    type: "module",
+  });
+  writeText(path.join(pluginDir, "bin", "plugin.js"), "export function OnPluginStart() {}\n");
+  writeText(path.join(pluginDir, "bin", "bootstrap.js"), "export {};\n");
+
+  const { generateModuleBootstrap } = require("../lib/build");
+  generateModuleBootstrap(pluginDir, "bootstrap.js");
+
+  const bootstrapContent = fs.readFileSync(path.join(pluginDir, "bin", "bootstrap.js"), "utf8");
+  assert.match(bootstrapContent, /^#!/);
+  assert.match(bootstrapContent, /^import\s*{/m);
+  cleanupTempDir(root);
+});
+
+test("detectEsmMode returns false for package.json type: commonjs", () => {
+  const root = makeTempDir("openvcs-sdk-test");
+  const pluginDir = path.join(root, "plugin");
+
+  writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
+    id: "cjs-plugin",
+    module: { exec: "bootstrap.js" },
+  });
+  writeJson(path.join(pluginDir, "package.json"), {
+    name: "cjs-plugin",
+    type: "commonjs",
+  });
+  writeText(path.join(pluginDir, "bin", "plugin.js"), "export function OnPluginStart() {}\n");
+  writeText(path.join(pluginDir, "bin", "bootstrap.js"), "export {};\n");
+
+  const { generateModuleBootstrap } = require("../lib/build");
+  generateModuleBootstrap(pluginDir, "bootstrap.js");
+
+  const bootstrapContent = fs.readFileSync(path.join(pluginDir, "bin", "bootstrap.js"), "utf8");
+  assert.match(bootstrapContent, /require\(/);
+  assert.match(bootstrapContent, /\(\s*async\s*\(\s*\)\s*=>/);
+  cleanupTempDir(root);
+});

package/test/cli.test.js

@@ -67,9 +67,10 @@ test("openvcs dist command creates bundle", () => {
 
   writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
     id: "cli-plugin",
-    module: { exec: "plugin.js" },
+    module: { exec: "openvcs-plugin.js" },
   });
-  writeText(path.join(pluginDir, "bin", "plugin.js"), "export {};\n");
+  writeText(path.join(pluginDir, "bin", "plugin.js"), "export function OnPluginStart() {}\n");
+  writeText(path.join(pluginDir, "bin", "openvcs-plugin.js"), "export {};\n");
 
   const result = runCli([
     "dist",
@@ -100,7 +101,7 @@ test("openvcs build command builds code plugin assets", () => {
 
   writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
     id: "build-plugin",
-    module: { exec: "plugin.js" },
+    module: { exec: "openvcs-plugin.js" },
   });
   writeJson(path.join(pluginDir, "package.json"), {
     name: "build-plugin",
@@ -119,6 +120,7 @@ test("openvcs build command builds code plugin assets", () => {
   assert.equal(result.status, 0);
   assert.equal(result.stdout.trim(), "build-plugin");
   assert.equal(fs.existsSync(path.join(pluginDir, "bin", "plugin.js")), true);
+  assert.equal(fs.existsSync(path.join(pluginDir, "bin", "openvcs-plugin.js")), true);
 
   cleanupTempDir(root);
 });

package/test/dist.test.js

@@ -108,7 +108,7 @@ test("readManifest rejects id with path separators", () => {
 test("validateDeclaredModuleExec accepts .js/.mjs/.cjs", () => {
   const root = makeTempDir("openvcs-sdk-test");
   const pluginDir = path.join(root, "plugin");
-  writeText(path.join(pluginDir, "bin", "plugin.js"), "export {};\n");
+  writeText(path.join(pluginDir, "bin", "plugin.js"), "export function OnPluginStart() {}\n");
   writeText(path.join(pluginDir, "bin", "plugin.mjs"), "export {};\n");
   writeText(path.join(pluginDir, "bin", "plugin.cjs"), "module.exports = {};\n");
 
@@ -133,7 +133,7 @@ test("validateDeclaredModuleExec rejects non-node extension", () => {
 test("validateDeclaredModuleExec rejects absolute path", () => {
   const root = makeTempDir("openvcs-sdk-test");
   const pluginDir = path.join(root, "plugin");
-  writeText(path.join(pluginDir, "bin", "plugin.js"), "export {};\n");
+  writeText(path.join(pluginDir, "bin", "plugin.js"), "export function OnPluginStart() {}\n");
   assert.throws(
     () => __private.validateDeclaredModuleExec(pluginDir, path.resolve(pluginDir, "bin", "plugin.js")),
     /must be a relative path under bin/
@@ -279,6 +279,7 @@ test("bundlePlugin trims module.exec and includes extra bin files", async () =>
     id: "x",
     module: { exec: "  module.mjs  " },
   });
+  writeText(path.join(pluginDir, "bin", "plugin.js"), "export function OnPluginStart() {}\n");
   writeText(path.join(pluginDir, "bin", "module.mjs"), "export {};\n");
   writeText(path.join(pluginDir, "bin", "helpers", "util.mjs"), "export const x = 1;\n");
 
@@ -291,6 +292,7 @@ test("bundlePlugin trims module.exec and includes extra bin files", async () =>
   });
   const entries = await readBundleEntries(outPath);
 
+  assert.equal(entries.has("x/bin/plugin.js"), true);
   assert.equal(entries.has("x/bin/module.mjs"), true);
   assert.equal(entries.has("x/bin/helpers/util.mjs"), true);
   cleanupTempDir(root);
@@ -303,7 +305,7 @@ test("bundlePlugin builds code plugins before packaging", async () => {
 
   writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
     id: "builder",
-    module: { exec: "plugin.js" },
+    module: { exec: "openvcs-plugin.js" },
   });
   writeJson(path.join(pluginDir, "package.json"), {
     name: "builder",
@@ -327,6 +329,7 @@ test("bundlePlugin builds code plugins before packaging", async () => {
   const entries = await readBundleEntries(outPath);
 
   assert.equal(entries.has("builder/bin/plugin.js"), true);
+  assert.equal(entries.has("builder/bin/openvcs-plugin.js"), true);
   cleanupTempDir(root);
 });
 
@@ -337,12 +340,12 @@ test("bundlePlugin with no-build requires prebuilt module entrypoint", async ()
 
   writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
     id: "prebuilt",
-    module: { exec: "plugin.js" },
+    module: { exec: "openvcs-plugin.js" },
   });
 
   await assert.rejects(
     () => bundlePlugin({ pluginDir, outDir, verbose: false, noBuild: true, noNpmDeps: true }),
-    /module entrypoint not found/
+    /compiled plugin module not found/
   );
 
   cleanupTempDir(root);
@@ -355,7 +358,7 @@ test("bundlePlugin errors when code plugin lacks build:plugin", async () => {
 
   writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
     id: "missing-script",
-    module: { exec: "plugin.js" },
+    module: { exec: "openvcs-plugin.js" },
   });
   writeJson(path.join(pluginDir, "package.json"), {
     name: "missing-script",
@@ -416,9 +419,10 @@ test("bundlePlugin rejects plugin id with path separators", async () => {
 
   writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
     id: "bad/id",
-    module: { exec: "plugin.js" },
+    module: { exec: "openvcs-plugin.js" },
   });
-  writeText(path.join(pluginDir, "bin", "plugin.js"), "export {};\n");
+  writeText(path.join(pluginDir, "bin", "plugin.js"), "export function OnPluginStart() {}\n");
+  writeText(path.join(pluginDir, "bin", "openvcs-plugin.js"), "export {};\n");
 
   await assert.rejects(
     () => bundlePlugin({ pluginDir, outDir, verbose: false, noBuild: true, noNpmDeps: true }),
@@ -439,9 +443,10 @@ test("bundlePlugin rejects symlink in bin", async () => {
 
   writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
     id: "x",
-    module: { exec: "plugin.js" },
+    module: { exec: "openvcs-plugin.js" },
   });
-  writeText(path.join(pluginDir, "bin", "plugin.js"), "export {};\n");
+  writeText(path.join(pluginDir, "bin", "plugin.js"), "export function OnPluginStart() {}\n");
+  writeText(path.join(pluginDir, "bin", "openvcs-plugin.js"), "export {};\n");
   writeText(path.join(pluginDir, "bin", "target.js"), "export {};\n");
   fs.symlinkSync(path.join(pluginDir, "bin", "target.js"), path.join(pluginDir, "bin", "link.js"));
 
@@ -460,9 +465,10 @@ test("bundlePlugin output archive keeps plugin-id root directory", async () => {
 
   writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
     id: "root-check",
-    module: { exec: "plugin.js" },
+    module: { exec: "openvcs-plugin.js" },
   });
-  writeText(path.join(pluginDir, "bin", "plugin.js"), "export {};\n");
+  writeText(path.join(pluginDir, "bin", "plugin.js"), "export function OnPluginStart() {}\n");
+  writeText(path.join(pluginDir, "bin", "openvcs-plugin.js"), "export {};\n");
 
   const outPath = await bundlePlugin({
     pluginDir,
@@ -487,9 +493,10 @@ test("bundlePlugin overwrites existing bundle file", async () => {
 
   writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
     id: "replace",
-    module: { exec: "plugin.js" },
+    module: { exec: "openvcs-plugin.js" },
   });
-  writeText(path.join(pluginDir, "bin", "plugin.js"), "export {};\n");
+  writeText(path.join(pluginDir, "bin", "plugin.js"), "export function OnPluginStart() {}\n");
+  writeText(path.join(pluginDir, "bin", "openvcs-plugin.js"), "export {};\n");
 
   const existingPath = path.join(outDir, "replace.ovcsp");
   writeText(existingPath, "not-a-tar");
@@ -514,9 +521,10 @@ test("bundlePlugin generates package-lock in staging, not pluginDir", async () =
 
   writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
     id: "npm-plugin",
-    module: { exec: "plugin.js" },
+    module: { exec: "openvcs-plugin.js" },
   });
-  writeText(path.join(pluginDir, "bin", "plugin.js"), "export {};\n");
+  writeText(path.join(pluginDir, "bin", "plugin.js"), "export function OnPluginStart() {}\n");
+  writeText(path.join(pluginDir, "bin", "openvcs-plugin.js"), "export {};\n");
   writeJson(path.join(pluginDir, "package.json"), {
     name: "npm-plugin",
     version: "0.1.0",
@@ -546,9 +554,10 @@ test("bundlePlugin with --no-npm-deps does not generate lockfile", async () => {
 
   writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
     id: "no-npm",
-    module: { exec: "plugin.js" },
+    module: { exec: "openvcs-plugin.js" },
   });
-  writeText(path.join(pluginDir, "bin", "plugin.js"), "export {};\n");
+  writeText(path.join(pluginDir, "bin", "plugin.js"), "export function OnPluginStart() {}\n");
+  writeText(path.join(pluginDir, "bin", "openvcs-plugin.js"), "export {};\n");
   writeJson(path.join(pluginDir, "package.json"), {
     name: "no-npm",
     version: "0.1.0",

package/test/init.test.js

@@ -81,9 +81,13 @@ test("writeModuleTemplate scaffolds SDK runtime entrypoint", () => {
   });
 
   const pluginSource = fs.readFileSync(path.join(targetDir, "src", "plugin.ts"), "utf8");
+  const manifest = JSON.parse(
+    fs.readFileSync(path.join(targetDir, "openvcs.plugin.json"), "utf8")
+  );
 
-  assert.match(pluginSource, /createPluginRuntime/);
-  assert.match(pluginSource, /startPluginRuntime/);
+  assert.equal(manifest.module.exec, "openvcs-plugin.js");
+  assert.match(pluginSource, /OnPluginStart/);
+  assert.match(pluginSource, /PluginDefinition/);
   assert.match(pluginSource, /context\.host\.info\('OpenVCS plugin started'\)/);
 
   cleanupTempDir(root);

package/test/runtime.test.js

@@ -2,7 +2,10 @@ const assert = require("node:assert/strict");
 const { EventEmitter } = require("node:events");
 const test = require("node:test");
 
-const { createPluginRuntime } = require("../lib/runtime");
+const {
+  bootstrapPluginModule,
+  createPluginRuntime,
+} = require("../lib/runtime");
 const {
   parseFramedMessages,
   serializeFramedMessage,
@@ -116,3 +119,117 @@ test("createPluginRuntime reports missing methods as plugin failures", async ()
     },
   ]);
 });
+
+test("bootstrapPluginModule runs OnPluginStart before starting runtime", async () => {
+  const stdin = new EventEmitter();
+  const chunks = [];
+  const stdout = {
+    write(chunk) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      return true;
+    },
+  };
+
+  await bootstrapPluginModule({
+    modulePath: "./plugin.js",
+    transport: { stdin, stdout },
+    async importPluginModule() {
+      return {
+        PluginDefinition: {
+          plugin: {
+            async "plugin.init"(_params, context) {
+              context.host.info("booted");
+              return null;
+            },
+          },
+          vcs: {
+            async "vcs.get_caps"() {
+              return { commits: true };
+            },
+          },
+        },
+        OnPluginStart() {
+        },
+      };
+    },
+  });
+
+  stdin.emit(
+    "data",
+    serializeFramedMessage({
+      jsonrpc: "2.0",
+      id: 4,
+      method: "plugin.initialize",
+      params: {},
+    })
+  );
+  stdin.emit(
+    "data",
+    serializeFramedMessage({
+      jsonrpc: "2.0",
+      id: 5,
+      method: "plugin.init",
+      params: {},
+    })
+  );
+  await new Promise((resolve) => setImmediate(resolve));
+
+  const parsed = parseFramedMessages(Buffer.concat(chunks));
+  assert.deepEqual(parsed.messages, [
+    {
+      jsonrpc: "2.0",
+      id: 4,
+      result: {
+        protocol_version: 1,
+        implements: {
+          plugin: true,
+          vcs: true,
+        },
+      },
+    },
+    {
+      jsonrpc: "2.0",
+      method: "host.log",
+      params: {
+        level: "info",
+        target: "openvcs.plugin",
+        message: "booted",
+      },
+    },
+    {
+      jsonrpc: "2.0",
+      id: 5,
+      result: null,
+    },
+  ]);
+});
+
+test("bootstrapPluginModule rejects modules without OnPluginStart", async () => {
+  await assert.rejects(
+    () =>
+      bootstrapPluginModule({
+        modulePath: "./plugin.js",
+        async importPluginModule() {
+          return {};
+        },
+      }),
+    /must export OnPluginStart/
+  );
+});
+
+test("bootstrapPluginModule rejects when OnPluginStart throws", async () => {
+  await assert.rejects(
+    () =>
+      bootstrapPluginModule({
+        modulePath: "./plugin.js",
+        async importPluginModule() {
+          return {
+            OnPluginStart() {
+              throw new Error("startup failure");
+            },
+          };
+        },
+      }),
+    /plugin startup failed/
+  );
+});

package/test/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": ".."
+  },
+  "include": ["../src/**/*.ts", "./vcs-delegate-base.types.ts", "./vcs-delegate-base.test.ts"]
+}