zotero-plugin-scaffold 0.2.0-beta.9 → 0.2.1

package/README.md

@@ -1,167 +1,10 @@
 # Zotero Plugin Development Scaffold
 
-[![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)
-[![code style](https://antfu.me/badge-code-style.svg)](https://github.com/antfu/eslint-config)
+Delivering a modern and elegant development experience for Zotero plugins.
 
-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.
+## Documentation
 
-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
-
-<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();
-```
-
-## Contributing
-
-```bash
-# Git Clone
-git clone https://github.com/northword/zotero-plugin-scaffold.git zotero-plugin-scaffold
-cd zotero-plugin-scaffold/
-
-# Install deps
-pnpm install
-
-# Development Mode
-# 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
-
-# ES Lint
-pnpm run lint:fix
-```
+[Read the Docs to Learn More](https://northword.github.io/zotero-plugin-scaffold).
 
 ## License
 

package/bin/zotero-plugin.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import cli from "../dist/cli.mjs";
+
+cli();

package/dist/cli.d.mts

@@ -1,3 +1,3 @@
-declare function main(): Promise<void>;
+declare function run(): Promise<void>;
 
-export { main as default };
+export { run as default };

package/dist/cli.d.ts

@@ -1,3 +1,3 @@
-declare function main(): Promise<void>;
+declare function run(): Promise<void>;
 
-export { main as default };
+export { run as default };

package/dist/cli.mjs

@@ -1,7 +1,8 @@
-#!/usr/bin/env node
-import process, { exit, env } from 'node:process';
+import process from 'node:process';
 import { Command } from '@commander-js/extra-typings';
-import { L as Log, E as ExitSignals, C as Config, a as Build, S as Serve, T as Test, R as Release } from './shared/zotero-plugin-scaffold.2ad7a023.mjs';
+import { E as ExitSignals, l as logger, C as Config, B as Build, S as Serve, T as Test, R as Release } from './shared/zotero-plugin-scaffold.DiPAIBFh.mjs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { pathExists, ensureFile } from 'fs-extra';
 import tinyUpdateNotifier from 'tiny-update-notifier';
 import 'c12';
 import 'es-toolkit';
@@ -10,16 +11,17 @@ import 'hookable';
 import 'node:readline';
 import 'chalk';
 import 'std-env';
-import './shared/zotero-plugin-scaffold.77c9802c.mjs';
-import 'node:fs/promises';
+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 '@swc/core';
 import 'node:child_process';
 import 'bumpp';
+import 'octokit';
 import 'chokidar';
 import 'node:net';
 import 'node:buffer';
@@ -30,15 +32,16 @@ import 'xvfb-ts';
 
 const name = "zotero-plugin-scaffold";
 const type = "module";
-const version = "0.2.0-beta.9";
-const packageManager = "pnpm@9.15.0";
+const version = "0.2.1";
+const packageManager = "pnpm@9.15.4";
 const description = "A scaffold for Zotero plugin development.";
 const author = "northword";
 const license = "AGPL-3.0-or-later";
 const homepage = "https://github.com/northword/zotero-plugin-scaffold#readme";
 const repository = {
 	type: "git",
-	url: "https://github.com/northword/zotero-plugin-scaffold.git"
+	url: "https://github.com/northword/zotero-plugin-scaffold.git",
+	directory: "packages/scaffold"
 };
 const bugs = {
 	url: "https://github.com/northword/zotero-plugin-scaffold/issues"
@@ -55,6 +58,9 @@ const exports = {
 		types: "./dist/index.d.ts",
 		"import": "./dist/index.mjs"
 	},
+	"./cli": {
+		"import": "./dist/cli.mjs"
+	},
 	"./vendor": {
 		types: "./dist/vendor/index.d.ts",
 		"import": "./dist/vendor/index.mjs"
@@ -64,9 +70,10 @@ const main$1 = "./dist/index.mjs";
 const module = "./dist/index.mjs";
 const types = "./dist/index.d.ts";
 const bin = {
-	"zotero-plugin": "./dist/cli.mjs"
+	"zotero-plugin": "./bin/zotero-plugin.mjs"
 };
 const files = [
+	"bin",
 	"dist"
 ];
 const engines = {
@@ -75,10 +82,6 @@ const engines = {
 const scripts = {
 	dev: "unbuild --stub",
 	build: "tsc --noEmit && unbuild",
-	"lint:check": "eslint .",
-	"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"
 };
 const publishConfig = {
@@ -86,8 +89,7 @@ const publishConfig = {
 	registry: "https://registry.npmjs.org"
 };
 const directories = {
-	lib: "dist",
-	doc: "docs"
+	lib: "dist"
 };
 const peerDependencies = {
 	"conventional-changelog": "^6.0.0"
@@ -98,33 +100,27 @@ const peerDependenciesMeta = {
 	}
 };
 const dependencies = {
-	"@commander-js/extra-typings": "^12.1.0",
+	"@commander-js/extra-typings": "^13.1.0",
+	"@swc/core": "^1.10.12",
 	"adm-zip": "^0.5.16",
-	bumpp: "^9.9.1",
+	bumpp: "^10.0.1",
 	c12: "^2.0.1",
-	chalk: "^5.3.0",
-	chokidar: "^4.0.1",
-	commander: "^12.1.0",
-	"es-toolkit": "^1.29.0",
-	esbuild: "^0.24.0",
-	"fs-extra": "^11.2.0",
+	chalk: "^5.4.1",
+	chokidar: "^4.0.3",
+	commander: "^13.1.0",
+	"es-toolkit": "^1.32.0",
+	esbuild: "^0.24.2",
+	"fs-extra": "^11.3.0",
 	hookable: "^5.5.3",
-	mime: "^4.0.4",
-	octokit: "^4.0.2",
+	octokit: "^4.1.0",
 	"std-env": "^3.8.0",
 	"tiny-update-notifier": "^2.0.0",
 	tinyglobby: "^0.2.10",
 	"xvfb-ts": "^1.1.0"
 };
 const devDependencies = {
-	"@antfu/eslint-config": "^3.11.2",
 	"@types/adm-zip": "^0.5.7",
-	"@types/fs-extra": "^11.0.4",
-	"@types/node": "^22.10.2",
-	eslint: "^9.16.0",
-	"eslint-plugin-format": "^0.1.3",
-	typescript: "^5.7.2",
-	unbuild: "^2.0.0"
+	"@types/fs-extra": "^11.0.4"
 };
 const pkg = {
 	name: name,
@@ -154,31 +150,41 @@ const pkg = {
 	devDependencies: devDependencies
 };
 
-const logger$1 = new Log();
+async function checkGitIgnore() {
+  if (!pathExists(".git"))
+    return;
+  await ensureFile(".gitignore");
+  const contents = (await readFile(".gitignore", "utf-8")).split("\n");
+  const ignores = ["node_modules", ".env", ".scaffold"];
+  ignores.forEach((ignore) => {
+    if (!contents.includes(ignore))
+      contents.push(ignore);
+  });
+  await writeFile(".gitignore", contents.join("\n"));
+}
+
 function updateNotifier(name, version) {
   tinyUpdateNotifier({ pkg: { name, version } }).then((update) => {
     if (update) {
       const notify = () => {
-        logger$1.newLine();
-        logger$1.info(`New version of ${update.name} available!`);
-        logger$1.info(`Update: ${update.current} \u2192 ${update.latest} (${update.type})`);
-        logger$1.newLine();
+        logger.newLine();
+        logger.info(`New version of ${update.name} available!`);
+        logger.info(`Update: ${update.current} \u2192 ${update.latest} (${update.type})`);
+        logger.newLine();
       };
       ExitSignals.forEach((sig) => process.once(sig, notify));
     }
   }).catch();
 }
 
-const logger = new Log();
 async function main() {
-  var _a;
   const { name, version } = pkg;
   updateNotifier(name, version);
-  (_a = env).NODE_ENV ?? (_a.NODE_ENV = "development");
+  process.env.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());
@@ -187,7 +193,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;
@@ -202,7 +208,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: {
@@ -219,11 +225,15 @@ async function main() {
   });
   cli.parse();
 }
-main().catch(onError);
-process.on("uncaughtException", onError);
+async function run() {
+  main().then(() => {
+    checkGitIgnore();
+  }).catch(onError);
+  process.on("uncaughtException", onError);
+}
 function onError(err) {
   logger.error(err);
-  exit(1);
+  process.exit(1);
 }
 
-export { main as default };
+export { run as default };

package/dist/index.d.mts

@@ -2,12 +2,27 @@ import { Hookable } from 'hookable';
 import * as esbuild from 'esbuild';
 import { BuildOptions } from 'esbuild';
 
+/**
+ * Log level
+ */
+declare enum LOG_LEVEL {
+    trace = 0,
+    debug = 1,
+    info = 2,
+    warn = 3,
+    error = 4
+}
+type LogLevelType = keyof typeof LOG_LEVEL;
 /**
  * Logger
  */
 declare class Log {
+    private static instance;
     private logLevel;
-    constructor(config?: Config$1);
+    constructor(level?: LOG_LEVEL);
+    static getInstance(): Log;
+    setLogLevel(level: LogLevelType): void;
+    get level(): number;
     private formatArgs;
     private logArgs;
     log(...args: any[]): void;
@@ -36,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;
-        };
     };
 }
 
@@ -66,7 +76,7 @@ interface UpdateJSON {
                 update_hash?: string;
                 applications: {
                     zotero: {
-                        strict_min_version: string;
+                        strict_min_version?: string;
                         strict_max_version?: string;
                     };
                     [application: string]: {
@@ -221,7 +231,7 @@ interface Config$1 {
      *
      * @default "info"
      */
-    logLevel: "trace" | "debug" | "info" | "warn" | "error";
+    logLevel: LogLevelType;
 }
 interface BuildConfig {
     /**
@@ -285,6 +295,48 @@ interface BuildConfig {
          * @default true
          */
         prefixFluentMessages: boolean;
+        /**
+         * Messages to ignore.
+         *
+         * 需要忽略的 Fluent Messages。
+         *
+         * @default []
+         */
+        ignore: string[];
+    };
+    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.
@@ -411,6 +463,8 @@ interface ServerConfig {
      * @default false
      */
     asProxy: boolean;
+    prebuild: boolean;
+    createProfileIfMissing: boolean;
     /**
      * The lifecycle hook.
      */
@@ -591,12 +645,6 @@ interface ReleaseConfig {
         comment: boolean;
         releaseNote: (ctx: Context) => string;
     };
-    /**
-     * Release to Gitee
-     *
-     * @todo Not implemented yet
-     */
-    gitee: ReleaseConfig["github"];
     hooks: Partial<ReleaseHooks>;
 }
 interface ReleaseHooks {
@@ -635,14 +683,6 @@ interface TestConfig {
          */
         timeout: number;
     };
-    /**
-     * Port for the test server.
-     *
-     * 测试服务器的端口。
-     *
-     * @default 9876
-     */
-    port: number;
     /**
      * Abort the test when the first test fails.
      *
@@ -698,6 +738,10 @@ interface TestConfig {
      * ```
      */
     waitForPlugin: string;
+    /**
+     * @todo not
+     */
+    watch: boolean;
     hooks: Partial<TestHooks>;
 }
 interface TestHooks {
@@ -715,6 +759,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
  */
@@ -778,6 +823,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>;
@@ -805,7 +851,6 @@ declare class Serve extends Base {
     private builder;
     private runner?;
     private _zoteroBinPath?;
-    private _profilePath?;
     constructor(ctx: Context);
     run(): Promise<void>;
     /**
@@ -817,22 +862,21 @@ 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 {
     private builder;
     private runner?;
-    private _server?;
+    private communicator;
     constructor(ctx: Context);
     run(): Promise<void>;
-    createManifest(): Promise<void>;
-    createBootstrap(): Promise<void>;
-    createTestResources(): Promise<void>;
+    createTestPlugin(): Promise<void>;
+    copyTestLibraries(): Promise<void>;
     bundleTests(): Promise<void>;
-    startTestServer(): Promise<void>;
-    handleTestUpdate(body: {
+    startHttpServer(): Promise<void>;
+    onHttpDataUpdated(body: {
         type: "start" | "suite" | "suite end" | "pending" | "pass" | "fail" | "end" | "debug";
         data?: {
             title: string;
@@ -841,14 +885,16 @@ declare class Test extends Base {
             stack?: string;
         };
     }): Promise<void>;
+    watch(): Promise<void>;
+    onCodeChanged(_path: string): Promise<void>;
     startZoteroHeadless(): Promise<void>;
     startZotero(): Promise<void>;
-    exit: (code?: string | number) => never;
+    private exit;
     private get zoteroBinPath();
     private get profilePath();
     private get dataDir();
-    private get testBuildDir();
     private get testPluginDir();
+    private get cacheDir();
     private get testPluginRef();
     private get testPluginID();
     private get prefs();