@droposs/plugin-cli 0.1.0 → 0.2.0

package/bin/drop-plugin.js

@@ -1,5 +1,14 @@
 #!/usr/bin/env node
-import { signPlugin, packPlugin } from "../dist/signer.js";
+import {
+  signPlugin,
+  packPlugin,
+  buildPlugin,
+  testPlugin,
+  initPlugin,
+  validateManifest,
+} from "../dist/index.js";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
 
 const command = process.argv[2];
 const args = process.argv.slice(3);
@@ -9,26 +18,72 @@ async function main() {
     case "sign": {
       const dir = args[0] || ".";
       const res = await signPlugin(dir);
-      console.log(`Signed bundle at ${dir}: ${res.fileCount} files verified (signature: ${res.signed ? "yes" : "no"})`);
+      console.log(
+        `Signed bundle at ${dir}: ${res.fileCount} files verified (signature: ${res.signed ? "yes" : "no"})`,
+      );
       break;
     }
     case "pack": {
       const dir = args[0] || ".";
       const outDir = args[1];
       const res = await packPlugin(dir, outDir);
-      console.log(`Packed plugin '${res.id}' v${res.version} to ${res.packagePath}`);
+      console.log(
+        `Packed plugin '${res.id}' v${res.version} to ${res.packagePath}`,
+      );
+      break;
+    }
+    case "build": {
+      const dir = args[0] || ".";
+      const res = await buildPlugin(dir);
+      console.log(
+        `Built plugin at ${dir} (server: ${res.serverBuilt ? "yes" : "no"}, client: ${res.clientBuilt ? "yes" : "no"})`,
+      );
+      break;
+    }
+    case "test": {
+      const dir = args[0] || ".";
+      await testPlugin(dir);
+      break;
+    }
+    case "init": {
+      const dir = args[0] || "my-drop-plugin";
+      const res = await initPlugin(dir);
+      console.log(`Initialized new Drop plugin '${res.id}' at ${res.targetPath}`);
+      break;
+    }
+    case "validate": {
+      const dir = args[0] || ".";
+      const manifestPath = path.join(path.resolve(process.cwd(), dir), "drop-plugin.json");
+      const manifest = JSON.parse(await readFile(manifestPath, "utf-8"));
+      const validation = await validateManifest(manifest);
+      if (!validation.valid) {
+        console.error("Validation failed:");
+        for (const err of validation.errors) {
+          console.error(`  - ${err}`);
+        }
+        process.exit(1);
+      } else {
+        console.log(`Manifest at ${manifestPath} is valid.`);
+      }
       break;
     }
     case "help":
+    case "--help":
+    case "-h":
     default:
       console.log(`Drop Plugin CLI (drop-plugin)
 
 Usage:
+  drop-plugin init [dir]         Initialize a new plugin from starter template
+  drop-plugin build [dir]        Bundle server/client entry points with esbuild and sign
   drop-plugin sign [dir]         Calculate SHA-256 digests and sign drop-plugin.json
+  drop-plugin validate [dir]     Validate drop-plugin.json against official schema
+  drop-plugin test [dir]         Run plugin tests with Node test runner
   drop-plugin pack [dir] [out]   Verify, sign, and package bundle into .dropplugin archive
-  drop-plugin build              Compile plugin bundle
-  drop-plugin test               Run plugin tests
 `);
+      if (command && command !== "help" && command !== "--help" && command !== "-h") {
+        process.exit(1);
+      }
       break;
   }
 }

package/dist/builder.d.ts

@@ -0,0 +1,10 @@
+export interface BuildOptions {
+    minify?: boolean;
+    sourcemap?: boolean;
+    sign?: boolean;
+    signingKey?: string;
+}
+export declare function buildPlugin(targetDir?: string, options?: BuildOptions): Promise<{
+    serverBuilt: boolean;
+    clientBuilt: boolean;
+}>;

package/dist/builder.js

@@ -0,0 +1,84 @@
+import * as esbuild from "esbuild";
+import path from "node:path";
+import { readFile, stat } from "node:fs/promises";
+import { signPlugin } from "./signer.js";
+export async function buildPlugin(targetDir = ".", options = {}) {
+    const dir = path.resolve(process.cwd(), targetDir);
+    const manifestPath = path.join(dir, "drop-plugin.json");
+    const manifest = JSON.parse(await readFile(manifestPath, "utf-8"));
+    let serverBuilt = false;
+    let clientBuilt = false;
+    // 1. Build Server Entry if source exists
+    const serverSourceCandidates = [
+        manifest.server?.source,
+        "src/index.ts",
+        "src/index.js",
+        "src/server.ts",
+    ].filter(Boolean);
+    let serverEntrySource = null;
+    for (const candidate of serverSourceCandidates) {
+        const p = path.join(dir, candidate);
+        if (await stat(p).catch(() => null)) {
+            serverEntrySource = p;
+            break;
+        }
+    }
+    const serverOutFile = path.resolve(dir, manifest.server?.entry ?? manifest.entry ?? "dist/src/index.js");
+    if (serverEntrySource) {
+        await esbuild.build({
+            entryPoints: [serverEntrySource],
+            outfile: serverOutFile,
+            bundle: true,
+            platform: "node",
+            target: "node22",
+            format: "esm",
+            sourcemap: options.sourcemap ?? true,
+            minify: options.minify ?? false,
+            external: [
+                "@droposs/plugin-sdk",
+                "@drop/plugin-sdk",
+                "h3",
+                "pino",
+            ],
+        });
+        serverBuilt = true;
+    }
+    // 2. Build Client Entry if source exists
+    const clientSourceCandidates = [
+        manifest.client?.source,
+        "src/client.ts",
+        "src/client.js",
+    ].filter(Boolean);
+    let clientEntrySource = null;
+    for (const candidate of clientSourceCandidates) {
+        const p = path.join(dir, candidate);
+        if (await stat(p).catch(() => null)) {
+            clientEntrySource = p;
+            break;
+        }
+    }
+    const clientOutFile = path.resolve(dir, manifest.client?.entry ?? manifest.clientEntry ?? "dist/src/client.js");
+    if (clientEntrySource) {
+        await esbuild.build({
+            entryPoints: [clientEntrySource],
+            outfile: clientOutFile,
+            bundle: true,
+            platform: "browser",
+            target: "es2022",
+            format: "esm",
+            sourcemap: options.sourcemap ?? true,
+            minify: options.minify ?? false,
+            external: [
+                "vue",
+                "@droposs/plugin-sdk",
+                "@drop/plugin-sdk",
+            ],
+        });
+        clientBuilt = true;
+    }
+    // 3. Automatically re-sign the plugin bundle after building
+    if (options.sign !== false) {
+        await signPlugin(dir, options.signingKey);
+    }
+    return { serverBuilt, clientBuilt };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./signer.js";
+export * from "./builder.js";
+export * from "./testRunner.js";
+export * from "./scaffolder.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./signer.js";
+export * from "./builder.js";
+export * from "./testRunner.js";
+export * from "./scaffolder.js";

package/dist/scaffolder.d.ts

@@ -0,0 +1,9 @@
+export interface InitOptions {
+    id?: string;
+    name?: string;
+    author?: string;
+}
+export declare function initPlugin(targetDir: string, options?: InitOptions): Promise<{
+    targetPath: string;
+    id: string;
+}>;

package/dist/scaffolder.js

@@ -0,0 +1,51 @@
+import path from "node:path";
+import { cp, mkdir, readFile, writeFile, stat } from "node:fs/promises";
+export async function initPlugin(targetDir, options = {}) {
+    const targetPath = path.resolve(process.cwd(), targetDir);
+    await mkdir(targetPath, { recursive: true });
+    const candidates = [
+        path.resolve(path.dirname(new URL(import.meta.url).pathname), "../../../templates/starter-plugin"),
+        path.resolve(path.dirname(new URL(import.meta.url).pathname), "../templates/starter-plugin"),
+        path.resolve(process.cwd(), "templates/starter-plugin"),
+    ];
+    let templateDir = null;
+    for (const cand of candidates) {
+        if (await stat(cand).catch(() => null)) {
+            templateDir = cand;
+            break;
+        }
+    }
+    if (!templateDir) {
+        throw new Error("Starter plugin template directory not found");
+    }
+    await cp(templateDir, targetPath, {
+        recursive: true,
+        filter: (src) => {
+            const basename = path.basename(src);
+            return basename !== "node_modules" && basename !== "dist";
+        },
+    });
+    const pluginId = options.id ||
+        path
+            .basename(targetPath)
+            .toLowerCase()
+            .replace(/[^a-z0-9._-]/g, "-");
+    const pluginName = options.name || pluginId;
+    // Update drop-plugin.json
+    const manifestPath = path.join(targetPath, "drop-plugin.json");
+    const manifest = JSON.parse(await readFile(manifestPath, "utf-8"));
+    manifest.id = pluginId;
+    manifest.name = pluginName;
+    if (options.author)
+        manifest.author = options.author;
+    delete manifest.checksum;
+    delete manifest.files;
+    delete manifest.signature;
+    await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+    // Update package.json
+    const pkgPath = path.join(targetPath, "package.json");
+    const pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
+    pkg.name = `drop-${pluginId}`;
+    await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    return { targetPath, id: pluginId };
+}

package/dist/signer.d.ts

@@ -1,5 +1,10 @@
+export declare function isInside(base: string, candidate: string): boolean;
+export declare function validateManifest(manifest: unknown): Promise<{
+    valid: boolean;
+    errors: string[];
+}>;
 export declare function listFiles(root: string, prefix?: string): Promise<string[]>;
-export declare function signPlugin(targetDir: string, signingKey?: string): Promise<{
+export declare function signPlugin(targetDir: string, signingKey?: string, validate?: boolean): Promise<{
     fileCount: number;
     signed: boolean;
 }>;

package/dist/signer.js

@@ -1,22 +1,66 @@
 import { createHash, createHmac } from "node:crypto";
 import { readdir, readFile, realpath, stat, writeFile, mkdir } from "node:fs/promises";
+import { createRequire } from "node:module";
 import path from "node:path";
+import Ajv from "ajv";
 const MANIFEST_FILE = "drop-plugin.json";
-function isInside(base, candidate) {
-    const relative = path.relative(base, candidate);
-    return (relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative));
+export function isInside(base, candidate) {
+    const rel = path.relative(path.resolve(base), path.resolve(candidate));
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+async function loadSchema() {
+    try {
+        const require = createRequire(import.meta.url);
+        const schemaPath = require.resolve("@droposs/plugin-sdk/schema.json");
+        return JSON.parse(await readFile(schemaPath, "utf-8"));
+    }
+    catch {
+        const fallback = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../../plugin-sdk/schema/drop-plugin.schema.json");
+        return JSON.parse(await readFile(fallback, "utf-8"));
+    }
+}
+let cachedValidator = null;
+let cachedErrors = [];
+export async function validateManifest(manifest) {
+    if (!cachedValidator) {
+        const schema = await loadSchema();
+        // @ts-ignore
+        const AjvClass = Ajv.default ?? Ajv;
+        const ajv = new AjvClass({ allErrors: true, strict: false });
+        const compiled = ajv.compile(schema);
+        cachedValidator = (data) => {
+            const ok = compiled(data);
+            if (!ok && compiled.errors) {
+                cachedErrors = compiled.errors.map((err) => `${err.instancePath || "/"} ${err.message}`);
+            }
+            else {
+                cachedErrors = [];
+            }
+            return Boolean(ok);
+        };
+    }
+    const valid = cachedValidator(manifest);
+    return { valid, errors: [...cachedErrors] };
 }
 export async function listFiles(root, prefix = "") {
     const results = [];
-    const entries = await readdir(path.join(root, prefix), { withFileTypes: true });
+    const dirPath = path.join(root, prefix);
+    const entries = await readdir(dirPath, { withFileTypes: true });
     for (const entry of entries) {
         const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
-        if (entry.isDirectory()) {
+        const fullPath = path.join(root, rel);
+        // Enforce confinement invariant: symlinks or traversal outside bundle root are rejected
+        const real = await realpath(fullPath).catch(() => null);
+        if (!real || !isInside(root, real)) {
+            throw new Error(`Path traversal or symlink escape detected: ${rel}`);
+        }
+        const s = await stat(real);
+        if (s.isDirectory()) {
             if (entry.name === "node_modules" || entry.name === ".git")
                 continue;
             results.push(...(await listFiles(root, rel)));
         }
-        else if (entry.isFile()) {
+        else if (s.isFile()) {
             if (!prefix && entry.name === MANIFEST_FILE)
                 continue;
             results.push(rel);
@@ -24,7 +68,7 @@ export async function listFiles(root, prefix = "") {
     }
     return results.sort((a, b) => a.localeCompare(b));
 }
-export async function signPlugin(targetDir, signingKey) {
+export async function signPlugin(targetDir, signingKey, validate = true) {
     const resolvedPath = path.resolve(process.cwd(), targetDir);
     const bundleDir = await realpath(resolvedPath).catch(() => null);
     if (!bundleDir) {
@@ -32,12 +76,21 @@ export async function signPlugin(targetDir, signingKey) {
     }
     const manifestPath = path.join(bundleDir, MANIFEST_FILE);
     const manifest = JSON.parse(await readFile(manifestPath, "utf-8"));
+    if (validate) {
+        const validation = await validateManifest(manifest);
+        if (!validation.valid) {
+            throw new Error(`Manifest validation failed against schema:\n  ${validation.errors.join("\n  ")}`);
+        }
+    }
     // Identify primary entry (v1 or v2 server/client entry)
     const entry = manifest.entry ??
         manifest.server?.entry ??
         manifest.client?.entry ??
         "index.js";
     const entryPath = path.resolve(bundleDir, entry);
+    if (!isInside(bundleDir, entryPath) && entryPath !== bundleDir) {
+        throw new Error(`Entry path outside bundle directory: ${entry}`);
+    }
     const entryExists = await stat(entryPath).catch(() => null);
     if (entryExists) {
         const entryBytes = await readFile(entryPath);

package/dist/testRunner.d.ts

@@ -0,0 +1 @@
+export declare function testPlugin(targetDir?: string): Promise<void>;

package/dist/testRunner.js

@@ -0,0 +1,52 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { readdir, stat } from "node:fs/promises";
+export async function testPlugin(targetDir = ".") {
+    const dir = path.resolve(process.cwd(), targetDir);
+    const candidates = [
+        path.join(dir, "dist", "test"),
+        path.join(dir, "test"),
+    ];
+    let testFiles = [];
+    for (const cand of candidates) {
+        if (await stat(cand).catch(() => null)) {
+            const files = await readdir(cand, { recursive: true });
+            for (const f of files) {
+                if (typeof f === "string" &&
+                    (f.endsWith(".test.js") || f.endsWith(".spec.js"))) {
+                    testFiles.push(path.join(cand, f));
+                }
+            }
+            if (testFiles.length > 0)
+                break;
+        }
+    }
+    if (testFiles.length === 0) {
+        const testDir = path.join(dir, "test");
+        if (await stat(testDir).catch(() => null)) {
+            const files = await readdir(testDir, { recursive: true });
+            testFiles = files
+                .filter((f) => typeof f === "string" &&
+                (f.endsWith(".test.ts") || f.endsWith(".spec.ts")))
+                .map((f) => path.join(testDir, f));
+        }
+    }
+    if (testFiles.length === 0) {
+        console.log(`No test files found in ${targetDir}`);
+        return;
+    }
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, ["--test", ...testFiles], {
+            cwd: dir,
+            stdio: "inherit",
+        });
+        child.on("close", (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`Tests exited with code ${code}`));
+            }
+        });
+    });
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@droposs/plugin-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Drop Plugin build, test, signing, and packaging CLI for Drop OSS",
   "type": "module",
   "bin": {
     "drop-plugin": "./bin/drop-plugin.js"
   },
-  "main": "dist/signer.js",
-  "types": "dist/signer.d.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
     "bin",
     "dist"
@@ -35,10 +35,15 @@
     "playnite"
   ],
   "devDependencies": {
-    "typescript": "^5.7.0",
-    "@types/node": "^22.0.0"
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
   },
   "license": "MIT",
+  "dependencies": {
+    "@droposs/plugin-sdk": "0.2.0",
+    "ajv": "^8.20.0",
+    "esbuild": "^0.28.2"
+  },
   "scripts": {
     "build": "tsc",
     "test": "node --test"