@openvcs/sdk 0.2.0 → 0.2.1

package/README.md

@@ -7,7 +7,7 @@
 OpenVCS SDK for npm-based plugin development.
 
 Install this package in plugin projects, scaffold a starter plugin, and package
-plugins into `.ovcsp` bundles with `npm run build`.
+plugins into `.ovcsp` bundles.
 
 ## Install
 
@@ -15,18 +15,53 @@ plugins into `.ovcsp` bundles with `npm run build`.
 npm install --save-dev @openvcs/sdk
 ```
 
+This package installs a local CLI command named `openvcs`.
+
+One-off usage without adding to a project:
+
+```bash
+npx --package @openvcs/sdk openvcs --help
+```
+
+## SDK development
+
+This repository is authored in TypeScript under `src/` and compiles runtime files
+to `bin/` and `lib/`.
+
+Build the SDK:
+
+```bash
+npm run build
+```
+
+Run tests (builds first):
+
+```bash
+npm test
+```
+
+Run the local CLI through npm scripts:
+
+```bash
+npm run openvcs -- --help
+npm run openvcs -- init --help
+npm run openvcs -- dist --help
+```
+
 ## Scaffold a plugin
 
 Interactive module plugin scaffold:
 
 ```bash
-npx @openvcs/sdk init my-plugin
+openvcs init my-plugin
 ```
 
+The generated module template includes TypeScript and Node typings (`@types/node`).
+
 Interactive theme plugin scaffold:
 
 ```bash
-npx @openvcs/sdk init --theme my-theme
+openvcs init --theme my-theme
 ```
 
 ## Build a `.ovcsp` bundle
@@ -39,6 +74,9 @@ npm run build
 
 This produces `dist/<plugin-id>.ovcsp`.
 
+`.ovcsp` is a gzip-compressed tar archive (`tar.gz`) that contains a top-level
+`<plugin-id>/` directory with `openvcs.plugin.json` and plugin runtime assets.
+
 Dependency behavior while packaging:
 
 - npm dependency bundling is enabled by default when `package.json` exists.
@@ -48,11 +86,28 @@ Dependency behavior while packaging:
 - Disable npm dependency processing with `--no-npm-deps`.
 - Native Node addons (`*.node`) are rejected for portable bundles.
 
-## Native implementation
+## CLI usage
+
+Package a plugin manually:
+
+```bash
+openvcs dist --plugin-dir /path/to/plugin --out /path/to/dist
+```
+
+Show command help:
+
+```bash
+openvcs --help
+openvcs dist --help
+openvcs init --help
+```
+
+## Releases
 
-The native implementation (Rust crate and binaries) lives in `native/`.
+Stable releases are published from `.github/workflows/release.yml`.
 
-See `native/README.md` for Rust-focused development and crates.io publishing.
+- npm publishes use npm Trusted Publishing (OIDC), so no `NPM_TOKEN` is required.
+- `npm prepack` compiles TypeScript so published packages include `bin/` and `lib/` JS outputs.
 
 ## License
 

package/bin/openvcs.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/bin/openvcs.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cli_1 = require("../lib/cli");
+(0, cli_1.runCli)(process.argv.slice(2)).catch((error) => {
+    const detail = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${detail}\n`);
+    process.exit(1);
+});

package/lib/cli.d.ts

@@ -0,0 +1 @@
+export declare function runCli(args: string[]): Promise<void>;

package/lib/cli.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCli = runCli;
+const dist_1 = require("./dist");
+const init_1 = require("./init");
+const packageJson = require("../package.json");
+function hasCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}
+function usage() {
+    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";
+}
+async function runCli(args) {
+    if (args.length === 0) {
+        process.stderr.write(usage());
+        process.exitCode = 1;
+        return;
+    }
+    if (args.includes("-v") || args.includes("--version")) {
+        process.stdout.write(`openvcs ${packageJson.version}\n`);
+        return;
+    }
+    const [command, ...rest] = args;
+    if (command === "help" || command === "--help" || command === "-h") {
+        process.stdout.write(usage());
+        return;
+    }
+    if (command === "dist") {
+        if (rest.includes("--help")) {
+            process.stdout.write((0, dist_1.distUsage)());
+            return;
+        }
+        try {
+            const parsed = (0, dist_1.parseDistArgs)(rest);
+            const outPath = await (0, dist_1.bundlePlugin)(parsed);
+            process.stdout.write(`${outPath}\n`);
+            return;
+        }
+        catch (error) {
+            if (hasCode(error, "USAGE")) {
+                throw new Error((0, dist_1.distUsage)());
+            }
+            throw error;
+        }
+    }
+    if (command === "init") {
+        if (rest.includes("--help")) {
+            process.stdout.write((0, init_1.initUsage)());
+            return;
+        }
+        try {
+            const targetDir = await (0, init_1.runInitCommand)(rest);
+            process.stdout.write(`Initialized plugin at ${targetDir}\n`);
+            return;
+        }
+        catch (error) {
+            if (hasCode(error, "USAGE")) {
+                throw new Error((0, init_1.initUsage)());
+            }
+            throw error;
+        }
+    }
+    throw new Error(`unknown command: ${command}`);
+}

package/lib/dist.d.ts

@@ -0,0 +1,30 @@
+interface DistArgs {
+    pluginDir: string;
+    outDir: string;
+    verbose: boolean;
+    noNpmDeps: boolean;
+}
+interface ManifestInfo {
+    pluginId: string;
+    moduleExec: string | undefined;
+    manifestPath: string;
+}
+export declare function distUsage(commandName?: string): string;
+export declare function parseDistArgs(args: string[]): DistArgs;
+declare function readManifest(pluginDir: string): ManifestInfo;
+declare function validateDeclaredModuleExec(pluginDir: string, moduleExec: string | undefined): void;
+declare function rejectNativeAddonsRecursive(dirPath: string): void;
+declare function copyIcon(pluginDir: string, bundleDir: string): void;
+declare function uniqueStagingDir(outDir: string): string;
+declare function writeTarGz(outPath: string, baseDir: string, folderName: string): Promise<void>;
+export declare function bundlePlugin(parsedArgs: DistArgs): Promise<string>;
+export declare const __private: {
+    ICON_EXTENSIONS: string[];
+    copyIcon: typeof copyIcon;
+    readManifest: typeof readManifest;
+    rejectNativeAddonsRecursive: typeof rejectNativeAddonsRecursive;
+    uniqueStagingDir: typeof uniqueStagingDir;
+    validateDeclaredModuleExec: typeof validateDeclaredModuleExec;
+    writeTarGz: typeof writeTarGz;
+};
+export {};

package/lib/dist.js

@@ -0,0 +1,277 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__private = void 0;
+exports.distUsage = distUsage;
+exports.parseDistArgs = parseDistArgs;
+exports.bundlePlugin = bundlePlugin;
+const fs = require("node:fs");
+const path = require("node:path");
+const node_child_process_1 = require("node:child_process");
+const tar = require("tar");
+const fs_utils_1 = require("./fs-utils");
+const ICON_EXTENSIONS = ["png", "jpg", "jpeg", "webp", "avif", "svg"];
+function npmExecutable() {
+    return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+function distUsage(commandName = "openvcs") {
+    return `${commandName} dist [args]\n\n  --plugin-dir <path>   Plugin repository root (contains openvcs.plugin.json)\n  --out <path>          Output directory (default: ./dist)\n  --no-npm-deps         Disable npm dependency bundling (enabled by default)\n  -V, --verbose         Enable verbose output\n`;
+}
+function parseDistArgs(args) {
+    let pluginDir = process.cwd();
+    let outDir = "dist";
+    let verbose = false;
+    let noNpmDeps = 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];
+            continue;
+        }
+        if (arg === "--out") {
+            index += 1;
+            if (index >= args.length) {
+                throw new Error("missing value for --out");
+            }
+            outDir = args[index];
+            continue;
+        }
+        if (arg === "--no-npm-deps") {
+            noNpmDeps = true;
+            continue;
+        }
+        if (arg === "-V" || arg === "--verbose") {
+            verbose = true;
+            continue;
+        }
+        if (arg === "--help") {
+            const error = new Error(distUsage());
+            error.code = "USAGE";
+            throw error;
+        }
+        throw new Error(`unknown flag: ${arg}`);
+    }
+    return {
+        pluginDir: path.resolve(pluginDir),
+        outDir: path.resolve(outDir),
+        verbose,
+        noNpmDeps,
+    };
+}
+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 manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`parse ${manifestPath}: ${detail}`);
+    }
+    const pluginId = typeof manifest.id === "string"
+        ? manifest.id.trim()
+        : "";
+    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.module;
+    const moduleExec = typeof moduleValue?.exec === "string" ? moduleValue.exec.trim() : undefined;
+    return {
+        pluginId,
+        moduleExec,
+        manifestPath,
+    };
+}
+function validateDeclaredModuleExec(pluginDir, moduleExec) {
+    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 (!(0, fs_utils_1.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}`);
+    }
+}
+function hasPackageJson(pluginDir) {
+    const packageJsonPath = path.join(pluginDir, "package.json");
+    return fs.existsSync(packageJsonPath) && fs.lstatSync(packageJsonPath).isFile();
+}
+function runCommand(program, args, cwd, verbose) {
+    if (verbose) {
+        process.stderr.write(`Running command in ${cwd}: ${program} ${args.join(" ")}\n`);
+    }
+    const result = (0, node_child_process_1.spawnSync)(program, args, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    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()}'`);
+}
+function ensurePackageLock(pluginDir, verbose) {
+    if (!hasPackageJson(pluginDir)) {
+        return;
+    }
+    const lockPath = path.join(pluginDir, "package-lock.json");
+    if (fs.existsSync(lockPath) && fs.lstatSync(lockPath).isFile()) {
+        return;
+    }
+    if (verbose) {
+        process.stderr.write(`Generating package-lock.json in ${pluginDir}\n`);
+    }
+    runCommand(npmExecutable(), ["install", "--package-lock-only", "--ignore-scripts", "--no-audit", "--no-fund"], pluginDir, verbose);
+}
+function copyNpmFilesToStaging(pluginDir, bundleDir) {
+    const packageJsonPath = path.join(pluginDir, "package.json");
+    const lockPath = path.join(pluginDir, "package-lock.json");
+    if (!fs.existsSync(packageJsonPath) || !fs.lstatSync(packageJsonPath).isFile()) {
+        throw new Error(`missing package.json at ${packageJsonPath}`);
+    }
+    if (!fs.existsSync(lockPath) || !fs.lstatSync(lockPath).isFile()) {
+        throw new Error(`missing package-lock.json at ${lockPath}`);
+    }
+    (0, fs_utils_1.copyFileStrict)(packageJsonPath, path.join(bundleDir, "package.json"));
+    (0, fs_utils_1.copyFileStrict)(lockPath, path.join(bundleDir, "package-lock.json"));
+}
+function rejectNativeAddonsRecursive(dirPath) {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const entryPath = path.join(dirPath, entry.name);
+        const stats = fs.lstatSync(entryPath);
+        if (stats.isSymbolicLink()) {
+            throw new Error(`plugin contains a symlink: ${entryPath}`);
+        }
+        if (stats.isDirectory()) {
+            rejectNativeAddonsRecursive(entryPath);
+            continue;
+        }
+        if (!stats.isFile()) {
+            continue;
+        }
+        if (entry.name.toLowerCase().endsWith(".node")) {
+            throw new Error(`native Node addon files are not supported in portable bundles: ${entryPath}`);
+        }
+    }
+}
+function installNpmDependencies(pluginDir, bundleDir, verbose) {
+    copyNpmFilesToStaging(pluginDir, bundleDir);
+    runCommand(npmExecutable(), ["ci", "--omit=dev", "--ignore-scripts", "--no-bin-links", "--no-audit", "--no-fund"], bundleDir, verbose);
+    const nodeModulesPath = path.join(bundleDir, "node_modules");
+    if (!fs.existsSync(nodeModulesPath)) {
+        return;
+    }
+    if (!fs.lstatSync(nodeModulesPath).isDirectory()) {
+        throw new Error(`npm install produced non-directory node_modules path: ${nodeModulesPath}`);
+    }
+    rejectNativeAddonsRecursive(nodeModulesPath);
+}
+function copyIcon(pluginDir, bundleDir) {
+    for (const extension of ICON_EXTENSIONS) {
+        const fileName = `icon.${extension}`;
+        const sourcePath = path.join(pluginDir, fileName);
+        if (!fs.existsSync(sourcePath)) {
+            continue;
+        }
+        (0, fs_utils_1.copyFileStrict)(sourcePath, path.join(bundleDir, fileName));
+        return;
+    }
+}
+function uniqueStagingDir(outDir) {
+    return path.join(outDir, `.openvcs-plugin-staging-${Date.now()}-${process.pid}`);
+}
+async function writeTarGz(outPath, baseDir, folderName) {
+    const folderPath = path.join(baseDir, folderName);
+    (0, fs_utils_1.rejectSymlinksRecursive)(folderPath);
+    await tar.create({
+        cwd: baseDir,
+        file: outPath,
+        gzip: true,
+        portable: true,
+        noMtime: true,
+        preservePaths: false,
+        strict: true,
+    }, [folderName]);
+}
+async function bundlePlugin(parsedArgs) {
+    const { pluginDir, outDir, verbose, noNpmDeps } = parsedArgs;
+    if (verbose) {
+        process.stderr.write(`Bundling plugin from: ${pluginDir}\n`);
+    }
+    const { pluginId, moduleExec, manifestPath } = readManifest(pluginDir);
+    const themesPath = path.join(pluginDir, "themes");
+    const hasThemes = fs.existsSync(themesPath) && fs.lstatSync(themesPath).isDirectory();
+    if (!moduleExec && !hasThemes) {
+        throw new Error("manifest has no module.exec or themes/");
+    }
+    validateDeclaredModuleExec(pluginDir, moduleExec);
+    (0, fs_utils_1.ensureDirectory)(outDir);
+    const stagingRoot = uniqueStagingDir(outDir);
+    const bundleDir = path.join(stagingRoot, pluginId);
+    (0, fs_utils_1.ensureDirectory)(bundleDir);
+    try {
+        (0, fs_utils_1.copyFileStrict)(manifestPath, path.join(bundleDir, "openvcs.plugin.json"));
+        copyIcon(pluginDir, bundleDir);
+        const sourceBinDir = path.join(pluginDir, "bin");
+        if (fs.existsSync(sourceBinDir) && fs.lstatSync(sourceBinDir).isDirectory()) {
+            (0, fs_utils_1.copyDirectoryRecursiveStrict)(sourceBinDir, path.join(bundleDir, "bin"));
+        }
+        if (hasThemes) {
+            (0, fs_utils_1.copyDirectoryRecursiveStrict)(themesPath, path.join(bundleDir, "themes"));
+        }
+        if (!noNpmDeps && hasPackageJson(pluginDir)) {
+            ensurePackageLock(pluginDir, verbose);
+            installNpmDependencies(pluginDir, bundleDir, verbose);
+        }
+        const outPath = path.join(outDir, `${pluginId}.ovcsp`);
+        if (fs.existsSync(outPath)) {
+            fs.rmSync(outPath, { force: true });
+        }
+        await writeTarGz(outPath, stagingRoot, pluginId);
+        return outPath;
+    }
+    finally {
+        fs.rmSync(stagingRoot, { recursive: true, force: true });
+    }
+}
+exports.__private = {
+    ICON_EXTENSIONS,
+    copyIcon,
+    readManifest,
+    rejectNativeAddonsRecursive,
+    uniqueStagingDir,
+    validateDeclaredModuleExec,
+    writeTarGz,
+};

package/lib/fs-utils.d.ts

@@ -0,0 +1,5 @@
+export declare function isPathInside(rootPath: string, candidatePath: string): boolean;
+export declare function rejectSymlinksRecursive(rootDir: string): void;
+export declare function ensureDirectory(filePath: string): void;
+export declare function copyFileStrict(sourcePath: string, destinationPath: string): void;
+export declare function copyDirectoryRecursiveStrict(sourceDir: string, destinationDir: string): void;

package/lib/fs-utils.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPathInside = isPathInside;
+exports.rejectSymlinksRecursive = rejectSymlinksRecursive;
+exports.ensureDirectory = ensureDirectory;
+exports.copyFileStrict = copyFileStrict;
+exports.copyDirectoryRecursiveStrict = copyDirectoryRecursiveStrict;
+const fs = require("node:fs");
+const path = require("node:path");
+function isPathInside(rootPath, candidatePath) {
+    const relative = path.relative(rootPath, candidatePath);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function rejectSymlinksRecursive(rootDir) {
+    const stack = [rootDir];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current) {
+            continue;
+        }
+        const entries = fs.readdirSync(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const entryPath = path.join(current, entry.name);
+            const stats = fs.lstatSync(entryPath);
+            if (stats.isSymbolicLink()) {
+                throw new Error(`plugin contains a symlink: ${entryPath}`);
+            }
+            if (stats.isDirectory()) {
+                stack.push(entryPath);
+            }
+        }
+    }
+}
+function ensureDirectory(filePath) {
+    fs.mkdirSync(filePath, { recursive: true });
+}
+function copyFileStrict(sourcePath, destinationPath) {
+    const stats = fs.lstatSync(sourcePath);
+    if (stats.isSymbolicLink()) {
+        throw new Error(`plugin contains a symlink: ${sourcePath}`);
+    }
+    if (!stats.isFile()) {
+        throw new Error(`expected file: ${sourcePath}`);
+    }
+    ensureDirectory(path.dirname(destinationPath));
+    fs.copyFileSync(sourcePath, destinationPath);
+}
+function copyDirectoryRecursiveStrict(sourceDir, destinationDir) {
+    if (!fs.existsSync(sourceDir)) {
+        return;
+    }
+    const stats = fs.lstatSync(sourceDir);
+    if (stats.isSymbolicLink()) {
+        throw new Error(`plugin contains a symlink: ${sourceDir}`);
+    }
+    if (!stats.isDirectory()) {
+        throw new Error(`expected directory: ${sourceDir}`);
+    }
+    ensureDirectory(destinationDir);
+    const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = path.join(sourceDir, entry.name);
+        const destinationPath = path.join(destinationDir, entry.name);
+        const entryStats = fs.lstatSync(sourcePath);
+        if (entryStats.isSymbolicLink()) {
+            throw new Error(`plugin contains a symlink: ${sourcePath}`);
+        }
+        if (entryStats.isDirectory()) {
+            copyDirectoryRecursiveStrict(sourcePath, destinationPath);
+            continue;
+        }
+        if (entryStats.isFile()) {
+            fs.copyFileSync(sourcePath, destinationPath);
+        }
+    }
+}

package/lib/init.d.ts

@@ -0,0 +1,7 @@
+interface InitCommandError {
+    code?: string;
+}
+export declare function initUsage(commandName?: string): string;
+export declare function runInitCommand(args: string[]): Promise<string>;
+export declare function isUsageError(error: unknown): error is InitCommandError;
+export {};