@pagepocket/cli 0.7.0 → 0.8.0

package/README.md

@@ -1,7 +1,7 @@
 # @pagepocket/cli
 
 CLI for capturing offline snapshots of web pages using the PagePocket library and
-NetworkInterceptorAdapter event streams.
+plugin-owned HTTP capture.
 
 ## Install
 
@@ -12,15 +12,68 @@ npm i -g @pagepocket/cli
 ## Usage
 
 ```bash
-pp https://example.com
-pp https://example.com -o ./snapshots
-pp https://example.com -o ./snapshots --overwrite
+pp archive https://example.com
+pp archive https://example.com -o ./snapshots
+pp archive https://example.com -o ./snapshots --overwrite
 ```
 
+## Configuration
+
+PagePocket CLI stores a persistent config file under your user config directory:
+
+- Linux: `~/.config/pagepocket/config.json`
+- Windows: `%APPDATA%\\pagepocket\\config.json`
+
+Initial config:
+
+```json
+{
+  "plugins": []
+}
+```
+
+## Plugins
+
+Manage configured plugins:
+
+```bash
+pp plugin ls
+pp plugin add <plugin-name>
+pp plugin remove <plugin-name>
+```
+
+Options passing:
+
+```bash
+# no options
+pp plugin add @scope/plugin
+
+# object options (becomes { options: { arg1: "xxx" } })
+pp plugin add @scope/plugin --option-arg1 xxx --option-arg2 yyy
+
+# array options (becomes { options: ["1", "2"] })
+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).
+- 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.
+
 ## Output
 
-Snapshots are written to a folder named after the page title (or `snapshot`) inside
-the output directory (default: current directory). Example layout:
+Snapshots are written to a folder named after the page title inside the output
+directory (default: current directory).
+
+- The title is sanitized for safe filesystem usage.
+- If the title is missing/blank, we fall back to the page hostname, then `snapshot`.
+- If the target path already exists and `--overwrite` is not set, we de-dupe by
+  appending `-2`, `-3`, ...
+
+For `--emit zip`, the output is written as `<output>/<title>.zip`.
+
+Example layout:
 
 ```
 <output>/<title>/index.html

package/dist/commands/archive.js

@@ -0,0 +1,155 @@
+"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 build_snapshot_unit_1 = require("@pagepocket/build-snapshot-unit");
+const capture_http_cdp_unit_1 = require("@pagepocket/capture-http-cdp-unit");
+const capture_http_lighterceptor_unit_1 = require("@pagepocket/capture-http-lighterceptor-unit");
+const capture_http_puppeteer_unit_1 = require("@pagepocket/capture-http-puppeteer-unit");
+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 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) {
+        return url;
+    }
+    return `${url.slice(0, MAX_STATUS_URL_LENGTH - 3)}...`;
+};
+class ArchiveCommand extends core_1.Command {
+    async run() {
+        const { args, flags } = await this.parse(ArchiveCommand);
+        const targetUrl = args.url;
+        const outputFlag = flags.output ? flags.output.trim() : undefined;
+        const emit = flags.emit;
+        const type = flags.type;
+        const overwrite = flags.overwrite === true;
+        const triggerActions = (flags.action ?? []);
+        const runtime = flags.runtime;
+        const timeoutMs = typeof flags.timeout === "number" ? flags.timeout : undefined;
+        const maxDurationMs = typeof flags.maxDuration === "number" ? flags.maxDuration : undefined;
+        const headers = {
+            "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
+            accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
+            "accept-language": "en-US,en;q=0.9",
+            referer: targetUrl
+        };
+        const pagepocket = lib_1.PagePocket.fromURL(targetUrl);
+        if (type === "single-file" && emit === "zip") {
+            throw new Error("--type single-file is not compatible with --emit zip (single-file is a directory output)");
+        }
+        const result = await (0, with_spinner_1.withSpinner)(async (spinner) => {
+            {
+                const writeDownOptions = {
+                    type: emit,
+                    outputPath: outputFlag ?? process.cwd(),
+                    overwrite
+                };
+                const captureUnit = runtime === "puppeteer"
+                    ? new capture_http_puppeteer_unit_1.CaptureHttpPuppeteerUnit({ triggerActions })
+                    : runtime === "lighterceptor"
+                        ? new capture_http_lighterceptor_unit_1.CaptureHttpLighterceptorUnit({ headers, triggerActions })
+                        : new capture_http_cdp_unit_1.CaptureHttpCdpUnit({ triggerActions });
+                const units = [
+                    new network_observer_unit_1.NetworkObserverUnit({
+                        onRequest: (event) => {
+                            spinner.text = `Freezing page (${formatStatusUrl(event.url)})`;
+                        }
+                    }),
+                    captureUnit,
+                    new build_snapshot_unit_1.BuildSnapshotUnit()
+                ];
+                if (type === "single-file") {
+                    units.push(new single_file_unit_1.SingleFileUnit());
+                }
+                units.push(new write_down_unit_1.WriteDownUnit(writeDownOptions));
+                const entryTarget = runtime === "cdp"
+                    ? (() => {
+                        const tabId = flags.tabId;
+                        if (typeof tabId !== "number") {
+                            throw new Error("--tabId is required when --runtime cdp");
+                        }
+                        return lib_1.PagePocket.fromCDPTab(tabId);
+                    })()
+                    : pagepocket;
+                const result = await entryTarget.capture({
+                    timeoutMs,
+                    maxDurationMs,
+                    blacklist: [...lib_1.ga, ...lib_1.ns],
+                    units,
+                    plugins: await (0, load_configured_plugins_1.loadConfiguredPlugins)().catch(() => [])
+                });
+                return result;
+            }
+        }, "Freezing page");
+        this.log(chalk_1.default.green("All done! Snapshot created."));
+        if (result.kind === "zip") {
+            this.log(`Snapshot saved to ${chalk_1.default.cyan(result.zip.outputPath)}`);
+        }
+        else if (result.kind === "raw") {
+            this.log(`Snapshot saved to ${chalk_1.default.cyan(result.outputDir)}`);
+        }
+        process.exit();
+    }
+}
+ArchiveCommand.description = "Archive a web page as an offline snapshot.";
+ArchiveCommand.args = {
+    url: core_1.Args.string({
+        description: "URL to archive",
+        required: true
+    })
+};
+ArchiveCommand.flags = {
+    help: core_1.Flags.help({
+        char: "h"
+    }),
+    output: core_1.Flags.string({
+        char: "o",
+        description: "Output directory"
+    }),
+    emit: core_1.Flags.string({
+        description: "Output format",
+        options: ["raw", "zip"],
+        default: "raw"
+    }),
+    type: core_1.Flags.string({
+        description: "Snapshot type",
+        options: ["directory", "single-file"],
+        default: "directory"
+    }),
+    overwrite: core_1.Flags.boolean({
+        description: "Overwrite existing output directory instead of suffixing",
+        default: false
+    }),
+    action: core_1.Flags.string({
+        char: "a",
+        description: "Trigger action to run during/after capture (repeatable). Use -a multiple times to run multiple actions.",
+        options: Object.values({ HOVER: "HOVER", SCROLL_TO_END: "SCROLL_TO_END" }),
+        multiple: true
+    }),
+    runtime: core_1.Flags.string({
+        char: "r",
+        description: "Interceptor runtime to use",
+        options: ["lighterceptor", "puppeteer", "cdp"],
+        default: "puppeteer"
+    }),
+    tabId: core_1.Flags.integer({
+        description: "CDP tabId (required when --runtime cdp)"
+    }),
+    timeout: core_1.Flags.integer({
+        char: "t",
+        description: "Network idle duration in milliseconds before capture stops",
+        default: 5000
+    }),
+    maxDuration: core_1.Flags.integer({
+        description: "Hard max capture duration in milliseconds",
+        default: 60000
+    })
+};
+exports.default = ArchiveCommand;

package/dist/commands/plugin/add.js

@@ -0,0 +1,85 @@
+"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 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;
+        if (!name) {
+            throw new Error("plugin add: missing <plugin-name>");
+        }
+        if (name === "--help" || name === "-h") {
+            this.log("Usage: pp plugin add <plugin-name> [--option-* <value> ...] [--option <value> ...]");
+            return;
+        }
+        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}`));
+            return;
+        }
+        const parsed = parseDynamicOptions(rest);
+        const entry = parsed.kind === "none"
+            ? 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).`);
+        }
+        const nextConfig = store.addPluginToConfig(config, entry);
+        configService.writeConfig(nextConfig);
+        await store.runOptionalSetup(name);
+        this.log(chalk_1.default.green(`Added plugin: ${name}`));
+    }
+}
+PluginAddCommand.description = "Install a plugin package, add it to config, and run its optional setup().";
+exports.default = PluginAddCommand;

package/dist/commands/plugin/ls.js

@@ -0,0 +1,38 @@
+"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");
+class PluginLsCommand extends core_1.Command {
+    async run() {
+        const configService = new config_service_1.ConfigService();
+        const store = new plugin_store_1.PluginStore(configService);
+        configService.ensureConfigFileExists();
+        const config = configService.readConfigOrDefault();
+        const entries = config.plugins;
+        if (entries.length === 0) {
+            this.log(chalk_1.default.gray("No plugins configured."));
+            return;
+        }
+        entries
+            .map((entry) => {
+            const name = typeof entry === "string" ? entry : entry.name;
+            const meta = store.readInstalledPackageMeta(name);
+            if (!meta) {
+                return `${chalk_1.default.yellow(name)} ${chalk_1.default.gray("(not installed)")}`;
+            }
+            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}`;
+        })
+            .forEach((line) => this.log(line));
+    }
+}
+PluginLsCommand.description = "List configured plugins.";
+exports.default = PluginLsCommand;

package/dist/commands/plugin/remove.js

@@ -0,0 +1,34 @@
+"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");
+class PluginRemoveCommand extends core_1.Command {
+    async run() {
+        const { args } = await this.parse(PluginRemoveCommand);
+        const name = args.name;
+        const configService = new config_service_1.ConfigService();
+        const store = new plugin_store_1.PluginStore(configService);
+        configService.ensureConfigFileExists();
+        const config = configService.readConfigOrDefault();
+        const out = store.removePluginFromConfig(config, name);
+        if (!out.removed) {
+            this.log(chalk_1.default.gray(`Plugin not found in config: ${name}`));
+            return;
+        }
+        configService.writeConfig(out.config);
+        this.log(chalk_1.default.green(`Removed from config: ${name}`));
+    }
+}
+PluginRemoveCommand.description = "Remove a plugin from config (does not uninstall).";
+PluginRemoveCommand.args = {
+    name: core_1.Args.string({
+        description: "npm package name",
+        required: true
+    })
+};
+exports.default = PluginRemoveCommand;

package/dist/commands/view.js

@@ -0,0 +1,63 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_process_1 = __importDefault(require("node:process"));
+const core_1 = require("@oclif/core");
+const chalk_1 = __importDefault(require("chalk"));
+const view_1 = require("../view");
+class ViewCommand extends core_1.Command {
+    async run() {
+        const { args, flags } = await this.parse(ViewCommand);
+        const rootDir = node_path_1.default.resolve(node_process_1.default.cwd(), args.directory);
+        const indexPath = node_path_1.default.join(rootDir, "index.html");
+        const stat = await node_fs_1.default.promises.stat(rootDir).catch(() => null);
+        if (!stat || !stat.isDirectory()) {
+            throw new Error(`view: directory not found: ${rootDir}`);
+        }
+        const indexStat = await node_fs_1.default.promises.stat(indexPath).catch(() => null);
+        if (!indexStat || !indexStat.isFile()) {
+            throw new Error(`view: index.html not found under: ${rootDir}`);
+        }
+        const portFromEnv = node_process_1.default.env.PORT ? Number(node_process_1.default.env.PORT) : undefined;
+        const port = typeof flags.port === "number"
+            ? flags.port
+            : typeof portFromEnv === "number"
+                ? portFromEnv
+                : 4173;
+        if (!Number.isFinite(port) || port < 0 || port > 65535) {
+            throw new Error(`Invalid --port: ${String(flags.port ?? node_process_1.default.env.PORT)}`);
+        }
+        const server = await (0, view_1.createViewServer)({
+            rootDir,
+            host: flags.host,
+            port
+        });
+        this.log(`Serving ${chalk_1.default.cyan(rootDir)}`);
+        this.log(chalk_1.default.green(server.url));
+    }
+}
+ViewCommand.description = "Serve a directory via a local static server (SPA fallback to index.html).";
+ViewCommand.args = {
+    directory: core_1.Args.string({
+        description: "Directory to serve (must contain index.html)",
+        required: true
+    })
+};
+ViewCommand.flags = {
+    help: core_1.Flags.help({
+        char: "h"
+    }),
+    host: core_1.Flags.string({
+        description: "Host to bind",
+        default: "127.0.0.1"
+    }),
+    port: core_1.Flags.integer({
+        description: "Port to listen on (0 for random)",
+        default: 4173
+    })
+};
+exports.default = ViewCommand;

package/dist/index.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
-(0, core_1.run)().catch((error) => {
+const normalize_argv_1 = require("./utils/normalize-argv");
+(0, core_1.run)((0, normalize_argv_1.normalizeArgv)(process.argv.slice(2))).catch((error) => {
     const message = error && typeof error.message === "string" ? error.message : String(error);
     console.error(message);
     const exitCode = error && typeof error.exitCode === "number" ? error.exitCode : 1;

package/dist/services/config-service.js

@@ -0,0 +1,110 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigService = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const env_paths_1 = __importDefault(require("env-paths"));
+const defaultConfig = {
+    plugins: []
+};
+class ConfigService {
+    constructor(appName = "pagepocket") {
+        this.appName = appName;
+    }
+    getConfigDir() {
+        if (process.platform === "win32") {
+            const p = (0, env_paths_1.default)(this.appName, { suffix: "" });
+            return p.config;
+        }
+        const homeDir = node_os_1.default.homedir();
+        const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+        const base = xdgConfigHome && xdgConfigHome.trim() ? xdgConfigHome : node_path_1.default.join(homeDir, ".config");
+        return node_path_1.default.join(base, this.appName);
+    }
+    getConfigPath() {
+        return node_path_1.default.join(this.getConfigDir(), "config.json");
+    }
+    getPluginsInstallDir() {
+        return node_path_1.default.join(this.getConfigDir(), "plugins");
+    }
+    ensureConfigDirExists() {
+        this.ensureDirExists(this.getConfigDir());
+    }
+    ensureDirExists(dirPath) {
+        node_fs_1.default.mkdirSync(dirPath, { recursive: true });
+    }
+    writeJsonAtomic(filePath, value) {
+        const dir = node_path_1.default.dirname(filePath);
+        this.ensureDirExists(dir);
+        const tmpPath = `${filePath}.tmp`;
+        node_fs_1.default.writeFileSync(tmpPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+        node_fs_1.default.renameSync(tmpPath, filePath);
+    }
+    isObject(value) {
+        return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+    }
+    normalizeConfig(value) {
+        if (!this.isObject(value)) {
+            return defaultConfig;
+        }
+        const pluginsRaw = value.plugins;
+        if (!Array.isArray(pluginsRaw)) {
+            return defaultConfig;
+        }
+        const plugins = pluginsRaw
+            .map((entry) => {
+            if (typeof entry === "string") {
+                return entry;
+            }
+            if (this.isObject(entry) && typeof entry.name === "string") {
+                const options = "options" in entry ? entry.options : undefined;
+                return {
+                    name: entry.name,
+                    ...(typeof options === "undefined" ? {} : { options })
+                };
+            }
+            return null;
+        })
+            .filter((x) => x !== null);
+        return { plugins };
+    }
+    readConfig() {
+        const configPath = this.getConfigPath();
+        const rawText = node_fs_1.default.readFileSync(configPath, "utf8");
+        const parsed = JSON.parse(rawText);
+        return this.normalizeConfig(parsed);
+    }
+    isConfigFilePresent() {
+        return node_fs_1.default.existsSync(this.getConfigPath());
+    }
+    readConfigOrDefault() {
+        const configPath = this.getConfigPath();
+        const text = node_fs_1.default.existsSync(configPath) ? node_fs_1.default.readFileSync(configPath, "utf8") : null;
+        if (!text) {
+            return defaultConfig;
+        }
+        try {
+            const parsed = JSON.parse(text);
+            return this.normalizeConfig(parsed);
+        }
+        catch {
+            return defaultConfig;
+        }
+    }
+    writeConfig(config) {
+        this.writeJsonAtomic(this.getConfigPath(), this.normalizeConfig(config));
+    }
+    ensureConfigFileExists() {
+        const configPath = this.getConfigPath();
+        if (node_fs_1.default.existsSync(configPath)) {
+            return this.readConfigOrDefault();
+        }
+        this.writeConfig(defaultConfig);
+        return defaultConfig;
+    }
+}
+exports.ConfigService = ConfigService;

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

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfiguredPlugins = void 0;
+const config_service_1 = require("./config-service");
+const plugin_store_1 = require("./plugin-store");
+const loadConfiguredPlugins = async () => {
+    const configService = new config_service_1.ConfigService();
+    const store = new plugin_store_1.PluginStore(configService);
+    configService.ensureConfigFileExists();
+    const config = configService.readConfigOrDefault();
+    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.`);
+                return null;
+            }
+            return p;
+        }
+        catch (e) {
+            const msg = e && typeof e.message === "string"
+                ? e.message
+                : String(e);
+            console.error(`Failed to load plugin ${spec.name}: ${msg}`);
+            return null;
+        }
+    }));
+    return loaded.filter((x) => x !== null);
+};
+exports.loadConfiguredPlugins = loadConfiguredPlugins;

package/dist/services/plugin-installer.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installPluginPackage = void 0;
+const node_child_process_1 = require("node:child_process");
+const installPluginPackage = (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", ["add", "--silent", input.packageName]);
+    if (pnpm.ok) {
+        return;
+    }
+    const npm = tryRun("npm", ["install", "--silent", input.packageName]);
+    if (npm.ok) {
+        return;
+    }
+    throw new Error(`Failed to install ${input.packageName}. Ensure pnpm or npm is available.`);
+};
+exports.installPluginPackage = installPluginPackage;

package/dist/services/plugin-store.js

@@ -0,0 +1,128 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": 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_url_1 = require("node:url");
+const normalizePluginConfigEntry = (entry) => {
+    if (typeof entry === "string") {
+        return { name: entry };
+    }
+    return {
+        name: entry.name,
+        ...(typeof entry.options === "undefined" ? {} : { options: entry.options })
+    };
+};
+exports.normalizePluginConfigEntry = normalizePluginConfigEntry;
+const getPluginNameFromSpec = (spec) => spec.name;
+exports.getPluginNameFromSpec = getPluginNameFromSpec;
+class PluginStore {
+    constructor(configService) {
+        this.configService = configService;
+    }
+    getInstallDir() {
+        return this.configService.getPluginsInstallDir();
+    }
+    ensureInstallDir() {
+        node_fs_1.default.mkdirSync(this.getInstallDir(), { recursive: true });
+    }
+    ensurePluginPackageJson() {
+        this.ensureInstallDir();
+        const pkgJsonPath = node_path_1.default.join(this.getInstallDir(), "package.json");
+        if (node_fs_1.default.existsSync(pkgJsonPath)) {
+            return 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 pkgJsonPath;
+    }
+    createPluginsRequire() {
+        const pkgJsonPath = this.ensurePluginPackageJson();
+        return (0, node_module_1.createRequire)(pkgJsonPath);
+    }
+    resolveInstalledPackageJsonPath(pluginName) {
+        const req = this.createPluginsRequire();
+        return req.resolve(`${pluginName}/package.json`);
+    }
+    readInstalledPackageMeta(pluginName) {
+        try {
+            const pkgJsonPath = this.resolveInstalledPackageJsonPath(pluginName);
+            const text = node_fs_1.default.readFileSync(pkgJsonPath, "utf8");
+            const json = JSON.parse(text);
+            if (!json || typeof json !== "object") {
+                return { name: pluginName };
+            }
+            const o = json;
+            return {
+                name: typeof o.name === "string" ? o.name : pluginName,
+                description: typeof o.description === "string" ? o.description : undefined,
+                version: typeof o.version === "string" ? o.version : undefined
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    async importPluginModule(pluginName) {
+        const req = this.createPluginsRequire();
+        const resolved = req.resolve(pluginName);
+        const dynamicImport = new Function("specifier", "return import(specifier)");
+        const mod = await dynamicImport((0, node_url_1.pathToFileURL)(resolved).href);
+        return (mod ?? {});
+    }
+    async instantiatePluginFromSpec(spec) {
+        const mod = await this.importPluginModule(spec.name);
+        const defaultExport = mod.default;
+        if (typeof defaultExport !== "function") {
+            throw new Error(`Plugin ${spec.name} has no default export (class/function).`);
+        }
+        const ctor = defaultExport;
+        if (typeof spec.options === "undefined") {
+            return new ctor();
+        }
+        if (Array.isArray(spec.options)) {
+            return new ctor(...spec.options);
+        }
+        return new ctor(spec.options);
+    }
+    async runOptionalSetup(pluginName) {
+        const mod = await this.importPluginModule(pluginName);
+        const setup = mod.setup;
+        if (typeof setup === "function") {
+            await setup();
+        }
+    }
+    readConfig() {
+        return this.configService.readConfigOrDefault();
+    }
+    writeConfig(next) {
+        this.configService.writeConfig(next);
+    }
+    hasPlugin(config, pluginName) {
+        return config.plugins.some((e) => (0, exports.getPluginNameFromSpec)((0, exports.normalizePluginConfigEntry)(e)) === pluginName);
+    }
+    addPluginToConfig(config, entry) {
+        const spec = (0, exports.normalizePluginConfigEntry)(entry);
+        if (this.hasPlugin(config, spec.name)) {
+            return config;
+        }
+        return { ...config, plugins: [...config.plugins, entry] };
+    }
+    removePluginFromConfig(config, pluginName) {
+        const before = config.plugins;
+        const after = before.filter((e) => (0, exports.getPluginNameFromSpec)((0, exports.normalizePluginConfigEntry)(e)) !== pluginName);
+        return {
+            config: { ...config, plugins: after },
+            removed: after.length !== before.length
+        };
+    }
+}
+exports.PluginStore = PluginStore;

package/dist/units/network-observer-unit.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetworkObserverUnit = void 0;
+const contracts_1 = require("@pagepocket/contracts");
+const lib_1 = require("@pagepocket/lib");
+/**
+ * Observes the network@1 channel and forwards events to user-provided callbacks.
+ *
+ * This unit is intentionally UI-agnostic (no CLI/spinner coupling).
+ */
+class NetworkObserverUnit extends lib_1.Unit {
+    constructor(config = {}) {
+        super();
+        this.id = "networkObserver";
+        this.kind = "observe.network";
+        this.config = config;
+    }
+    async run(_ctx, rt) {
+        const config = this.config;
+        const task = (async () => {
+            for await (const event of rt.subscribe(contracts_1.NETWORK)) {
+                await config.onEvent?.(event);
+                if (event.type === "request") {
+                    await config.onRequest?.(event);
+                }
+                else if (event.type === "response") {
+                    await config.onResponse?.(event);
+                }
+                else if (event.type === "failed") {
+                    await config.onFailed?.(event);
+                }
+            }
+        })();
+        rt.defer(task);
+    }
+}
+exports.NetworkObserverUnit = NetworkObserverUnit;

package/dist/utils/normalize-argv.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeArgv = exports.isUrlLike = void 0;
+const isUrlLike = (value) => {
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+};
+exports.isUrlLike = isUrlLike;
+const normalizeArgv = (argv) => {
+    // pnpm forwards args to scripts by inserting a literal `--`.
+    // oclif does not treat that as a flag; strip it if present.
+    if (argv[0] === "--") {
+        argv = argv.slice(1);
+    }
+    if (argv.length === 0) {
+        return argv;
+    }
+    const first = argv[0];
+    if (first === "plugin") {
+        const sub = argv[1];
+        if (sub === "ls" || sub === "add" || sub === "remove") {
+            return [`plugin:${sub}`, ...argv.slice(2)];
+        }
+    }
+    // If the first token is a URL, treat it as implicit `archive`.
+    if (first && (0, exports.isUrlLike)(first)) {
+        return ["archive", ...argv];
+    }
+    return argv;
+};
+exports.normalizeArgv = normalizeArgv;

package/dist/view.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createViewServer = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const koa_1 = __importDefault(require("koa"));
+const koa_send_1 = __importDefault(require("koa-send"));
+const koa_static_1 = __importDefault(require("koa-static"));
+const createViewServer = async (args) => {
+    const indexPath = node_path_1.default.join(args.rootDir, "index.html");
+    const stat = await node_fs_1.default.promises.stat(args.rootDir).catch(() => null);
+    if (!stat || !stat.isDirectory()) {
+        throw new Error(`view: directory not found: ${args.rootDir}`);
+    }
+    const indexStat = await node_fs_1.default.promises.stat(indexPath).catch(() => null);
+    if (!indexStat || !indexStat.isFile()) {
+        throw new Error(`view: index.html not found under: ${args.rootDir}`);
+    }
+    const app = new koa_1.default();
+    // Avoid Koa's generator-function detection (and its dependency chain) by
+    // not calling `app.use()`.
+    //
+    // In some ESM/CJS interop environments, koa's transitive dependency
+    // `is-generator-function` can break ("getGeneratorFunction is not a function")
+    // when it tries to require `generator-function`. We don't need generator
+    // middleware support here, so bypass it entirely.
+    const staticMw = (0, koa_static_1.default)(args.rootDir, { index: false });
+    app.middleware.push(staticMw);
+    app.middleware.push(async (ctx) => {
+        // SPA fallback (anything not matched by static middleware)
+        ctx.status = 200;
+        await (0, koa_send_1.default)(ctx, "index.html", {
+            root: args.rootDir
+        });
+    });
+    const server = await new Promise((resolve, reject) => {
+        const s = app.listen(args.port, args.host, () => resolve(s));
+        s.on("error", reject);
+    });
+    const address = server.address();
+    const port = typeof address === "object" && address ? address.port : args.port;
+    const host = args.host;
+    const url = `http://${host}:${port}`;
+    return {
+        url,
+        close: async () => {
+            await new Promise((resolve, reject) => {
+                server.close((err) => (err ? reject(err) : resolve()));
+            });
+        }
+    };
+};
+exports.createViewServer = createViewServer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pagepocket/cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "CLI for capturing offline snapshots of web pages.",
   "main": "dist/index.js",
   "bin": {
@@ -15,27 +15,39 @@
   "dependencies": {
     "@oclif/core": "^4.0.9",
     "chalk": "^4.1.2",
+    "koa": "^2.16.2",
+    "koa-send": "^5.0.1",
+    "koa-static": "^5.0.0",
     "ora": "^9.0.0",
-    "@pagepocket/lib": "0.7.0",
-    "@pagepocket/interceptor": "0.7.0",
-    "@pagepocket/lighterceptor-adapter": "0.7.0",
-    "@pagepocket/puppeteer-adapter": "0.7.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"
   },
   "devDependencies": {
     "@types/node": "^20.11.30",
+    "@types/koa": "^2.15.0",
+    "@types/koa-send": "^4.1.5",
+    "@types/koa-static": "^4.0.4",
     "tsx": "^4.19.3",
     "typescript": "^5.4.5"
   },
   "oclif": {
     "bin": "pp",
     "commands": {
-      "strategy": "single",
-      "target": "dist/cli.js"
+      "strategy": "pattern",
+      "target": "dist/commands"
     }
   },
   "scripts": {
-    "build": "tsc",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
     "start": "node dist/index.js",
-    "test": "tsx --test specs/*.spec.ts"
+    "test": "pnpm build && tsx --test specs/*.spec.ts"
   }
 }

package/dist/cli.js

@@ -1,125 +0,0 @@
-"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 interceptor_1 = require("@pagepocket/interceptor");
-const lib_1 = require("@pagepocket/lib");
-const lighterceptor_adapter_1 = require("@pagepocket/lighterceptor-adapter");
-const puppeteer_adapter_1 = require("@pagepocket/puppeteer-adapter");
-const chalk_1 = __importDefault(require("chalk"));
-const prepare_output_1 = require("./stages/prepare-output");
-const write_snapshot_1 = require("./stages/write-snapshot");
-const with_spinner_1 = require("./utils/with-spinner");
-const MAX_STATUS_URL_LENGTH = 80;
-const formatStatusUrl = (url) => {
-    if (url.length <= MAX_STATUS_URL_LENGTH) {
-        return url;
-    }
-    return `${url.slice(0, MAX_STATUS_URL_LENGTH - 3)}...`;
-};
-class PagepocketCommand extends core_1.Command {
-    async run() {
-        const { args, flags } = await this.parse(PagepocketCommand);
-        const targetUrl = args.url;
-        const outputFlag = flags.output ? flags.output.trim() : undefined;
-        const overwrite = flags.overwrite === true;
-        const triggerActions = (flags.action ?? []);
-        const runtime = flags.runtime;
-        const timeoutMs = typeof flags.timeout === "number" ? flags.timeout : undefined;
-        const maxDurationMs = typeof flags.maxDuration === "number" ? flags.maxDuration : undefined;
-        const headers = {
-            "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
-            accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
-            "accept-language": "en-US,en;q=0.9",
-            referer: targetUrl
-        };
-        const interceptor = runtime === "puppeteer"
-            ? new puppeteer_adapter_1.PuppeteerAdapter({
-                // gotoOptions: { waitUntil: "networkidle2" },
-                triggerActions
-            })
-            : new lighterceptor_adapter_1.LighterceptorAdapter({ headers, triggerActions });
-        const pagepocket = lib_1.PagePocket.fromURL(targetUrl);
-        const snapshot = await (0, with_spinner_1.withSpinner)(async (spinner) => {
-            const eventsTask = (async () => {
-                for await (const event of pagepocket.interceptedRequestEvents()) {
-                    if (event.type === "request") {
-                        spinner.text = `Freezing page (${formatStatusUrl(event.url)})`;
-                    }
-                }
-            })();
-            try {
-                return await pagepocket.capture({
-                    interceptor,
-                    timeoutMs,
-                    maxDurationMs,
-                    blacklist: [...lib_1.ga, ...lib_1.sw_iframe, ...lib_1.ns]
-                });
-            }
-            finally {
-                try {
-                    await eventsTask;
-                }
-                catch {
-                    // Ignore event stream errors during shutdown.
-                }
-            }
-        }, "Freezing page");
-        const { outputDir } = await (0, with_spinner_1.withSpinner)((_spinner) => (0, prepare_output_1.prepareOutputDir)(snapshot.title ?? "snapshot", outputFlag), "Preparing output directory");
-        const writeResult = await (0, with_spinner_1.withSpinner)(async (_spinner) => {
-            return (0, write_snapshot_1.writeSnapshotFiles)({
-                outputDir,
-                snapshot,
-                overwrite
-            });
-        }, "Writing snapshot files");
-        const resolvedOutputDir = writeResult?.outputDir ?? outputDir;
-        this.log(chalk_1.default.green("All done! Snapshot created."));
-        this.log(`Snapshot saved to ${chalk_1.default.cyan(resolvedOutputDir)}`);
-        process.exit();
-    }
-}
-PagepocketCommand.description = "Save a snapshot of a web page.";
-PagepocketCommand.args = {
-    url: core_1.Args.string({
-        description: "URL to snapshot",
-        required: true
-    })
-};
-PagepocketCommand.flags = {
-    help: core_1.Flags.help({
-        char: "h"
-    }),
-    output: core_1.Flags.string({
-        char: "o",
-        description: "Output path for the snapshot HTML file"
-    }),
-    overwrite: core_1.Flags.boolean({
-        description: "Overwrite existing output directory instead of suffixing",
-        default: false
-    }),
-    action: core_1.Flags.string({
-        char: "a",
-        description: "Trigger action to run during/after capture (repeatable). Use -a multiple times to run multiple actions.",
-        options: Object.values(interceptor_1.TriggerActionValues),
-        multiple: true
-    }),
-    runtime: core_1.Flags.string({
-        char: "r",
-        description: "Interceptor runtime to use",
-        options: ["lighterceptor", "puppeteer"],
-        default: "lighterceptor"
-    }),
-    timeout: core_1.Flags.integer({
-        char: "t",
-        description: "Network idle duration in milliseconds before capture stops",
-        default: 5000
-    }),
-    maxDuration: core_1.Flags.integer({
-        description: "Hard max capture duration in milliseconds",
-        default: 60000
-    })
-};
-exports.default = PagepocketCommand;

package/dist/stages/write-snapshot.js

@@ -1,9 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.writeSnapshotFiles = void 0;
-const writeSnapshotFiles = async (input) => {
-    return input.snapshot.toDirectory(input.outputDir, {
-        overwrite: input.overwrite
-    });
-};
-exports.writeSnapshotFiles = writeSnapshotFiles;