@pagepocket/cli 0.8.0 → 0.8.2

package/README.md

@@ -61,6 +61,12 @@ Notes:
 - During `pp archive ...`, the CLI reads `config.json` and tries to load all configured plugins.
   If a plugin fails to load, it will be skipped and the archive will continue.
 
+Plugin packages are installed to your user data directory (not the config directory):
+
+- Linux: `~/.local/share/pagepocket/plugins/`
+- macOS: `~/Library/Application Support/pagepocket/plugins/`
+- Windows: `%APPDATA%\\pagepocket\\plugins\\`
+
 ## Output
 
 Snapshots are written to a folder named after the page title inside the output

package/dist/commands/archive.js

@@ -12,9 +12,9 @@ const lib_1 = require("@pagepocket/lib");
 const single_file_unit_1 = require("@pagepocket/single-file-unit");
 const write_down_unit_1 = require("@pagepocket/write-down-unit");
 const chalk_1 = __importDefault(require("chalk"));
+const load_configured_plugins_1 = require("../services/load-configured-plugins");
 const network_observer_unit_1 = require("../units/network-observer-unit");
 const with_spinner_1 = require("../utils/with-spinner");
-const load_configured_plugins_1 = require("../services/load-configured-plugins");
 const MAX_STATUS_URL_LENGTH = 80;
 const formatStatusUrl = (url) => {
     if (url.length <= MAX_STATUS_URL_LENGTH) {

package/dist/commands/plugin/add.js

@@ -8,6 +8,8 @@ const chalk_1 = __importDefault(require("chalk"));
 const config_service_1 = require("../../services/config-service");
 const plugin_installer_1 = require("../../services/plugin-installer");
 const plugin_store_1 = require("../../services/plugin-store");
+const parse_plugin_spec_1 = require("../../utils/parse-plugin-spec");
+const validate_plugin_default_export_1 = require("../../utils/validate-plugin-default-export");
 const parseDynamicOptions = (argv) => {
     const tokens = argv.filter(Boolean);
     const pairs = tokens
@@ -56,29 +58,35 @@ class PluginAddCommand extends core_1.Command {
             this.log("Usage: pp plugin add <plugin-name> [--option-* <value> ...] [--option <value> ...]");
             return;
         }
+        const parsedSpec = (0, parse_plugin_spec_1.parsePluginSpec)(name);
         const configService = new config_service_1.ConfigService();
         const store = new plugin_store_1.PluginStore(configService);
         configService.ensureConfigFileExists();
         const config = configService.readConfigOrDefault();
-        if (store.hasPlugin(config, name)) {
-            this.log(chalk_1.default.gray(`Plugin already exists in config: ${name}`));
+        if (store.hasPlugin(config, parsedSpec.name)) {
+            this.log(chalk_1.default.gray(`Plugin already exists in config: ${parsedSpec.name}`));
             return;
         }
         const parsed = parseDynamicOptions(rest);
         const entry = parsed.kind === "none"
-            ? name
+            ? parsedSpec.name
             : parsed.kind === "array"
-                ? { name, options: parsed.value }
-                : { name, options: parsed.value };
-        (0, plugin_installer_1.installPluginPackage)(store, { packageName: name });
-        const mod = await store.importPluginModule(name);
-        if (typeof mod.default !== "function") {
-            throw new Error(`Plugin ${name} must have a default export (class).`);
+                ? { name: parsedSpec.name, spec: parsedSpec.spec, options: parsed.value }
+                : { name: parsedSpec.name, spec: parsedSpec.spec, options: parsed.value };
+        (0, plugin_installer_1.installPluginPackage)(store, { packageName: parsedSpec.spec });
+        const mod = await store.importPluginModule(parsedSpec.name);
+        const validation = (0, validate_plugin_default_export_1.validatePluginDefaultExport)({
+            pluginName: parsedSpec.name,
+            moduleExports: mod,
+            options: parsed.kind === "none" ? undefined : parsed.value
+        });
+        if (!validation.ok) {
+            throw validation.error;
         }
         const nextConfig = store.addPluginToConfig(config, entry);
         configService.writeConfig(nextConfig);
-        await store.runOptionalSetup(name);
-        this.log(chalk_1.default.green(`Added plugin: ${name}`));
+        await store.runOptionalSetup(parsedSpec.name);
+        this.log(chalk_1.default.green(`Added plugin: ${parsedSpec.name}`));
     }
 }
 PluginAddCommand.description = "Install a plugin package, add it to config, and run its optional setup().";

package/dist/commands/plugin/ls.js

@@ -21,15 +21,22 @@ class PluginLsCommand extends core_1.Command {
         entries
             .map((entry) => {
             const name = typeof entry === "string" ? entry : entry.name;
+            const configuredSpec = typeof entry === "string"
+                ? undefined
+                : typeof entry.spec === "string" && entry.spec.trim().length > 0
+                    ? entry.spec
+                    : undefined;
             const meta = store.readInstalledPackageMeta(name);
             if (!meta) {
-                return `${chalk_1.default.yellow(name)} ${chalk_1.default.gray("(not installed)")}`;
+                const specText = configuredSpec ? chalk_1.default.gray(`(configured: ${configuredSpec})`) : "";
+                return `${chalk_1.default.yellow(name)} ${chalk_1.default.gray("(not installed)")} ${specText}`.trim();
             }
+            const specText = configuredSpec ? chalk_1.default.gray(`(configured: ${configuredSpec})`) : "";
             const desc = meta.description
                 ? chalk_1.default.gray(meta.description)
                 : chalk_1.default.gray("(no description)");
             const version = meta.version ? chalk_1.default.cyan(`v${meta.version}`) : chalk_1.default.gray("(no version)");
-            return `${chalk_1.default.green(meta.name)} ${version}  ${desc}`;
+            return `${chalk_1.default.green(meta.name)} ${version} ${specText}  ${desc}`.replace(/\s{2,}/g, "  ");
         })
             .forEach((line) => this.log(line));
     }

package/dist/services/config-service.js

@@ -25,11 +25,15 @@ class ConfigService {
         const base = xdgConfigHome && xdgConfigHome.trim() ? xdgConfigHome : node_path_1.default.join(homeDir, ".config");
         return node_path_1.default.join(base, this.appName);
     }
+    getDataDir() {
+        const p = (0, env_paths_1.default)(this.appName, { suffix: "" });
+        return p.data;
+    }
     getConfigPath() {
         return node_path_1.default.join(this.getConfigDir(), "config.json");
     }
     getPluginsInstallDir() {
-        return node_path_1.default.join(this.getConfigDir(), "plugins");
+        return node_path_1.default.join(this.getDataDir(), "plugins");
     }
     ensureConfigDirExists() {
         this.ensureDirExists(this.getConfigDir());
@@ -61,9 +65,11 @@ class ConfigService {
                 return entry;
             }
             if (this.isObject(entry) && typeof entry.name === "string") {
+                const spec = "spec" in entry && typeof entry.spec === "string" ? entry.spec : undefined;
                 const options = "options" in entry ? entry.options : undefined;
                 return {
                     name: entry.name,
+                    ...(typeof spec === "undefined" ? {} : { spec }),
                     ...(typeof options === "undefined" ? {} : { options })
                 };
             }

package/dist/services/load-configured-plugins.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadConfiguredPlugins = void 0;
+const validate_plugin_default_export_1 = require("../utils/validate-plugin-default-export");
 const config_service_1 = require("./config-service");
 const plugin_store_1 = require("./plugin-store");
 const loadConfiguredPlugins = async () => {
@@ -11,12 +12,17 @@ const loadConfiguredPlugins = async () => {
     const specs = config.plugins.map(plugin_store_1.normalizePluginConfigEntry);
     const loaded = await Promise.all(specs.map(async (spec) => {
         try {
-            const p = await store.instantiatePluginFromSpec(spec);
-            if (!p || typeof p.setup !== "function") {
-                console.error(`Skipping plugin ${spec.name}: default export is not a PagePocket plugin instance.`);
+            const mod = await store.importPluginModule(spec.name);
+            const validation = (0, validate_plugin_default_export_1.validatePluginDefaultExport)({
+                pluginName: spec.name,
+                moduleExports: mod,
+                options: spec.options
+            });
+            if (!validation.ok) {
+                console.error(`Skipping plugin ${spec.name}: ${validation.error.message}`);
                 return null;
             }
-            return p;
+            return validation.plugin;
         }
         catch (e) {
             const msg = e && typeof e.message === "string"

package/dist/services/plugin-store.js

@@ -5,8 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PluginStore = exports.getPluginNameFromSpec = exports.normalizePluginConfigEntry = void 0;
 const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
 const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
 const node_url_1 = require("node:url");
 const normalizePluginConfigEntry = (entry) => {
     if (typeof entry === "string") {
@@ -14,6 +14,7 @@ const normalizePluginConfigEntry = (entry) => {
     }
     return {
         name: entry.name,
+        ...(typeof entry.spec === "string" ? { spec: entry.spec } : {}),
         ...(typeof entry.options === "undefined" ? {} : { options: entry.options })
     };
 };
@@ -44,10 +45,22 @@ class PluginStore {
         node_fs_1.default.writeFileSync(pkgJsonPath, `${JSON.stringify(pkgJson, null, 2)}\n`, "utf8");
         return pkgJsonPath;
     }
-    createPluginsRequire() {
-        const pkgJsonPath = this.ensurePluginPackageJson();
+    createPluginsRequireFromDir(dirPath) {
+        const pkgJsonPath = node_path_1.default.join(dirPath, "package.json");
+        if (!node_fs_1.default.existsSync(pkgJsonPath)) {
+            const pkgJson = {
+                name: "pagepocket-user-plugins",
+                private: true,
+                version: "0.0.0"
+            };
+            node_fs_1.default.writeFileSync(pkgJsonPath, `${JSON.stringify(pkgJson, null, 2)}\n`, "utf8");
+        }
         return (0, node_module_1.createRequire)(pkgJsonPath);
     }
+    createPluginsRequire() {
+        this.ensurePluginPackageJson();
+        return this.createPluginsRequireFromDir(this.getInstallDir());
+    }
     resolveInstalledPackageJsonPath(pluginName) {
         const req = this.createPluginsRequire();
         return req.resolve(`${pluginName}/package.json`);
@@ -74,6 +87,9 @@ class PluginStore {
     async importPluginModule(pluginName) {
         const req = this.createPluginsRequire();
         const resolved = req.resolve(pluginName);
+        return this.importResolvedPath(resolved);
+    }
+    async importResolvedPath(resolved) {
         const dynamicImport = new Function("specifier", "return import(specifier)");
         const mod = await dynamicImport((0, node_url_1.pathToFileURL)(resolved).href);
         return (mod ?? {});

package/dist/utils/parse-plugin-spec.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePluginSpec = void 0;
+const parsePluginSpec = (spec) => {
+    const trimmed = spec.trim();
+    if (!trimmed) {
+        throw new Error("plugin spec is empty");
+    }
+    const npa = require("npm-package-arg");
+    const parsed = npa(trimmed);
+    if (!parsed || typeof parsed.name !== "string" || !parsed.name) {
+        throw new Error(`Invalid plugin spec: ${trimmed}`);
+    }
+    return { name: parsed.name, spec: trimmed };
+};
+exports.parsePluginSpec = parsePluginSpec;

package/dist/utils/validate-plugin-default-export.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePluginDefaultExport = void 0;
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const toError = (value) => {
+    if (value instanceof Error) {
+        return value;
+    }
+    return new Error(typeof value === "string" ? value : JSON.stringify(value));
+};
+const validatePluginDefaultExport = (input) => {
+    const { pluginName, moduleExports, options } = input;
+    const defaultExport = moduleExports.default;
+    if (typeof defaultExport !== "function") {
+        return {
+            ok: false,
+            error: new Error(`Plugin ${pluginName} must default export a class/constructor.`)
+        };
+    }
+    const ctor = defaultExport;
+    try {
+        const instance = typeof options === "undefined"
+            ? new ctor()
+            : Array.isArray(options)
+                ? new ctor(...options)
+                : new ctor(options);
+        if (!isRecord(instance)) {
+            return {
+                ok: false,
+                error: new Error(`Plugin ${pluginName} default export did not construct an object.`)
+            };
+        }
+        const name = instance.name;
+        if (typeof name !== "string" || name.trim().length === 0) {
+            return {
+                ok: false,
+                error: new Error(`Plugin ${pluginName} instance must have a non-empty string 'name'.`)
+            };
+        }
+        const setup = instance.setup;
+        if (typeof setup !== "function") {
+            return {
+                ok: false,
+                error: new Error(`Plugin ${pluginName} instance must implement setup(host).`)
+            };
+        }
+        const contribute = instance.contribute;
+        if (typeof contribute !== "undefined" && typeof contribute !== "function") {
+            return {
+                ok: false,
+                error: new Error(`Plugin ${pluginName} contribute must be a function if provided.`)
+            };
+        }
+        return { ok: true, plugin: instance };
+    }
+    catch (e) {
+        return { ok: false, error: toError(e) };
+    }
+};
+exports.validatePluginDefaultExport = validatePluginDefaultExport;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pagepocket/cli",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "CLI for capturing offline snapshots of web pages.",
   "main": "dist/index.js",
   "bin": {
@@ -15,26 +15,27 @@
   "dependencies": {
     "@oclif/core": "^4.0.9",
     "chalk": "^4.1.2",
+    "env-paths": "^2.2.1",
     "koa": "^2.16.2",
     "koa-send": "^5.0.1",
     "koa-static": "^5.0.0",
+    "npm-package-arg": "^13.0.2",
     "ora": "^9.0.0",
-    "env-paths": "^2.2.1",
-    "@pagepocket/lib": "0.8.0",
-    "@pagepocket/capture-http-cdp-unit": "0.8.0",
-    "@pagepocket/capture-http-puppeteer-unit": "0.8.0",
-    "@pagepocket/build-snapshot-unit": "0.8.0",
-    "@pagepocket/capture-http-lighterceptor-unit": "0.8.0",
-    "@pagepocket/plugin-yt-dlp": "0.8.0",
-    "@pagepocket/single-file-unit": "0.8.0",
-    "@pagepocket/write-down-unit": "0.8.0",
-    "@pagepocket/contracts": "0.8.0"
+    "@pagepocket/build-snapshot-unit": "0.8.2",
+    "@pagepocket/capture-http-puppeteer-unit": "0.8.2",
+    "@pagepocket/capture-http-cdp-unit": "0.8.2",
+    "@pagepocket/contracts": "0.8.2",
+    "@pagepocket/lib": "0.8.2",
+    "@pagepocket/capture-http-lighterceptor-unit": "0.8.2",
+    "@pagepocket/plugin-yt-dlp": "0.8.2",
+    "@pagepocket/single-file-unit": "0.8.2",
+    "@pagepocket/write-down-unit": "0.8.2"
   },
   "devDependencies": {
-    "@types/node": "^20.11.30",
     "@types/koa": "^2.15.0",
     "@types/koa-send": "^4.1.5",
     "@types/koa-static": "^4.0.4",
+    "@types/node": "^20.11.30",
     "tsx": "^4.19.3",
     "typescript": "^5.4.5"
   },