zotero-plugin-scaffold 0.2.0-beta.13 → 0.2.0-beta.15

package/dist/chunks/github.mjs

@@ -4,7 +4,7 @@ import process from 'node:process';
 import { Octokit } from 'octokit';
 import { globSync, glob } from 'tinyglobby';
 import { isCI } from 'std-env';
-import { B as Base } from '../shared/zotero-plugin-scaffold.CnLqPvW1.mjs';
+import { B as Base } from '../shared/zotero-plugin-scaffold.DQuI5OK-.mjs';
 import 'c12';
 import 'es-toolkit';
 import 'fs-extra/esm';
@@ -12,10 +12,10 @@ import 'hookable';
 import 'node:readline';
 import 'chalk';
 import '../shared/zotero-plugin-scaffold.v8dJZZ-v.mjs';
+import 'node:fs';
 import 'adm-zip';
 import 'esbuild';
 import 'node:crypto';
-import 'node:fs';
 import 'node:child_process';
 import 'bumpp';
 import 'chokidar';

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 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.CnLqPvW1.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.DQuI5OK-.mjs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { pathExists, ensureFile } from 'fs-extra';
 import tinyUpdateNotifier from 'tiny-update-notifier';
@@ -13,11 +13,11 @@ import 'chalk';
 import 'std-env';
 import './shared/zotero-plugin-scaffold.v8dJZZ-v.mjs';
 import 'tinyglobby';
+import 'node:fs';
 import 'node:path';
 import 'adm-zip';
 import 'esbuild';
 import 'node:crypto';
-import 'node:fs';
 import 'node:child_process';
 import 'bumpp';
 import 'chokidar';
@@ -30,8 +30,8 @@ import 'xvfb-ts';
 
 const name = "zotero-plugin-scaffold";
 const type = "module";
-const version = "0.2.0-beta.13";
-const packageManager = "pnpm@9.15.1";
+const version = "0.2.0-beta.15";
+const packageManager = "pnpm@9.15.2";
 const description = "A scaffold for Zotero plugin development.";
 const author = "northword";
 const license = "AGPL-3.0-or-later";
@@ -98,13 +98,13 @@ const peerDependenciesMeta = {
 	}
 };
 const dependencies = {
-	"@commander-js/extra-typings": "^12.1.0",
+	"@commander-js/extra-typings": "^13.0.0",
 	"adm-zip": "^0.5.16",
 	bumpp: "^9.9.2",
 	c12: "^2.0.1",
 	chalk: "^5.4.1",
 	chokidar: "^4.0.3",
-	commander: "^12.1.0",
+	commander: "^13.0.0",
 	"es-toolkit": "^1.31.0",
 	esbuild: "^0.24.2",
 	"fs-extra": "^11.2.0",

package/dist/index.d.mts

@@ -51,14 +51,9 @@ interface Manifest {
         zotero: {
             id: string;
             update_url: string;
-            strict_min_version: string;
+            strict_min_version?: string;
             strict_max_version?: string;
         };
-        gecko: {
-            id: string;
-            update_url: string;
-            strict_min_version: string;
-        };
     };
 }
 
@@ -81,7 +76,7 @@ interface UpdateJSON {
                 update_hash?: string;
                 applications: {
                     zotero: {
-                        strict_min_version: string;
+                        strict_min_version?: string;
                         strict_max_version?: string;
                     };
                     [application: string]: {
@@ -301,6 +296,40 @@ interface BuildConfig {
          */
         prefixFluentMessages: boolean;
     };
+    prefs: {
+        /**
+         * Prefixes the keys of preferences in `prefs.js` and
+         * the value of the `preference` attribute in XHTML files.
+         *
+         * 为 `prefs.js` 中的首选项键和 XHTML 文件中的 `preference` 属性的值
+         * 添加前缀。
+         *
+         * @default true
+         */
+        prefixPrefKeys: boolean;
+        /**
+         * Prefixes for Preference Keys, no dot at the end.
+         *
+         * 首选项键的前缀，结尾不需要加点号。
+         *
+         * @default 'extensions.${namespace}'
+         */
+        prefix: string;
+        /**
+         * Generate prefs.d.ts form prefs.js.
+         *
+         * - false: disable
+         * - string: path of dts file
+         *
+         * 为首选项生成类型声明文件。
+         *
+         * - false: 禁用
+         * - string：dts 文件路径
+         *
+         * @default 'typings/prefs.d.ts'
+         */
+        dts: false | string;
+    };
     /**
      * Configurations of esbuild.
      *
@@ -426,6 +455,8 @@ interface ServerConfig {
      * @default false
      */
     asProxy: boolean;
+    prebuild: boolean;
+    createProfileIfMissing: boolean;
     /**
      * The lifecycle hook.
      */
@@ -726,6 +757,7 @@ interface Hooks extends BuildHooks, ServeHooks, ReleaseHooks, TestHooks {
 type RecursivePartial<T> = {
     [P in keyof T]?: T[P] extends object ? RecursivePartial<T[P]> : T[P];
 };
+
 /**
  * User config
  */
@@ -789,6 +821,7 @@ declare class Build extends Base {
      */
     makeManifest(): Promise<void>;
     prepareLocaleFiles(): Promise<void>;
+    preparePrefs(): Promise<void>;
     esbuild(): Promise<esbuild.BuildResult<esbuild.BuildOptions>[]> | undefined;
     makeUpdateJson(): Promise<void>;
     pack(): Promise<void>;
@@ -816,7 +849,6 @@ declare class Serve extends Base {
     private builder;
     private runner?;
     private _zoteroBinPath?;
-    private _profilePath?;
     constructor(ctx: Context);
     run(): Promise<void>;
     /**
@@ -828,8 +860,8 @@ declare class Serve extends Base {
     exit: () => never;
     private onZoteroExit;
     get zoteroBinPath(): string;
-    get profilePath(): string;
-    get dataDir(): string;
+    get profilePath(): string | undefined;
+    get dataDir(): string | undefined;
 }
 
 declare class Test extends Base {

package/dist/index.d.ts

@@ -51,14 +51,9 @@ interface Manifest {
         zotero: {
             id: string;
             update_url: string;
-            strict_min_version: string;
+            strict_min_version?: string;
             strict_max_version?: string;
         };
-        gecko: {
-            id: string;
-            update_url: string;
-            strict_min_version: string;
-        };
     };
 }
 
@@ -81,7 +76,7 @@ interface UpdateJSON {
                 update_hash?: string;
                 applications: {
                     zotero: {
-                        strict_min_version: string;
+                        strict_min_version?: string;
                         strict_max_version?: string;
                     };
                     [application: string]: {
@@ -301,6 +296,40 @@ interface BuildConfig {
          */
         prefixFluentMessages: boolean;
     };
+    prefs: {
+        /**
+         * Prefixes the keys of preferences in `prefs.js` and
+         * the value of the `preference` attribute in XHTML files.
+         *
+         * 为 `prefs.js` 中的首选项键和 XHTML 文件中的 `preference` 属性的值
+         * 添加前缀。
+         *
+         * @default true
+         */
+        prefixPrefKeys: boolean;
+        /**
+         * Prefixes for Preference Keys, no dot at the end.
+         *
+         * 首选项键的前缀，结尾不需要加点号。
+         *
+         * @default 'extensions.${namespace}'
+         */
+        prefix: string;
+        /**
+         * Generate prefs.d.ts form prefs.js.
+         *
+         * - false: disable
+         * - string: path of dts file
+         *
+         * 为首选项生成类型声明文件。
+         *
+         * - false: 禁用
+         * - string：dts 文件路径
+         *
+         * @default 'typings/prefs.d.ts'
+         */
+        dts: false | string;
+    };
     /**
      * Configurations of esbuild.
      *
@@ -426,6 +455,8 @@ interface ServerConfig {
      * @default false
      */
     asProxy: boolean;
+    prebuild: boolean;
+    createProfileIfMissing: boolean;
     /**
      * The lifecycle hook.
      */
@@ -726,6 +757,7 @@ interface Hooks extends BuildHooks, ServeHooks, ReleaseHooks, TestHooks {
 type RecursivePartial<T> = {
     [P in keyof T]?: T[P] extends object ? RecursivePartial<T[P]> : T[P];
 };
+
 /**
  * User config
  */
@@ -789,6 +821,7 @@ declare class Build extends Base {
      */
     makeManifest(): Promise<void>;
     prepareLocaleFiles(): Promise<void>;
+    preparePrefs(): Promise<void>;
     esbuild(): Promise<esbuild.BuildResult<esbuild.BuildOptions>[]> | undefined;
     makeUpdateJson(): Promise<void>;
     pack(): Promise<void>;
@@ -816,7 +849,6 @@ declare class Serve extends Base {
     private builder;
     private runner?;
     private _zoteroBinPath?;
-    private _profilePath?;
     constructor(ctx: Context);
     run(): Promise<void>;
     /**
@@ -828,8 +860,8 @@ declare class Serve extends Base {
     exit: () => never;
     private onZoteroExit;
     get zoteroBinPath(): string;
-    get profilePath(): string;
-    get dataDir(): string;
+    get profilePath(): string | undefined;
+    get dataDir(): string | undefined;
 }
 
 declare class Test extends Base {

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.CnLqPvW1.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.DQuI5OK-.mjs';
 import 'c12';
 import 'es-toolkit';
 import 'fs-extra/esm';
@@ -10,11 +10,11 @@ import 'std-env';
 import './shared/zotero-plugin-scaffold.v8dJZZ-v.mjs';
 import 'node:fs/promises';
 import 'tinyglobby';
+import 'node:fs';
 import 'node:path';
 import 'adm-zip';
 import 'esbuild';
 import 'node:crypto';
-import 'node:fs';
 import 'node:child_process';
 import 'bumpp';
 import 'chokidar';

package/dist/shared/{zotero-plugin-scaffold.CnLqPvW1.mjs → zotero-plugin-scaffold.DQuI5OK-.mjs}

@@ -1,19 +1,19 @@
 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 { isPlainObject, kebabCase, mapValues, isNotNil, toMerged, escapeRegExp, delay, debounce } from 'es-toolkit';
+import { readJsonSync, outputFile, emptyDir, copy, readJSON, outputJSON, move, writeJson, pathExists, ensureDir, remove } from 'fs-extra/esm';
 import { createHooks } from 'hookable';
 import process from 'node:process';
 import readline from 'node:readline';
 import chalk from 'chalk';
 import { isDebug, isCI, isWindows, isMacOS, isLinux } from 'std-env';
 import { p as parseRepoUrl, d as dateFormat, t as template, b as toArray, a as replaceInFile } from './zotero-plugin-scaffold.v8dJZZ-v.mjs';
+import { createReadStream, existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { basename, dirname, join, resolve } from 'node:path';
 import AdmZip from 'adm-zip';
 import { build } from 'esbuild';
 import { glob } from 'tinyglobby';
 import { createHash } from 'node:crypto';
-import { createReadStream, existsSync } from 'node:fs';
 import { execSync, spawn } from 'node:child_process';
 import { versionBump, ProgressEvent } from 'bumpp';
 import chokidar from 'chokidar';
@@ -146,6 +146,7 @@ function resolveConfig(config) {
   config.id ||= config.name;
   config.namespace ||= config.name;
   config.xpiName ||= kebabCase(config.name);
+  config.build.prefs.prefix ||= `extensions.${config.namespace}`;
   const isPreRelease = version.includes("-");
   const templateData = {
     owner,
@@ -192,31 +193,22 @@ const defaultConfig = {
       prefixFluentMessages: true,
       prefixLocaleFiles: true
     },
+    prefs: {
+      prefix: "",
+      prefixPrefKeys: true,
+      dts: "typings/prefs.d.ts"
+    },
     esbuildOptions: [],
     makeManifest: {
       enable: true,
       template: {
         manifest_version: 2,
-        name: "__addonName__",
-        version: "__buildVersion__",
-        description: "__description__",
-        homepage_url: "__homepage__",
-        author: "__author__",
-        icons: {
-          48: "content/icons/favicon@0.5x.png",
-          96: "content/icons/favicon.png"
-        },
+        name: "",
+        version: "",
         applications: {
           zotero: {
-            id: "__addonID__",
-            update_url: "__updateURL__",
-            strict_min_version: "6.999",
-            strict_max_version: "7.0.*"
-          },
-          gecko: {
-            id: "__addonID__",
-            update_url: "__updateURL__",
-            strict_min_version: "102"
+            id: "",
+            update_url: ""
           }
         }
       }
@@ -231,6 +223,9 @@ const defaultConfig = {
     devtools: true,
     startArgs: [],
     asProxy: false,
+    prebuild: true,
+    // keepProfileChanges: true,
+    createProfileIfMissing: true,
     hooks: {}
   },
   addonLint: {},
@@ -301,6 +296,109 @@ function generateHash(filePath, algorithm) {
   });
 }
 
+class PrefsManager {
+  namespace;
+  prefs = {};
+  constructor(namespace) {
+    this.namespace = namespace;
+  }
+  parse(content) {
+    const prefPattern = /^(pref|user_pref)\s*\(\s*["']([^"']+)["']\s*,\s*(.+)\s*\)\s*;$/gm;
+    const matches = content.matchAll(prefPattern);
+    for (const match of matches) {
+      const key = match[2].trim();
+      const value = match[3].trim();
+      this.prefs[key] = value;
+    }
+  }
+  render() {
+    return Object.entries(this.prefs).map(([key, value]) => {
+      if (!isNotNil(value))
+        return "";
+      let cleanValue = "";
+      if (typeof value === "boolean") {
+        cleanValue = `${value}`;
+      } else if (typeof value === "string") {
+        cleanValue = value;
+      } else if (typeof value === "number") {
+        cleanValue = value.toString();
+      }
+      return `${this.namespace}("${key}", ${cleanValue});`;
+    }).filter((c) => !!c).join("\n");
+  }
+  async read(path) {
+    const content = await readFile(path, "utf-8");
+    this.parse(content);
+  }
+  async write(path) {
+    const content = this.render();
+    await outputFile(path, content, "utf-8");
+    logger.debug("The <profile>/prefs.js has been modified.");
+  }
+  setPref(key, value) {
+    this.prefs[key] = value;
+  }
+  setPrefs(prefs) {
+    Object.entries(prefs).forEach(([key, value]) => {
+      this.setPref(key, value);
+    });
+  }
+  getPref(key) {
+    return this.prefs[key] ?? void 0;
+  }
+  getPrefs() {
+    return this.prefs;
+  }
+  clearPrefs() {
+    this.prefs = {};
+  }
+  getPrefsWithPrefix(prefix) {
+    const _prefs = {};
+    for (const pref in this.prefs) {
+      if (pref.startsWith(prefix))
+        _prefs[pref] = this.prefs[pref];
+      else
+        _prefs[`${prefix}.${pref}`] = this.prefs[pref];
+    }
+    return _prefs;
+  }
+  getPrefsWithoutPrefix(prefix) {
+    const _prefs = {};
+    for (const pref in this.prefs) {
+      _prefs[pref.replace(`${prefix}.`, "")] = this.prefs[pref];
+    }
+    return _prefs;
+  }
+}
+function renderPluginPrefsDts(prefs, prefix) {
+  const dtsContent = `
+/* prettier-ignore */
+/* eslint-disable */
+// @ts-nocheck
+// Generated by zotero-plugin-scaffold
+
+type _PluginPrefsMap = {
+  ${Object.entries(prefs).map(([key, value]) => {
+    return `"${key}": ${typeof value};`;
+  }).join("\n  ")}
+};
+
+type PluginPrefKey<K extends keyof _PluginPrefsMap> = \`${prefix}.\${K}\`;
+
+type PluginPrefsMap = {
+  [K in keyof _PluginPrefsMap as PluginPrefKey<K>]: _PluginPrefsMap[K]
+};
+
+declare namespace _ZoteroTypes {
+  interface Prefs {
+    get: <K extends keyof PluginPrefsMap>(key: K, global?: boolean) => PluginPrefsMap[K];
+    set: <K extends keyof PluginPrefsMap>(key: K, value: PluginPrefsMap[K], global?: boolean) => any;
+  }
+}
+`;
+  return dtsContent;
+}
+
 class Base {
   ctx;
   constructor(ctx) {
@@ -342,6 +440,7 @@ class Build extends Base {
     this.logger.debug("Preparing locale files");
     await this.prepareLocaleFiles();
     await this.ctx.hooks.callHook("build:fluent", this.ctx);
+    await this.preparePrefs();
     this.logger.tip("Bundling scripts");
     await this.esbuild();
     await this.ctx.hooks.callHook("build:bundle", this.ctx);
@@ -400,7 +499,6 @@ class Build extends Base {
       ...version && { version },
       manifest_version: 2,
       applications: {
-        // @ts-expect-error 此处不包含版本限制
         zotero: {
           id,
           update_url: updateURL
@@ -472,6 +570,48 @@ class Build extends Base {
       }
     });
   }
+  async preparePrefs() {
+    const { dts, prefixPrefKeys, prefix } = this.ctx.build.prefs;
+    const { dist } = this.ctx;
+    if (!prefixPrefKeys && !dts)
+      return;
+    const prefsFilePath = join(dist, "addon", "prefs.js");
+    if (!existsSync(prefsFilePath))
+      return;
+    const prefsManager = new PrefsManager("pref");
+    await prefsManager.read(prefsFilePath);
+    const prefsWithPrefix = prefsManager.getPrefsWithPrefix(prefix);
+    const prefsWithoutPrefix = prefsManager.getPrefsWithoutPrefix(prefix);
+    if (dts) {
+      const dtsContent = renderPluginPrefsDts(prefsWithoutPrefix, prefix);
+      await outputFile(dts, dtsContent, "utf-8");
+    }
+    if (prefixPrefKeys) {
+      prefsManager.clearPrefs();
+      prefsManager.setPrefs(prefsWithPrefix);
+      await prefsManager.write(prefsFilePath);
+    }
+    if (prefixPrefKeys) {
+      const HTML_PREFERENCE_PATTERN = new RegExp(`preference="((?!${prefix})\\S*)"`, "g");
+      const xhtmlPaths = await glob(`${dist}/addon/**/*.xhtml`);
+      await Promise.all(xhtmlPaths.map(async (path) => {
+        let content = await readFile(path, "utf-8");
+        const matchs = [...content.matchAll(HTML_PREFERENCE_PATTERN)];
+        for (const match of matchs) {
+          const [matched, key] = match;
+          if (!prefsWithoutPrefix[key] && !prefsWithoutPrefix[key]) {
+            this.logger.warn(`preference key '${key}' in ${path} not init in prefs.js`);
+            continue;
+          }
+          if (key.startsWith(prefix))
+            continue;
+          else
+            content = content.replace(matched, `preference="${prefix}.${key}"`);
+        }
+        await outputFile(path, content, "utf-8");
+      }));
+    }
+  }
   esbuild() {
     const { build: { esbuildOptions } } = this.ctx;
     if (esbuildOptions.length === 0)
@@ -503,7 +643,7 @@ class Build extends Base {
               },
               applications: {
                 zotero: {
-                  strict_min_version: min,
+                  ...min && { strict_min_version: min },
                   ...max && { strict_max_version: max }
                 }
               }
@@ -1176,18 +1316,43 @@ function findFreeTcpPort() {
   });
 }
 
+const default_options = {
+  binary: {
+    // path: "",
+    args: [],
+    devtools: true
+  },
+  profile: {
+    path: "./.scaffold/profile",
+    dataDir: "",
+    // keepChanges: true,
+    createIfMissing: true,
+    customPrefs: {}
+  },
+  plugins: {
+    asProxy: false,
+    list: []
+  }
+};
 class ZoteroRunner {
   options;
-  remoteFirefox;
+  remoteFirefox = new RemoteFirefox();
   zotero;
   constructor(options) {
-    this.options = options;
-    this.remoteFirefox = new RemoteFirefox();
+    this.options = toMerged(default_options, options);
+    if (!options.binary.path)
+      throw new Error("Binary path must be provided.");
+    if (!options.profile.path && !options.profile.dataDir)
+      this.options.profile.dataDir = "./.scaffold/data";
+    logger.debug(this.options);
+  }
+  get default_profile_path() {
+    return default_options.profile.path;
   }
   async run() {
-    await this.setupProfileDir();
+    await this.setupProfile();
     await this.startZoteroInstance();
-    if (!this.options.asProxy)
+    if (!this.options.plugins.asProxy)
       await this.installTemporaryPlugins();
   }
   /**
@@ -1197,45 +1362,51 @@ class ZoteroRunner {
    *
    * @see https://www.zotero.org/support/dev/client_coding/plugin_development#setting_up_a_plugin_development_environment
    */
-  async setupProfileDir() {
-    if (!this.options.profilePath) ;
-    const defaultPrefs = Object.entries(prefs).map(([key, value]) => {
-      return `user_pref("${key}", ${JSON.stringify(value)});`;
-    });
-    const customPrefs = Object.entries(this.options.customPrefs || []).map(([key, value]) => {
-      return `user_pref("${key}", ${JSON.stringify(value)});`;
-    });
-    let exsitedPrefs = [];
-    const prefsPath = join(this.options.profilePath, "prefs.js");
-    if (await pathExists(prefsPath)) {
-      const PrefsLines = (await readFile(prefsPath, "utf-8")).split("\n");
-      exsitedPrefs = PrefsLines.map((line) => {
-        if (line.includes("extensions.lastAppBuildId") || line.includes("extensions.lastAppVersion")) {
-          return "";
-        }
-        return line;
-      });
+  async setupProfile() {
+    const { path, createIfMissing } = this.options.profile;
+    if (!await pathExists(path)) {
+      if (createIfMissing)
+        await this.createProfile(this.default_profile_path);
+      else
+        throw new Error("The 'profile.path' must be provided when 'createIfMissing' is false.");
     }
-    const updatedPrefs = [...defaultPrefs, ...exsitedPrefs, ...customPrefs].join("\n");
-    await outputFile(prefsPath, updatedPrefs, "utf-8");
-    logger.debug("The <profile>/prefs.js has been modified.");
-    if (this.options.asProxy) {
+    const prefsPath = join(this.options.profile.path, "prefs.js");
+    const prefsManager = new PrefsManager("user_pref");
+    prefsManager.setPrefs(prefs);
+    prefsManager.setPrefs(this.options.profile.customPrefs);
+    if (await pathExists(prefsPath))
+      await prefsManager.read(prefsPath);
+    prefsManager.setPrefs({
+      "extensions.lastAppBuildId": null,
+      "extensions.lastAppVersion": null
+    });
+    await prefsManager.write(prefsPath);
+    if (this.options.plugins.asProxy) {
       await this.installProxyPlugins();
     }
   }
+  async createProfile(path) {
+    logger.debug(`Creating profile at ${this.default_profile_path}...`);
+    await ensureDir(path);
+  }
+  // private async copyProfile(from: string, to = this.default_profile_path) {
+  //   logger.debug(`Copying profile from '${this.options.profile.path}' to ${this.default_profile_path}...`);
+  //   await copy(from, to);
+  //   this.options.profile.path = to;
+  // }
   async startZoteroInstance() {
     let args = ["--purgecaches", "no-remote"];
-    if (this.options.profilePath) {
-      args.push("-profile", resolve(this.options.profilePath));
+    if (this.options.profile.path) {
+      args.push("-profile", resolve(this.options.profile.path));
     }
-    if (this.options.dataDir) {
-      args.push("--dataDir", resolve(this.options.dataDir));
+    if (this.options.profile.dataDir) {
+      args.push("--dataDir", resolve(this.options.profile.dataDir));
     }
-    if (this.options.devtools) {
+    if (this.options.binary.devtools) {
       args.push("--jsdebugger");
     }
-    if (this.options.binaryArgs) {
-      args = [...args, ...this.options.binaryArgs];
+    if (this.options.binary.args) {
+      args = [...args, ...this.options.binary.args];
     }
     const remotePort = await findFreeTcpPort();
     args.push("-start-debugger-server", String(remotePort));
@@ -1245,7 +1416,9 @@ class ZoteroRunner {
       XPCOM_DEBUG_BREAK: "stack",
       NS_TRACE_MALLOC_DISABLE_STACKS: "1"
     };
-    this.zotero = spawn(this.options.binaryPath, args, { env });
+    if (!await pathExists(this.options.binary.path))
+      throw new Error("The Zotero binary not found.");
+    this.zotero = spawn(this.options.binary.path, args, { env });
     logger.debug("Zotero started, pid:", this.zotero.pid);
     this.zotero.stdout?.on("data", (_data) => {
     });
@@ -1254,7 +1427,7 @@ class ZoteroRunner {
     logger.debug(`Connected to the remote Firefox debugger on port: ${remotePort}`);
   }
   async installTemporaryPlugins() {
-    for (const plugin of this.options.plugins) {
+    for (const plugin of this.options.plugins.list) {
       const addonId = await this.remoteFirefox.installTemporaryAddon(resolve(plugin.sourceDir)).then((installResult) => {
         return installResult.addon.id;
       });
@@ -1264,7 +1437,7 @@ class ZoteroRunner {
     }
   }
   async installProxyPlugin(id, sourceDir) {
-    const addonProxyFilePath = join(this.options.profilePath, `extensions/${id}`);
+    const addonProxyFilePath = join(this.options.profile.path, `extensions/${id}`);
     const buildPath = resolve(sourceDir);
     await outputFile(addonProxyFilePath, buildPath);
     logger.debug(
@@ -1274,12 +1447,12 @@ class ZoteroRunner {
         `  Addon path: ${buildPath}`
       ].join("\n")
     );
-    const addonXpiFilePath = join(this.options.profilePath, `extensions/${id}.xpi`);
+    const addonXpiFilePath = join(this.options.profile.path, `extensions/${id}.xpi`);
     if (await pathExists(addonXpiFilePath)) {
       await remove(addonXpiFilePath);
       logger.debug(`XPI file found, removed.`);
     }
-    const addonInfoFilePath = join(this.options.profilePath, "extensions.json");
+    const addonInfoFilePath = join(this.options.profile.path, "extensions.json");
     if (await pathExists(addonInfoFilePath)) {
       const content = await readJSON(addonInfoFilePath);
       content.addons = content.addons.map((addon) => {
@@ -1294,7 +1467,7 @@ class ZoteroRunner {
     }
   }
   async installProxyPlugins() {
-    for (const { id, sourceDir } of this.options.plugins) {
+    for (const { id, sourceDir } of this.options.plugins.list) {
       await this.installProxyPlugin(id, sourceDir);
     }
   }
@@ -1302,7 +1475,7 @@ class ZoteroRunner {
     await this.remoteFirefox.reloadAddon(id);
   }
   async reloadTemporaryPluginBySourceDir(sourceDir) {
-    const addonId = this.options.plugins.find((p) => p.sourceDir === sourceDir)?.id;
+    const addonId = this.options.plugins.list.find((p) => p.sourceDir === sourceDir)?.id;
     if (!addonId) {
       return {
         sourceDir,
@@ -1322,7 +1495,7 @@ class ZoteroRunner {
     return { sourceDir, reloadError: void 0 };
   }
   async reloadAllTemporaryPlugins() {
-    for (const { sourceDir } of this.options.plugins) {
+    for (const { sourceDir } of this.options.plugins.list) {
       const res = await this.reloadTemporaryPluginBySourceDir(sourceDir);
       if (res.reloadError instanceof Error) {
         logger.error(res.reloadError);
@@ -1349,20 +1522,20 @@ class ZoteroRunner {
     const url = `zotero://ztoolkit-debug/?run=${encodeURIComponent(
       reloadScript
     )}`;
-    const startZoteroCmd = `"${this.options.binaryPath}" --purgecaches -profile "${this.options.profilePath}"`;
+    const startZoteroCmd = `"${this.options.binary.path}" --purgecaches -profile "${this.options.profile.path}"`;
     const command = `${startZoteroCmd} -url "${url}"`;
     execSync(command);
   }
   // Do not use this method if possible,
   // as frequent execSync can cause Zotero to crash.
   async reloadAllProxyPlugins() {
-    for (const { id } of this.options.plugins) {
+    for (const { id } of this.options.plugins.list) {
       await this.reloadProxyPluginByZToolkit(id, id, id);
       await delay(2e3);
     }
   }
   async reloadAllPlugins() {
-    if (this.options.asProxy)
+    if (this.options.plugins.asProxy)
       await this.reloadAllProxyPlugins();
     else
       await this.reloadAllTemporaryPlugins();
@@ -1401,7 +1574,6 @@ class Serve extends Base {
   builder;
   runner;
   _zoteroBinPath;
-  _profilePath;
   constructor(ctx) {
     super(ctx);
     process.env.NODE_ENV ??= "development";
@@ -1410,20 +1582,30 @@ class Serve extends Base {
   async run() {
     process.on("SIGINT", this.exit);
     this.runner = new ZoteroRunner({
-      binaryPath: this.zoteroBinPath,
-      profilePath: this.profilePath,
-      dataDir: this.dataDir,
-      plugins: [{
-        id: this.ctx.id,
-        sourceDir: join(this.ctx.dist, "addon")
-      }],
-      asProxy: this.ctx.server.asProxy,
-      devtools: this.ctx.server.devtools,
-      binaryArgs: this.ctx.server.startArgs
+      binary: {
+        path: this.zoteroBinPath,
+        devtools: this.ctx.server.devtools,
+        args: this.ctx.server.startArgs
+      },
+      profile: {
+        path: this.profilePath,
+        dataDir: this.dataDir,
+        // keepChanges: this.ctx.server.keepProfileChanges,
+        createIfMissing: this.ctx.server.createProfileIfMissing
+      },
+      plugins: {
+        list: [{
+          id: this.ctx.id,
+          sourceDir: join(this.ctx.dist, "addon")
+        }],
+        asProxy: this.ctx.server.asProxy
+      }
     });
     await this.ctx.hooks.callHook("serve:init", this.ctx);
-    await this.builder.run();
-    await this.ctx.hooks.callHook("serve:prebuild", this.ctx);
+    if (this.ctx.server.prebuild) {
+      await this.builder.run();
+      await this.ctx.hooks.callHook("serve:prebuild", this.ctx);
+    }
     await this.runner.run();
     this.runner.zotero?.on("exit", this.onZoteroExit);
     this.runner.zotero?.on("close", this.onZoteroExit);
@@ -1490,15 +1672,10 @@ class Serve extends Base {
     return this._zoteroBinPath;
   }
   get profilePath() {
-    if (this._profilePath)
-      return this._profilePath;
-    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;
+    return process.env.ZOTERO_PLUGIN_PROFILE_PATH;
   }
   get dataDir() {
-    return process.env.ZOTERO_PLUGIN_DATA_DIR ?? "";
+    return process.env.ZOTERO_PLUGIN_DATA_DIR;
   }
 }
 
@@ -2036,19 +2213,25 @@ class Test extends Base {
   }
   async startZotero() {
     this.runner = new ZoteroRunner({
-      binaryPath: this.zoteroBinPath,
-      profilePath: this.profilePath,
-      dataDir: this.dataDir,
-      plugins: [{
-        id: this.ctx.id,
-        sourceDir: join(this.ctx.dist, "addon")
-      }, {
-        id: this.testPluginID,
-        sourceDir: this.testPluginDir
-      }],
-      devtools: this.ctx.server.devtools,
-      binaryArgs: this.ctx.server.startArgs,
-      customPrefs: this.prefs
+      binary: {
+        path: this.zoteroBinPath,
+        devtools: this.ctx.server.devtools,
+        args: this.ctx.server.startArgs
+      },
+      profile: {
+        path: this.profilePath,
+        dataDir: this.dataDir,
+        customPrefs: this.prefs
+      },
+      plugins: {
+        list: [{
+          id: this.ctx.id,
+          sourceDir: join(this.ctx.dist, "addon")
+        }, {
+          id: this.testPluginID,
+          sourceDir: this.testPluginDir
+        }]
+      }
     });
     await this.runner.run();
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zotero-plugin-scaffold",
   "type": "module",
-  "version": "0.2.0-beta.13",
+  "version": "0.2.0-beta.15",
   "description": "A scaffold for Zotero plugin development.",
   "author": "northword",
   "license": "AGPL-3.0-or-later",
@@ -63,13 +63,13 @@
     }
   },
   "dependencies": {
-    "@commander-js/extra-typings": "^12.1.0",
+    "@commander-js/extra-typings": "^13.0.0",
     "adm-zip": "^0.5.16",
     "bumpp": "^9.9.2",
     "c12": "^2.0.1",
     "chalk": "^5.4.1",
     "chokidar": "^4.0.3",
-    "commander": "^12.1.0",
+    "commander": "^13.0.0",
     "es-toolkit": "^1.31.0",
     "esbuild": "^0.24.2",
     "fs-extra": "^11.2.0",