zotero-plugin-scaffold 0.2.0-beta.10 → 0.2.0-beta.12

package/README.md

@@ -14,132 +14,9 @@ This project is under active development, and some APIs may change. However, it
 
 For best practices regarding this package, please refer to [zotero-plugin-template](https://github.com/windingwind/zotero-plugin-template).
 
-## Using in a blank project
+## Documentation
 
-<details>
-
-<summary>WIP: Not yet implemented</summary>
-
-```bash
-# npm
-npx zotero-plugin create
-# pnpm
-pnpm dlx zotero-plugin create
-```
-
-</details>
-
-## Using in an existing project
-
-### 01. Install
-
-#### From NPM
-
-```bash
-npm install -D zotero-plugin-scaffold
-
-yarn add -D zotero-plugin-scaffold
-
-pnpm add -D zotero-plugin-scaffold
-```
-
-#### From source code
-
-```bash
-# clone this repo
-git clone https://github.com/northword/zotero-plugin-scaffold.git zotero-plugin-scaffold/
-cd zotero-plugin-scaffold/
-
-# build
-pnpm install
-pnpm build # or pnpm dev
-
-# npm link
-cd your-plugin-work-dir/
-pnpm link ../zotero-plugin-scaffold
-```
-
-### 02. Create a config file
-
-The configuration file needs to be stored in the following location.
-
-```bash
-zotero-plugin.config.ts  # also avaliable in *.js  *.mjs  *.cjs  *.ts
-```
-
-You can import helper `defineConfig` to get type hints. If no value is specified for an optional property, the default value will be used.
-
-```ts
-import { defineConfig } from "zotero-plugin-scaffold";
-
-export default defineConfig({
-  name: "the plugin name",
-  id: "the plugin id",
-  namespace: "the plugin namespace",
-  build: {
-    esbuildOptions: [
-      {
-        entryPoints: ["src/index.ts"],
-        bundle: true,
-        target: "firefox115",
-      },
-    ],
-  },
-});
-```
-
-Full config please refrence in [src/types](./src/types/index.ts).
-
-### 03. Create a env file
-
-This file defines Zotero's runtime configuration such as binary paths, profile paths, and environment variables required for Node scripts to run.
-
-NOTE: Do not check-in this file to the repository!
-
-```bash
-.env
-```
-
-```ini
-# The path of the Zotero binary file.
-# The path is `*/Zotero.app/Contents/MacOS/zotero` for macOS.
-ZOTERO_PLUGIN_ZOTERO_BIN_PATH = /path/to/zotero.exe
-
-# The path of the profile used for development.
-# Start the profile manager by `/path/to/zotero.exe -p` to create a profile for development.
-# @see https://www.zotero.org/support/kb/profile_directory
-ZOTERO_PLUGIN_PROFILE_PATH = /path/to/profile
-```
-
-### 04. Add scripts to package.json
-
-```json
-{
-  "scripts": {
-    "start": "zotero-plugin serve",
-    "build": "zotero-plugin build",
-    "release": "zotero-plugin release"
-  }
-}
-```
-
-### 05. Run
-
-```bash
-pnpm run start
-pnpm run build
-```
-
-## Using in NodeJS code
-
-```ts
-import { Build, Config } from "zotero-plugin-scaffold";
-
-const config = await Config.loadConfig();
-
-const Builder = new Build(config);
-await Builder.run();
-```
+[Read the Docs to Learn More.](https://northword.github.io/zotero-plugin-scaffold)
 
 ## Contributing
 
@@ -156,6 +33,18 @@ pnpm install
 # and the modified code does not need to be built again.
 pnpm run dev
 
+# link local scaffold to your plugin
+cd your-plugin-work-dir/
+pnpm link ../zotero-plugin-scaffold
+cd zotero-plugin-scaffold/
+
+```
+
+Now you can make changes to Scaffold and test them in your plugin.
+
+When you're done modifying, make sure that you can pass the build and that the code style meets the requirements of this repository.
+
+```bash
 # Build
 pnpm run build
 

package/dist/chunks/github.mjs

@@ -1,11 +1,11 @@
 import { readFile, stat } from 'node:fs/promises';
 import { join, basename } from 'node:path';
-import { env } from 'node:process';
+import process from 'node:process';
 import mime from 'mime';
 import { Octokit } from 'octokit';
 import { globSync, glob } from 'tinyglobby';
 import { isCI } from 'std-env';
-import { B as Base } from '../shared/zotero-plugin-scaffold.802444a9.mjs';
+import { B as Base } from '../shared/zotero-plugin-scaffold.af8d03c3.mjs';
 import 'c12';
 import 'es-toolkit';
 import 'fs-extra/esm';
@@ -180,10 +180,10 @@ class GitHub extends ReleaseBase {
     return releaseNote(this.ctx);
   }
   getClient() {
-    if (!env.GITHUB_TOKEN)
+    if (!process.env.GITHUB_TOKEN)
       throw new Error("No GITHUB_TOKEN.");
     const client = new Octokit({
-      auth: env.GITHUB_TOKEN,
+      auth: process.env.GITHUB_TOKEN,
       userAgent: "zotero-plugin-scaffold"
     });
     return client;

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import process, { exit, env } from 'node:process';
+import process from 'node:process';
 import { Command } from '@commander-js/extra-typings';
-import { E as ExitSignals, l as logger, C as Config, a as Build, S as Serve, T as Test, R as Release } from './shared/zotero-plugin-scaffold.802444a9.mjs';
+import { E as ExitSignals, l as logger, C as Config, a as Build, S as Serve, T as Test, R as Release } from './shared/zotero-plugin-scaffold.af8d03c3.mjs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { pathExists, ensureFile } from 'fs-extra';
 import tinyUpdateNotifier from 'tiny-update-notifier';
@@ -31,7 +31,7 @@ import 'xvfb-ts';
 
 const name = "zotero-plugin-scaffold";
 const type = "module";
-const version = "0.2.0-beta.10";
+const version = "0.2.0-beta.12";
 const packageManager = "pnpm@9.15.0";
 const description = "A scaffold for Zotero plugin development.";
 const author = "northword";
@@ -80,7 +80,10 @@ const scripts = {
 	"lint:fix": "eslint . --fix",
 	release: "bumpp --commit \"chore(release): publish v%s\"",
 	"update:deps": "pnpx taze minor -w -f -l",
-	test: "echo \"Error: no test specified\" && exit 1"
+	test: "echo \"Error: no test specified\" && exit 1",
+	"docs:dev": "vitepress dev docs",
+	"docs:build": "vitepress build docs",
+	"docs:preview": "vitepress preview docs"
 };
 const publishConfig = {
 	access: "public",
@@ -125,7 +128,8 @@ const devDependencies = {
 	eslint: "^9.16.0",
 	"eslint-plugin-format": "^0.1.3",
 	typescript: "^5.7.2",
-	unbuild: "^2.0.0"
+	unbuild: "^2.0.0",
+	vitepress: "^1.5.0"
 };
 const pkg = {
 	name: name,
@@ -186,11 +190,11 @@ async function main() {
   var _a;
   const { name, version } = pkg;
   updateNotifier(name, version);
-  (_a = env).NODE_ENV ?? (_a.NODE_ENV = "development");
+  (_a = process.env).NODE_ENV ?? (_a.NODE_ENV = "development");
   const cli = new Command();
   cli.version(version).usage("<command> [options]");
   cli.command("build").description("Build the plugin").option("--dev", "Builds the plugin in dev mode").option("--dist <dir>", "The relative path for the new output directory (default: build)").action((options) => {
-    env.NODE_ENV = options.dev ? "development" : "production";
+    process.env.NODE_ENV = options.dev ? "development" : "production";
     Config.loadConfig({
       dist: options.dist
     }).then((ctx) => new Build(ctx).run());
@@ -199,7 +203,7 @@ async function main() {
     Config.loadConfig({}).then((ctx) => new Serve(ctx).run());
   });
   cli.command("test").description("Run tests").option("--abort-on-fail", "Abort the test suite on first failure").option("--exit-on-finish", "Exit the test suite after all tests have run").action((options) => {
-    env.NODE_ENV = "test";
+    process.env.NODE_ENV = "test";
     Config.loadConfig({}).then((ctx) => {
       if (options.abortOnFail) {
         ctx.test.abortOnFail = true;
@@ -214,7 +218,7 @@ async function main() {
     logger.error("The create not yet implemented");
   });
   cli.command("release").description("Release the plugin").argument("[version]", "Target version: major, minor, patch, pre*, or specify version").option("--preid <preid>", "ID for prerelease").option("-y, --yes", "Skip confirmation").action(async (version2, options) => {
-    env.NODE_ENV = "production";
+    process.env.NODE_ENV = "production";
     Config.loadConfig({
       release: {
         bumpp: {
@@ -237,7 +241,7 @@ main().then(() => {
 process.on("uncaughtException", onError);
 function onError(err) {
   logger.error(err);
-  exit(1);
+  process.exit(1);
 }
 
 export { main as default };

package/dist/index.d.mts

@@ -22,6 +22,7 @@ declare class Log {
     constructor(level?: LOG_LEVEL);
     static getInstance(): Log;
     setLogLevel(level: LogLevelType): void;
+    get level(): number;
     private formatArgs;
     private logArgs;
     log(...args: any[]): void;

package/dist/index.d.ts

@@ -22,6 +22,7 @@ declare class Log {
     constructor(level?: LOG_LEVEL);
     static getInstance(): Log;
     setLogLevel(level: LogLevelType): void;
+    get level(): number;
     private formatArgs;
     private logArgs;
     log(...args: any[]): void;

package/dist/index.mjs

@@ -1,4 +1,4 @@
-export { a as Build, C as Config, R as Release, S as Serve, T as Test, d as defineConfig } from './shared/zotero-plugin-scaffold.802444a9.mjs';
+export { a as Build, C as Config, R as Release, S as Serve, T as Test, d as defineConfig } from './shared/zotero-plugin-scaffold.af8d03c3.mjs';
 import 'c12';
 import 'es-toolkit';
 import 'fs-extra/esm';

package/dist/shared/{zotero-plugin-scaffold.802444a9.mjs → zotero-plugin-scaffold.af8d03c3.mjs}

@@ -2,7 +2,7 @@ import { loadConfig as loadConfig$1 } from 'c12';
 import { isPlainObject, kebabCase, mapValues, toMerged, escapeRegExp, delay, debounce } from 'es-toolkit';
 import { readJsonSync, emptyDir, copy, readJSON, outputJSON, move, writeJson, pathExists, outputFile, remove } from 'fs-extra/esm';
 import { createHooks } from 'hookable';
-import process, { env, platform, exit, cwd } from 'node:process';
+import process from 'node:process';
 import readline from 'node:readline';
 import chalk from 'chalk';
 import { isDebug, isCI, isWindows, isMacOS, isLinux } from 'std-env';
@@ -43,8 +43,8 @@ const _Log = class _Log {
     __publicField$7(this, "logLevel");
     if (isDebug)
       this.logLevel = 0 /* trace */;
-    else if (env.ZOTERO_PLUGIN_LOG_LEVEL)
-      this.logLevel = LOG_LEVEL[env.ZOTERO_PLUGIN_LOG_LEVEL];
+    else if (process.env.ZOTERO_PLUGIN_LOG_LEVEL)
+      this.logLevel = LOG_LEVEL[process.env.ZOTERO_PLUGIN_LOG_LEVEL];
     else if (level)
       this.logLevel = level;
     else
@@ -59,6 +59,9 @@ const _Log = class _Log {
   setLogLevel(level) {
     this.logLevel = LOG_LEVEL[level];
   }
+  get level() {
+    return this.logLevel;
+  }
   formatArgs(arg) {
     if (typeof arg === "string")
       return arg;
@@ -333,7 +336,7 @@ class Build extends Base {
     super(ctx);
     __publicField$5(this, "buildTime");
     __publicField$5(this, "isPreRelease");
-    (_a = env).NODE_ENV ?? (_a.NODE_ENV = "production");
+    (_a = process.env).NODE_ENV ?? (_a.NODE_ENV = "production");
     this.buildTime = "";
     this.isPreRelease = this.ctx.version.includes("-");
   }
@@ -345,7 +348,7 @@ class Build extends Base {
     const t = /* @__PURE__ */ new Date();
     this.buildTime = dateFormat("YYYY-mm-dd HH:MM:SS", t);
     this.logger.info(
-      `Building version ${chalk.blue(version)} to ${chalk.blue(dist)} at ${chalk.blue(this.buildTime)} in ${chalk.blue(env.NODE_ENV)} mode.`
+      `Building version ${chalk.blue(version)} to ${chalk.blue(dist)} at ${chalk.blue(this.buildTime)} in ${chalk.blue(process.env.NODE_ENV)} mode.`
     );
     await this.ctx.hooks.callHook("build:init", this.ctx);
     await emptyDir(dist);
@@ -362,7 +365,7 @@ class Build extends Base {
     this.logger.tip("Bundling scripts");
     await this.esbuild();
     await this.ctx.hooks.callHook("build:bundle", this.ctx);
-    if (env.NODE_ENV === "production") {
+    if (process.env.NODE_ENV === "production") {
       this.logger.tip("Packing plugin");
       await this.pack();
       await this.ctx.hooks.callHook("build:pack", this.ctx);
@@ -733,7 +736,7 @@ ${changelog}
 
 function isRunning(query) {
   let cmd = "";
-  switch (platform) {
+  switch (process.platform) {
     case "win32":
       cmd = `tasklist`;
       break;
@@ -1069,6 +1072,7 @@ class RemoteFirefox {
         await this.client.connect(port);
         return this.client;
       } catch (error) {
+        logger.fail("Failed to connecte to RDP client, retry...");
         if (isErrorWithCode("ECONNREFUSED", error)) {
           await new Promise((resolve) => setTimeout(resolve, RETRY_INTERVAL));
           lastError = error;
@@ -1275,18 +1279,17 @@ class ZoteroRunner {
     }
     const remotePort = await findFreeTcpPort();
     args.push("-start-debugger-server", String(remotePort));
-    const defaultFirefoxEnv = {
+    logger.debug("Zotero start args: ", args);
+    const env = {
+      ...process.env,
       XPCOM_DEBUG_BREAK: "stack",
       NS_TRACE_MALLOC_DISABLE_STACKS: "1"
     };
-    this.zotero = spawn(this.options.binaryPath, args, {
-      env: {
-        ...env,
-        ...defaultFirefoxEnv
-      }
-    });
+    this.zotero = spawn(this.options.binaryPath, args, { env });
+    logger.debug("Zotero started, pid:", this.zotero.pid);
     this.zotero.stdout?.on("data", (_data) => {
     });
+    logger.debug("Connecting to the remote Firefox debugger...");
     await this.remoteFirefox.connect(remotePort);
     logger.debug(`Connected to the remote Firefox debugger on port: ${remotePort}`);
   }
@@ -1412,8 +1415,8 @@ class ZoteroRunner {
 function killZotero() {
   function kill() {
     try {
-      if (env.ZOTERO_PLUGIN_KILL_COMMAND) {
-        execSync(env.ZOTERO_PLUGIN_KILL_COMMAND);
+      if (process.env.ZOTERO_PLUGIN_KILL_COMMAND) {
+        execSync(process.env.ZOTERO_PLUGIN_KILL_COMMAND);
       } else if (isWindows) {
         execSync("taskkill /f /im zotero.exe");
       } else if (isMacOS) {
@@ -1457,7 +1460,7 @@ class Serve extends Base {
     });
     __publicField$1(this, "onZoteroExit", (_code, _signal) => {
       this.logger.info(`Zotero terminated.`);
-      exit();
+      process.exit();
     });
     (_a = process.env).NODE_ENV ?? (_a.NODE_ENV = "development");
     this.builder = new Build(ctx);
@@ -1528,7 +1531,7 @@ class Serve extends Base {
   get zoteroBinPath() {
     if (this._zoteroBinPath)
       return this._zoteroBinPath;
-    this._zoteroBinPath = env.ZOTERO_PLUGIN_ZOTERO_BIN_PATH;
+    this._zoteroBinPath = process.env.ZOTERO_PLUGIN_ZOTERO_BIN_PATH;
     if (!this._zoteroBinPath || !existsSync(this._zoteroBinPath))
       throw new Error("The Zotero binary not found.");
     return this._zoteroBinPath;
@@ -1536,13 +1539,13 @@ class Serve extends Base {
   get profilePath() {
     if (this._profilePath)
       return this._profilePath;
-    this._profilePath = env.ZOTERO_PLUGIN_PROFILE_PATH;
+    this._profilePath = process.env.ZOTERO_PLUGIN_PROFILE_PATH;
     if (!this._profilePath || !existsSync(this._profilePath))
       throw new Error("The Zotero profile not found.");
     return this._profilePath;
   }
   get dataDir() {
-    return env.ZOTERO_PLUGIN_DATA_DIR ?? "";
+    return process.env.ZOTERO_PLUGIN_DATA_DIR ?? "";
   }
 }
 
@@ -1551,42 +1554,63 @@ async function saveResource(url, path) {
   await outputFile(path, await res.text());
 }
 
+function isPackageInstalled(packageName) {
+  try {
+    execSync(`dpkg-query -W ${packageName}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function installPackage(packageName) {
+  const debug = isDebug || logger.level <= LOG_LEVEL.debug;
+  try {
+    logger.debug(`Installing ${packageName}...`);
+    execSync(`sudo apt update && sudo apt install -y ${packageName}`, { stdio: debug ? "inherit" : "pipe" });
+    logger.debug(`${packageName} installed successfully.`);
+  } catch (error) {
+    logger.fail(`Failed to install ${packageName}.`, error);
+    throw error;
+  }
+}
+function checkAndInstallDependencies(packages) {
+  packages.forEach((pkg) => {
+    if (isPackageInstalled(pkg)) {
+      logger.debug(`${pkg} is already installed.`);
+    } else {
+      installPackage(pkg);
+    }
+  });
+}
 async function installXvfb() {
-  logger.debug("Installing xvfb...");
   if (!isLinux) {
     logger.error("Unsupported platform. Please install Xvfb manually.");
-    exit(1);
+    return;
   }
-  try {
-    execSync("which xvfb", { stdio: "ignore" });
-  } catch {
-    try {
-      const osId = execSync("cat /etc/os-release | grep '^ID='").toString();
-      if (osId.includes("ubuntu") || osId.includes("debian")) {
-        logger.debug("Detected Ubuntu/Debian. Installing Xvfb...");
-        execSync("sudo apt-get update && sudo apt-get install -y xvfb", { stdio: "pipe" });
-      } else if (osId.includes("centos") || osId.includes("rhel")) {
-        logger.debug("Detected CentOS/RHEL. Installing Xvfb...");
-        execSync("sudo yum install -y xorg-x11-server-Xvfb", { stdio: "pipe" });
-      } else {
-        throw new Error("Unsupported Linux distribution.");
-      }
-      logger.debug("Xvfb installation completed.");
-    } catch (error) {
-      logger.error("Failed to install Xvfb:", error);
-      exit(1);
-    }
+  const osId = execSync("cat /etc/os-release | grep '^ID='").toString();
+  if (!(osId.includes("ubuntu") || osId.includes("debian"))) {
+    logger.error("Unsupported Linux distribution.");
+    return;
+  }
+  checkAndInstallDependencies(["xvfb", "x11-xkb-utils", "xkb-data"]);
+}
+async function installDepsForUbuntu24() {
+  const version = execSync("cat /etc/os-release | grep '^VERSION_ID='").toString();
+  if (!version.includes("24")) {
+    logger.error("Skip to install deps due to version not 24.04.");
+    return;
   }
+  checkAndInstallDependencies(["libasound2t64", "libdbus-glib-1-2"]);
 }
 async function installZoteroLinux() {
-  logger.debug("Installing Zotero...");
-  try {
-    execSync("wget -O zotero.tar.bz2 'https://www.zotero.org/download/client/dl?platform=linux-x86_64&channel=beta'", { stdio: "pipe" });
-    execSync("tar -xvf zotero.tar.bz2", { stdio: "pipe" });
-  } catch (e) {
-    logger.error(e);
-    throw new Error("Zotero extracted failed");
+  if (process.env.ZOTERO_PLUGIN_ZOTERO_BIN_PATH) {
+    logger.debug("Local Zotero found, skip to download.");
+    return;
   }
+  logger.debug("Installing Zotero...");
+  execSync("wget -O zotero.tar.bz2 'https://www.zotero.org/download/client/dl?platform=linux-x86_64&channel=beta'", { stdio: "pipe" });
+  execSync("tar -xvf zotero.tar.bz2", { stdio: "pipe" });
+  process.env.ZOTERO_PLUGIN_ZOTERO_BIN_PATH = `${process.cwd()}/Zotero_linux-x86_64/zotero`;
 }
 
 var __defProp = Object.defineProperty;
@@ -1608,16 +1632,16 @@ class Test extends Base {
       this.ctx.hooks.callHook("test:exit", this.ctx);
       if (code === 1) {
         this.logger.error("Test run failed");
-        exit(1);
+        process.exit(1);
       } else if (code === "SIGINT") {
         this.logger.info("Tester shutdown by user request");
-        exit();
+        process.exit();
       } else {
         this.logger.success("Test run completed successfully");
-        exit();
+        process.exit();
       }
     });
-    (_a = env).NODE_ENV ?? (_a.NODE_ENV = "test");
+    (_a = process.env).NODE_ENV ?? (_a.NODE_ENV = "test");
     this.builder = new Build(ctx);
     if (isCI) {
       this.ctx.test.exitOnFinish = true;
@@ -2071,8 +2095,8 @@ class Test extends Base {
   }
   async startZoteroHeadless() {
     await installXvfb();
+    await installDepsForUbuntu24();
     await installZoteroLinux();
-    env.ZOTERO_PLUGIN_ZOTERO_BIN_PATH = `${cwd()}/Zotero_linux-x86_64/zotero`;
     const xvfb = new Xvfb({
       timeout: 2e3
     });
@@ -2098,9 +2122,9 @@ class Test extends Base {
     await this.runner.run();
   }
   get zoteroBinPath() {
-    if (!env.ZOTERO_PLUGIN_ZOTERO_BIN_PATH)
+    if (!process.env.ZOTERO_PLUGIN_ZOTERO_BIN_PATH)
       throw new Error("No Zotero Found.");
-    return env.ZOTERO_PLUGIN_ZOTERO_BIN_PATH;
+    return process.env.ZOTERO_PLUGIN_ZOTERO_BIN_PATH;
   }
   get profilePath() {
     return `.scaffold/test/profile`;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zotero-plugin-scaffold",
   "type": "module",
-  "version": "0.2.0-beta.10",
+  "version": "0.2.0-beta.12",
   "description": "A scaffold for Zotero plugin development.",
   "author": "northword",
   "license": "AGPL-3.0-or-later",
@@ -85,7 +85,8 @@
     "eslint": "^9.16.0",
     "eslint-plugin-format": "^0.1.3",
     "typescript": "^5.7.2",
-    "unbuild": "^2.0.0"
+    "unbuild": "^2.0.0",
+    "vitepress": "^1.5.0"
   },
   "scripts": {
     "dev": "unbuild --stub",
@@ -94,6 +95,9 @@
     "lint:fix": "eslint . --fix",
     "release": "bumpp --commit \"chore(release): publish v%s\"",
     "update:deps": "pnpx taze minor -w -f -l",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   }
 }