@openvcs/sdk 0.2.1 → 0.2.2

package/README.md

@@ -57,6 +57,8 @@ openvcs init my-plugin
 ```
 
 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 `\\`).
 
 Interactive theme plugin scaffold:
 

package/lib/dist.js

@@ -63,12 +63,30 @@ function parseDistArgs(args) {
 }
 function readManifest(pluginDir) {
     const manifestPath = path.join(pluginDir, "openvcs.plugin.json");
-    if (!fs.existsSync(manifestPath) || !fs.statSync(manifestPath).isFile()) {
-        throw new Error(`missing openvcs.plugin.json at ${manifestPath}`);
-    }
+    let manifestRaw;
+    let manifestFd;
     let manifest;
     try {
-        manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+        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);
@@ -122,24 +140,15 @@ function runCommand(program, args, cwd, verbose) {
     }
     const result = (0, node_child_process_1.spawnSync)(program, args, {
         cwd,
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "pipe"],
+        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) {
-        if (verbose) {
-            if (result.stdout?.trim()) {
-                process.stderr.write(`${result.stdout.trim()}\n`);
-            }
-            if (result.stderr?.trim()) {
-                process.stderr.write(`${result.stderr.trim()}\n`);
-            }
-        }
         return;
     }
-    throw new Error(`command failed (${program} ${args.join(" ")}), exit code ${result.status}, stdout='${(result.stdout || "").trim()}', stderr='${(result.stderr || "").trim()}'`);
+    throw new Error(`command failed (${program} ${args.join(" ")}), exit code ${result.status}`);
 }
 function ensurePackageLock(pluginDir, verbose) {
     if (!hasPackageJson(pluginDir)) {

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) {
@@ -244,15 +270,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 +298,10 @@ function isUsageError(error) {
         "code" in error &&
         typeof error.code === "string");
 }
+exports.__private = {
+    collectAnswers,
+    createReadlinePromptDriver,
+    defaultPluginIdFromDir,
+    sanitizeIdToken,
+    validatePluginId,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openvcs/sdk",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "OpenVCS SDK CLI for plugin scaffolding and .ovcsp tar.gz packaging",
   "license": "GPL-3.0-or-later",
   "homepage": "https://bbgames.dev/",

package/src/lib/dist.ts

@@ -30,8 +30,6 @@ interface ManifestInfo {
 interface CommandResult {
   status: number | null;
   error?: Error;
-  stdout?: string | null;
-  stderr?: string | null;
 }
 
 function npmExecutable(): string {
@@ -92,13 +90,29 @@ export function parseDistArgs(args: string[]): DistArgs {
 
 function readManifest(pluginDir: string): ManifestInfo {
   const manifestPath = path.join(pluginDir, "openvcs.plugin.json");
-  if (!fs.existsSync(manifestPath) || !fs.statSync(manifestPath).isFile()) {
-    throw new Error(`missing openvcs.plugin.json at ${manifestPath}`);
+  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);
+    }
   }
 
-  let manifest: unknown;
   try {
-    manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    manifest = JSON.parse(manifestRaw);
   } catch (error: unknown) {
     const detail = error instanceof Error ? error.message : String(error);
     throw new Error(`parse ${manifestPath}: ${detail}`);
@@ -161,28 +175,17 @@ function runCommand(program: string, args: string[], cwd: string, verbose: boole
 
   const result = spawnSync(program, args, {
     cwd,
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"],
+    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) {
-    if (verbose) {
-      if (result.stdout?.trim()) {
-        process.stderr.write(`${result.stdout.trim()}\n`);
-      }
-      if (result.stderr?.trim()) {
-        process.stderr.write(`${result.stderr.trim()}\n`);
-      }
-    }
     return;
   }
 
-  throw new Error(
-    `command failed (${program} ${args.join(" ")}), exit code ${result.status}, stdout='${(result.stdout || "").trim()}', stderr='${(result.stderr || "").trim()}'`
-  );
+  throw new Error(`command failed (${program} ${args.join(" ")}), exit code ${result.status}`);
 }
 
 function ensurePackageLock(pluginDir: string, verbose: boolean): void {

package/src/lib/init.ts

@@ -23,6 +23,12 @@ interface CollectAnswersOptions {
   targetHint?: string;
 }
 
+interface PromptDriver {
+  promptText(label: string, defaultValue?: string): Promise<string>;
+  promptBoolean(label: string, defaultValue: boolean): Promise<boolean>;
+  close(): void;
+}
+
 interface InitCommandError {
   code?: string;
 }
@@ -68,37 +74,49 @@ function defaultPluginNameFromId(pluginId: string): string {
   return words.length > 0 ? words.join(" ") : "OpenVCS Plugin";
 }
 
-async function promptText(
-  rl: readline.Interface,
-  label: string,
-  defaultValue = ""
-): Promise<string> {
-  const suffix = defaultValue ? ` [${defaultValue}]` : "";
-  const answer = await rl.question(`${label}${suffix}: `);
-  const trimmed = answer.trim();
-  return trimmed || defaultValue;
+function validatePluginId(pluginId: string): string | undefined {
+  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;
 }
 
-async function promptBoolean(
-  rl: readline.Interface,
-  label: string,
-  defaultValue: boolean
-): Promise<boolean> {
-  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 createReadlinePromptDriver(output: NodeJS.WritableStream = process.stderr): PromptDriver {
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  return {
+    async promptText(label: string, defaultValue = ""): Promise<string> {
+      const suffix = defaultValue ? ` [${defaultValue}]` : "";
+      const answer = await rl.question(`${label}${suffix}: `);
+      const trimmed = answer.trim();
+      return trimmed || defaultValue;
+    },
+    async promptBoolean(label: string, defaultValue: boolean): Promise<boolean> {
+      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(): void {
+      rl.close();
+    },
+  };
 }
 
 function writeJson(filePath: string, value: unknown): void {
@@ -116,11 +134,14 @@ function directoryHasEntries(targetDir: string): boolean {
   return entries.length > 0;
 }
 
-async function collectAnswers({ forceTheme, targetHint }: CollectAnswersOptions): Promise<InitAnswers> {
+async function collectAnswers(
+  { forceTheme, targetHint }: CollectAnswersOptions,
+  promptDriver: PromptDriver = createReadlinePromptDriver(),
+  output: NodeJS.WritableStream = process.stderr
+): Promise<InitAnswers> {
   const defaultTarget = targetHint || path.join(process.cwd(), "openvcs-plugin");
-  const rl = readline.createInterface({ input: stdin, output: 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" | "theme" = "module";
@@ -128,7 +149,7 @@ async function collectAnswers({ forceTheme, targetHint }: CollectAnswersOptions)
       kind = "theme";
     } 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") {
@@ -139,29 +160,35 @@ async function collectAnswers({ forceTheme, targetHint }: CollectAnswersOptions)
           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: string | undefined;
     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,
@@ -173,7 +200,7 @@ async function collectAnswers({ forceTheme, targetHint }: CollectAnswersOptions)
       runNpmInstall,
     };
   } finally {
-    rl.close();
+    promptDriver.close();
   }
 }
 
@@ -292,10 +319,9 @@ export async function runInitCommand(args: string[]): Promise<string> {
   } else if (!fs.lstatSync(answers.targetDir).isDirectory()) {
     throw new Error(`target path exists but is not a directory: ${answers.targetDir}`);
   } else if (directoryHasEntries(answers.targetDir)) {
-    const rl = readline.createInterface({ input: stdin, output: stdout });
+    const promptDriver = createReadlinePromptDriver();
     try {
-      const proceed = await promptBoolean(
-        rl,
+      const proceed = await promptDriver.promptBoolean(
         `Directory ${answers.targetDir} is not empty. Continue and overwrite known files`,
         false
       );
@@ -303,7 +329,7 @@ export async function runInitCommand(args: string[]): Promise<string> {
         throw new Error("aborted by user");
       }
     } finally {
-      rl.close();
+      promptDriver.close();
     }
   }
 
@@ -328,3 +354,11 @@ export function isUsageError(error: unknown): error is InitCommandError {
     typeof (error as InitCommandError).code === "string"
   );
 }
+
+export const __private = {
+  collectAnswers,
+  createReadlinePromptDriver,
+  defaultPluginIdFromDir,
+  sanitizeIdToken,
+  validatePluginId,
+};

package/test/init.test.js

@@ -0,0 +1,65 @@
+const assert = require("node:assert/strict");
+const test = require("node:test");
+const path = require("node:path");
+
+const { __private } = require("../lib/init");
+
+test("validatePluginId accepts regular ids", () => {
+  assert.equal(__private.validatePluginId("my.plugin"), undefined);
+  assert.equal(__private.validatePluginId("my-plugin_1"), undefined);
+});
+
+test("validatePluginId rejects empty id", () => {
+  assert.match(__private.validatePluginId(""), /required/);
+});
+
+test("validatePluginId rejects dot segments", () => {
+  assert.match(__private.validatePluginId("."), /must not be/);
+  assert.match(__private.validatePluginId(".."), /must not be/);
+});
+
+test("validatePluginId rejects path separators", () => {
+  assert.match(__private.validatePluginId("bad/id"), /path separators/);
+  assert.match(__private.validatePluginId("bad\\id"), /path separators/);
+});
+
+test("collectAnswers re-prompts invalid plugin id", async () => {
+  const prompts = [
+    "plugin-dir",
+    "module",
+    "bad/id",
+    "good-id",
+    "Good Plugin",
+    "0.2.0",
+  ];
+  const booleans = [true, false];
+  const messages = [];
+
+  const promptDriver = {
+    async promptText() {
+      return prompts.shift() || "";
+    },
+    async promptBoolean() {
+      return booleans.shift() || false;
+    },
+    close() {},
+  };
+
+  const output = {
+    write(message) {
+      messages.push(message);
+    },
+  };
+
+  const answers = await __private.collectAnswers(
+    { forceTheme: false, targetHint: "plugin-dir" },
+    promptDriver,
+    output
+  );
+
+  assert.equal(answers.pluginId, "good-id");
+  assert.equal(answers.targetDir, path.resolve("plugin-dir"));
+  assert.equal(answers.defaultEnabled, true);
+  assert.equal(answers.runNpmInstall, false);
+  assert.equal(messages.some((message) => message.includes("must not contain path separators")), true);
+});