zotero-plugin-scaffold 0.1.0-beta.2 → 0.1.0

package/README.md

@@ -1,14 +1,23 @@
 # Zotero Plugin Development Scaffold
 
-Working in progress.
+[![NPM Version](https://img.shields.io/npm/v/zotero-plugin-scaffold)](https://www.npmjs.com/package/zotero-plugin-scaffold)
+[![NPM Downloads](https://img.shields.io/npm/dm/zotero-plugin-scaffold)](https://www.npmjs.com/package/zotero-plugin-scaffold)
+![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/zotero-plugin-scaffold)
+![GitHub License](https://img.shields.io/github/license/northword/zotero-plugin-scaffold)
 
-Create a standalone npm package for scripts in the zotero-plugin-template repository, so that downstream developers can follow along.
+This is an npm package designed to assist in the development of Zotero plugins. It provides features such as compiling plugins, starting Zotero and installing plugins from source code, reloading plugins when the source code changes, and releasing plugins, and so on.
 
-This repository serves only as a proof-of-concept for the above.
+Initially, the code of this package was part of the [zotero-plugin-template](https://github.com/windingwind/zotero-plugin-template) repository. To allow downstream developers to easily stay up-to-date, we have abstracted these scripts into a standalone npm package.
+
+This project is under active development, and some APIs may change. However, it is ready for production and has been [used in several projects](https://github.com/northword/zotero-plugin-scaffold/network/dependents).
+
+For best practices regarding this package, please refer to [zotero-plugin-template](https://github.com/windingwind/zotero-plugin-template).
 
 ## Using in a blank project
 
-> WIP: Not yet implemented
+<details>
+
+<summary>WIP: Not yet implemented</summary>
 
 ```bash
 # npm
@@ -17,6 +26,8 @@ npx zotero-plugin create
 pnpm dlx zotero-plugin create
 ```
 
+</details>
+
 ## Using in an existing project
 
 ### 01. Install
@@ -49,28 +60,25 @@ pnpm link ../zotero-plugin-scaffold
 
 ### 02. Create a config file
 
-The configuration file needs to be stored in the following location. If the configuration file is not found, an error will be thrown.
+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 `defineConfig` in js module to get type hints. If no value is specified for an optional property, the default value will be used.
+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: pkg.config.addonName,
-  id: pkg.config.addonID,
-  namespace: pkg.config.addonRef,
+  name: "the plugin name",
+  id: "the plugin id",
+  namespace: "the plugin namespace",
   build: {
     esbuildOptions: [
       {
         entryPoints: ["src/index.ts"],
-        define: {
-          __env__: `"${process.env.NODE_ENV}"`,
-        },
         bundle: true,
         target: "firefox115",
       },
@@ -93,8 +101,7 @@ NOTE: Do not check-in this file to the repository!
 
 ```ini
 # The path of the Zotero binary file.
-# The path delimiter should be escaped as `\\` for win32.
-# The path is `*/Zotero.app/Contents/MacOS/zotero` for MacOS.
+# 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.
@@ -144,13 +151,14 @@ cd zotero-plugin-scaffold/
 pnpm install
 
 # Development Mode
-# This command creates a js runtime using jiti, and the modified code does not need to be built again.
+# This command creates a typescript runtime using jiti,
+# and the modified code does not need to be built again.
 pnpm run dev
 
 # Build
 pnpm run build
 
-# Lint and Prettier
+# ES Lint
 pnpm run lint:fix
 ```
 

package/dist/cli.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { exit, env } from 'node:process';
-import { Command } from 'commander';
+import { Command } from '@commander-js/extra-typings';
 import updateNotifier from 'update-notifier';
-import { L as Log, C as Config, B as Build, S as Serve, R as Release } from './shared/zotero-plugin-scaffold.125bc4ce.mjs';
+import { L as Log, C as Config, B as Build, S as Serve, R as Release } from './shared/zotero-plugin-scaffold.06668c10.mjs';
 import 'node:path';
 import 'c12';
 import 'fs-extra';
@@ -25,7 +25,7 @@ import 'chokidar';
 import 'node:fs';
 
 const name = "zotero-plugin-scaffold";
-const version = "0.1.0-beta.2";
+const version = "0.1.0";
 
 const logger = new Log();
 async function main() {
@@ -34,35 +34,38 @@ async function main() {
   (_a = 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(async (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";
-    const config = await Config.loadConfig({
+    Config.loadConfig({
       dist: options.dist
-    });
-    new Build(config).run();
+    }).then((ctx) => new Build(ctx).run());
   });
-  cli.command("serve").description("Start development server.").action(async (_options) => {
-    const config = await Config.loadConfig({});
-    new Serve(config).run();
+  cli.command("serve").alias("dev").description("Start development server").action((_options) => {
+    Config.loadConfig({}).then((ctx) => new Serve(ctx).run());
   });
-  cli.command("create").description("Create the plugin template.").action((_options) => {
+  cli.command("create").description("Create the plugin template").action((_options) => {
     logger.error("The create not yet implemented");
   });
-  cli.command("release").description("Release.").action(async (_options) => {
+  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";
-    const config = await Config.loadConfig({});
-    new Release(config).run();
+    Config.loadConfig({
+      release: {
+        bumpp: {
+          release: version2,
+          preid: options.preid,
+          confirm: !options.yes
+        }
+      }
+    }).then((ctx) => new Release(ctx).run());
   });
   cli.arguments("<command>").action((cmd) => {
     cli.outputHelp();
-    logger.error(`Unknown command name=${cmd}.`);
+    logger.error(`Unknown command name "${cmd}".`);
   });
   cli.parse();
 }
 main().catch((err) => {
-  logger.newLine();
   logger.error(err);
-  logger.newLine();
   exit(1);
 });
 

package/dist/index.d.mts

@@ -106,67 +106,97 @@ interface Config$1 {
      */
     dist: string;
     /**
-     * The name of plugin
+     * The name of plugin.
      *
-     * 插件名
+     * 插件名。
      *
      * @default package-json.name
      *
      */
     name: string;
     /**
-     * The ID of plugin
+     * The ID of plugin.
      *
-     * 插件 ID
+     * Usually in the form of an email address or UUID.
+     *
+     * 插件 ID。
+     *
+     * 通常是邮箱地址或UUID的形式。
      *
      * @default package-json.name
      */
     id: string;
     /**
-     * namespace of plugin
+     * namespace of plugin.
+     *
+     * This attribute is also used to prevent plugin conflicts,
+     * it may be used for plugin HTML element ids, preference prefixes,
+     * fluent filename prefixes, fluent message prefixes, etc.
+     *
+     * Unlike the plugin id, this value should be HTML ID and Fluent Message compliant,
+     * i.e.: contain at least one character and only letters and dashes.
      *
-     * 插件命名空间
+     * 插件命名空间。
+     *
+     * 这个属性也用于防止插件冲突，它可能被用于插件的 HTML 元素 id，
+     * 首选项前缀，Fluent 文件名前缀、Fluent message 前缀等。
+     *
+     * 与插件 ID 不同的是，这个值应是符合 HTML ID 和 Fluent Message 规范的，
+     * 即：至少包含一个字符，仅包含字母和短横线。
      *
      * @default kebabCase(name)
      */
     namespace: string;
     /**
-     * XPI filename
+     * XPI filename.
+     *
+     * XPI 文件名。
      *
      * @default kebabCase(name)
      */
     xpiName: string;
     /**
-     * XPI 文件的地址
+     * The download link of XPI.
+     *
+     * XPI 文件的地址。
      *
      * @default `https://github.com/{{owner}}/{{repo}}/release/download/v{{version}}/{{xpiName}}.xpi`
      */
     xpiDownloadLink: string;
     /**
-     * update.json 文件的地址
+     * The uri of update.json.
+     *
+     * update.json 文件的地址。
      *
      * @default `https://github.com/{{owner}}/{{repo}}/release/download/release/update.json`
      */
     updateURL: string;
     /**
-     * 构建所需的配置
+     * Configurations required to run the build.
+     *
+     * 构建所需的配置。
      */
     build: BuildConfig;
     /**
-     * serve 所需的配置
+     * Configurations required to run the server.
+     *
+     * serve 所需的配置。
      */
     server: ServerConfig;
     /**
-     * @todo Use addonLint package to lint XPI
+     * @todo Use addonLint package to lint XPI.
      */
     addonLint: object;
     /**
-     * 发布相关配置
+     * Configurations required to run the release.
      *
+     * 发布相关配置。
      */
     release: ReleaseConfig;
     /**
-     * Log level
+     * Level of the log.
+     *
+     * 日志等级。
      *
      * @default "info"
      */
@@ -174,7 +204,11 @@ interface Config$1 {
 }
 interface BuildConfig {
     /**
-     * glob list of static assets
+     * The static assets.
+     *
+     * - Typically includes icons, ftl files, 3rd party JavaScript files, CSS files, XHTML files, etc.
+     * - is an array of `glob` modes and supports negation modes.
+     * - Do not add an entire directory unless it has no files to exclude.
      *
      * 静态资源文件。
      *
@@ -190,7 +224,10 @@ interface BuildConfig {
      */
     assets: string | string[];
     /**
-     * placeholders to replace in static assets
+     * The placeholders to replace in static assets.
+     *
+     * - At build time, scaffolding uses the key of the placeholder to build the regular pattern `/__${key}__/g` and replaces matches with `value`.
+     * - Replacement happens for all files under `assets`.
      *
      * 静态资源文本占位符。
      *
@@ -202,45 +239,53 @@ interface BuildConfig {
     };
     fluent: {
         /**
-         * 为所有 FTL 文件添加插件前缀以避免冲突
+         * Add plugin namespace prefixes to all FTL files to avoid conflicts.
          *
-         * 默认前缀为 `${namespace}-`
+         * The default prefix is `${namespace}-`.
+         *
+         * 为所有 FTL 文件添加插件前缀以避免冲突。
+         *
+         * 默认前缀为 `${namespace}-`。
          *
          * @default true
          */
         prefixLocaleFiles: boolean;
         /**
-         * 为所有 FTL message 添加插件前缀以避免冲突
+         * Add plugin namespace prefixes to all FTL messages to avoid conflicts.
+         *
+         * The default prefix is `${namespace}-`.
+         *
+         * 为所有 FTL message 添加插件前缀以避免冲突。
          *
-         * 默认前缀为 `${namespace}-`
+         * 默认前缀为 `${namespace}-`。
          *
          * @default true
          */
         prefixFluentMessages: boolean;
     };
     /**
-     * The config of esbuild
+     * Configurations of esbuild.
      *
-     * esbuild 配置
+     * esbuild 配置。
      *
      * @default []
      *
      */
     esbuildOptions: BuildOptions[];
     /**
-     * Make manifest.json
+     * Make manifest.json.
      *
      */
     makeManifest: {
         /**
          * 是否自动管理 manifest.json。
-         * 如果此项为 false，则开发者应自行准备 manifest.json
+         * 如果此项为 false，则开发者应自行准备 manifest.json。
          *
          * @default true
          */
         enable: boolean;
         /**
-         * template of manifest
+         * template of manifest.
          *
          * @deprecated
          *
@@ -270,26 +315,33 @@ interface BuildConfig {
         template: Manifest;
     };
     /**
-     * Make update manifest
+     * Make update manifest.
      *
-     * 生成 `update.json`
+     * 生成 `update.json`。
      *
      */
     makeUpdateJson: {
         /**
-         * Enable make update.json
+         * Historical update data.
          *
-         * @default true
-         */
-        enable: boolean | "only-production";
-        /**
-         * 已有的更新数据
+         * This can be useful if you need to distribute different plugin versions
+         * for different versions of Zotero.
+         *
+         * 已有的更新数据。
+         *
+         * 如果你需要为不同版本的 Zotero 分发不同的插件版本，这可能会很有用。
+         *
+         * @see {@link https://www.zotero.org/support/dev/zotero_7_for_developers#updaterdf_updatesjson | Zotero 7 for developers}
+         * @see {@link https://extensionworkshop.com/documentation/manage/updating-your-extension/ | Updating your extension}
+         * @see {@link https://zotero-chinese.com/plugin-dev-guide/reference/update | 更新清单 (In chinese)}
          *
          * @default []
          */
         updates: UpdateJSON["addons"][string]["updates"];
         /**
-         * 是否向 update.json 中写入 xpi 文件的 hash
+         * Whether or not to write the hash of the xpi file to update.json.
+         *
+         * 是否向 update.json 中写入 xpi 文件的 hash。
          *
          * @default true
          */
@@ -314,18 +366,24 @@ interface BuildHooks {
 }
 interface ServerConfig {
     /**
-     * Open devtool on Zotero start
+     * Open devtool on Zotero start.
+     *
+     * 在 Zotero 启动时打开 devtool。
      *
      * @default true
      */
     devtools: boolean;
     /**
-     * 启动 Zotero 时附加的命令行参数
+     * Additional command line arguments when starting Zotero.
+     *
+     * 启动 Zotero 时附加的命令行参数。
      *
-     * @default ["--purgecaches"]
+     * @default []
      */
     startArgs: string[];
     /**
+     * Install the plugin as a Proxy File mode.
+     *
      * 以 Proxy File 方式载入插件
      *
      * @default false
@@ -346,7 +404,9 @@ interface ServeHooks {
 }
 interface ReleaseConfig {
     /**
-     * Config of bumpp
+     * Configurations of bumpp
+     *
+     * bumpp 包的部分配置。
      */
     bumpp: {
         /**
@@ -355,13 +415,27 @@ interface ReleaseConfig {
          * - A release type (e.g. "major", "minor", "patch", "prerelease", etc.)
          * - "prompt" to prompt the user for the version number
          *
-         * @default "prompt".
+         * In general, it is recommended to set this to “prompt”.
+         * If you need a command that always releases a certain type,
+         * you can override this option on the command line.
+         *
+         * 发布的类型，可以是以下其中之一：
+         *
+         * - 版本类型（如 “major”、“minor”、“patch”、“prerelease”等）
+         * - “prompt” 以选择版本号
+         *
+         * 通常来说，建议将此项设置为“prompt”。
+         * 如果需要一个始终发布某类型的命令，可以在命令行中覆盖该选项。
+         *
+         * @default "prompt"
          */
         release: string;
         /**
          * The prerelease type (e.g. "alpha", "beta", "next").
          *
-         * @default "beta".
+         * 预发布的类型，如 alpha，beta，next 等。
+         *
+         * @default "beta"
          */
         preid: string;
         /**
@@ -371,6 +445,11 @@ interface ReleaseConfig {
          * If the message string does _not_ contain any `%s` placeholders,
          * then the new version number will be appended to the message.
          *
+         * 提交说明模板。
+         *
+         * 模板中的 `%s` 占位符将被替换为新版本号。
+         * 如果模板中不包含任何 `%s` 占位符，则新版本号将附加到模板末端。
+         *
          * @default "chore(publish): release %s"
          */
         commit: string;
@@ -381,6 +460,11 @@ interface ReleaseConfig {
          * If the tag string does _not_ contain any `%s` placeholders,
          * then the new version number will be appended to the tag.
          *
+         * 标签模板。
+         *
+         * 模板中的 `%s` 占位符将被替换为新版本号。
+         * 如果模板中不包含任何 `%s` 占位符，则新版本号将附加到模板末端。
+         *
          * @default "v%s"
          */
         tag: string;
@@ -388,38 +472,56 @@ interface ReleaseConfig {
          * Indicates whether the git commit should include ALL files (`git commit --all`)
          * rather than just the files that were modified by `versionBump()`.
          *
-         * Defaults to `false`.
+         * 表示 git 提交是否应包括所有文件（`git commit --all`)，
+         * 而不是只包含被 `versionBump()` 修改过的文件。
+         *
+         * @default false
+         *
          */
-        all?: boolean;
+        all: boolean;
         /**
-         * Prompt for confirmation
+         * Prompt for confirmation.
+         *
+         * 选择版本号后是否要求二次确认。
          *
          * @default true
          */
-        confirm?: boolean;
+        confirm: boolean;
         /**
          * Indicates whether to bypass git commit hooks (`git commit --no-verify`).
          *
-         * Defaults to `false`.
+         * 表示是否绕过 git commit hooks（`git commit --no-verify` ）。
+         *
+         * @default false
          */
-        noVerify?: boolean;
+        noVerify: boolean;
         /**
-         * Excute additional command after bumping and before commiting
+         * Excute additional command after bumping and before commiting.
+         *
+         * 在提升版本号之后，提交之前运行的额外命令。
+         *
+         * @default "npm run build"
+         *
          */
-        execute?: string;
+        execute: string;
     };
     /**
-     * Changelog
+     * Changelog.
+     *
+     * If a string is provided, it must be command line
+     * and with changelog output to stdout.
+     *
+     * 如果提供了字符串，则必须为命令行，且变更日志输出到stdout
      *
      * @default "git log {{previousTag}}..{{currentTag}}"
      */
     changelog: string | ((ctx: Context) => string);
     /**
-     * Release to GitHub
+     * Release to GitHub.
      */
     github: {
         /**
-         * Enable release to GitHub
+         * Enable release to GitHub.
          *
          * Include uploading XPI asset to GitHub release and all following steps.
          *
@@ -432,13 +534,19 @@ interface ReleaseConfig {
          */
         enable: "ci" | "local" | "always" | "false";
         /**
-         * Upload update.json to release
+         * Upload update.json to release.
+         *
+         * This is the tagName of the release when the value is a string.
+         *
+         * 将 update.json 上传到指定的 GitHub release。
+         *
+         * 当值为字符串时，其为 release 的tagName。
          *
          * @default "release"
          */
         updater: string | false;
         /**
-         * Comment to issues and prs inlcuded in release
+         * Comment to issues and prs inlcuded in release.
          *
          * @todo Not implemented yet
          *

package/dist/index.d.ts

@@ -106,67 +106,97 @@ interface Config$1 {
      */
     dist: string;
     /**
-     * The name of plugin
+     * The name of plugin.
      *
-     * 插件名
+     * 插件名。
      *
      * @default package-json.name
      *
      */
     name: string;
     /**
-     * The ID of plugin
+     * The ID of plugin.
      *
-     * 插件 ID
+     * Usually in the form of an email address or UUID.
+     *
+     * 插件 ID。
+     *
+     * 通常是邮箱地址或UUID的形式。
      *
      * @default package-json.name
      */
     id: string;
     /**
-     * namespace of plugin
+     * namespace of plugin.
+     *
+     * This attribute is also used to prevent plugin conflicts,
+     * it may be used for plugin HTML element ids, preference prefixes,
+     * fluent filename prefixes, fluent message prefixes, etc.
+     *
+     * Unlike the plugin id, this value should be HTML ID and Fluent Message compliant,
+     * i.e.: contain at least one character and only letters and dashes.
      *
-     * 插件命名空间
+     * 插件命名空间。
+     *
+     * 这个属性也用于防止插件冲突，它可能被用于插件的 HTML 元素 id，
+     * 首选项前缀，Fluent 文件名前缀、Fluent message 前缀等。
+     *
+     * 与插件 ID 不同的是，这个值应是符合 HTML ID 和 Fluent Message 规范的，
+     * 即：至少包含一个字符，仅包含字母和短横线。
      *
      * @default kebabCase(name)
      */
     namespace: string;
     /**
-     * XPI filename
+     * XPI filename.
+     *
+     * XPI 文件名。
      *
      * @default kebabCase(name)
      */
     xpiName: string;
     /**
-     * XPI 文件的地址
+     * The download link of XPI.
+     *
+     * XPI 文件的地址。
      *
      * @default `https://github.com/{{owner}}/{{repo}}/release/download/v{{version}}/{{xpiName}}.xpi`
      */
     xpiDownloadLink: string;
     /**
-     * update.json 文件的地址
+     * The uri of update.json.
+     *
+     * update.json 文件的地址。
      *
      * @default `https://github.com/{{owner}}/{{repo}}/release/download/release/update.json`
      */
     updateURL: string;
     /**
-     * 构建所需的配置
+     * Configurations required to run the build.
+     *
+     * 构建所需的配置。
      */
     build: BuildConfig;
     /**
-     * serve 所需的配置
+     * Configurations required to run the server.
+     *
+     * serve 所需的配置。
      */
     server: ServerConfig;
     /**
-     * @todo Use addonLint package to lint XPI
+     * @todo Use addonLint package to lint XPI.
      */
     addonLint: object;
     /**
-     * 发布相关配置
+     * Configurations required to run the release.
      *
+     * 发布相关配置。
      */
     release: ReleaseConfig;
     /**
-     * Log level
+     * Level of the log.
+     *
+     * 日志等级。
      *
      * @default "info"
      */
@@ -174,7 +204,11 @@ interface Config$1 {
 }
 interface BuildConfig {
     /**
-     * glob list of static assets
+     * The static assets.
+     *
+     * - Typically includes icons, ftl files, 3rd party JavaScript files, CSS files, XHTML files, etc.
+     * - is an array of `glob` modes and supports negation modes.
+     * - Do not add an entire directory unless it has no files to exclude.
      *
      * 静态资源文件。
      *
@@ -190,7 +224,10 @@ interface BuildConfig {
      */
     assets: string | string[];
     /**
-     * placeholders to replace in static assets
+     * The placeholders to replace in static assets.
+     *
+     * - At build time, scaffolding uses the key of the placeholder to build the regular pattern `/__${key}__/g` and replaces matches with `value`.
+     * - Replacement happens for all files under `assets`.
      *
      * 静态资源文本占位符。
      *
@@ -202,45 +239,53 @@ interface BuildConfig {
     };
     fluent: {
         /**
-         * 为所有 FTL 文件添加插件前缀以避免冲突
+         * Add plugin namespace prefixes to all FTL files to avoid conflicts.
          *
-         * 默认前缀为 `${namespace}-`
+         * The default prefix is `${namespace}-`.
+         *
+         * 为所有 FTL 文件添加插件前缀以避免冲突。
+         *
+         * 默认前缀为 `${namespace}-`。
          *
          * @default true
          */
         prefixLocaleFiles: boolean;
         /**
-         * 为所有 FTL message 添加插件前缀以避免冲突
+         * Add plugin namespace prefixes to all FTL messages to avoid conflicts.
+         *
+         * The default prefix is `${namespace}-`.
+         *
+         * 为所有 FTL message 添加插件前缀以避免冲突。
          *
-         * 默认前缀为 `${namespace}-`
+         * 默认前缀为 `${namespace}-`。
          *
          * @default true
          */
         prefixFluentMessages: boolean;
     };
     /**
-     * The config of esbuild
+     * Configurations of esbuild.
      *
-     * esbuild 配置
+     * esbuild 配置。
      *
      * @default []
      *
      */
     esbuildOptions: BuildOptions[];
     /**
-     * Make manifest.json
+     * Make manifest.json.
      *
      */
     makeManifest: {
         /**
          * 是否自动管理 manifest.json。
-         * 如果此项为 false，则开发者应自行准备 manifest.json
+         * 如果此项为 false，则开发者应自行准备 manifest.json。
          *
          * @default true
          */
         enable: boolean;
         /**
-         * template of manifest
+         * template of manifest.
          *
          * @deprecated
          *
@@ -270,26 +315,33 @@ interface BuildConfig {
         template: Manifest;
     };
     /**
-     * Make update manifest
+     * Make update manifest.
      *
-     * 生成 `update.json`
+     * 生成 `update.json`。
      *
      */
     makeUpdateJson: {
         /**
-         * Enable make update.json
+         * Historical update data.
          *
-         * @default true
-         */
-        enable: boolean | "only-production";
-        /**
-         * 已有的更新数据
+         * This can be useful if you need to distribute different plugin versions
+         * for different versions of Zotero.
+         *
+         * 已有的更新数据。
+         *
+         * 如果你需要为不同版本的 Zotero 分发不同的插件版本，这可能会很有用。
+         *
+         * @see {@link https://www.zotero.org/support/dev/zotero_7_for_developers#updaterdf_updatesjson | Zotero 7 for developers}
+         * @see {@link https://extensionworkshop.com/documentation/manage/updating-your-extension/ | Updating your extension}
+         * @see {@link https://zotero-chinese.com/plugin-dev-guide/reference/update | 更新清单 (In chinese)}
          *
          * @default []
          */
         updates: UpdateJSON["addons"][string]["updates"];
         /**
-         * 是否向 update.json 中写入 xpi 文件的 hash
+         * Whether or not to write the hash of the xpi file to update.json.
+         *
+         * 是否向 update.json 中写入 xpi 文件的 hash。
          *
          * @default true
          */
@@ -314,18 +366,24 @@ interface BuildHooks {
 }
 interface ServerConfig {
     /**
-     * Open devtool on Zotero start
+     * Open devtool on Zotero start.
+     *
+     * 在 Zotero 启动时打开 devtool。
      *
      * @default true
      */
     devtools: boolean;
     /**
-     * 启动 Zotero 时附加的命令行参数
+     * Additional command line arguments when starting Zotero.
+     *
+     * 启动 Zotero 时附加的命令行参数。
      *
-     * @default ["--purgecaches"]
+     * @default []
      */
     startArgs: string[];
     /**
+     * Install the plugin as a Proxy File mode.
+     *
      * 以 Proxy File 方式载入插件
      *
      * @default false
@@ -346,7 +404,9 @@ interface ServeHooks {
 }
 interface ReleaseConfig {
     /**
-     * Config of bumpp
+     * Configurations of bumpp
+     *
+     * bumpp 包的部分配置。
      */
     bumpp: {
         /**
@@ -355,13 +415,27 @@ interface ReleaseConfig {
          * - A release type (e.g. "major", "minor", "patch", "prerelease", etc.)
          * - "prompt" to prompt the user for the version number
          *
-         * @default "prompt".
+         * In general, it is recommended to set this to “prompt”.
+         * If you need a command that always releases a certain type,
+         * you can override this option on the command line.
+         *
+         * 发布的类型，可以是以下其中之一：
+         *
+         * - 版本类型（如 “major”、“minor”、“patch”、“prerelease”等）
+         * - “prompt” 以选择版本号
+         *
+         * 通常来说，建议将此项设置为“prompt”。
+         * 如果需要一个始终发布某类型的命令，可以在命令行中覆盖该选项。
+         *
+         * @default "prompt"
          */
         release: string;
         /**
          * The prerelease type (e.g. "alpha", "beta", "next").
          *
-         * @default "beta".
+         * 预发布的类型，如 alpha，beta，next 等。
+         *
+         * @default "beta"
          */
         preid: string;
         /**
@@ -371,6 +445,11 @@ interface ReleaseConfig {
          * If the message string does _not_ contain any `%s` placeholders,
          * then the new version number will be appended to the message.
          *
+         * 提交说明模板。
+         *
+         * 模板中的 `%s` 占位符将被替换为新版本号。
+         * 如果模板中不包含任何 `%s` 占位符，则新版本号将附加到模板末端。
+         *
          * @default "chore(publish): release %s"
          */
         commit: string;
@@ -381,6 +460,11 @@ interface ReleaseConfig {
          * If the tag string does _not_ contain any `%s` placeholders,
          * then the new version number will be appended to the tag.
          *
+         * 标签模板。
+         *
+         * 模板中的 `%s` 占位符将被替换为新版本号。
+         * 如果模板中不包含任何 `%s` 占位符，则新版本号将附加到模板末端。
+         *
          * @default "v%s"
          */
         tag: string;
@@ -388,38 +472,56 @@ interface ReleaseConfig {
          * Indicates whether the git commit should include ALL files (`git commit --all`)
          * rather than just the files that were modified by `versionBump()`.
          *
-         * Defaults to `false`.
+         * 表示 git 提交是否应包括所有文件（`git commit --all`)，
+         * 而不是只包含被 `versionBump()` 修改过的文件。
+         *
+         * @default false
+         *
          */
-        all?: boolean;
+        all: boolean;
         /**
-         * Prompt for confirmation
+         * Prompt for confirmation.
+         *
+         * 选择版本号后是否要求二次确认。
          *
          * @default true
          */
-        confirm?: boolean;
+        confirm: boolean;
         /**
          * Indicates whether to bypass git commit hooks (`git commit --no-verify`).
          *
-         * Defaults to `false`.
+         * 表示是否绕过 git commit hooks（`git commit --no-verify` ）。
+         *
+         * @default false
          */
-        noVerify?: boolean;
+        noVerify: boolean;
         /**
-         * Excute additional command after bumping and before commiting
+         * Excute additional command after bumping and before commiting.
+         *
+         * 在提升版本号之后，提交之前运行的额外命令。
+         *
+         * @default "npm run build"
+         *
          */
-        execute?: string;
+        execute: string;
     };
     /**
-     * Changelog
+     * Changelog.
+     *
+     * If a string is provided, it must be command line
+     * and with changelog output to stdout.
+     *
+     * 如果提供了字符串，则必须为命令行，且变更日志输出到stdout
      *
      * @default "git log {{previousTag}}..{{currentTag}}"
      */
     changelog: string | ((ctx: Context) => string);
     /**
-     * Release to GitHub
+     * Release to GitHub.
      */
     github: {
         /**
-         * Enable release to GitHub
+         * Enable release to GitHub.
          *
          * Include uploading XPI asset to GitHub release and all following steps.
          *
@@ -432,13 +534,19 @@ interface ReleaseConfig {
          */
         enable: "ci" | "local" | "always" | "false";
         /**
-         * Upload update.json to release
+         * Upload update.json to release.
+         *
+         * This is the tagName of the release when the value is a string.
+         *
+         * 将 update.json 上传到指定的 GitHub release。
+         *
+         * 当值为字符串时，其为 release 的tagName。
          *
          * @default "release"
          */
         updater: string | false;
         /**
-         * Comment to issues and prs inlcuded in release
+         * Comment to issues and prs inlcuded in release.
          *
          * @todo Not implemented yet
          *

package/dist/index.mjs

@@ -1,4 +1,4 @@
-export { B as Build, C as Config, R as Release, S as Serve, d as defineConfig } from './shared/zotero-plugin-scaffold.125bc4ce.mjs';
+export { B as Build, C as Config, R as Release, S as Serve, d as defineConfig } from './shared/zotero-plugin-scaffold.06668c10.mjs';
 import 'node:path';
 import 'c12';
 import 'fs-extra';

package/dist/shared/{zotero-plugin-scaffold.125bc4ce.mjs → zotero-plugin-scaffold.06668c10.mjs}

@@ -62,7 +62,9 @@ ${arg.stack}`;
     console.log(...args);
   }
   error(...args) {
+    this.newLine();
     this.logArgs(4 /* error */, chalk.bgRed(" ERROR "), ...args);
+    this.newLine();
   }
   warn(...args) {
     this.newLine();
@@ -260,7 +262,6 @@ const defaultConfig = {
       }
     },
     makeUpdateJson: {
-      enable: true,
       updates: [],
       hash: true
     },
@@ -276,11 +277,12 @@ const defaultConfig = {
   release: {
     bumpp: {
       release: "prompt",
-      confirm: true,
       preid: "beta",
-      // execute: "npm run build",
+      confirm: true,
+      execute: "",
       all: false,
       commit: "chore(publish): release v%s",
+      noVerify: false,
       tag: "v%s"
     },
     changelog: "",
@@ -874,8 +876,8 @@ class Release extends Base {
     const isGitHubEnabled = this.isEnabled(release.github.enable);
     const isGiteeEnabled = this.isEnabled(release.gitee.enable);
     const isPublishNeeded = isGitHubEnabled || isGiteeEnabled;
-    if (isBumpNeeded && isPublishNeeded && !!release.bumpp.execute) {
-      this.logger.warn("The current release needs to run the build after bumping the version number, please configure the build script in config.release.bumpp.execute.");
+    if (isPublishNeeded && !release.bumpp.execute) {
+      this.logger.warn(`The current release needs to run the build after bumping the version number, please configure the build script in 'config.release.bumpp.execute'${isBumpNeeded ? "" : " or run build before run release"}.`);
       (_a = this.ctx.release.bumpp).execute || (_a.execute = "npm run build");
     }
     this.logger.debug("Release config: ", this.ctx.release);
@@ -911,19 +913,25 @@ class Release extends Base {
     const currentTagIndex = tags.indexOf(currentTag);
     if (currentTagIndex === -1)
       throw new Error(`Tag "${currentTag}" not found.`);
+    let previousTagIndex = currentTagIndex - 1;
+    let previousTag;
     if (currentTagIndex === 0) {
-      return execSync(`git log ${currentTag} --pretty=format:"* %s (%h)"`).toString().trim();
+      previousTag = false;
+    } else if (currentTag.includes("-")) {
+      previousTag = tags[previousTagIndex];
     } else {
-      let previousTagIndex = currentTagIndex - 1;
       while (previousTagIndex >= 0 && tags[previousTagIndex].includes("-")) {
         previousTagIndex--;
       }
-      if (previousTagIndex < 0) {
-        return execSync(`git log ${currentTag} --pretty=format:"* %s (%h)"`).toString().trim();
-      }
-      const previousTag = tags[previousTagIndex];
-      return execSync(`git log ${previousTag}..${currentTag} --pretty=format:"* %s (%h)"`).toString().trim();
+      if (previousTagIndex < 0)
+        previousTag = false;
+      else
+        previousTag = tags[previousTagIndex];
     }
+    if (previousTag)
+      return execSync(`git log --pretty=format:"* %s (%h)" ${previousTag}..${currentTag}`).toString().trim();
+    else
+      return execSync(`git log --pretty=format:"* %s (%h)" ${currentTag}`).toString().trim();
   }
   getFilteredChangelog(rawLog, commitMessage) {
     const filterRegex = new RegExp(escapeRegExp(commitMessage));
@@ -946,7 +954,8 @@ class Release extends Base {
       changelog = this.getFilteredChangelog(rawLog, resolvedCommitMessage);
     }
     this.logger.debug(`Got changelog:
-`, changelog, "\n");
+${changelog}
+`);
     return changelog;
   }
   isEnabled(enable) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zotero-plugin-scaffold",
   "type": "module",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0",
   "description": "A scaffold for Zotero plugin development.",
   "author": "northword",
   "license": "AGPL-3.0-or-later",
@@ -51,34 +51,35 @@
     "doc": "docs"
   },
   "dependencies": {
-    "@inquirer/prompts": "5.3.6",
-    "bumpp": "9.4.1",
-    "c12": "1.11.1",
-    "chalk": "5.3.0",
-    "chokidar": "3.6.0",
-    "commander": "12.1.0",
-    "conventional-changelog": "6.0.0",
+    "@commander-js/extra-typings": "^12.1.0",
+    "@inquirer/prompts": "^5.3.8",
+    "bumpp": "^9.5.2",
+    "c12": "^1.11.1",
+    "chalk": "^5.3.0",
+    "chokidar": "^3.6.0",
+    "commander": "^12.1.0",
+    "conventional-changelog": "^6.0.0",
     "es-toolkit": "^1.16.0",
-    "esbuild": "0.23.0",
-    "fs-extra": "11.2.0",
+    "esbuild": "^0.23.1",
+    "fs-extra": "^11.2.0",
     "globby": "^14.0.2",
-    "hookable": "5.5.3",
-    "mime": "4.0.4",
-    "octokit": "4.0.2",
-    "replace-in-file": "8.1.0",
-    "std-env": "3.7.0",
-    "update-notifier": "7.1.0",
-    "web-ext": "8.2.0"
+    "hookable": "^5.5.3",
+    "mime": "^4.0.4",
+    "octokit": "^4.0.2",
+    "replace-in-file": "^8.1.0",
+    "std-env": "^3.7.0",
+    "update-notifier": "^7.2.0",
+    "web-ext": "^8.2.0"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^2.23.0",
-    "@types/fs-extra": "11.0.4",
-    "@types/node": "20.14.13",
-    "@types/update-notifier": "6.0.8",
-    "eslint": "9.8.0",
+    "@antfu/eslint-config": "^2.27.1",
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^20.16.1",
+    "@types/update-notifier": "^6.0.8",
+    "eslint": "^9.9.1",
     "eslint-plugin-format": "^0.1.2",
-    "typescript": "5.5.4",
-    "unbuild": "2.0.0"
+    "typescript": "^5.5.4",
+    "unbuild": "^2.0.0"
   },
   "scripts": {
     "dev": "unbuild --stub",