@openvcs/sdk 0.2.0 → 0.2.2

package/src/lib/init.ts

@@ -0,0 +1,364 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as readline from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { spawnSync } from "node:child_process";
+
+const packageJson: { version: string } = require("../package.json");
+
+type UsageError = Error & { code?: string };
+
+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;
+}
+
+function npmExecutable(): string {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
+export function initUsage(commandName = "openvcs"): string {
+  return `Usage: ${commandName} init [--theme] [target-dir]\n\nOptions:\n  --theme                Start with a theme-only plugin template\n`;
+}
+
+function sanitizeIdToken(raw: string): string {
+  let output = "";
+  let lastWasSeparator = false;
+  for (const char of raw) {
+    const isValid = /[a-zA-Z0-9._-]/.test(char);
+    if (isValid) {
+      output += char.toLowerCase();
+      lastWasSeparator = false;
+      continue;
+    }
+    if (!lastWasSeparator) {
+      output += "-";
+      lastWasSeparator = true;
+    }
+  }
+  return output.replace(/^-+|-+$/g, "");
+}
+
+function defaultPluginIdFromDir(targetDir: string): string {
+  const name = path.basename(targetDir) || "openvcs-plugin";
+  const token = sanitizeIdToken(name);
+  return token || "openvcs.plugin";
+}
+
+function defaultPluginNameFromId(pluginId: string): string {
+  const words = pluginId
+    .split(/[._-]+/)
+    .map((word) => word.trim())
+    .filter(Boolean)
+    .map((word) => word[0].toUpperCase() + word.slice(1));
+  return words.length > 0 ? words.join(" ") : "OpenVCS Plugin";
+}
+
+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;
+}
+
+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 {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function writeText(filePath: string, content: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, "utf8");
+}
+
+function directoryHasEntries(targetDir: string): boolean {
+  const entries = fs.readdirSync(targetDir);
+  return entries.length > 0;
+}
+
+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");
+  try {
+    const targetText = await promptDriver.promptText("Target directory", defaultTarget);
+    const targetDir = path.resolve(targetText);
+
+    let kind: "module" | "theme" = "module";
+    if (forceTheme) {
+      kind = "theme";
+    } else {
+      while (true) {
+        const value = (await promptDriver.promptText("Template type (module/theme)", "module"))
+          .trim()
+          .toLowerCase();
+        if (value === "module" || value === "m") {
+          kind = "module";
+          break;
+        }
+        if (value === "theme" || value === "t") {
+          kind = "theme";
+          break;
+        }
+        output.write("Please choose 'module' or 'theme'.\n");
+      }
+    }
+
+    const defaultId = defaultPluginIdFromDir(targetDir);
+    let pluginId: string | undefined;
+    while (!pluginId) {
+      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 promptDriver.promptText("Plugin name", defaultName)).trim();
+    }
+
+    let pluginVersion = "";
+    while (!pluginVersion) {
+      pluginVersion = (await promptDriver.promptText("Version", "0.1.0")).trim();
+    }
+
+    const defaultEnabled = await promptDriver.promptBoolean("Default enabled", true);
+    const runNpmInstall = await promptDriver.promptBoolean("Run npm install now", true);
+
+    return {
+      targetDir,
+      kind,
+      pluginId,
+      pluginName,
+      pluginVersion,
+      defaultEnabled,
+      runNpmInstall,
+    };
+  } finally {
+    promptDriver.close();
+  }
+}
+
+function runNpmInstall(targetDir: string): void {
+  const result = spawnSync(npmExecutable(), ["install"], {
+    cwd: targetDir,
+    stdio: "inherit",
+  });
+  if (result.error) {
+    throw new Error(`failed to spawn npm install in ${targetDir}: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    throw new Error(`npm install failed in ${targetDir} (code ${result.status})`);
+  }
+}
+
+function writeCommonFiles(answers: InitAnswers): void {
+  writeJson(path.join(answers.targetDir, "openvcs.plugin.json"), {
+    id: answers.pluginId,
+    name: answers.pluginName,
+    version: answers.pluginVersion,
+    default_enabled: answers.defaultEnabled,
+    ...(answers.kind === "module" ? { module: { exec: "plugin.js" } } : {}),
+  });
+  writeText(path.join(answers.targetDir, ".gitignore"), "node_modules/\ndist/\n");
+}
+
+function writeModuleTemplate(answers: InitAnswers): void {
+  writeCommonFiles(answers);
+  writeJson(path.join(answers.targetDir, "package.json"), {
+    name: answers.pluginId,
+    version: answers.pluginVersion,
+    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",
+    },
+    devDependencies: {
+      "@openvcs/sdk": `^${packageJson.version}`,
+      "@types/node": "^22.0.0",
+      typescript: "^5.8.2",
+    },
+  });
+  writeJson(path.join(answers.targetDir, "tsconfig.json"), {
+    compilerOptions: {
+      target: "ES2022",
+      module: "NodeNext",
+      moduleResolution: "NodeNext",
+      types: ["node"],
+      strict: true,
+      skipLibCheck: true,
+      outDir: "bin",
+      rootDir: "src",
+    },
+    include: ["src/**/*.ts"],
+  });
+  writeText(
+    path.join(answers.targetDir, "src", "plugin.ts"),
+    "const message = \"OpenVCS plugin started\";\nprocess.stderr.write(`${message}\\n`);\n"
+  );
+}
+
+function writeThemeTemplate(answers: InitAnswers): void {
+  writeCommonFiles(answers);
+  writeJson(path.join(answers.targetDir, "package.json"), {
+    name: answers.pluginId,
+    version: answers.pluginVersion,
+    private: true,
+    scripts: {
+      build: "openvcs dist --plugin-dir . --out dist",
+      test: "openvcs dist --plugin-dir . --out dist --no-npm-deps",
+    },
+    devDependencies: {
+      "@openvcs/sdk": `^${packageJson.version}`,
+    },
+  });
+  writeJson(path.join(answers.targetDir, "themes", "default", "theme.json"), {
+    name: answers.pluginName || "Default Theme",
+    description: "Starter OpenVCS theme generated by @openvcs/sdk",
+    tokens: {
+      accent: "#2a7fff",
+      background: "#0f172a",
+      foreground: "#e2e8f0",
+    },
+  });
+}
+
+export async function runInitCommand(args: string[]): Promise<string> {
+  let forceTheme = false;
+  let targetHint: string | undefined;
+
+  for (const arg of args) {
+    if (arg === "--theme") {
+      forceTheme = true;
+      continue;
+    }
+    if (arg === "--help") {
+      const error = new Error(initUsage()) as UsageError;
+      error.code = "USAGE";
+      throw error;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`unknown argument for init: ${arg}`);
+    }
+    if (targetHint) {
+      throw new Error("init accepts at most one target directory");
+    }
+    targetHint = arg;
+  }
+
+  const answers = await collectAnswers({ forceTheme, targetHint });
+  if (!fs.existsSync(answers.targetDir)) {
+    fs.mkdirSync(answers.targetDir, { recursive: true });
+  } 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 promptDriver = createReadlinePromptDriver();
+    try {
+      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 {
+      promptDriver.close();
+    }
+  }
+
+  if (answers.kind === "module") {
+    writeModuleTemplate(answers);
+  } else {
+    writeThemeTemplate(answers);
+  }
+
+  if (answers.runNpmInstall) {
+    runNpmInstall(answers.targetDir);
+  }
+
+  return answers.targetDir;
+}
+
+export function isUsageError(error: unknown): error is InitCommandError {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    typeof (error as InitCommandError).code === "string"
+  );
+}
+
+export const __private = {
+  collectAnswers,
+  createReadlinePromptDriver,
+  defaultPluginIdFromDir,
+  sanitizeIdToken,
+  validatePluginId,
+};

package/test/cli.test.js

@@ -0,0 +1,87 @@
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const test = require("node:test");
+
+const packageJson = require("../package.json");
+const { cleanupTempDir, makeTempDir, writeJson, writeText } = require("./helpers");
+
+const cliPath = path.join(__dirname, "..", "bin", "openvcs.js");
+
+function runCli(args, cwd = process.cwd(), input = "") {
+  return spawnSync(process.execPath, [cliPath, ...args], {
+    cwd,
+    input,
+    encoding: "utf8",
+  });
+}
+
+test("openvcs --version prints package version", () => {
+  const result = runCli(["--version"]);
+  assert.equal(result.status, 0);
+  assert.equal(result.stdout.trim(), `openvcs ${packageJson.version}`);
+});
+
+test("openvcs --help prints usage", () => {
+  const result = runCli(["--help"]);
+  assert.equal(result.status, 0);
+  assert.match(result.stdout, /Usage: openvcs <command>/);
+});
+
+test("openvcs with no args exits non-zero", () => {
+  const result = runCli([]);
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /Usage: openvcs <command>/);
+});
+
+test("openvcs dist --help prints dist usage", () => {
+  const result = runCli(["dist", "--help"]);
+  assert.equal(result.status, 0);
+  assert.match(result.stdout, /openvcs dist \[args\]/);
+});
+
+test("openvcs init --help prints init usage", () => {
+  const result = runCli(["init", "--help"]);
+  assert.equal(result.status, 0);
+  assert.match(result.stdout, /Usage: openvcs init/);
+});
+
+test("openvcs rejects unknown command", () => {
+  const result = runCli(["unknown"]);
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /unknown command: unknown/);
+});
+
+test("openvcs dist command creates bundle", () => {
+  const root = makeTempDir("openvcs-sdk-test");
+  const pluginDir = path.join(root, "plugin");
+  const outDir = path.join(root, "out");
+
+  writeJson(path.join(pluginDir, "openvcs.plugin.json"), {
+    id: "cli-plugin",
+    module: { exec: "plugin.js" },
+  });
+  writeText(path.join(pluginDir, "bin", "plugin.js"), "export {};\n");
+
+  const result = runCli([
+    "dist",
+    "--plugin-dir",
+    pluginDir,
+    "--out",
+    outDir,
+    "--no-npm-deps",
+  ]);
+
+  assert.equal(result.status, 0);
+  assert.match(result.stdout.trim(), /cli-plugin\.ovcsp$/);
+  assert.equal(fs.existsSync(path.join(outDir, "cli-plugin.ovcsp")), true);
+
+  cleanupTempDir(root);
+});
+
+test("openvcs dist reports argument errors", () => {
+  const result = runCli(["dist", "--plugin-dir"]);
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /missing value for --plugin-dir/);
+});