zotero-plugin-scaffold 0.0.4

package/README.md

@@ -0,0 +1,168 @@
+# Zotero Plugin Development Scaffold
+
+Working in progress.
+
+Create a standalone npm package for scripts in the zotero-plugin-template repository, so that downstream developers can follow along.
+
+This repository serves only as a proof-of-concept for the above.
+
+## Using in a blank project
+
+> WIP
+
+```bash
+# npm
+npx zotero-plugin create
+# pnpm
+pnpm dlx zotero-plugin create
+```
+
+## Using in an existing project
+
+### 01. Install
+
+#### From NPM
+
+> WIP
+
+```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 run build
+
+# 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. If the configuration file is not found, an error will be thrown.
+
+```bash
+zotero-plugin.config.ts
+# also avaliable in *.js  *.mjs  *.cjs  *.ts
+# Or The `zotero-plugin`` property in `package.json`
+# see https://github.com/cosmiconfig/cosmiconfig?tab=readme-ov-file#usage-for-end-users
+```
+
+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.
+
+```ts
+import { defineConfig } from "zotero-plugin-scaffold";
+
+export default defineConfig({
+  placeholders: {
+    addonName: "Test Addon for Zotero",
+    addonID: "",
+    addonRef: "",
+    addonInstance: "",
+    updateJSON: "",
+    releasePage: ""
+  },
+});
+```
+
+Full config please refrence in [src/types.ts](./src/types.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
+# Please input the path of the Zotero binary file in `zoteroBinPath`.
+# The path delimiter should be escaped as `\\` for win32. The path is `*/Zotero.app/Contents/MacOS/zotero` for MacOS.
+zoteroBinPath = /path/to/zotero.exe
+
+# Please input the path of the profile used for development in `profilePath`.
+# Start the profile manager by `/path/to/zotero.exe -p` to create a profile for development
+# https://www.zotero.org/support/kb/profile_directory
+profilePath = /path/to/profile
+
+# Please input the directory where the database is located in dataDir
+# If this field is kept empty, Zotero will start with the default data.
+# https://www.zotero.org/support/zotero_data
+dataDir =
+
+# Other environment variables (optional)
+# GITHUB_TOKEN =
+```
+
+### 04. Add scripts to package.json
+
+```json
+{
+  "scripts": {
+    "start": "zotero-plugin server",
+    "build": "zotero-plugin build",
+    "release": "zotero-plugin release"
+  }
+}
+```
+
+### 05. Run
+
+```bash
+pnpm run start
+pnpm run build
+
+# Or, run cmd in terminal
+pnpm exec zotero-plugin build
+```
+
+## Using in NodeJS code
+
+```ts
+import { Build, Config } from "zotero-plugin-scaffold";
+
+const config = await Config.loadConfig();
+
+const Builder = new Build(config, "production");
+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
+
+# Watch
+pnpm run dev
+
+# Build
+pnpm run build
+
+# Lint and Prettier
+pnpm run lint:fix
+```
+
+## Acknowledgements
+
+This project references the design and code of the [Zotero Plugin Template](https://github.com/windingwind/zotero-plugin-template).
+
+This project would not be possible without the support of the [open source community](https://github.com/northword/zotero-plugin-scaffold/network/dependencies).

package/bin/zotero-plugin.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import cli from "../dist/cli.js";
+import Log from "../dist/utils/log.js";
+
+const Logger = new Log();
+
+cli();
+
+process.on("unhandledRejection", (err) => {
+  Logger.log("");
+  Logger.error(err);
+  Logger.log("");
+
+  process.exit(1);
+});

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export default function main(): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,81 @@
+import { Build, Config, Create, Release, Serve } from "./index.js";
+import Log from "./utils/log.js";
+import { Command } from "commander";
+import { default as fs } from "fs-extra";
+import _ from "lodash";
+import path from "path";
+import updateNotifier from "update-notifier";
+import { fileURLToPath } from "url";
+export default async function main() {
+    const Logger = new Log();
+    // Use readFileSync instead of import json to avoid loging warning
+    const pkg = fs.readJsonSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "../package.json"), {
+        encoding: "utf-8",
+    });
+    updateNotifier({ pkg: pkg }).notify();
+    // Env variables are initialized to dev, but can be overridden by each command
+    // For example, "zotero-plugin build" overrides them to "production"
+    process.env.NODE_ENV ??= "development";
+    const cli = new Command();
+    cli.version(pkg.version).usage("<command> [options]");
+    cli
+        .command("build")
+        .description("Build the plugin.")
+        .option("--dev", "Builds the plugin in dev mode.")
+        .option("--dist <dir>", "the full path for the new output directory, relative to the current workspace (default: build)")
+        .option("--config <config>", "path to zotero-plugin config file (default: `zotero-plugin.config.ts`)")
+        .action(async (options) => {
+        process.env.NODE_ENV = options.dev ? "development" : "production";
+        const configFile = await Config.loadConfig(options.config);
+        const configCli = {
+            dist: options.dist,
+        };
+        const configMerged = _.merge(configFile, configCli);
+        new Build(configMerged).run();
+    });
+    cli
+        .command("serve")
+        .description("Start development server.")
+        .option("--config <config>", "path to zotero-plugin config file (default: `zotero-plugin.config.ts`)")
+        // .option(
+        //   "--skip-build",
+        //   "skip building website before deploy it (default: false)",
+        // )
+        // .option(
+        //   "--only-start",
+        //   "skip building website before deploy it (default: false)",
+        // )
+        .action(async (options) => {
+        const configFile = await Config.loadConfig(options.config);
+        const configCli = {
+        //
+        };
+        const configMerged = _.merge(configFile, configCli);
+        new Serve(configMerged).run();
+    });
+    cli
+        .command("create")
+        .description("Create the plugin template.")
+        .action((options) => {
+        console.log("The create not yet implemented");
+        new Create().run();
+    });
+    cli
+        .command("release")
+        .description("Release.")
+        .option("--config <config>", "path to zotero-plugin config file (default: `zotero-plugin.config.ts`)")
+        .action(async (options) => {
+        process.env.NODE_ENV = "production";
+        const configFile = await Config.loadConfig(options.config);
+        const configCli = {
+        //
+        };
+        const configMerged = _.merge(configFile, configCli);
+        new Release(configMerged).run();
+    });
+    cli.arguments("<command>").action((cmd) => {
+        cli.outputHelp();
+        Logger.error(`Unknown command name=${cmd}.`);
+    });
+    cli.parse(process.argv);
+}

package/dist/config.d.ts

@@ -0,0 +1,15 @@
+import { Config, UserConfig } from "./types";
+/**
+ * Define the configuration.
+ *
+ * Defines the configuration in the parameters of this function to provide type checking for user configurations.
+ * @param [userConfig]
+ * @returns Config with userDefined.
+ */
+export declare const defineConfig: (userConfig: UserConfig) => UserConfig;
+/**
+ * Loads config
+ * @param [file="zotero-plugin.config.{ts,js,mjs,cjs}"] The path of config file.
+ * @returns Config with userDefined and defaultConfig merged.
+ */
+export declare function loadConfig(file?: string): Promise<Config>;

package/dist/config.js

@@ -0,0 +1,174 @@
+import { cosmiconfig } from "cosmiconfig";
+import * as dotenv from "dotenv";
+import { default as fs } from "fs-extra";
+import _ from "lodash";
+import path from "path";
+import { fileURLToPath } from "url";
+/**
+ * Define the configuration.
+ *
+ * Defines the configuration in the parameters of this function to provide type checking for user configurations.
+ * @param [userConfig]
+ * @returns Config with userDefined.
+ */
+export const defineConfig = (userConfig) => {
+    return userConfig;
+};
+/**
+ * Loads config
+ * @param [file="zotero-plugin.config.{ts,js,mjs,cjs}"] The path of config file.
+ * @returns Config with userDefined and defaultConfig merged.
+ */
+export async function loadConfig(file) {
+    // load user defined config file
+    // Do not use the sync method, as the sync method only supports compiling configuration files into cjs modules.
+    const explorer = cosmiconfig("zotero-plugin"), result = await explorer.search(file);
+    const userConfig = result?.config ?? {};
+    // load `.env` file.
+    const dotenvResult = dotenv.config({
+        path: path.resolve(process.cwd(), userConfig.dotEnvPath ?? ".env"),
+    }).parsed;
+    if (!dotenvResult)
+        throw new Error(".env file not found");
+    // Load user's package.json
+    const pkg = fs.readJsonSync(path.join("package.json"), {
+        encoding: "utf-8",
+    });
+    // define addon config 防呆
+    const addonName = userConfig.define?.addonName ||
+        pkg.config?.addonName ||
+        _.startCase(pkg.name) ||
+        "", addonRef = userConfig.define?.addonRef ||
+        pkg.config?.addonRef ||
+        _.kebabCase(addonName), xpiName = userConfig.define?.xpiName || pkg.name || _.kebabCase(addonName), [, owner, repo] = (pkg.repository?.url ?? "").match(/:\/\/github.com\/([^/]+)\/([^.]+)\.git$/), releasePage = userConfig.define?.releasePage ||
+        (owner && repo ? `https://github.com/${owner}/${repo}/release` : ""), isPreRelease = pkg.version.includes("-");
+    // define default config.
+    const defaultConfig = {
+        source: ["src"],
+        dist: "build",
+        assets: ["src/**/*.*", "!src/**/*.ts"],
+        define: {
+            addonName: addonName,
+            addonID: pkg.config?.addonID || "",
+            description: pkg.description || "",
+            homepage: pkg.homepage,
+            author: pkg.author,
+            ghOwner: owner,
+            ghRepo: repo,
+            addonRef: pkg.config?.addonRef || _.kebabCase(addonName),
+            addonInstance: pkg.config?.addonInstence || _.camelCase(addonName),
+            prefsPrefix: `extensions.zotero.${addonRef}`,
+            xpiName: xpiName,
+            releasePage: releasePage,
+            updateURL: `${releasePage}/download/${userConfig.makeUpdateJson?.tagName || "release"}/${isPreRelease ? "update-beta" : "update"}.json`,
+            updateLink: `${releasePage}/download/v${pkg.version}/${xpiName}.xpi`,
+            buildVersion: pkg.version,
+        },
+        fluent: {
+            prefixFluentMessages: true,
+            prefixLocaleFiles: true,
+        },
+        esbuildOptions: [
+            {
+                entryPoints: ["src/index.ts"],
+                define: {
+                    __env__: `"${process.env.NODE_ENV}"`,
+                },
+                bundle: true,
+                target: "firefox102",
+                outfile: path.join(process.cwd(), userConfig.dist || "build", `addon/${addonRef || "index"}.js`),
+                minify: process.env.NODE_ENV === "production",
+            },
+        ],
+        makeBootstrap: true,
+        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",
+                },
+                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",
+                    },
+                },
+            },
+        },
+        makeUpdateJson: {
+            enable: true,
+            tagName: "release",
+            template: {
+                addons: {
+                    __addonID__: {
+                        updates: [
+                            {
+                                version: "__version__",
+                                update_link: "__updateLink__",
+                                update_hash: "__updateHash__",
+                                applications: {
+                                    zotero: {
+                                        strict_min_version: "6.999",
+                                    },
+                                },
+                            },
+                        ],
+                    },
+                },
+            },
+        },
+        extraServer: () => { },
+        extraBuilder: () => { },
+        addonLint: {},
+        release: {
+            releaseIt: {
+                preReleaseId: "beta",
+                git: {
+                    tagName: "v${version}",
+                    requireCleanWorkingDir: false,
+                },
+                npm: {
+                    publish: false,
+                },
+                github: {
+                    assets: [`${userConfig.dist}/*.xpi`],
+                },
+            },
+            bumpp: {
+                release: "prompt",
+                preid: "beta",
+                // execute: "npm run build",
+                all: true,
+                commit: "Release v%s",
+                tag: "v%s",
+                push: true,
+            },
+        },
+        logLevel: "info",
+        dotEnvPath: ".env",
+        cmd: {
+            zoteroBinPath: dotenvResult["zoteroBinPath"],
+            profilePath: dotenvResult["profilePath"],
+            dataDir: dotenvResult["dataDir"],
+        },
+        pkgUser: pkg,
+        pkgAbsolute: path.join(path.dirname(fileURLToPath(import.meta.url)), "../"),
+    };
+    // merge config
+    const config = _.defaultsDeep(userConfig, defaultConfig);
+    return config;
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { defineConfig, loadConfig } from "./config.js";
+import Build from "./lib/build.js";
+import Create from "./lib/create.js";
+import Release from "./lib/release.js";
+import Serve from "./lib/serve.js";
+declare const Config: {
+    defineConfig: (userConfig: import("./types.js").UserConfig) => import("./types.js").UserConfig;
+    loadConfig: typeof loadConfig;
+};
+export { defineConfig, Config, Create, Build, Serve, Release };

package/dist/index.js

@@ -0,0 +1,10 @@
+import { defineConfig, loadConfig } from "./config.js";
+import Build from "./lib/build.js";
+import Create from "./lib/create.js";
+import Release from "./lib/release.js";
+import Serve from "./lib/serve.js";
+const Config = {
+    defineConfig,
+    loadConfig,
+};
+export { defineConfig, Config, Create, Build, Serve, Release };

package/dist/lib/build.d.ts

@@ -0,0 +1,25 @@
+import { Config } from "../types.js";
+import { LibBase } from "../utils/libBase.js";
+export default class Build extends LibBase {
+    private buildTime;
+    private isPreRelease;
+    constructor(config: Config);
+    /**
+     * Default build runner
+     */
+    run(): Promise<void>;
+    /**
+     * Copys files in `Config.assets` to `Config.dist`
+     */
+    copyAssets(): void;
+    makeManifest(): void;
+    makebootstrap(): void;
+    /**
+     * Replace all `placeholder.key` to `placeholder.value` for all files in `dist`
+     */
+    replaceString(): void;
+    prepareLocaleFiles(): void;
+    esbuild(): void;
+    makeUpdateJson(): void;
+    pack(): Promise<void>;
+}