@openvcs/sdk 0.4.0 → 0.4.1-edge.20260530.101

package/test/modal.test.js

@@ -0,0 +1,74 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+
+const { ModalBuilder } = require("../lib/runtime");
+
+test("ModalBuilder serializes all supported content item types", async () => {
+  const modal = new ModalBuilder("  Settings  ")
+    .text("Hello", { title: "Greeting", align: "center" })
+    .separator()
+    .button(" save ", "Save", { title: "Persist", variant: "primary", align: "end", payload: { ok: true } })
+    .input(" name ", " Name ", { kind: "text", value: "OpenVCS", placeholder: "Name", required: true, align: "start" })
+    .select("theme", "Theme", { value: "dark", align: "center", options: [{ value: "dark", label: "Dark" }] })
+    .list("files", { label: "Files", emptyText: "None", align: "start", items: [{ id: "a", label: "A" }] })
+    .build();
+
+  assert.equal(modal.title, "Settings");
+  assert.deepEqual(modal.content.map((item) => item.type), [
+    "text",
+    "separator",
+    "button",
+    "input",
+    "select",
+    "list",
+  ]);
+  assert.deepEqual(modal.content[2].payload, { ok: true });
+  assert.equal(modal.content[3].required, true);
+});
+
+test("ModalBuilder omits optional fields when not provided", () => {
+  const modal = new ModalBuilder("  ")
+    .text("Plain")
+    .button(" save ", "Save")
+    .input(" name ", " Name ")
+    .select("theme", "Theme", { options: [] })
+    .list("files", { items: [] })
+    .horizontalBox([{ type: "text", content: "child" }])
+    .verticalBox([{ type: "text", content: "child" }])
+    .grid([{ type: "text", content: "child" }], { columns: " 1fr " })
+    .build();
+
+  assert.equal(modal.title, "");
+  assert.equal(modal.content[0].title, undefined);
+  assert.equal(modal.content[1].variant, undefined);
+  assert.equal(modal.content[2].kind, undefined);
+  assert.equal(modal.content[3].value, undefined);
+  assert.equal(modal.content[4].label, undefined);
+  assert.equal(modal.content[5].gap, undefined);
+  assert.equal(modal.content[6].gap, undefined);
+  assert.equal(modal.content[7].gap, undefined);
+  assert.equal(modal.content[7].columns, "1fr");
+});
+
+test("ModalBuilder clones nested container content before returning definitions", () => {
+  const nested = [{ type: "text", content: "inside" }];
+  const builder = new ModalBuilder("Nested")
+    .horizontalBox(nested, { gap: "4px", align: "center", wrap: true })
+    .verticalBox(nested, { gap: "8px" })
+    .grid(nested, { columns: "1fr 1fr", gap: "2px" });
+
+  const first = builder.build();
+  first.content[0].content[0].content = "mutated";
+  nested[0].content = "source mutated";
+  const second = builder.build();
+
+  assert.equal(second.content[0].content[0].content, "inside");
+  assert.equal(second.content[1].content[0].content, "inside");
+  assert.equal(second.content[2].columns, "1fr 1fr");
+});
+
+test("ModalBuilder.open returns the same payload shape as build", async () => {
+  const builder = new ModalBuilder("Open").text("Body");
+
+  assert.deepEqual(await builder.open(), builder.build());
+});

package/test/npm-runner.test.js

@@ -0,0 +1,89 @@
+const assert = require("node:assert/strict");
+const path = require("node:path");
+const test = require("node:test");
+
+const { npmArgsPrefix, npmCommand, npmExecutable, resolveNpmCli } = require("../lib/npm-runner");
+
+test("npmCommand uses npm directly on non-Windows platforms", () => {
+  const command = npmCommand("linux", "/usr/bin/node");
+
+  assert.deepEqual(command, { program: "npm", argsPrefix: [] });
+});
+
+test("npmExecutable and npmArgsPrefix expose the default npm command", () => {
+  if (process.platform === "win32") {
+    assert.equal(npmExecutable(), process.execPath);
+    assert.ok(npmArgsPrefix().length > 0);
+  } else {
+    assert.equal(npmExecutable(), "npm");
+    assert.deepEqual(npmArgsPrefix(), []);
+  }
+});
+
+test("npmCommand runs npm through node.exe on Windows without cmd.exe", () => {
+  const execPath = "C:\\Program Files\\nodejs\\node.exe";
+  const localCli = path.join(path.dirname(execPath), "node_modules", "npm", "bin", "npm-cli.js");
+
+  const command = npmCommand("win32", execPath, (candidate) => candidate === localCli);
+
+  assert.equal(command.program, execPath);
+  assert.deepEqual(command.argsPrefix, [localCli]);
+  assert.notEqual(command.program.toLowerCase(), "cmd.exe");
+  assert.notEqual(path.basename(command.argsPrefix[0]).toLowerCase(), "npm.cmd");
+});
+
+test("resolveNpmCli falls back to require.resolve when local npm cli is unavailable", () => {
+  const resolved = resolveNpmCli(
+    "C:\\Program Files\\nodejs\\node.exe",
+    () => false,
+    (specifier) => `resolved:${specifier}`,
+  );
+
+  assert.equal(resolved, "resolved:npm/bin/npm-cli.js");
+});
+
+test("resolveNpmCli prefers npm cli beside node.exe before require.resolve", () => {
+  const execPath = "C:\\Tools With Spaces\\nodejs\\node.exe";
+  const localCli = path.join(path.dirname(execPath), "node_modules", "npm", "bin", "npm-cli.js");
+  let fallbackCalled = false;
+
+  const resolved = resolveNpmCli(
+    execPath,
+    (candidate) => candidate === localCli,
+    () => {
+      fallbackCalled = true;
+      return "fallback";
+    },
+  );
+
+  assert.equal(resolved, localCli);
+  assert.equal(fallbackCalled, false);
+});
+
+test("npmCommand keeps Windows paths unquoted because spawn receives argv array", () => {
+  const execPath = "C:\\Program Files\\nodejs\\node.exe";
+  const cliPath = "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js";
+  const command = npmCommand("win32", execPath, () => false, () => cliPath);
+
+  assert.equal(command.program, execPath);
+  assert.equal(command.argsPrefix[0], cliPath);
+  assert.equal(command.program.startsWith('"'), false);
+  assert.equal(command.argsPrefix[0].startsWith('"'), false);
+});
+
+test("npmCommand returns a fresh argsPrefix array per Windows call", () => {
+  const execPath = "C:\\nodejs\\node.exe";
+  const cliPath = "C:\\nodejs\\node_modules\\npm\\bin\\npm-cli.js";
+  const first = npmCommand("win32", execPath, () => false, () => cliPath);
+  const second = npmCommand("win32", execPath, () => false, () => cliPath);
+
+  first.argsPrefix.push("mutated");
+
+  assert.deepEqual(second.argsPrefix, [cliPath]);
+});
+
+test("SDK build module no longer exposes shell-wrapper helper", () => {
+  const buildModule = require("../lib/build");
+
+  assert.equal(Object.hasOwn(buildModule, "shouldUseWindowsShell"), false);
+});

package/test/runtime.test.js

@@ -5,6 +5,8 @@ const test = require("node:test");
 const {
   bootstrapPluginModule,
   createRegisteredPluginRuntime,
+  createPluginRuntime,
+  startPluginRuntime,
   resetMenuRegistry,
 } = require("../lib/runtime");
 const {
@@ -134,6 +136,110 @@ test("createPluginRuntime reports missing methods as plugin failures", async ()
   ]);
 });
 
+test("createPluginRuntime ignores chunks before start and duplicate starts", async () => {
+  const stdin = new EventEmitter();
+  const chunks = [];
+  const stdout = {
+    write(chunk) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      return true;
+    },
+  };
+  const runtime = createRegisteredPluginRuntime({});
+
+  runtime.consumeChunk(serializeFramedMessage({ jsonrpc: "2.0", id: 40, method: "plugin.initialize", params: {} }));
+  runtime.start({ stdin, stdout });
+  runtime.start({ stdin, stdout });
+  stdin.emit("data", serializeFramedMessage({ jsonrpc: "2.0", id: 41, method: "plugin.initialize", params: {} }));
+  await new Promise((resolve) => setImmediate(resolve));
+
+  const parsed = parseFramedMessages(Buffer.concat(chunks));
+  assert.deepEqual(parsed.messages.map((message) => message.id), [41]);
+});
+
+test("createPluginRuntime logs invalid requests instead of responding", async () => {
+  const harness = createRuntimeHarness({});
+
+  const messages = await harness.request({ jsonrpc: "2.0", id: null, method: "   ", params: [] });
+
+  assert.deepEqual(messages, [{
+    jsonrpc: "2.0",
+    method: "host.log",
+    params: {
+      level: "error",
+      target: "openvcs.plugin",
+      message: "invalid request: missing method, invalid id type: object",
+    },
+  }]);
+});
+
+test("createPluginRuntime stop is idempotent and invokes shutdown callback", async () => {
+  const stdin = new EventEmitter();
+  const stdout = { write() { return true; } };
+  let shutdowns = 0;
+  const runtime = createRegisteredPluginRuntime({ onShutdown() { shutdowns += 1; } });
+
+  runtime.stop();
+  runtime.start({ stdin, stdout });
+  runtime.stop();
+  runtime.stop();
+  await new Promise((resolve) => setImmediate(resolve));
+
+  assert.equal(shutdowns, 1);
+});
+
+test("startPluginRuntime uses the runtime start method", () => {
+  const runtime = createPluginRuntime();
+  let started = 0;
+  const originalStart = runtime.start.bind(runtime);
+  runtime.start = (transport) => {
+    started += 1;
+    return originalStart(transport);
+  };
+
+  startPluginRuntime(runtime, {
+    stdin: new EventEmitter(),
+    stdout: { write() { return true; } },
+  });
+
+  assert.equal(started, 1);
+  runtime.stop();
+});
+
+test("runtime root exports and type constants are live bindings", () => {
+  const runtimeRoot = require("../lib/runtime");
+  const typesRoot = require("../lib/types");
+
+  assert.equal(runtimeRoot.createPluginRuntime, createPluginRuntime);
+  assert.equal(runtimeRoot.startPluginRuntime, startPluginRuntime);
+  assert.equal(typeof runtimeRoot.createDefaultPluginDelegates, "function");
+  assert.equal(typeof runtimeRoot.createRuntimeDispatcher, "function");
+  assert.equal(typeof runtimeRoot.isPluginFailure, "function");
+  assert.equal(typeof runtimeRoot.pluginError, "function");
+  assert.equal(typeof runtimeRoot.createHost, "function");
+  assert.equal(typeof runtimeRoot.ModalBuilder, "function");
+  assert.equal(typeof runtimeRoot.bootstrapPluginModule, "function");
+  assert.equal(typeof runtimeRoot.createRegisteredPluginRuntime, "function");
+  assert.equal(typeof runtimeRoot.VcsDelegateBase, "function");
+  assert.equal(typeof runtimeRoot.getMenu, "function");
+  assert.equal(typeof runtimeRoot.getOrCreateMenu, "function");
+  assert.equal(typeof runtimeRoot.createMenu, "function");
+  assert.equal(typeof runtimeRoot.addMenuItem, "function");
+  assert.equal(typeof runtimeRoot.addMenuSeparator, "function");
+  assert.equal(typeof runtimeRoot.removeMenu, "function");
+  assert.equal(typeof runtimeRoot.hideMenu, "function");
+  assert.equal(typeof runtimeRoot.showMenu, "function");
+  assert.equal(typeof runtimeRoot.registerAction, "function");
+  assert.equal(typeof runtimeRoot.resetMenuRegistry, "function");
+  assert.equal(typeof runtimeRoot.invoke, "function");
+  assert.equal(typeof runtimeRoot.notify, "function");
+
+  assert.equal(typesRoot.PROTOCOL_VERSION, 1);
+  assert.equal(typesRoot.PLUGIN_FAILURE_CODE, -32001);
+  assert.equal(typesRoot.PLUGIN_INTERNAL_ERROR_CODE, -32002);
+  assert.equal(typesRoot.PROTOCOL_VERSION_MISMATCH_CODE, -32003);
+});
+
 test("bootstrapPluginModule runs OnPluginStart before starting runtime", async () => {
   const stdin = new EventEmitter();
   const chunks = [];
@@ -523,6 +629,43 @@ test("plugin.handle_action logs unhandled actions without explicit handler", asy
   ]);
 });
 
+test("registered runtime merges explicit and generated menus", async () => {
+  resetMenuRegistry();
+  createMenu("generated", "Generated", { surface: "menubar" });
+  addMenuItem("generated", { label: "Generated Item", action: "generated-action" });
+  const harness = createRuntimeHarness({
+    plugin: {
+      async "plugin.get_menus"() {
+        return [{ id: "explicit", label: "Explicit", surface: "settings", order: 1, elements: [] }];
+      },
+    },
+  });
+
+  const messages = await harness.request({ jsonrpc: "2.0", id: 50, method: "plugin.get_menus", params: {} });
+
+  assert.deepEqual(messages[0].result.map((menu) => menu.id), ["explicit", "generated"]);
+});
+
+test("registered runtime falls back to explicit action handler when action is unregistered", async () => {
+  resetMenuRegistry();
+  const harness = createRuntimeHarness({
+    plugin: {
+      async "plugin.handle_action"(params) {
+        return `explicit:${params.action_id}`;
+      },
+    },
+  });
+
+  const messages = await harness.request({
+    jsonrpc: "2.0",
+    id: 51,
+    method: "plugin.handle_action",
+    params: { action_id: "not-registered" },
+  });
+
+  assert.deepEqual(messages, [{ jsonrpc: "2.0", id: 51, result: "explicit:not-registered" }]);
+});
+
 test("bootstrapPluginModule resets menu registry before OnPluginStart", async () => {
   resetMenuRegistry();
   // Pre-populate state that should be cleared.

package/test/transport.test.js

@@ -0,0 +1,71 @@
+const assert = require("node:assert/strict");
+const { EventEmitter } = require("node:events");
+const test = require("node:test");
+
+const { parseFramedMessages, serializeFramedMessage, writeFramedMessage } = require("../lib/runtime/transport");
+
+test("parseFramedMessages keeps incomplete frames as remainder", () => {
+  const frame = serializeFramedMessage({ jsonrpc: "2.0", id: 1, method: "plugin.init", params: {} });
+  const partial = frame.subarray(0, frame.length - 3);
+
+  const parsed = parseFramedMessages(partial);
+
+  assert.deepEqual(parsed.messages, []);
+  assert.deepEqual(parsed.remainder, partial);
+});
+
+test("parseFramedMessages skips invalid JSON payloads and continues at next frame", () => {
+  const invalidPayload = Buffer.from("Content-Length: 4\r\n\r\noops", "utf8");
+  const valid = serializeFramedMessage({ jsonrpc: "2.0", id: 2, method: "plugin.deinit", params: {} });
+
+  const parsed = parseFramedMessages(Buffer.concat([invalidPayload, valid]));
+
+  assert.equal(parsed.messages.length, 1);
+  assert.equal(parsed.messages[0].id, 2);
+  assert.equal(parsed.remainder.length, 0);
+});
+
+test("parseFramedMessages drops malformed header blocks", () => {
+  const malformed = Buffer.from("Bogus: 1\r\n\r\n", "utf8");
+  const valid = serializeFramedMessage({ jsonrpc: "2.0", id: 3, method: "plugin.deinit", params: {} });
+  const parsed = parseFramedMessages(Buffer.concat([malformed, valid]));
+
+  assert.equal(parsed.messages.length, 1);
+  assert.equal(parsed.messages[0].id, 3);
+  assert.equal(parsed.remainder.length, 0);
+});
+
+test("parseFramedMessages leaves garbage payload bytes after invalid content lengths", () => {
+  const badNegative = Buffer.from("Content-Length: -1\r\n\r\n{}", "utf8");
+  const parsed = parseFramedMessages(badNegative);
+
+  assert.deepEqual(parsed.messages, []);
+  assert.deepEqual(parsed.remainder, Buffer.from("{}", "utf8"));
+});
+
+test("writeFramedMessage waits for drain when stream backpressures", async () => {
+  const writer = new EventEmitter();
+  let wrote = false;
+  writer.write = (chunk) => {
+    wrote = Buffer.isBuffer(chunk);
+    setImmediate(() => writer.emit("drain"));
+    return false;
+  };
+
+  await writeFramedMessage(writer, { ok: true });
+
+  assert.equal(wrote, true);
+});
+
+test("writeFramedMessage reports writer failures without throwing", async () => {
+  const originalError = console.error;
+  const messages = [];
+  console.error = (message) => messages.push(String(message));
+  try {
+    await writeFramedMessage({ write() { throw new Error("closed"); } }, { ok: true });
+  } finally {
+    console.error = originalError;
+  }
+
+  assert.match(messages[0], /failed to write framed message: closed/);
+});

package/test/vcs-delegate-base.test.js

@@ -167,3 +167,24 @@ test('VcsDelegateBase accepts an empty deps object without errors', () => {
   const delegates = new SharedBranchDelegates({}).toDelegates();
   assert.deepEqual(Object.keys(delegates), ['vcs.get_current_branch']);
 });
+
+test('VcsDelegateBase base implementation excludes all stubs from delegate map', () => {
+  class EmptyDelegates extends VcsDelegateBase {}
+
+  assert.deepEqual(new EmptyDelegates({}).toDelegates(), {});
+});
+
+test('all VcsDelegateBase stubs throw method-specific errors', () => {
+  class EmptyDelegates extends VcsDelegateBase {}
+  const delegate = new EmptyDelegates({});
+  const stubNames = Object.getOwnPropertyNames(VcsDelegateBase.prototype)
+    .filter((name) => !['constructor', 'toDelegates', 'assignDelegate', 'unimplemented'].includes(name));
+
+  assert.ok(stubNames.length > 30);
+  for (const name of stubNames) {
+    assert.throws(
+      () => delegate[name]({}, {}),
+      new RegExp(`VCS delegate method '${name}' must be overridden before registration`),
+    );
+  }
+});