@serwist/cli 8.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Google LLC, 2019 ShadowWalker w@weiw.io https://weiw.io, 2023 Serwist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+This module's documentation can be found at https://developers.google.com/web/tools/workbox/modules/workbox-cli

package/dist/bin.js

@@ -0,0 +1,539 @@
+import meow from 'meow';
+import updateNotifier from 'update-notifier';
+import { injectManifest } from '@serwist/build';
+import assert from 'assert';
+import chokidar from 'chokidar';
+import prettyBytes from 'pretty-bytes';
+import upath from 'upath';
+import { oneLine } from 'common-tags';
+import chalk from 'chalk';
+import { createRequire } from 'node:module';
+import fse from 'fs-extra';
+import stringifyObject from 'stringify-object';
+import inquirer from 'inquirer';
+import { glob } from 'glob';
+import ora from 'ora';
+
+/*
+  Copyright 2018 Google LLC
+
+  Use of this source code is governed by an MIT-style
+  license that can be found in the LICENSE file or at
+  https://opensource.org/licenses/MIT.
+*/ const constants = {
+    defaultConfigFile: "serwist.config.js",
+    ignoredDirectories: [
+        "node_modules"
+    ],
+    ignoredFileExtensions: [
+        "map"
+    ],
+    ignoreURLParametersMatching: [
+        /^utm_/,
+        /^fbclid$/
+    ]
+};
+
+const errors = {
+    "missing-input": `params.input value was not set properly.`,
+    "missing-dest-dir-param": oneLine`Please provide the path to a directory in which
+    the libraries will be copied.`,
+    "invalid-common-js-module": oneLine`Please pass in a valid CommonJS module that
+    exports your configuration.`,
+    "config-validation-failed": `Your configuration is invalid:`,
+    "serwist-build-runtime-error": `Service worker generation failed:`,
+    "unknown-command": `Unknown command:`,
+    "no-file-extensions-found": oneLine`No files could be found that are suitable for
+    caching.`,
+    "no-file-extensions-selected": `Please select at least one file extension.`,
+    "invalid-sw-dest": oneLine`Please enter a valid path to use for the service worker
+    file that's created.`,
+    "glob-directory-invalid": oneLine`The path you entered isn't a valid directory.`,
+    "invalid-config-location": oneLine`Please enter a valid path to use for the saved
+    configuration file.`,
+    "sw-src-missing-injection-point": oneLine`That is not a valid source service worker
+    file. Please try again with a file containing
+    'self.__SW_MANIFEST'.`,
+    "no-search-parameters-supplied": oneLine`Please provide the url search param(s)
+    you would like to ignore.`,
+    "invalid-search-parameters-supplied": oneLine`Please provide the valid URL search parameter(s)
+    without the leading '/' or '?' (i.e. source,version,language).`
+};
+
+const logger = {
+    debug: (...args)=>console.log(chalk.gray(...args)),
+    log: (...args)=>console.log(...args),
+    warn: (...args)=>console.warn(chalk.yellow(...args)),
+    error: (...args)=>console.error(chalk.red.bold(...args))
+};
+
+const require = createRequire(import.meta.url);
+// A really light wrapper on top of Node's require() to make it easier to stub
+// out reading the configuration during tests.
+function readConfig(configFile) {
+    return require(configFile);
+}
+
+// The key used for the question/answer.
+const name$3 = "configLocation";
+const configLocationQuestion = {
+    name: name$3,
+    message: oneLine`Where would you like to save these configuration options?`,
+    type: "input",
+    default: constants.defaultConfigFile
+};
+/**
+ * @returns The answers from inquirer.
+ */ function askQuestion$5() {
+    return inquirer.prompt([
+        configLocationQuestion
+    ]);
+}
+async function askConfigLocation() {
+    const answers = await askQuestion$5();
+    // The value of the answer when the question type is 'input' is String
+    // and it has a default value, the casting is safe.
+    const configLocation = answers[name$3].trim();
+    assert(configLocation, errors["invalid-config-location"]);
+    return configLocation;
+}
+
+// The key used for the question/answer.
+const name$2 = "globPatterns";
+/**
+ * @param globDirectory The directory used for the root of globbing.
+ * @returns The unique file extensions corresponding
+ * to all of the files under globDirectory.
+ */ async function getAllFileExtensions(globDirectory) {
+    // Use a pattern to match any file that contains a '.', since that signifies
+    // the presence of a file extension.
+    const files = await glob("**/*.*", {
+        cwd: globDirectory,
+        nodir: true,
+        ignore: [
+            ...constants.ignoredDirectories.map((directory)=>`**/${directory}/**`),
+            ...constants.ignoredFileExtensions.map((extension)=>`**/*.${extension}`)
+        ]
+    });
+    const extensions = new Set();
+    for (const file of files){
+        const extension = upath.extname(file);
+        if (extension) {
+            // Get rid of the leading . character.
+            extensions.add(extension.replace(/^\./, ""));
+        }
+    }
+    return [
+        ...extensions
+    ];
+}
+/**
+ * @param globDirectory The directory used for the root of globbing.
+ * @returns The answers from inquirer.
+ */ async function askQuestion$4(globDirectory) {
+    // We need to get a list of extensions corresponding to files in the directory
+    // to use when asking the next question. That could potentially take some
+    // time, so we show a spinner and explanatory text.
+    const spinner = ora({
+        text: `Examining files in ${globDirectory}...`,
+        stream: process.stdout
+    }).start();
+    const fileExtensions = await getAllFileExtensions(globDirectory);
+    spinner.stop();
+    assert(fileExtensions.length > 0, errors["no-file-extensions-found"]);
+    return inquirer.prompt([
+        {
+            name: name$2,
+            message: "Which file types would you like to precache?",
+            type: "checkbox",
+            choices: fileExtensions,
+            default: fileExtensions
+        }
+    ]);
+}
+async function askExtensionsToCache(globDirectory) {
+    const answers = await askQuestion$4(globDirectory);
+    // The return value is an array of strings with the selected values
+    // and there is a default, the casting is safe.
+    const extensions = answers[name$2];
+    assert(extensions.length > 0, errors["no-file-extensions-selected"]);
+    // glob isn't happy with a single option inside of a {} group, so use a
+    // pattern without a {} group when there's only one extension.
+    const extensionsPattern = extensions.length === 1 ? extensions[0] : `{${extensions.join(",")}}`;
+    return [
+        `**/*.${extensionsPattern}`
+    ];
+}
+
+const ROOT_PROMPT = "Please enter the path to the root of your web app:";
+// The keys used for the questions/answers.
+const questionRootDirectory = "globDirectory";
+const questionManualInput = "manualDirectoryInput";
+/**
+ * @returns The subdirectories of the current
+ * working directory, with hidden and ignored ones filtered out.
+ */ async function getSubdirectories() {
+    return await glob("*/", {
+        ignore: constants.ignoredDirectories.map((directory)=>`${directory}/`)
+    });
+}
+/**
+ * @returns The answers from inquirer.
+ */ async function askQuestion$3() {
+    const subdirectories = await getSubdirectories();
+    if (subdirectories.length > 0) {
+        const manualEntryChoice = "Manually enter path";
+        return inquirer.prompt([
+            {
+                name: questionRootDirectory,
+                type: "list",
+                message: oneLine`What is the root of your web app (i.e. which directory do
+        you deploy)?`,
+                choices: subdirectories.concat([
+                    new inquirer.Separator(),
+                    manualEntryChoice
+                ])
+            },
+            {
+                name: questionManualInput,
+                when: (answers)=>answers.globDirectory === manualEntryChoice,
+                message: ROOT_PROMPT
+            }
+        ]);
+    }
+    return inquirer.prompt([
+        {
+            name: questionRootDirectory,
+            message: ROOT_PROMPT,
+            default: "."
+        }
+    ]);
+}
+async function askRootOfWebApp() {
+    const { manualDirectoryInput, globDirectory } = await askQuestion$3();
+    try {
+        const stat = await fse.stat(manualDirectoryInput || globDirectory);
+        assert(stat.isDirectory());
+    } catch (error) {
+        throw new Error(errors["glob-directory-invalid"]);
+    }
+    return manualDirectoryInput || globDirectory;
+}
+
+const START_URL_QUERY_PARAMS_PROMPT = "Please enter the search parameter(s) that you would like to ignore (separated by comma):";
+// The keys used for the questions/answers.
+const question_ignoreURLParametersMatching = "ignoreURLParametersMatching";
+const question_shouldAskForIgnoreURLParametersMatching = "shouldAskForIgnoreURLParametersMatching";
+/**
+ * @returns The answers from inquirer.
+ */ async function askQuestion$2() {
+    return inquirer.prompt([
+        {
+            name: question_shouldAskForIgnoreURLParametersMatching,
+            message: oneLine`Does your web app manifest include search parameter(s)
+      in the 'start_url', other than 'utm_' or 'fbclid'
+      (like '?source=pwa')?`,
+            type: "confirm",
+            default: false
+        },
+        {
+            name: question_ignoreURLParametersMatching,
+            when: (answer)=>answer.shouldAskForIgnoreURLParametersMatching,
+            message: START_URL_QUERY_PARAMS_PROMPT,
+            type: "input"
+        }
+    ]);
+}
+async function askQueryParametersInStartUrl(defaultIgnoredSearchParameters = constants.ignoreURLParametersMatching) {
+    const { shouldAskForIgnoreURLParametersMatching, ignoreURLParametersMatching = "" } = await askQuestion$2();
+    if (!shouldAskForIgnoreURLParametersMatching) {
+        return defaultIgnoredSearchParameters;
+    }
+    assert(ignoreURLParametersMatching.length > 0, errors["no-search-parameters-supplied"]);
+    const ignoreSearchParameters = ignoreURLParametersMatching.trim().split(",").filter(Boolean);
+    assert(ignoreSearchParameters.length > 0, errors["no-search-parameters-supplied"]);
+    assert(ignoreSearchParameters.every((param)=>!param.match(/^[^\w|-]/g)), errors["invalid-search-parameters-supplied"]);
+    return defaultIgnoredSearchParameters.concat(ignoreSearchParameters.map((searchParam)=>new RegExp(`^${searchParam}`)));
+}
+
+// The key used for the question/answer.
+const name$1 = "swDest";
+/**
+ * @param defaultDir
+ * @returns The answers from inquirer.
+ */ function askQuestion$1(defaultDir) {
+    return inquirer.prompt([
+        {
+            name: name$1,
+            message: `Where would you like your service worker file to be saved?`,
+            type: "input",
+            default: upath.join(defaultDir, "sw.js")
+        }
+    ]);
+}
+async function askSWDest(defaultDir = ".") {
+    const answers = await askQuestion$1(defaultDir);
+    // When prompt type is input the return type is string
+    // casting is safe
+    const swDest = answers[name$1].trim();
+    assert(swDest, errors["invalid-sw-dest"]);
+    return swDest;
+}
+
+// The key used for the question/answer.
+const name = "swSrc";
+/**
+ * @returns The answers from inquirer.
+ */ function askQuestion() {
+    return inquirer.prompt([
+        {
+            name,
+            message: oneLine`Where's your existing service worker file? To be used with
+      injectManifest, it should include a call to
+      'self.__SW_MANIFEST'`,
+            type: "input"
+        }
+    ]);
+}
+async function askSWSrc() {
+    const answers = await askQuestion();
+    // When prompt type is input the return is string or null
+    return answers[name] ? answers[name].trim() : null;
+}
+
+async function askQuestions(options = {}) {
+    const isInjectManifest = "injectManifest" in options;
+    const globDirectory = await askRootOfWebApp();
+    const globPatterns = await askExtensionsToCache(globDirectory);
+    const swSrc = isInjectManifest ? await askSWSrc() : undefined;
+    const swDest = await askSWDest(globDirectory);
+    const configLocation = await askConfigLocation();
+    // See https://github.com/GoogleChrome/workbox/issues/2985
+    const ignoreURLParametersMatching = isInjectManifest ? undefined : await askQueryParametersInStartUrl();
+    const config = {
+        globDirectory,
+        globPatterns,
+        swDest
+    };
+    if (swSrc) {
+        config.swSrc = swSrc;
+    }
+    if (ignoreURLParametersMatching) {
+        config.ignoreURLParametersMatching = ignoreURLParametersMatching;
+    }
+    return {
+        config,
+        configLocation
+    };
+}
+
+async function runWizard(options = {}) {
+    const { configLocation, config } = await askQuestions(options);
+    // See https://github.com/GoogleChrome/workbox/issues/2796
+    const contents = `module.exports = ${stringifyObject(config)};`;
+    await fse.writeFile(configLocation, contents);
+    logger.log(`To build your service worker, run
+
+  serwist injectManifest ${configLocation}
+
+as part of a build process. See https://goo.gl/fdTQBf for details.`);
+    const configDocsURL = "injectManifest" in options ? "https://goo.gl/8bs14N" : "https://goo.gl/gVo87N";
+    logger.log(oneLine`You can further customize your service worker by making changes
+    to ${configLocation}. See ${configDocsURL} for details.`);
+}
+
+/**
+ * Runs the specified build command with the provided configuration.
+ *
+ * @param options
+ */ async function runBuildCommand({ config, watch }) {
+    const { count, filePaths, size, warnings } = await injectManifest(config);
+    for (const warning of warnings){
+        logger.warn(warning);
+    }
+    if (filePaths.length === 1) {
+        logger.log(`The service worker file was written to ${config.swDest}`);
+    } else {
+        const message = filePaths.sort().map((filePath)=>`  • ${filePath}`).join(`\n`);
+        logger.log(`The service worker files were written to:\n${message}`);
+    }
+    logger.log(`The service worker will precache ${count} URLs, ` + `totaling ${prettyBytes(size)}.`);
+    if (watch) {
+        logger.log(`\nWatching for changes...`);
+    }
+}
+const app = async (params)=>{
+    // This should not be a user-visible error, unless meow() messes something up.
+    assert(params && Array.isArray(params.input), errors["missing-input"]);
+    // Default to showing the help message if there's no command provided.
+    const [command = "help", option] = params.input;
+    switch(command){
+        case "wizard":
+            {
+                await runWizard(params.flags);
+                break;
+            }
+        case "copyLibraries":
+            {
+                logger.log("This feature is under maintenance. We are really sorry for the inconvenience.");
+                break;
+            }
+        case "injectManifest":
+            {
+                const configPath = upath.resolve(process.cwd(), option || constants.defaultConfigFile);
+                let config;
+                try {
+                    config = readConfig(configPath);
+                } catch (error) {
+                    config = null;
+                    if (error instanceof Error) {
+                        logger.error(errors["invalid-common-js-module"]);
+                        throw error;
+                    }
+                }
+                if (config === null) {
+                    throw logger.error(errors["invalid-config-location"]);
+                }
+                logger.log(`Using configuration from ${configPath}.`);
+                // Determine whether we're in --watch mode, or one-off mode.
+                if (params?.flags?.watch) {
+                    const options = {
+                        ignoreInitial: true
+                    };
+                    if (config.globIgnores) {
+                        options.ignored = config.globIgnores;
+                    }
+                    if (config.globDirectory) {
+                        options.cwd = config.globDirectory;
+                    }
+                    if (config.globPatterns) {
+                        chokidar.watch(config.globPatterns, options).on("all", async ()=>{
+                            if (config === null) return;
+                            await runBuildCommand({
+                                config,
+                                watch: true
+                            });
+                        }).on("ready", async ()=>{
+                            if (config === null) return;
+                            await runBuildCommand({
+                                config,
+                                watch: true
+                            });
+                        }).on("error", (err)=>{
+                            logger.error(err.toString());
+                        });
+                    }
+                } else {
+                    await runBuildCommand({
+                        config,
+                        watch: false
+                    });
+                }
+                break;
+            }
+        case "help":
+            {
+                params.showHelp();
+            }
+        default:
+            {
+                throw new Error(errors["unknown-command"] + ` ` + command);
+            }
+    }
+};
+
+/*
+  Copyright 2018 Google LLC
+
+  Use of this source code is governed by an MIT-style
+  license that can be found in the LICENSE file or at
+  https://opensource.org/licenses/MIT.
+*/ // Helper to parse out less relevant info from an Error's stack trace.
+// Removes the initial portion, since that's obtained from error.message.
+// Removes every stack frame earlier than the last instance of moduleName,
+// since that's just frames related to the Node runtime/loader.
+function cleanupStackTrace(error, moduleName) {
+    if (!error.stack) {
+        return "";
+    }
+    const frames = error.stack.split(`\n`);
+    let startFrame;
+    let lastFrame = 0;
+    frames.forEach((frame, index)=>{
+        if (startFrame === undefined && frame.includes(`    at `)) {
+            startFrame = index;
+        }
+        if (frame.includes(`${moduleName}:`)) {
+            lastFrame = index;
+        }
+    });
+    return frames.slice(startFrame, lastFrame + 1).join(`\n`);
+}
+
+/*
+  Copyright 2018 Google LLC
+
+  Use of this source code is governed by an MIT-style
+  license that can be found in the LICENSE file or at
+  https://opensource.org/licenses/MIT.
+*/ const helpText = `Usage:
+$ serwist <command> [options]
+
+Commands:
+  wizard [--injectManifest]
+    Runs the configuration wizard, which will generate a
+    config file based on answers to questions.
+
+  injectManifest [<path/to/config.js>] [--watch]
+    Takes an existing service worker file and creates a
+    copy of it with a precache manifest "injected" into
+    it. The precache manifest is generated based on the
+    options in the config file (defaults to serwist.config.js).
+    If --watch is provided, the CLI will stay running, and will
+    rebuild the service worker each time a file in the precache
+    manifest changes.
+    See https://bit.ly/wb-injectManifest
+
+  copyLibraries <path/to/parent/dir>
+    Makes a local copy of all of the Workbox libraries inside
+    a version directory at the location specified. This is intended
+    for developers using injectManifest who prefer using local,
+    rather than CDN hosted, libraries.
+
+Config file:
+  In 'injectManifest' mode, the config file should be a
+  JavaScript file, in CommonJS module format.
+  By default, a config file named serwist.config.js in the current
+  directory is assumed, but this can be overridden.
+
+Examples:
+  $ serwist wizard
+  $ serwist wizard --injectManifest
+  $ serwist injectManifest configs/serwist-dev-config.js
+  $ serwist copyLibraries build/
+`;
+
+void (async ()=>{
+    const params = meow(helpText, {
+        importMeta: import.meta
+    });
+    updateNotifier({
+        pkg: params.pkg
+    }).notify();
+    try {
+        await app(params);
+    } catch (error) {
+        if (error instanceof Error) {
+            // Show the full error and stack trace if we're run with --debug.
+            if (params.flags.debug) {
+                if (error.stack) {
+                    logger.error(`\n${error.stack}`);
+                }
+            } else {
+                logger.error(`\n${error.message}`);
+                logger.debug(`${cleanupStackTrace(error, "app.js")}\n`);
+            }
+        }
+        process.exit(1);
+    }
+})();

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@serwist/cli",
+  "version": "8.0.0",
+  "type": "module",
+  "description": "@serwist/cli is the command line interface for Serwist.",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "serwist",
+    "serwistjs",
+    "service worker",
+    "caching",
+    "fetch requests",
+    "offline",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "author": "Google's Web DevRel Team, Serwist's Team",
+  "license": "MIT",
+  "repository": "serwist/serwist",
+  "bugs": "https://github.com/serwist/serwist/issues",
+  "homepage": "https://github.com/serwist/serwist",
+  "bin": {
+    "serwist": "dist/bin.js"
+  },
+  "dependencies": {
+    "chalk": "5.3.0",
+    "chokidar": "3.5.3",
+    "common-tags": "1.8.2",
+    "fs-extra": "11.1.1",
+    "glob": "10.3.10",
+    "inquirer": "9.2.11",
+    "meow": "12.1.1",
+    "ora": "7.0.1",
+    "pretty-bytes": "6.1.1",
+    "stringify-object": "5.0.0",
+    "upath": "2.0.1",
+    "update-notifier": "6.0.2",
+    "@serwist/build": "8.0.0"
+  },
+  "devDependencies": {
+    "@types/common-tags": "1.8.3",
+    "@types/fs-extra": "11.0.2",
+    "@types/inquirer": "9.0.5",
+    "@types/stringify-object": "4.0.3",
+    "@types/update-notifier": "6.0.5",
+    "rollup": "3.28.1",
+    "@serwist/constants": "8.0.0"
+  },
+  "scripts": {
+    "build": "rimraf dist && cross-env NODE_ENV=production rollup --config rollup.config.js",
+    "lint": "eslint src --ext ts,tsx,js,jsx,cjs,mjs",
+    "typecheck": "tsc"
+  }
+}