@pagepocket/cli 0.9.0 → 0.9.2

package/README.md

@@ -39,8 +39,12 @@ Manage configured plugins:
 ```bash
 pp plugin ls
 pp plugin add <plugin-name>
+pp plugin set <plugin-name> [...options]
 pp plugin update [plugin-name]
+pp plugin doctor [plugin-name]
 pp plugin remove <plugin-name>
+pp plugin uninstall <plugin-name> [--from-config]
+pp plugin prune
 ```
 
 Options passing:
@@ -59,8 +63,12 @@ pp plugin add @scope/plugin --option 1 --option 2
 Notes:
 
 - `pp plugin remove` only removes the entry from `config.json` (it does not uninstall the package).
+- `pp plugin set` updates options for an already configured plugin.
 - `pp plugin update <plugin-name>` reinstalls that plugin to `latest`.
 - `pp plugin update` reinstalls all configured plugins to `latest`.
+- `pp plugin doctor` checks plugin install/load health and exits non-zero on failures.
+- `pp plugin uninstall <plugin-name>` removes the installed package; add `--from-config` to also remove config.
+- `pp plugin prune` removes installed packages that are no longer referenced in `config.json`.
 - 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.
 

package/dist/commands/plugin/add.js

@@ -8,46 +8,9 @@ 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_options_1 = require("../../utils/parse-plugin-options");
 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
-        .map((t, i) => ({ t, next: tokens[i + 1] }))
-        .filter(({ t }) => t === "--option" || t.startsWith("--option-"));
-    const object = pairs
-        .filter(({ t }) => t.startsWith("--option-"))
-        .reduce((acc, { t, next }) => {
-        const key = t.slice("--option-".length);
-        if (!key) {
-            throw new Error("--option-* key is empty");
-        }
-        if (typeof next === "undefined" || next.startsWith("-")) {
-            throw new Error(`${t} expects a value`);
-        }
-        return { ...acc, [key]: next };
-    }, {});
-    const arrayValues = pairs
-        .filter(({ t }) => t === "--option")
-        .map(({ next }) => {
-        if (typeof next === "undefined" || next.startsWith("-")) {
-            throw new Error("--option expects a value");
-        }
-        return next;
-    });
-    const hasObject = Object.keys(object).length > 0;
-    const hasArray = arrayValues.length > 0;
-    if (hasObject && hasArray) {
-        throw new Error("Cannot mix --option with --option-* flags");
-    }
-    if (hasObject) {
-        return { kind: "object", value: object };
-    }
-    if (hasArray) {
-        return { kind: "array", value: arrayValues };
-    }
-    return { kind: "none" };
-};
 class PluginAddCommand extends core_1.Command {
     async run() {
         const [name, ...rest] = this.argv;
@@ -67,7 +30,7 @@ class PluginAddCommand extends core_1.Command {
             this.log(chalk_1.default.gray(`Plugin already exists in config: ${parsedSpec.name}`));
             return;
         }
-        const parsed = parseDynamicOptions(rest);
+        const parsed = (0, parse_plugin_options_1.parsePluginOptions)(rest);
         const entry = parsed.kind === "none"
             ? parsedSpec.name
             : parsed.kind === "array"
@@ -90,4 +53,5 @@ class PluginAddCommand extends core_1.Command {
     }
 }
 PluginAddCommand.description = "Install a plugin package, add it to config, and run its optional setup().";
+PluginAddCommand.strict = false;
 exports.default = PluginAddCommand;

package/dist/commands/plugin/doctor.js

@@ -0,0 +1,91 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const chalk_1 = __importDefault(require("chalk"));
+const config_service_1 = require("../../services/config-service");
+const plugin_store_1 = require("../../services/plugin-store");
+const parse_plugin_spec_1 = require("../../utils/parse-plugin-spec");
+/**
+ * Validate one configured plugin can be loaded and instantiated.
+ *
+ * Usage:
+ * const result = await runDoctorCheck(store, spec);
+ */
+const runDoctorCheck = async (store, spec) => {
+    const installed = Boolean(store.readInstalledPackageMeta(spec.name));
+    if (!installed) {
+        return {
+            plugin: spec.name,
+            installed: false,
+            loadable: false,
+            error: "not installed"
+        };
+    }
+    try {
+        await store.instantiatePluginFromSpec(spec);
+        return {
+            plugin: spec.name,
+            installed: true,
+            loadable: true
+        };
+    }
+    catch (error) {
+        return {
+            plugin: spec.name,
+            installed: true,
+            loadable: false,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+};
+class PluginDoctorCommand extends core_1.Command {
+    async run() {
+        const { args } = await this.parse(PluginDoctorCommand);
+        const configService = new config_service_1.ConfigService();
+        const store = new plugin_store_1.PluginStore(configService);
+        configService.ensureConfigFileExists();
+        const config = store.readConfig();
+        const targetName = args.name ? (0, parse_plugin_spec_1.parsePluginSpec)(args.name).name : undefined;
+        const configured = config.plugins
+            .map((entry) => (0, plugin_store_1.normalizePluginConfigEntry)(entry))
+            .filter((entry) => {
+            if (!targetName) {
+                return true;
+            }
+            return entry.name === targetName;
+        });
+        if (configured.length === 0) {
+            if (targetName) {
+                this.log(chalk_1.default.gray(`Plugin not found in config: ${targetName}`));
+                return;
+            }
+            this.log(chalk_1.default.gray("No plugins configured."));
+            return;
+        }
+        const checks = await Promise.all(configured.map((entry) => runDoctorCheck(store, entry)));
+        const failed = checks.filter((item) => !item.installed || !item.loadable);
+        checks.forEach((item) => {
+            if (item.installed && item.loadable) {
+                this.log(chalk_1.default.green(`[OK] ${item.plugin}`));
+                return;
+            }
+            this.log(chalk_1.default.red(`[FAIL] ${item.plugin}: ${item.error ?? "unknown error"}`));
+        });
+        if (failed.length === 0) {
+            this.log(chalk_1.default.green("Plugin doctor checks passed."));
+            return;
+        }
+        throw new Error(`${failed.length} plugin(s) failed doctor checks.`);
+    }
+}
+PluginDoctorCommand.description = "Validate configured plugins are installed and loadable.";
+PluginDoctorCommand.args = {
+    name: core_1.Args.string({
+        description: "npm package name (optional; if omitted checks all configured plugins)",
+        required: false
+    })
+};
+exports.default = PluginDoctorCommand;

package/dist/commands/plugin/prune.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+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");
+/**
+ * Get configured plugin names from config.
+ *
+ * Usage:
+ * const names = getConfiguredPluginNames(store);
+ */
+const getConfiguredPluginNames = (store) => {
+    const config = store.readConfig();
+    const names = config.plugins
+        .map((entry) => (0, plugin_store_1.normalizePluginConfigEntry)(entry).name)
+        .filter((name) => name.trim().length > 0);
+    return new Set(names);
+};
+class PluginPruneCommand extends core_1.Command {
+    async run() {
+        const configService = new config_service_1.ConfigService();
+        const store = new plugin_store_1.PluginStore(configService);
+        configService.ensureConfigFileExists();
+        const configured = getConfiguredPluginNames(store);
+        const installed = store.readInstalledDependencyNames();
+        const orphans = installed.filter((name) => !configured.has(name));
+        if (orphans.length === 0) {
+            this.log(chalk_1.default.gray("No orphan plugin packages found."));
+            return;
+        }
+        orphans.forEach((name) => {
+            (0, plugin_installer_1.uninstallPluginPackage)(store, { packageName: name });
+            this.log(chalk_1.default.green(`Pruned plugin package: ${name}`));
+        });
+    }
+}
+PluginPruneCommand.description = "Uninstall plugin packages that are not referenced by config.";
+exports.default = PluginPruneCommand;

package/dist/commands/plugin/set.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const chalk_1 = __importDefault(require("chalk"));
+const config_service_1 = require("../../services/config-service");
+const parse_plugin_options_1 = require("../../utils/parse-plugin-options");
+const parse_plugin_spec_1 = require("../../utils/parse-plugin-spec");
+/**
+ * Replace options for a configured plugin and keep its current name/spec.
+ *
+ * Usage:
+ * const next = buildUpdatedPluginEntry(existingEntry, parsedOptions);
+ */
+const buildUpdatedPluginEntry = (entry, options) => {
+    if (typeof entry === "string") {
+        return {
+            name: entry,
+            options
+        };
+    }
+    return {
+        name: entry.name,
+        ...(typeof entry.spec === "string" ? { spec: entry.spec } : {}),
+        options
+    };
+};
+class PluginSetCommand extends core_1.Command {
+    async run() {
+        const [rawName, ...rest] = this.argv;
+        if (!rawName) {
+            throw new Error("plugin set: missing <plugin-name>");
+        }
+        const parsedOptions = (0, parse_plugin_options_1.parsePluginOptions)(rest);
+        if (parsedOptions.kind === "none") {
+            throw new Error("plugin set: provide options with --option or --option-*");
+        }
+        const targetName = (0, parse_plugin_spec_1.parsePluginSpec)(rawName).name;
+        const configService = new config_service_1.ConfigService();
+        configService.ensureConfigFileExists();
+        const config = configService.readConfigOrDefault();
+        const targetIndex = config.plugins.findIndex((entry) => {
+            return (typeof entry === "string" ? entry : entry.name) === targetName;
+        });
+        if (targetIndex < 0) {
+            this.log(chalk_1.default.gray(`Plugin not found in config: ${targetName}`));
+            return;
+        }
+        const targetEntry = config.plugins[targetIndex];
+        const nextEntry = buildUpdatedPluginEntry(targetEntry, parsedOptions.value);
+        const nextPlugins = config.plugins.map((entry, idx) => {
+            if (idx === targetIndex) {
+                return nextEntry;
+            }
+            return entry;
+        });
+        configService.writeConfig({
+            ...config,
+            plugins: nextPlugins
+        });
+        this.log(chalk_1.default.green(`Updated plugin options: ${targetName}`));
+    }
+}
+PluginSetCommand.description = "Update options for an already configured plugin.";
+PluginSetCommand.strict = false;
+exports.default = PluginSetCommand;

package/dist/commands/plugin/uninstall.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+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");
+class PluginUninstallCommand extends core_1.Command {
+    async run() {
+        const { args, flags } = await this.parse(PluginUninstallCommand);
+        const parsed = (0, parse_plugin_spec_1.parsePluginSpec)(args.name);
+        const targetName = parsed.name;
+        const configService = new config_service_1.ConfigService();
+        const store = new plugin_store_1.PluginStore(configService);
+        configService.ensureConfigFileExists();
+        const installedMeta = store.readInstalledPackageMeta(targetName);
+        if (!installedMeta) {
+            this.log(chalk_1.default.gray(`Plugin package is not installed: ${targetName}`));
+        }
+        else {
+            (0, plugin_installer_1.uninstallPluginPackage)(store, { packageName: targetName });
+            this.log(chalk_1.default.green(`Uninstalled plugin package: ${targetName}`));
+        }
+        if (!flags.fromConfig) {
+            return;
+        }
+        const config = configService.readConfigOrDefault();
+        const out = store.removePluginFromConfig(config, targetName);
+        if (!out.removed) {
+            this.log(chalk_1.default.gray(`Plugin not found in config: ${targetName}`));
+            return;
+        }
+        configService.writeConfig(out.config);
+        this.log(chalk_1.default.green(`Removed from config: ${targetName}`));
+    }
+}
+PluginUninstallCommand.description = "Uninstall a plugin package from the plugin install directory (optional config removal).";
+PluginUninstallCommand.args = {
+    name: core_1.Args.string({
+        description: "npm package name",
+        required: true
+    })
+};
+PluginUninstallCommand.flags = {
+    fromConfig: core_1.Flags.boolean({
+        description: "also remove the plugin from config",
+        aliases: ["from-config"],
+        default: false
+    })
+};
+exports.default = PluginUninstallCommand;

package/dist/services/plugin-installer.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.updatePluginPackageToLatest = exports.installPluginPackage = void 0;
+exports.uninstallPluginPackage = exports.updatePluginPackageToLatest = exports.installPluginPackage = void 0;
 const node_child_process_1 = require("node:child_process");
 /**
  * Install a package spec with pnpm first, then fallback to npm.
@@ -46,3 +46,37 @@ const updatePluginPackageToLatest = (store, input) => {
     tryInstallWithFallback(installDir, packageSpec);
 };
 exports.updatePluginPackageToLatest = updatePluginPackageToLatest;
+/**
+ * Uninstall a package name with pnpm first, then fallback to npm.
+ *
+ * Usage:
+ * uninstallPluginPackage(store, { packageName: "@scope/plugin" });
+ */
+const uninstallPluginPackage = (store, input) => {
+    store.ensurePluginPackageJson();
+    const installDir = store.getInstallDir();
+    const tryRun = (cmd, args) => {
+        const r = (0, node_child_process_1.spawnSync)(cmd, args, {
+            cwd: installDir,
+            stdio: "inherit",
+            shell: false
+        });
+        if (r.error) {
+            return { ok: false, error: r.error };
+        }
+        if (typeof r.status === "number" && r.status !== 0) {
+            return { ok: false, error: new Error(`${cmd} exited with code ${r.status}`) };
+        }
+        return { ok: true };
+    };
+    const pnpm = tryRun("pnpm", ["remove", "--silent", input.packageName]);
+    if (pnpm.ok) {
+        return;
+    }
+    const npm = tryRun("npm", ["uninstall", "--silent", input.packageName]);
+    if (npm.ok) {
+        return;
+    }
+    throw new Error(`Failed to uninstall ${input.packageName}. Ensure pnpm or npm is available.`);
+};
+exports.uninstallPluginPackage = uninstallPluginPackage;

package/dist/services/plugin-store.js

@@ -62,6 +62,12 @@ const isRecord = (value) => {
 const isCallable = (value) => {
     return typeof value === "function";
 };
+const isStringRecord = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    return Object.values(value).every((v) => typeof v === "string");
+};
 class PluginStore {
     constructor(configService) {
         this.configService = configService;
@@ -125,6 +131,26 @@ class PluginStore {
             return undefined;
         }
     }
+    /**
+     * Read top-level dependencies from plugins install `package.json`.
+     *
+     * Usage:
+     * const names = store.readInstalledDependencyNames();
+     */
+    readInstalledDependencyNames() {
+        const pkgJsonPath = this.ensurePluginPackageJson();
+        const text = node_fs_1.default.readFileSync(pkgJsonPath, "utf8");
+        const parsed = (0, parse_json_1.parseJson)(text);
+        if (!parsed.ok || !parsed.value || typeof parsed.value !== "object") {
+            return [];
+        }
+        const record = parsed.value;
+        const dependencies = record.dependencies;
+        if (!isStringRecord(dependencies)) {
+            return [];
+        }
+        return Object.keys(dependencies);
+    }
     async importPluginModule(pluginName) {
         const req = this.createPluginsRequire();
         const resolved = req.resolve(pluginName);

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

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePluginOptions = void 0;
+/**
+ * Parse plugin options from argv tokens.
+ *
+ * Usage:
+ * const parsed = parsePluginOptions(["--option-mode", "strict"]);
+ */
+const parsePluginOptions = (argv) => {
+    const tokens = argv.filter(Boolean);
+    const pairs = tokens
+        .map((t, i) => ({ t, next: tokens[i + 1] }))
+        .filter(({ t }) => t === "--option" || t.startsWith("--option-"));
+    const object = pairs
+        .filter(({ t }) => t.startsWith("--option-"))
+        .reduce((acc, { t, next }) => {
+        const key = t.slice("--option-".length);
+        if (!key) {
+            throw new Error("--option-* key is empty");
+        }
+        if (typeof next === "undefined" || next.startsWith("-")) {
+            throw new Error(`${t} expects a value`);
+        }
+        return { ...acc, [key]: next };
+    }, {});
+    const arrayValues = pairs
+        .filter(({ t }) => t === "--option")
+        .map(({ next }) => {
+        if (typeof next === "undefined" || next.startsWith("-")) {
+            throw new Error("--option expects a value");
+        }
+        return next;
+    });
+    const hasObject = Object.keys(object).length > 0;
+    const hasArray = arrayValues.length > 0;
+    if (hasObject && hasArray) {
+        throw new Error("Cannot mix --option with --option-* flags");
+    }
+    if (hasObject) {
+        return { kind: "object", value: object };
+    }
+    if (hasArray) {
+        return { kind: "array", value: arrayValues };
+    }
+    return { kind: "none" };
+};
+exports.parsePluginOptions = parsePluginOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pagepocket/cli",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "CLI for capturing offline snapshots of web pages.",
   "main": "dist/index.js",
   "bin": {
@@ -21,15 +21,15 @@
     "koa-static": "^5.0.0",
     "npm-package-arg": "^13.0.2",
     "ora": "^9.0.0",
-    "@pagepocket/build-snapshot-unit": "0.9.0",
-    "@pagepocket/contracts": "0.9.0",
-    "@pagepocket/capture-http-lighterceptor-unit": "0.9.0",
-    "@pagepocket/capture-http-puppeteer-unit": "0.9.0",
-    "@pagepocket/lib": "0.9.0",
-    "@pagepocket/capture-http-cdp-unit": "0.9.0",
-    "@pagepocket/single-file-unit": "0.9.0",
-    "@pagepocket/plugin-yt-dlp": "0.9.0",
-    "@pagepocket/write-down-unit": "0.9.0"
+    "@pagepocket/build-snapshot-unit": "0.9.2",
+    "@pagepocket/capture-http-lighterceptor-unit": "0.9.2",
+    "@pagepocket/contracts": "0.9.2",
+    "@pagepocket/capture-http-puppeteer-unit": "0.9.2",
+    "@pagepocket/lib": "0.9.2",
+    "@pagepocket/capture-http-cdp-unit": "0.9.2",
+    "@pagepocket/single-file-unit": "0.9.2",
+    "@pagepocket/plugin-yt-dlp": "0.9.2",
+    "@pagepocket/write-down-unit": "0.9.2"
   },
   "devDependencies": {
     "@types/koa": "^2.15.0",