@openvcs/sdk 0.2.1 → 0.2.3

package/lib/init.d.ts

@@ -1,7 +1,37 @@
+interface InitAnswers {
+    targetDir: string;
+    kind: "module" | "theme";
+    pluginId: string;
+    pluginName: string;
+    pluginVersion: string;
+    defaultEnabled: boolean;
+    runNpmInstall: boolean;
+}
+interface CollectAnswersOptions {
+    forceTheme: boolean;
+    targetHint?: string;
+}
+interface PromptDriver {
+    promptText(label: string, defaultValue?: string): Promise<string>;
+    promptBoolean(label: string, defaultValue: boolean): Promise<boolean>;
+    close(): void;
+}
 interface InitCommandError {
     code?: string;
 }
 export declare function initUsage(commandName?: string): string;
+declare function sanitizeIdToken(raw: string): string;
+declare function defaultPluginIdFromDir(targetDir: string): string;
+declare function validatePluginId(pluginId: string): string | undefined;
+declare function createReadlinePromptDriver(output?: NodeJS.WritableStream): PromptDriver;
+declare function collectAnswers({ forceTheme, targetHint }: CollectAnswersOptions, promptDriver?: PromptDriver, output?: NodeJS.WritableStream): Promise<InitAnswers>;
 export declare function runInitCommand(args: string[]): Promise<string>;
 export declare function isUsageError(error: unknown): error is InitCommandError;
+export declare const __private: {
+    collectAnswers: typeof collectAnswers;
+    createReadlinePromptDriver: typeof createReadlinePromptDriver;
+    defaultPluginIdFromDir: typeof defaultPluginIdFromDir;
+    sanitizeIdToken: typeof sanitizeIdToken;
+    validatePluginId: typeof validatePluginId;
+};
 export {};

package/lib/init.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.__private = void 0;
 exports.initUsage = initUsage;
 exports.runInitCommand = runInitCommand;
 exports.isUsageError = isUsageError;
@@ -45,28 +46,48 @@ function defaultPluginNameFromId(pluginId) {
         .map((word) => word[0].toUpperCase() + word.slice(1));
     return words.length > 0 ? words.join(" ") : "OpenVCS Plugin";
 }
-async function promptText(rl, label, defaultValue = "") {
-    const suffix = defaultValue ? ` [${defaultValue}]` : "";
-    const answer = await rl.question(`${label}${suffix}: `);
-    const trimmed = answer.trim();
-    return trimmed || defaultValue;
-}
-async function promptBoolean(rl, label, defaultValue) {
-    const suffix = defaultValue ? "Y/n" : "y/N";
-    while (true) {
-        const answer = await rl.question(`${label} (${suffix}): `);
-        const normalized = answer.trim().toLowerCase();
-        if (!normalized) {
-            return defaultValue;
-        }
-        if (normalized === "y" || normalized === "yes") {
-            return true;
-        }
-        if (normalized === "n" || normalized === "no") {
-            return false;
-        }
-        process.stderr.write("Please answer yes or no.\n");
+function validatePluginId(pluginId) {
+    if (!pluginId) {
+        return "Plugin id is required.";
+    }
+    if (pluginId === "." || pluginId === "..") {
+        return "Plugin id must not be '.' or '..'.";
     }
+    if (pluginId.includes("/") || pluginId.includes("\\")) {
+        return "Plugin id must not contain path separators (/ or \\).";
+    }
+    return undefined;
+}
+function createReadlinePromptDriver(output = process.stderr) {
+    const rl = readline.createInterface({ input: node_process_1.stdin, output: node_process_1.stdout });
+    return {
+        async promptText(label, defaultValue = "") {
+            const suffix = defaultValue ? ` [${defaultValue}]` : "";
+            const answer = await rl.question(`${label}${suffix}: `);
+            const trimmed = answer.trim();
+            return trimmed || defaultValue;
+        },
+        async promptBoolean(label, defaultValue) {
+            const suffix = defaultValue ? "Y/n" : "y/N";
+            while (true) {
+                const answer = await rl.question(`${label} (${suffix}): `);
+                const normalized = answer.trim().toLowerCase();
+                if (!normalized) {
+                    return defaultValue;
+                }
+                if (normalized === "y" || normalized === "yes") {
+                    return true;
+                }
+                if (normalized === "n" || normalized === "no") {
+                    return false;
+                }
+                output.write("Please answer yes or no.\n");
+            }
+        },
+        close() {
+            rl.close();
+        },
+    };
 }
 function writeJson(filePath, value) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -80,11 +101,10 @@ function directoryHasEntries(targetDir) {
     const entries = fs.readdirSync(targetDir);
     return entries.length > 0;
 }
-async function collectAnswers({ forceTheme, targetHint }) {
+async function collectAnswers({ forceTheme, targetHint }, promptDriver = createReadlinePromptDriver(), output = process.stderr) {
     const defaultTarget = targetHint || path.join(process.cwd(), "openvcs-plugin");
-    const rl = readline.createInterface({ input: node_process_1.stdin, output: node_process_1.stdout });
     try {
-        const targetText = await promptText(rl, "Target directory", defaultTarget);
+        const targetText = await promptDriver.promptText("Target directory", defaultTarget);
         const targetDir = path.resolve(targetText);
         let kind = "module";
         if (forceTheme) {
@@ -92,7 +112,7 @@ async function collectAnswers({ forceTheme, targetHint }) {
         }
         else {
             while (true) {
-                const value = (await promptText(rl, "Template type (module/theme)", "module"))
+                const value = (await promptDriver.promptText("Template type (module/theme)", "module"))
                     .trim()
                     .toLowerCase();
                 if (value === "module" || value === "m") {
@@ -103,25 +123,31 @@ async function collectAnswers({ forceTheme, targetHint }) {
                     kind = "theme";
                     break;
                 }
-                process.stderr.write("Please choose 'module' or 'theme'.\n");
+                output.write("Please choose 'module' or 'theme'.\n");
             }
         }
         const defaultId = defaultPluginIdFromDir(targetDir);
-        let pluginId = "";
+        let pluginId;
         while (!pluginId) {
-            pluginId = (await promptText(rl, "Plugin id", defaultId)).trim();
+            const candidateId = (await promptDriver.promptText("Plugin id", defaultId)).trim();
+            const validationError = validatePluginId(candidateId);
+            if (!validationError) {
+                pluginId = candidateId;
+                break;
+            }
+            output.write(`${validationError}\n`);
         }
         const defaultName = defaultPluginNameFromId(pluginId);
         let pluginName = "";
         while (!pluginName) {
-            pluginName = (await promptText(rl, "Plugin name", defaultName)).trim();
+            pluginName = (await promptDriver.promptText("Plugin name", defaultName)).trim();
         }
         let pluginVersion = "";
         while (!pluginVersion) {
-            pluginVersion = (await promptText(rl, "Version", "0.1.0")).trim();
+            pluginVersion = (await promptDriver.promptText("Version", "0.1.0")).trim();
         }
-        const defaultEnabled = await promptBoolean(rl, "Default enabled", true);
-        const runNpmInstall = await promptBoolean(rl, "Run npm install now", true);
+        const defaultEnabled = await promptDriver.promptBoolean("Default enabled", true);
+        const runNpmInstall = await promptDriver.promptBoolean("Run npm install now", true);
         return {
             targetDir,
             kind,
@@ -133,7 +159,7 @@ async function collectAnswers({ forceTheme, targetHint }) {
         };
     }
     finally {
-        rl.close();
+        promptDriver.close();
     }
 }
 function runNpmInstall(targetDir) {
@@ -166,9 +192,10 @@ function writeModuleTemplate(answers) {
         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: {
             "@openvcs/sdk": `^${packageJson.version}`,
@@ -198,8 +225,9 @@ function writeThemeTemplate(answers) {
         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: {
             "@openvcs/sdk": `^${packageJson.version}`,
@@ -244,15 +272,15 @@ async function runInitCommand(args) {
         throw new Error(`target path exists but is not a directory: ${answers.targetDir}`);
     }
     else if (directoryHasEntries(answers.targetDir)) {
-        const rl = readline.createInterface({ input: node_process_1.stdin, output: node_process_1.stdout });
+        const promptDriver = createReadlinePromptDriver();
         try {
-            const proceed = await promptBoolean(rl, `Directory ${answers.targetDir} is not empty. Continue and overwrite known files`, false);
+            const proceed = await promptDriver.promptBoolean(`Directory ${answers.targetDir} is not empty. Continue and overwrite known files`, false);
             if (!proceed) {
                 throw new Error("aborted by user");
             }
         }
         finally {
-            rl.close();
+            promptDriver.close();
         }
     }
     if (answers.kind === "module") {
@@ -272,3 +300,10 @@ function isUsageError(error) {
         "code" in error &&
         typeof error.code === "string");
 }
+exports.__private = {
+    collectAnswers,
+    createReadlinePromptDriver,
+    defaultPluginIdFromDir,
+    sanitizeIdToken,
+    validatePluginId,
+};

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@openvcs/sdk",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "OpenVCS SDK CLI for plugin scaffolding and .ovcsp tar.gz packaging",
   "license": "GPL-3.0-or-later",
-  "homepage": "https://bbgames.dev/",
+  "homepage": "https://openvcs.app/",
   "repository": {
     "type": "git",
     "url": "https://github.com/Open-VCS/OpenVCS-SDK"
@@ -25,7 +25,7 @@
     "openvcs": "node bin/openvcs.js"
   },
   "devDependencies": {
-    "@types/node": "^22.15.21",
+    "@types/node": "^25.3.3",
     "typescript": "^5.8.2"
   },
   "dependencies": {

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());