@wpelevator/wp-release 0.0.0-stage → 0.1.0

package/dist/checksums.js

@@ -0,0 +1,216 @@
+import { createReadStream } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { ValidationError } from "./errors.js";
+import { isErrorCode, selectFiles } from "./file-selection.js";
+export const CHECKSUMS_EXTENSION = '.checksums.json';
+/**
+ * Hash algorithms in each file entry. MD5 is kept for compatibility with the
+ * WordPress.org checksums format; verification prefers SHA-256.
+ */
+export const CHECKSUM_ALGORITHMS = ['md5', 'sha256'];
+const PACKAGE_TYPES = ['plugin', 'theme'];
+/**
+ * Hash a file with every checksum algorithm in a single read.
+ *
+ * @param path File path.
+ * @return Hex digests keyed by algorithm.
+ */
+export async function hashFile(path) {
+    const md5 = createHash('md5');
+    const sha256 = createHash('sha256');
+    for await (const chunk of createReadStream(path)) {
+        md5.update(chunk);
+        sha256.update(chunk);
+    }
+    return { md5: md5.digest('hex'), sha256: sha256.digest('hex') };
+}
+/**
+ * Hash files one at a time, so that large plugins don't run out of file
+ * descriptors.
+ *
+ * @param sourceDir Directory the paths are relative to.
+ * @param files     Relative file paths.
+ * @return Digests keyed by relative path, in the order of `files`.
+ */
+export async function hashFiles(sourceDir, files) {
+    const hashes = {};
+    for (const file of files) {
+        hashes[file] = await hashFile(join(sourceDir, file));
+    }
+    return hashes;
+}
+/**
+ * Create a checksums manifest for the selected files of a directory.
+ *
+ * The manifest uses the format of the WordPress.org plugin checksums API
+ * (downloads.wordpress.org/plugin-checksums/{slug}/{version}.json), with
+ * paths relative to the plugin or theme folder:
+ *
+ *     { "plugin": "my-plugin", "version": "1.2.0", "files": { "my-plugin.php": { "md5": "…", "sha256": "…" } } }
+ *
+ * Themes use a "theme" key instead of "plugin". The version is left out when
+ * it's unknown.
+ *
+ * @param input Directory, file rules and package details.
+ * @return Checksums manifest.
+ */
+export async function createChecksums(input) {
+    const { sourceDir, rules, slug, version = null, type = 'plugin' } = input;
+    if (!isPackageType(type)) {
+        throw new ValidationError(`Unknown type "${type}", use ${PACKAGE_TYPES.join(' or ')}.`);
+    }
+    const files = await selectFiles(sourceDir, rules);
+    // Keep the slug and version before the files in the JSON.
+    return {
+        ...('theme' === type ? { theme: slug } : { plugin: slug }),
+        ...(version ? { version } : {}),
+        files: await hashFiles(sourceDir, files),
+    };
+}
+function isPackageType(type) {
+    return PACKAGE_TYPES.includes(type);
+}
+/**
+ * Write a checksums manifest as JSON.
+ *
+ * @param  path     Target file path.
+ * @param  manifest Manifest from createChecksums().
+ * @param  force    Overwrite an existing file.
+ * @throws {ValidationError} If the file exists and force isn't set.
+ */
+export async function writeChecksums(path, manifest, force = false) {
+    try {
+        await writeFile(path, JSON.stringify(manifest, null, '\t') + '\n', {
+            flag: force ? 'w' : 'wx',
+        });
+    }
+    catch (error) {
+        if (isErrorCode(error, 'EEXIST')) {
+            throw new ValidationError(`${path} already exists, pass --force to overwrite it.`);
+        }
+        throw error;
+    }
+}
+/**
+ * Read and validate a checksums manifest. Accepts manifests from
+ * createChecksums() and the WordPress.org checksums API, where a hash can
+ * also be a list of accepted values.
+ *
+ * @param  path Manifest file path.
+ * @return Checksums manifest.
+ * @throws {ValidationError} If the file isn't a valid manifest.
+ */
+export async function readChecksums(path) {
+    const contents = await readFile(path, 'utf8').catch((error) => {
+        throw isErrorCode(error, 'ENOENT')
+            ? new ValidationError(`Checksums file ${path} doesn't exist.`)
+            : error;
+    });
+    return parseChecksums(contents, path);
+}
+/**
+ * Parse and validate checksums manifest JSON.
+ *
+ * @param  contents Manifest JSON.
+ * @param  source   Name of the manifest for error messages.
+ * @return Checksums manifest.
+ * @throws {ValidationError} If the JSON isn't a valid manifest.
+ */
+export function parseChecksums(contents, source = 'checksums') {
+    const manifest = parseJson(contents, source);
+    const files = isRecord(manifest) ? manifest.files : undefined;
+    if (!isRecord(manifest) || !isRecord(files)) {
+        throw new ValidationError(`${source} has no "files" object.`);
+    }
+    const invalidPaths = Object.keys(files).filter((path) => !isValidPath(path));
+    const invalidHashes = Object.entries(files)
+        .filter(([, hashes]) => !isValidEntry(hashes))
+        .map(([path]) => path);
+    if (invalidPaths.length) {
+        throw new ValidationError(`${source} has paths outside the package folder: ${invalidPaths.join(', ')}.`);
+    }
+    if (invalidHashes.length) {
+        throw new ValidationError(`${source} has no md5 or sha256 hash for ${invalidHashes.join(', ')}.`);
+    }
+    return manifest;
+}
+function isRecord(value) {
+    return (Boolean(value) &&
+        'object' === typeof value &&
+        !Array.isArray(value));
+}
+/**
+ * Check that a manifest path is relative to the package folder, with forward
+ * slashes and without "." or ".." segments.
+ *
+ * @param path Manifest path.
+ * @return Whether the path is valid.
+ */
+function isValidPath(path) {
+    const segments = path.split('/');
+    return (!path.includes('\\') &&
+        segments.every((segment) => segment && '.' !== segment && '..' !== segment));
+}
+function parseJson(contents, source) {
+    try {
+        return JSON.parse(contents);
+    }
+    catch (error) {
+        throw new ValidationError(`${source} isn't valid JSON: ${error.message}`);
+    }
+}
+function isValidEntry(hashes) {
+    return (isRecord(hashes) &&
+        CHECKSUM_ALGORITHMS.some((algorithm) => [hashes[algorithm]]
+            .flat()
+            .some((hash) => 'string' === typeof hash && hash.length > 0)));
+}
+/**
+ * Compare expected file hashes with actual ones. A file matches when its
+ * SHA-256 is one of the expected values, or its MD5 for manifests without
+ * SHA-256.
+ *
+ * @param expected Expected hashes keyed by relative path.
+ * @param actual   Actual hashes keyed by relative path.
+ * @return Sorted lists of matched, changed, missing and extra paths, and whether all match.
+ */
+export function compareChecksums(expected, actual) {
+    const expectedPaths = Object.keys(expected).sort();
+    const present = expectedPaths.filter((path) => Object.hasOwn(actual, path));
+    const isMatch = (path) => matchesChecksum(expected[path], actual[path]);
+    const changed = present.filter((path) => !isMatch(path));
+    const missing = expectedPaths.filter((path) => !Object.hasOwn(actual, path));
+    const extra = Object.keys(actual)
+        .filter((path) => !Object.hasOwn(expected, path))
+        .sort();
+    return {
+        valid: 0 === changed.length + missing.length + extra.length,
+        matched: present.filter(isMatch),
+        changed,
+        missing,
+        extra,
+    };
+}
+function matchesChecksum(expected, actual) {
+    const algorithm = expected?.sha256 ? 'sha256' : 'md5';
+    return [expected?.[algorithm]]
+        .flat()
+        .map((hash) => String(hash).toLowerCase())
+        .includes(actual?.[algorithm] ?? '');
+}
+/**
+ * Verify the files of a directory against a checksums manifest. Paths that
+ * the rules ignore are skipped on both sides, so files created after the
+ * install (such as caches) can be excluded.
+ *
+ * @param input Directory, manifest and file rules.
+ * @return Result from compareChecksums().
+ */
+export async function verifyChecksums(input) {
+    const { sourceDir, manifest, rules } = input;
+    const expected = Object.fromEntries(Object.entries(manifest.files).filter(([path]) => !rules.ignores(path)));
+    const files = await selectFiles(sourceDir, rules);
+    return compareChecksums(expected, await hashFiles(sourceDir, files));
+}

package/dist/cli.d.ts

@@ -0,0 +1,42 @@
+import type { OutputStream } from './logger.ts';
+import type { Command } from './commands/command.ts';
+export interface CliIo {
+    /** Stream for regular output. */
+    stdout?: OutputStream;
+    /** Stream for errors. */
+    stderr?: OutputStream;
+    /** Working directory that relative paths resolve against. */
+    cwd?: string;
+}
+export declare const EXIT_SUCCESS = 0;
+export declare const EXIT_FAILURE = 1;
+export declare const EXIT_INVALID = 2;
+export declare const commands: Command[];
+/**
+ * Get the top-level help text listing all commands.
+ *
+ * @return Help text.
+ */
+export declare function getHelp(): string;
+/**
+ * Get the help text of a single command.
+ *
+ * @param command Command definition.
+ * @return Help text.
+ */
+export declare function getCommandHelp(command: Command): string;
+/**
+ * Find the command named by the first argument.
+ *
+ * @param args CLI arguments.
+ * @return Command definition.
+ */
+export declare function findCommand(args: string[]): Command | undefined;
+/**
+ * Run the CLI.
+ *
+ * @param args CLI arguments without the node and script paths.
+ * @param io   Output streams and working directory.
+ * @return Exit code.
+ */
+export declare function run(args: string[], io?: CliIo): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,163 @@
+import { parseArgs } from 'node:util';
+import zip from "./commands/zip.js";
+import checksums from "./commands/checksums.js";
+import verify from "./commands/verify.js";
+import versionCheck from "./commands/version-check.js";
+import deploySvn from "./commands/deploy-svn.js";
+import { Logger } from "./logger.js";
+import { getBoolean } from "./commands/command.js";
+export const EXIT_SUCCESS = 0;
+export const EXIT_FAILURE = 1;
+export const EXIT_INVALID = 2;
+export const commands = [
+    zip,
+    checksums,
+    verify,
+    versionCheck,
+    deploySvn,
+];
+const globalArgs = {
+    help: { type: 'boolean', short: 'h' },
+    verbose: { type: 'boolean', short: 'v' },
+    quiet: { type: 'boolean', short: 'q' },
+    ci: { type: 'boolean' },
+    json: { type: 'boolean' },
+};
+const globalOptions = `Global options:
+  -h, --help        Show help for the command
+  -v, --verbose     Print more output
+  -q, --quiet       Print errors only
+      --ci          Use GitHub Actions annotations (default when GITHUB_ACTIONS=true)
+      --json        Print the result as JSON`;
+/**
+ * Get the top-level help text listing all commands.
+ *
+ * @return Help text.
+ */
+export function getHelp() {
+    const width = Math.max(...commands.map((command) => command.name.length));
+    const list = commands
+        .map((command) => `  ${command.name.padEnd(width)}  ${command.summary}`)
+        .join('\n');
+    return `Usage: wp-release <command> [options]
+
+Package, checksum, verify and version-check WordPress plugins and themes, and deploy plugins to WordPress.org.
+
+Commands:
+${list}
+
+${globalOptions}
+
+Run "wp-release <command> --help" for command options.`;
+}
+/**
+ * Get the help text of a single command.
+ *
+ * @param command Command definition.
+ * @return Help text.
+ */
+export function getCommandHelp(command) {
+    return `Usage: wp-release ${command.usage}
+
+${command.summary}
+
+${command.help}
+
+${globalOptions}`;
+}
+/**
+ * Find the command named by the first argument.
+ *
+ * @param args CLI arguments.
+ * @return Command definition.
+ */
+export function findCommand(args) {
+    return commands.find((command) => command.name === args[0]);
+}
+/**
+ * Get the exit code for an error thrown while running a command.
+ *
+ * @param error Thrown error.
+ * @return Exit code.
+ */
+function getErrorExitCode(error) {
+    const { exitCode, code } = (error ?? {});
+    if ('number' === typeof exitCode && exitCode) {
+        return exitCode;
+    }
+    if (String(code).startsWith('ERR_PARSE_ARGS')) {
+        return EXIT_INVALID;
+    }
+    return EXIT_FAILURE;
+}
+/**
+ * Parse the arguments of a command and run it.
+ *
+ * The command's run() gets the parsed values and positionals, the working
+ * directory and a logger, and returns the exit code with a result that is
+ * printed with --json. With --json, regular output is suppressed so that
+ * stdout stays valid JSON.
+ *
+ * @param command Command definition with options and run().
+ * @param args    Arguments after the command name.
+ * @param io      Output streams and working directory.
+ * @return Exit code.
+ */
+async function runCommand(command, args, io) {
+    const { stdout, stderr, cwd } = io;
+    let logger = new Logger({ stdout, stderr });
+    try {
+        const { values, positionals } = parseArgs({
+            args,
+            options: { ...globalArgs, ...command.options },
+            allowPositionals: true,
+        });
+        logger = new Logger({
+            ci: getBoolean(values, 'ci'),
+            quiet: getBoolean(values, 'quiet') || getBoolean(values, 'json'),
+            verbose: getBoolean(values, 'verbose'),
+            stdout,
+            stderr,
+        });
+        const { exitCode, result } = await command.run({
+            values,
+            positionals,
+            cwd,
+            logger,
+        });
+        if (getBoolean(values, 'json')) {
+            stdout.write(JSON.stringify(result, null, '\t') + '\n');
+        }
+        return exitCode;
+    }
+    catch (error) {
+        logger.error(error instanceof Error ? error.message : String(error));
+        return getErrorExitCode(error);
+    }
+}
+/**
+ * Run the CLI.
+ *
+ * @param args CLI arguments without the node and script paths.
+ * @param io   Output streams and working directory.
+ * @return Exit code.
+ */
+export async function run(args, io = {}) {
+    const { stdout = process.stdout, stderr = process.stderr, cwd = process.cwd(), } = io;
+    const wantsHelp = args.includes('--help') || args.includes('-h');
+    const command = findCommand(args);
+    if (command && wantsHelp) {
+        stdout.write(getCommandHelp(command) + '\n');
+        return EXIT_SUCCESS;
+    }
+    if (command) {
+        return runCommand(command, args.slice(1), { stdout, stderr, cwd });
+    }
+    if (0 === args.length || wantsHelp || 'help' === args[0]) {
+        stdout.write(getHelp() + '\n');
+        return EXIT_SUCCESS;
+    }
+    stderr.write(`Unknown command "${args[0]}".\n\n`);
+    stderr.write(getHelp() + '\n');
+    return EXIT_INVALID;
+}

package/dist/commands/args.d.ts

@@ -0,0 +1,81 @@
+import type { ParseArgsOptionsConfig } from 'node:util';
+import type { FileRules } from '../file-selection.ts';
+import type { ParsedValues } from './command.ts';
+/**
+ * Options shared by the commands that select files with .distignore and
+ * --exclude, in node:util parseArgs() format.
+ */
+export declare const fileSelectionArgs: ParseArgsOptionsConfig;
+/**
+ * Map the parsed file selection flags to resolveFileSelection() input.
+ *
+ * @param values Parsed CLI values.
+ * @return The distignore and exclude input.
+ */
+export declare function getFileSelectionInput(values: ParsedValues): {
+    distignore: string | false | undefined;
+    exclude: string[];
+};
+/**
+ * Check that a command got no more positional arguments than it accepts.
+ *
+ * @param  positionals Positional arguments.
+ * @param  max         Number of accepted arguments.
+ * @return The positional arguments.
+ * @throws {ValidationError} With unexpected arguments.
+ */
+export declare function checkPositionals(positionals: string[], max: number): string[];
+/**
+ * Check that a path is an existing directory.
+ *
+ * @param  path Directory path.
+ * @throws {ValidationError} If the path isn't a directory.
+ */
+export declare function checkDirectory(path: string): Promise<void>;
+/**
+ * Check if a path is an existing directory.
+ *
+ * @param path Path to check.
+ * @return Whether the path is a directory.
+ */
+export declare function isDirectory(path: string): Promise<boolean>;
+/**
+ * Ignore a file that the command writes or reads, such as the checksums
+ * manifest, when it's inside the selected directory.
+ *
+ * @param rules     Matcher from loadFileRules().
+ * @param sourceDir Selected directory.
+ * @param path      Absolute file path.
+ * @return The same matcher.
+ */
+export declare function ignoreOwnFile(rules: FileRules, sourceDir: string, path: string): FileRules;
+/**
+ * Option for the source directory, which can also be the first positional
+ * argument.
+ */
+export declare const sourceDirArgs: ParseArgsOptionsConfig;
+/**
+ * Get the source directory from the positional argument or --source-dir.
+ *
+ * @param  values      Parsed CLI values.
+ * @param  positionals Positional arguments.
+ * @return The source directory argument, default ".".
+ * @throws {ValidationError} With extra arguments, or both forms set to different paths.
+ */
+export declare function getSourceDirArg(values: ParsedValues, positionals: string[]): string;
+export interface ResolveOutputInput {
+    /** Working directory. */
+    cwd: string;
+    /** The --output file path. */
+    output?: string;
+    /** Default filename in the working directory. */
+    filename: string;
+}
+/**
+ * Resolve the path of the file that a command writes: --output, or the
+ * default filename in the working directory.
+ *
+ * @param input Working directory, --output value and default filename.
+ * @return Absolute file path.
+ */
+export declare function resolveOutput(input: ResolveOutputInput): string;

package/dist/commands/args.js

@@ -0,0 +1,116 @@
+import { stat } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { ValidationError } from "../errors.js";
+import { getBoolean, getString, getStrings } from "./command.js";
+/**
+ * Options shared by the commands that select files with .distignore and
+ * --exclude, in node:util parseArgs() format.
+ */
+export const fileSelectionArgs = {
+    distignore: { type: 'string' },
+    'no-distignore': { type: 'boolean' },
+    exclude: { type: 'string', multiple: true },
+};
+/**
+ * Map the parsed file selection flags to resolveFileSelection() input.
+ *
+ * @param values Parsed CLI values.
+ * @return The distignore and exclude input.
+ */
+export function getFileSelectionInput(values) {
+    return {
+        distignore: getBoolean(values, 'no-distignore')
+            ? false
+            : getString(values, 'distignore'),
+        exclude: getStrings(values, 'exclude'),
+    };
+}
+/**
+ * Check that a command got no more positional arguments than it accepts.
+ *
+ * @param  positionals Positional arguments.
+ * @param  max         Number of accepted arguments.
+ * @return The positional arguments.
+ * @throws {ValidationError} With unexpected arguments.
+ */
+export function checkPositionals(positionals, max) {
+    if (positionals.length > max) {
+        throw new ValidationError(`Unexpected argument "${positionals[max]}".`);
+    }
+    return positionals;
+}
+/**
+ * Check that a path is an existing directory.
+ *
+ * @param  path Directory path.
+ * @throws {ValidationError} If the path isn't a directory.
+ */
+export async function checkDirectory(path) {
+    if (!(await isDirectory(path))) {
+        throw new ValidationError(`${path} is not a directory.`);
+    }
+}
+/**
+ * Check if a path is an existing directory.
+ *
+ * @param path Path to check.
+ * @return Whether the path is a directory.
+ */
+export async function isDirectory(path) {
+    const stats = await stat(path).catch(() => null);
+    return Boolean(stats?.isDirectory());
+}
+/**
+ * Ignore a file that the command writes or reads, such as the checksums
+ * manifest, when it's inside the selected directory.
+ *
+ * @param rules     Matcher from loadFileRules().
+ * @param sourceDir Selected directory.
+ * @param path      Absolute file path.
+ * @return The same matcher.
+ */
+export function ignoreOwnFile(rules, sourceDir, path) {
+    const relativePath = relative(sourceDir, path).split('\\').join('/');
+    const isInside = relativePath &&
+        '..' !== relativePath &&
+        !relativePath.startsWith('../') &&
+        !isAbsolute(relativePath);
+    if (isInside) {
+        // Escape the gitignore wildcards so that the pattern matches only this file.
+        rules.add(`/${relativePath.replace(/[\\*?[\]!#]/g, '\\$&')}`);
+    }
+    return rules;
+}
+/**
+ * Option for the source directory, which can also be the first positional
+ * argument.
+ */
+export const sourceDirArgs = {
+    'source-dir': { type: 'string' },
+};
+/**
+ * Get the source directory from the positional argument or --source-dir.
+ *
+ * @param  values      Parsed CLI values.
+ * @param  positionals Positional arguments.
+ * @return The source directory argument, default ".".
+ * @throws {ValidationError} With extra arguments, or both forms set to different paths.
+ */
+export function getSourceDirArg(values, positionals) {
+    const [positional] = checkPositionals(positionals, 1);
+    const option = getString(values, 'source-dir');
+    if (positional && option && positional !== option) {
+        throw new ValidationError(`Pass the source directory either as an argument or with --source-dir, got "${positional}" and "${option}".`);
+    }
+    return positional ?? option ?? '.';
+}
+/**
+ * Resolve the path of the file that a command writes: --output, or the
+ * default filename in the working directory.
+ *
+ * @param input Working directory, --output value and default filename.
+ * @return Absolute file path.
+ */
+export function resolveOutput(input) {
+    return resolve(input.cwd, input.output ?? input.filename);
+}

package/dist/commands/checksums.d.ts

@@ -0,0 +1,34 @@
+declare const _default: {
+    name: string;
+    usage: string;
+    summary: string;
+    help: string;
+    options: {
+        force: {
+            type: "boolean";
+        };
+        slug: {
+            type: "string";
+        };
+        version: {
+            type: "string";
+        };
+        type: {
+            type: "string";
+        };
+        'filename-format': {
+            type: "string";
+        };
+        output: {
+            type: "string";
+        };
+    };
+    run({ values, positionals, cwd, logger }: import("./command.ts").CommandContext): Promise<{
+        exitCode: number;
+        result: {
+            checksumsPath: string;
+            files: number;
+        };
+    }>;
+};
+export default _default;