zotero-plugin-scaffold 0.0.4

package/dist/lib/serve.d.ts

@@ -0,0 +1,22 @@
+import { Config } from "../types.js";
+import { LibBase } from "../utils/libBase.js";
+export default class Serve extends LibBase {
+    private builder;
+    constructor(config: Config);
+    run(): Promise<void>;
+    /**
+     * watch source dir and build when file changed
+     */
+    watch(): Promise<void>;
+    startZotero(): void;
+    /**
+     * start zotero with plugin installed and reload when dist changed
+     */
+    startZoteroWebExt(): Promise<void>;
+    prepareDevEnv(): void;
+    reload(): void;
+    openDevTool(): void;
+    private get zoteroBinPath();
+    private get profilePath();
+    private get dataDir();
+}

package/dist/lib/serve.js

@@ -0,0 +1,233 @@
+import { LibBase } from "../utils/libBase.js";
+import Build from "./build.js";
+import { execSync, spawn } from "child_process";
+import chokidar from "chokidar";
+import fs from "fs-extra";
+import _ from "lodash";
+import path from "path";
+import { exit } from "process";
+import webext from "web-ext";
+export default class Serve extends LibBase {
+    builder;
+    constructor(config) {
+        super(config);
+        this.builder = new Build(config);
+    }
+    async run() {
+        // build
+        this.builder.run();
+        // start Zotero
+        // this.startZotero();
+        this.startZoteroWebExt();
+        // watch
+        await this.config.extraServer(this.config);
+        await this.watch();
+    }
+    /**
+     * watch source dir and build when file changed
+     */
+    async watch() {
+        const watcher = chokidar.watch(this.config.source, {
+            ignored: /(^|[/\\])\../, // ignore dotfiles
+            persistent: true,
+        });
+        const onChange = _.debounce((path) => {
+            try {
+                if (path.endsWith(".ts")) {
+                    this.builder.esbuild();
+                }
+                else {
+                    this.builder.run();
+                }
+            }
+            catch (err) {
+                // Do not abort the watcher when errors occur
+                // in builds triggered by the watcher.
+                this.logger.error(err);
+            }
+        }, 500);
+        watcher
+            .on("ready", () => {
+            this.logger.log("");
+            this.logger.info("Server Ready! \n");
+        })
+            .on("change", async (path) => {
+            this.logger.info(`${path} changed at ${new Date().toLocaleTimeString()}`);
+            onChange.cancel();
+            onChange(path);
+            this.reload();
+            this.logger.info("Reloaded done.");
+        })
+            .on("error", (err) => {
+            this.logger.error("Server start failed!", err);
+        });
+    }
+    startZotero() {
+        if (!fs.existsSync(this.zoteroBinPath)) {
+            throw new Error("Zotero binary does not exist.");
+        }
+        if (!fs.existsSync(this.profilePath)) {
+            throw new Error("The given Zotero profile does not exist.");
+        }
+        const zoteroProcess = spawn(this.zoteroBinPath, [
+            "--debugger",
+            "--purgecaches",
+            "-profile",
+            this.profilePath,
+        ]);
+        zoteroProcess.on("close", (code) => {
+            this.logger.info(`Zotero terminated with code ${code}.`);
+            exit(0);
+        });
+        process.on("SIGINT", () => {
+            // Handle interrupt signal (Ctrl+C) to gracefully terminate Zotero process
+            zoteroProcess.kill();
+            exit();
+        });
+    }
+    /**
+     * start zotero with plugin installed and reload when dist changed
+     */
+    async startZoteroWebExt() {
+        await webext.cmd.run({
+            firefox: this.config.cmd.zoteroBinPath,
+            firefoxProfile: this.config.cmd.profilePath,
+            sourceDir: path.resolve(`${this.config.dist}/addon`),
+            keepProfileChanges: true,
+            args: ["--debugger", "--purgecaches"],
+            // browserConsole: true,
+            // openDevTool: true, // need Zotero upgrade to firefox 115
+        }, {
+            // These are non CLI related options for each function.
+            // You need to specify this one so that your NodeJS application
+            // can continue running after web-ext is finished.
+            shouldExitProgram: false,
+        });
+    }
+    prepareDevEnv() {
+        const addonProxyFilePath = path.join(this.profilePath, `extensions/${this.addonID}`);
+        const buildPath = path.resolve("build/addon");
+        if (!fs.existsSync(addonProxyFilePath) ||
+            fs.readFileSync(addonProxyFilePath, "utf-8") !== buildPath) {
+            fs.writeFileSync(addonProxyFilePath, buildPath);
+            this.logger.debug(`Addon proxy file has been updated. 
+          File path: ${addonProxyFilePath} 
+          Addon path: ${buildPath} `);
+        }
+        const addonXpiFilePath = path.join(this.profilePath, `extensions/${this.addonID}.xpi`);
+        if (fs.existsSync(addonXpiFilePath)) {
+            fs.rmSync(addonXpiFilePath);
+        }
+        const prefsPath = path.join(this.profilePath, "prefs.js");
+        if (fs.existsSync(prefsPath)) {
+            const PrefsLines = fs.readFileSync(prefsPath, "utf-8").split("\n");
+            const filteredLines = PrefsLines.map((line) => {
+                if (line.includes("extensions.lastAppBuildId") ||
+                    line.includes("extensions.lastAppVersion")) {
+                    return;
+                }
+                if (line.includes("extensions.zotero.dataDir") && this.dataDir !== "") {
+                    return `user_pref("extensions.zotero.dataDir", "${this.dataDir}");`;
+                }
+                return line;
+            });
+            const updatedPrefs = filteredLines.join("\n");
+            fs.writeFileSync(prefsPath, updatedPrefs, "utf-8");
+            this.logger.debug("The <profile>/prefs.js has been modified.");
+        }
+    }
+    reload() {
+        this.logger.debug("Reloading...");
+        const reloadScript = `
+    (async () => {
+    Services.obs.notifyObservers(null, "startupcache-invalidate", null);
+    const { AddonManager } = ChromeUtils.import("resource://gre/modules/AddonManager.jsm");
+    const addon = await AddonManager.getAddonByID("${this.addonID}");
+    await addon.reload();
+    const progressWindow = new Zotero.ProgressWindow({ closeOnClick: true });
+    progressWindow.changeHeadline("${this.addonName} Hot Reload");
+    progressWindow.progress = new progressWindow.ItemProgress(
+        "chrome://zotero/skin/tick.png",
+        "VERSION=${this.version}, BUILD=${new Date().toLocaleString()}. By zotero-plugin-toolkit"
+    );
+    progressWindow.progress.setProgress(100);
+    progressWindow.show();
+    progressWindow.startCloseTimer(5000);
+    })()`;
+        const url = `zotero://ztoolkit-debug/?run=${encodeURIComponent(reloadScript)}`;
+        const startZoteroCmd = `"${this.zoteroBinPath}" --debugger --purgecaches -profile "${this.profilePath}"`;
+        const command = `${startZoteroCmd} -url "${url}"`;
+        execSync(command);
+    }
+    openDevTool() {
+        this.logger.debug("Open dev tools...");
+        const openDevToolScript = `
+    (async () => {
+    
+    // const { BrowserToolboxLauncher } = ChromeUtils.import(
+    //   "resource://devtools/client/framework/browser-toolbox/Launcher.jsm",
+    // );
+    // BrowserToolboxLauncher.init();
+    // TODO: Use the above code to open the devtool after https://github.com/zotero/zotero/pull/3387
+    
+    Zotero.Prefs.set("devtools.debugger.remote-enabled", true, true);
+    Zotero.Prefs.set("devtools.debugger.remote-port", 6100, true);
+    Zotero.Prefs.set("devtools.debugger.prompt-connection", false, true);
+    Zotero.Prefs.set("devtools.debugger.chrome-debugging-websocket", false, true);
+    
+    env =
+        Services.env ||
+        Cc["@mozilla.org/process/environment;1"].getService(Ci.nsIEnvironment);
+    
+    env.set("MOZ_BROWSER_TOOLBOX_PORT", 6100);
+    Zotero.openInViewer(
+        "chrome://devtools/content/framework/browser-toolbox/window.html",
+        {
+        onLoad: (doc) => {
+            doc.querySelector("#status-message-container").style.visibility =
+            "collapse";
+            let toolboxBody;
+            waitUntil(
+            () => {
+                toolboxBody = doc
+                .querySelector(".devtools-toolbox-browsertoolbox-iframe")
+                ?.contentDocument?.querySelector(".theme-body");
+                return toolboxBody;
+            },
+            () => {
+                toolboxBody.style = "pointer-events: all !important";
+            }
+            );
+        },
+        }
+    );
+    
+    function waitUntil(condition, callback, interval = 100, timeout = 10000) {
+        const start = Date.now();
+        const intervalId = setInterval(() => {
+        if (condition()) {
+            clearInterval(intervalId);
+            callback();
+        } else if (Date.now() - start > timeout) {
+            clearInterval(intervalId);
+        }
+        }, interval);
+    }  
+    })()`;
+        const url = `zotero://ztoolkit-debug/?run=${encodeURIComponent(openDevToolScript)}`;
+        const startZoteroCmd = `"${this.zoteroBinPath}" --debugger --purgecaches -profile "${this.profilePath}"`;
+        const command = `${startZoteroCmd} -url "${url}"`;
+        execSync(command);
+    }
+    get zoteroBinPath() {
+        this.logger.debug("zoteroBinPath", process.env.zoteroBinPath);
+        return process.env.zoteroBinPath ?? "";
+    }
+    get profilePath() {
+        this.logger.debug("profilePath", process.env.profilePath);
+        return process.env.profilePath ?? "";
+    }
+    get dataDir() {
+        return process.env.dataDir ?? "";
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,346 @@
+import { type VersionBumpOptions } from "bumpp";
+import { BuildOptions } from "esbuild";
+type RecursivePartial<T> = {
+    [P in keyof T]?: T[P] extends object ? RecursivePartial<T[P]> : T[P];
+};
+export interface UserConfig extends RecursivePartial<ConfigBase> {
+}
+export interface ConfigBase {
+    /**
+     * The source code directories.
+     *
+     * Can be multiple directories, and changes to these directories will be watched when `server` is running.
+     *
+     * 源码目录。
+     *
+     * 可以是多个目录，将在 `server` 运行时监听这些目录的变更。
+     *
+     * @default ["src"]
+     */
+    source: string[];
+    /**
+     * The build directories.
+     *
+     * Scaffold will store the code before packaging after the build at `${dist}/addon`.
+     * Store the packaging results at `${dist}/${package_json.name}.xpi`.
+     *
+     * 构建目录。
+     *
+     * 脚手架将在 `${dist}/addon` 存放构建后打包前的代码。
+     * 在 `${dist}/${package_json.name}.xpi` 存放打包结果。
+     *
+     * @default "build"
+     */
+    dist: string;
+    /**
+     * glob list of static assets
+     *
+     * 静态资源文件。
+     *
+     * - 通常包括图标、ftl 文件、第三方 JavaScript 文件、CSS 文件、XHTML 文件等。
+     * - 是一个 `glob` 模式数组，支持否定模式。
+     * - 除非一个目录没有需要排除的文件，否则不要添加整个目录。
+     *
+     * @see {@link https://github.com/mrmlnc/fast-glob?tab=readme-ov-file#pattern-syntax | Pattern syntax | 语法说明 }
+     *
+     * @default `["src/**\/*.*", "!src/**\/*.ts"]` (no `\`)
+     */
+    assets: string[];
+    /**
+     * placeholders to replace in static assets
+     *
+     * 静态资源文本占位符。
+     *
+     * - 在构建时，脚手架使用占位符的 key 建立正则模式 `/__${key}__/g`，并将匹配到的内容替换为 `value`。
+     * - 以下是一些预置的占位符，你可以在这里覆盖它们：
+     *   - `name`, `description`, `version`, `homepage`, `author` 从 `package.json` 读取。
+     *   - `__buildTime__` 为 `build.run` 调用时间。
+     *   - 出于兼容性考虑，`addonName`, `addonID`, `addonRef`, `addonInstense`, `prefsPrefix`, `releasePage` 也可以在 `package.json` 中的 `config` 属性中读取。
+     *   - 优先级：此处 > package.json > default
+     * - 替换发生在 `assets` 下的所有文件。
+     */
+    define: {
+        [key: string]: string | unknown;
+        /**
+         * The name of plugin
+         *
+         * 插件名
+         *
+         * @default _.startCase(pkg.name)
+         */
+        addonName: string;
+        /**
+         * 插件 ID
+         */
+        addonID: string;
+        author: string;
+        description: string;
+        homepage: string;
+        ghOwner: string;
+        ghRepo: string;
+        /**
+         * namespace of plugin
+         *
+         * 插件命名空间
+         *
+         * @default _.kebabCase(addonName)
+         */
+        addonRef: string;
+        /**
+         * 插件注册在 Zotero 下的实例
+         *
+         * @default _.camelCase(addonName)
+         */
+        addonInstance: string;
+        /**
+         * 插件首选项前缀
+         *
+         * @default `extensions.zotero.${addonRef}`
+         */
+        prefsPrefix: string;
+        /**
+         * @default pkg.version
+         */
+        buildVersion: string;
+        /**
+         * 打包 XPI 的文件名，不需要加后缀名
+         *
+         * @default pkg.name || _.kebabCase(addonName)
+         */
+        xpiName: string;
+        /**
+         * 插件发布页面
+         *
+         * 脚手架根据这个地址生成 update.json 地址和 xpi 地址
+         *
+         * @default `https://github.com/${owner}/${repo}/release`
+         */
+        releasePage: string;
+        /**
+         * XPI 文件的地址
+         *
+         * @default `${releasePage}/download/v${pkg.version}/${xpiName}.xpi`
+         */
+        updateLink: string;
+        /**
+         * update.json 文件的地址
+         *
+         * @default `${releasePage}/download/release/update.json`
+         */
+        updateURL: string;
+    };
+    fluent: {
+        /**
+         * 为所有 FTL 文件添加插件前缀以避免冲突
+         *
+         * 默认前缀为 `${addonRef}-`
+         *
+         * @default true
+         */
+        prefixLocaleFiles: boolean;
+        /**
+         * 为所有 FTL message 添加插件前缀以避免冲突
+         *
+         * 默认前缀为 `${addonRef}-`
+         *
+         * @default true
+         */
+        prefixFluentMessages: boolean;
+    };
+    /**
+     * The config of esbuild
+     *
+     * esbuild 配置
+     *
+     * 注意：
+     * - 默认配置中 `source` 和 `dist` 会跟随用户配置.
+     * - 此项配置会覆盖默认配置而不是在默认配置列表上新增.
+     *
+     * @default
+     *
+     * ```js
+     * {
+     *   entryPoints: [`${source}/index.ts`],
+     *   define: {
+     *     __env__: `"${env.NODE_ENV}"`,
+     *   },
+     *   bundle: true,
+     *   target: "firefox102",
+     *   outfile: `build/addon/${addonRef}.js`,
+     *   minify: env.NODE_ENV === "production",
+     * };
+     * ```
+     */
+    esbuildOptions: BuildOptions[];
+    /**
+     * Make manifest.json
+     *
+     */
+    makeManifest: {
+        /**
+         * 是否使用内置的模板 manifest.json。
+         * 如果此项为 false，则开发者应自行准备 manifest.json
+         *
+         * @default true
+         */
+        enable: boolean;
+        /**
+         * template of manifest
+         *
+         * @default
+         *
+         * ```json
+         * {
+         *   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",
+         *   },
+         *   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",
+         *     };
+         *   };
+         * };
+         * ```
+         */
+        template: Manifest;
+    };
+    /**
+     * 是否使用内置的模板 bootstrap。
+     * 如果此项为 false，则开发者应自行准备 bootstrap.js。
+     *
+     * @default true
+     */
+    makeBootstrap: boolean;
+    /**
+     * 是否使用内置的模板 update.json。
+     * 如果此项为 false，则开发者应自行准备 update.json。
+     *
+     * @default true
+     */
+    makeUpdateJson: {
+        enable: boolean | "only-production";
+        template: UpdateJSON;
+        tagName: "release" | "updater" | string;
+    };
+    /**
+     * The function called when build-in build resolved.
+     *
+     * Usually some extra build process.
+     * All configurations will be parameterized to this function.
+     *
+     * 在默认构建步骤执行结束后执行的函数.
+     *
+     * 通常是一些额外的构建流程.
+     * 所有的配置将作为参数传入此函数.
+     *
+     * @default ()=>{}
+     */
+    extraBuilder: (options: Config) => any | Promise<any>;
+    /**
+     * The function called after Zotero started, before build-in watcher ready.
+     *
+     * @default ()=>{}
+     */
+    extraServer: (options: Config) => any | Promise<any>;
+    /**
+     * TODO: 使用 addonLint 检查 XPI
+     */
+    addonLint: object;
+    /**
+     * .dotenv 文件路径
+     *
+     * @default `.env`
+     */
+    dotEnvPath: string;
+    /**
+     * 发布相关配置
+     */
+    release: {
+        releaseIt: Partial<ReleaseItConfig>;
+        bumpp: VersionBumpOptions;
+    };
+    /**
+     * 日志级别
+     *
+     * @default "info"
+     */
+    logLevel: "trace" | "debug" | "info" | "warn" | "error";
+}
+export interface Config extends ConfigBase {
+    cmd: {
+        zoteroBinPath: string;
+        profilePath: string;
+        dataDir: string;
+    };
+    pkgUser: any;
+    pkgAbsolute: string;
+}
+interface Manifest {
+    [key: string]: any;
+    manifest_version: number;
+    name: string;
+    version: string;
+    description?: string;
+    homepage_url?: string;
+    author?: string;
+    icons?: Record<string, string>;
+    applications: {
+        zotero: {
+            id: string;
+            update_url: string;
+            strict_min_version: string;
+            strict_max_version?: string;
+        };
+        gecko: {
+            id: string;
+            update_url: string;
+            strict_min_version: string;
+        };
+    };
+}
+/**
+ * Update json
+ * @see https://extensionworkshop.com/documentation/manage/updating-your-extension/
+ */
+interface UpdateJSON {
+    addons: {
+        [addonID: string]: {
+            updates: Array<{
+                version: string;
+                update_link?: string;
+                /**
+                 * A cryptographic hash of the file pointed to by `update_link`.
+                 * This must be provided if `update_link` is not a secure URL.
+                 * If present, this must be a string beginning with either `sha256:` or `sha512:`,
+                 * followed by the hexadecimal-encoded hash of the matching type.
+                 */
+                update_hash?: string;
+                applications: {
+                    zotero: {
+                        strict_min_version: string;
+                    };
+                    [application: string]: {
+                        strict_min_version?: string;
+                        strict_max_version?: string;
+                    };
+                };
+            }>;
+        };
+    };
+}
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/crypto.d.ts

@@ -0,0 +1,2 @@
+export declare function generateHash(filePath: string, algorithm: "sha256" | "sha512" | string): Promise<string>;
+export declare function generateHashSync(filePath: string, algorithm: "sha256" | "sha512" | string): string;

package/dist/utils/crypto.js

@@ -0,0 +1,23 @@
+import * as crypto from "crypto";
+import * as fs from "fs";
+export function generateHash(filePath, algorithm) {
+    return new Promise((resolve, reject) => {
+        const hash = crypto.createHash(algorithm);
+        const stream = fs.createReadStream(filePath);
+        stream.on("data", (data) => {
+            hash.update(data);
+        });
+        stream.on("end", () => {
+            const fileHash = hash.digest("hex");
+            resolve(`${algorithm}:${fileHash}`);
+        });
+        stream.on("error", (error) => {
+            reject(error);
+        });
+    });
+}
+export function generateHashSync(filePath, algorithm) {
+    const data = fs.readFileSync(filePath);
+    const hash = crypto.createHash(algorithm).update(data).digest("hex");
+    return `${algorithm}:${hash}`;
+}

package/dist/utils/libBase.d.ts

@@ -0,0 +1,15 @@
+import { Config } from "../types.js";
+import Log from "./log.js";
+export declare abstract class LibBase {
+    config: Config;
+    logger: InstanceType<typeof Log>;
+    constructor(config: Config);
+    get version(): string;
+    get addonName(): string;
+    get addonID(): string;
+    get addonRef(): string;
+    get addonInstence(): string;
+    get updateLink(): string;
+    get updateURL(): string;
+    get xpiName(): string;
+}

package/dist/utils/libBase.js

@@ -0,0 +1,33 @@
+import Log from "./log.js";
+export class LibBase {
+    config;
+    logger;
+    constructor(config) {
+        this.config = config;
+        this.logger = new Log(config);
+    }
+    get version() {
+        return this.config.define.buildVersion;
+    }
+    get addonName() {
+        return this.config.define.addonName;
+    }
+    get addonID() {
+        return this.config.define.addonID;
+    }
+    get addonRef() {
+        return this.config.define.addonRef;
+    }
+    get addonInstence() {
+        return this.config.define.addonInstance;
+    }
+    get updateLink() {
+        return this.config.define.updateLink;
+    }
+    get updateURL() {
+        return this.config.define.updateURL;
+    }
+    get xpiName() {
+        return this.config.define.xpiName;
+    }
+}

package/dist/utils/log.d.ts

@@ -0,0 +1,11 @@
+import { Config } from "../types";
+export default class Log {
+    private logLevel;
+    constructor(config?: Config);
+    log(...args: any[]): void;
+    error(...args: any[]): void;
+    warn(...args: any[]): void;
+    info(...args: any[]): void;
+    debug(...args: any[]): void;
+    trace(...args: any[]): void;
+}