@wpelevator/wp-release 0.0.0-stage → 0.1.0

package/dist/commands/checksums.js

@@ -0,0 +1,76 @@
+import { basename, resolve } from 'node:path';
+import { CHECKSUMS_EXTENSION, createChecksums, writeChecksums, } from "../checksums.js";
+import { loadFileRules, resolveFileSelection } from "../file-selection.js";
+import { FILENAME_FORMAT, formatFilename } from "../filename.js";
+import { readPackageMeta } from "../package-meta.js";
+import { checkDirectory, fileSelectionArgs, getFileSelectionInput, getSourceDirArg, ignoreOwnFile, resolveOutput, sourceDirArgs, } from "./args.js";
+import { getBoolean, getString } from "./command.js";
+export default {
+    name: 'checksums',
+    usage: 'checksums [<source-dir>] [options]',
+    summary: 'Write the MD5 and SHA-256 hashes of every distributed file to a checksums manifest.',
+    help: `Arguments:
+  <source-dir>                Plugin or theme directory (default: .), also
+                              accepted as --source-dir <dir>
+
+Options:
+  --output <file>             Manifest file (default: the --filename-format name
+                              in the current directory)
+  --slug <slug>               Plugin or theme slug (default: project directory name)
+  --version <version>         Version for the manifest and filename
+                              (default: Version header)
+  --type <type>               plugin or theme (default: detected from the
+                              headers, else plugin)
+  --filename-format <format>  Filename with {slug} and {version}, followed by
+                              .checksums.json (default: {slug}.{version})
+  --distignore <file>         Ignore file (default: <source-dir>/.distignore when present)
+  --no-distignore             Don't read any ignore file
+  --exclude <patterns>        Extra gitignore-style patterns, comma-separated or
+                              repeated, like build/,assets/*,images/**/*
+  --force                     Overwrite an existing --output file
+
+The manifest uses the WordPress.org plugin checksums format, with paths
+relative to <source-dir>. Select the same files as "zip" so that the manifest
+matches the ZIP contents.`,
+    options: {
+        slug: { type: 'string' },
+        version: { type: 'string' },
+        type: { type: 'string' },
+        'filename-format': { type: 'string' },
+        output: { type: 'string' },
+        ...sourceDirArgs,
+        ...fileSelectionArgs,
+        force: { type: 'boolean' },
+    },
+    async run({ values, positionals, cwd, logger }) {
+        const sourceDir = resolve(cwd, getSourceDirArg(values, positionals));
+        const slug = getString(values, 'slug') ?? basename(cwd);
+        await checkDirectory(sourceDir);
+        const meta = await readPackageMeta({ dir: sourceDir, slug });
+        const version = getString(values, 'version') ?? meta?.version ?? null;
+        const filename = formatFilename(getString(values, 'filename-format') ?? FILENAME_FORMAT, { slug, version });
+        const checksumsPath = resolveOutput({
+            cwd,
+            output: getString(values, 'output'),
+            filename: filename + CHECKSUMS_EXTENSION,
+        });
+        const selection = resolveFileSelection({
+            cwd,
+            sourceDir,
+            ...getFileSelectionInput(values),
+        });
+        const rules = ignoreOwnFile(await loadFileRules(selection), sourceDir, checksumsPath);
+        const manifest = await createChecksums({
+            sourceDir,
+            rules,
+            slug,
+            version,
+            type: getString(values, 'type') ?? meta?.type,
+        });
+        const files = Object.keys(manifest.files).length;
+        await writeChecksums(checksumsPath, manifest, getBoolean(values, 'force'));
+        logger.debug(`Hashed ${files} files in ${sourceDir}.`);
+        logger.info(checksumsPath);
+        return { exitCode: 0, result: { checksumsPath, files } };
+    },
+};

package/dist/commands/command.d.ts

@@ -0,0 +1,63 @@
+import type { ParseArgsOptionsConfig } from 'node:util';
+import type { Logger } from '../logger.ts';
+/**
+ * Parsed option values from node:util parseArgs().
+ */
+export type ParsedValues = Record<string, string | boolean | Array<string | boolean> | undefined>;
+export interface CommandContext {
+    /** Parsed option values. */
+    values: ParsedValues;
+    /** Positional arguments after the command name. */
+    positionals: string[];
+    /** Working directory that relative paths resolve against. */
+    cwd: string;
+    /** Logger for the command output. */
+    logger: Logger;
+}
+export interface CommandOutcome {
+    /** Process exit code. */
+    exitCode: number;
+    /** Result printed with --json. */
+    result: unknown;
+}
+/**
+ * CLI command definition.
+ */
+export interface Command {
+    /** Command name, a single word or dashed words. */
+    name: string;
+    /** Usage line after "wp-release". */
+    usage: string;
+    /** One-line description. */
+    summary: string;
+    /** Help text for the arguments and options. */
+    help: string;
+    /** Options in node:util parseArgs() format. */
+    options?: ParseArgsOptionsConfig;
+    /** Run the command with the parsed arguments. */
+    run: (context: CommandContext) => Promise<CommandOutcome>;
+}
+/**
+ * Get a string option value.
+ *
+ * @param values Parsed option values.
+ * @param name   Option name.
+ * @return Option value, or undefined when not set.
+ */
+export declare function getString(values: ParsedValues, name: string): string | undefined;
+/**
+ * Get a boolean option value.
+ *
+ * @param values Parsed option values.
+ * @param name   Option name.
+ * @return Whether the option is set.
+ */
+export declare function getBoolean(values: ParsedValues, name: string): boolean;
+/**
+ * Get the values of a repeatable string option.
+ *
+ * @param values Parsed option values.
+ * @param name   Option name.
+ * @return Option values, empty when not set.
+ */
+export declare function getStrings(values: ParsedValues, name: string): string[];

package/dist/commands/command.js

@@ -0,0 +1,33 @@
+/**
+ * Get a string option value.
+ *
+ * @param values Parsed option values.
+ * @param name   Option name.
+ * @return Option value, or undefined when not set.
+ */
+export function getString(values, name) {
+    const value = values[name];
+    return 'string' === typeof value ? value : undefined;
+}
+/**
+ * Get a boolean option value.
+ *
+ * @param values Parsed option values.
+ * @param name   Option name.
+ * @return Whether the option is set.
+ */
+export function getBoolean(values, name) {
+    return true === values[name];
+}
+/**
+ * Get the values of a repeatable string option.
+ *
+ * @param values Parsed option values.
+ * @param name   Option name.
+ * @return Option values, empty when not set.
+ */
+export function getStrings(values, name) {
+    return [values[name]]
+        .flat()
+        .filter((value) => 'string' === typeof value);
+}

package/dist/commands/deploy-svn.d.ts

@@ -0,0 +1,74 @@
+import type { DeployInput } from '../deploy-options.ts';
+import type { ParsedValues } from './command.ts';
+export interface DeployArgsInput {
+    /** Parsed CLI values. */
+    values: ParsedValues;
+    /** Positional arguments. */
+    positionals: string[];
+    /** Working directory. */
+    cwd: string;
+}
+/**
+ * Map the parsed "deploy-svn" arguments to resolveDeployOptions() input.
+ * Flags that aren't passed stay undefined, so that the same defaults apply
+ * as for the GitHub Action inputs.
+ *
+ * @param input Parsed values, positionals and working directory.
+ * @return Deploy input.
+ */
+export declare function getDeployInputFromArgs(input: DeployArgsInput): DeployInput;
+declare const _default: {
+    name: string;
+    usage: string;
+    summary: string;
+    help: string;
+    options: {
+        'svn-url': {
+            type: "string";
+        };
+        'svn-username': {
+            type: "string";
+        };
+        message: {
+            type: "string";
+        };
+        force: {
+            type: "boolean";
+        };
+        'dry-run': {
+            type: "boolean";
+        };
+        trunk: {
+            type: "boolean";
+        };
+        'readme-only': {
+            type: "boolean";
+        };
+        'svn-tag': {
+            type: "string";
+        };
+        'assets-dir': {
+            type: "string";
+        };
+        'no-assets': {
+            type: "boolean";
+        };
+        slug: {
+            type: "string";
+        };
+        version: {
+            type: "string";
+        };
+        readme: {
+            type: "string";
+        };
+        'from-zip': {
+            type: "string";
+        };
+    };
+    run({ values, positionals, cwd, logger }: import("./command.ts").CommandContext): Promise<{
+        exitCode: number;
+        result: import("../svn-deploy.ts").DeployResult;
+    }>;
+};
+export default _default;

package/dist/commands/deploy-svn.js

@@ -0,0 +1,103 @@
+import { resolveDeployOptions } from "../deploy-options.js";
+import { SvnDeploy } from "../svn-deploy.js";
+import { fileSelectionArgs, getFileSelectionInput, getSourceDirArg, sourceDirArgs, } from "./args.js";
+import { getBoolean, getString } from "./command.js";
+/**
+ * Map the parsed "deploy-svn" arguments to resolveDeployOptions() input.
+ * Flags that aren't passed stay undefined, so that the same defaults apply
+ * as for the GitHub Action inputs.
+ *
+ * @param input Parsed values, positionals and working directory.
+ * @return Deploy input.
+ */
+export function getDeployInputFromArgs(input) {
+    const { values, positionals, cwd } = input;
+    const flag = (name) => getBoolean(values, name) || undefined;
+    return {
+        cwd,
+        sourceDir: getSourceDirArg(values, positionals),
+        slug: getString(values, 'slug'),
+        version: getString(values, 'version'),
+        trunk: flag('trunk'),
+        readmeOnly: flag('readme-only'),
+        svnTag: getString(values, 'svn-tag'),
+        assets: getBoolean(values, 'no-assets') ? false : undefined,
+        assetsDir: getString(values, 'assets-dir'),
+        readme: getString(values, 'readme'),
+        fromZip: getString(values, 'from-zip'),
+        ...getFileSelectionInput(values),
+        svnUrl: getString(values, 'svn-url'),
+        svnUsername: getString(values, 'svn-username'),
+        gitRef: process.env.GITHUB_REF,
+        message: getString(values, 'message'),
+        force: flag('force'),
+        dryRun: flag('dry-run'),
+    };
+}
+export default {
+    name: 'deploy-svn',
+    usage: 'deploy-svn [<source-dir>] [options]',
+    summary: 'Deploy a plugin to the WordPress.org plugin SVN repository.',
+    help: `Arguments:
+  <source-dir>            Directory with the plugin files (default: .), also
+                          accepted as --source-dir <dir>
+
+Writes (none by default, assets only with --assets-dir):
+  --trunk                 Sync the full source directory to trunk/
+  --readme-only           Sync only the readme to trunk/ (not with --trunk)
+  --svn-tag <version>     Copy trunk/ to tags/<version> (requires --trunk).
+                          A leading "v" is stripped.
+  --assets-dir <dir>      Sync this directory with banners, icons and
+                          screenshots to assets/
+  --no-assets             Don't sync --assets-dir for this run
+
+Options:
+  --slug <slug>           Plugin slug (default: project directory name)
+  --version <version>     Version to check (default: --svn-tag, then the Version header)
+  --readme <file>         Readme file (default: readme.txt)
+  --from-zip <file>       Deploy the contents of a ZIP with a {slug}/ root folder
+                          instead of <source-dir>
+  --distignore <file>     Ignore file (default: <source-dir>/.distignore when present)
+  --no-distignore         Don't read any ignore file
+  --exclude <patterns>    Extra gitignore-style patterns, comma-separated or repeated
+  --svn-url <url>         Repository URL with {slug}
+                          (default: https://plugins.svn.wordpress.org/{slug}/)
+  --svn-username <name>   SVN username (env: SVN_USERNAME, password: SVN_PASSWORD)
+  --message <text>        Commit message
+  --force                 Replace an existing SVN tag
+  --dry-run               Run everything except the commit
+
+Credentials are only needed to commit. Exits with 3 when they're missing
+or rejected.
+
+Examples:
+  wp-release deploy-svn dist --trunk --svn-tag 1.2.0 --assets-dir .wordpress-org
+      Deploy 1.2.0 to trunk and the tag, and update the assets
+  wp-release deploy-svn dist --readme-only
+      Update only the readme
+  wp-release deploy-svn --assets-dir .wordpress-org
+      Update only the assets`,
+    options: {
+        ...sourceDirArgs,
+        trunk: { type: 'boolean' },
+        'readme-only': { type: 'boolean' },
+        'svn-tag': { type: 'string' },
+        'assets-dir': { type: 'string' },
+        'no-assets': { type: 'boolean' },
+        slug: { type: 'string' },
+        version: { type: 'string' },
+        readme: { type: 'string' },
+        'from-zip': { type: 'string' },
+        ...fileSelectionArgs,
+        'svn-url': { type: 'string' },
+        'svn-username': { type: 'string' },
+        message: { type: 'string' },
+        force: { type: 'boolean' },
+        'dry-run': { type: 'boolean' },
+    },
+    async run({ values, positionals, cwd, logger }) {
+        const options = resolveDeployOptions(getDeployInputFromArgs({ values, positionals, cwd }));
+        const result = await new SvnDeploy(options, logger).run();
+        return { exitCode: 0, result };
+    },
+};

package/dist/commands/verify.d.ts

@@ -0,0 +1,27 @@
+declare const _default: {
+    name: string;
+    usage: string;
+    summary: string;
+    help: string;
+    options: {
+        exclude: {
+            type: "string";
+            multiple: true;
+        };
+        checksums: {
+            type: "string";
+        };
+    };
+    run({ values, positionals, cwd, logger }: import("./command.ts").CommandContext): Promise<{
+        exitCode: number;
+        result: {
+            valid: boolean;
+            checksumsPath: string;
+            matched: number;
+            changed: string[];
+            missing: string[];
+            extra: string[];
+        };
+    }>;
+};
+export default _default;

package/dist/commands/verify.js

@@ -0,0 +1,60 @@
+import { resolve } from 'node:path';
+import { readChecksums, verifyChecksums } from "../checksums.js";
+import { loadFileRules, parseExclude } from "../file-selection.js";
+import { ValidationError } from "../errors.js";
+import { checkDirectory, getSourceDirArg, ignoreOwnFile, sourceDirArgs, } from "./args.js";
+import { getString, getStrings } from "./command.js";
+export default {
+    name: 'verify',
+    usage: 'verify [<source-dir>] --checksums <file> [options]',
+    summary: 'Check the files of a plugin or theme directory against a checksums manifest.',
+    help: `Arguments:
+  <source-dir>            Plugin or theme directory (default: .), also
+                          accepted as --source-dir <dir>
+
+Options:
+  --checksums <file>      Checksums manifest from "wp-release checksums" or the
+                          WordPress.org checksums API (required)
+  --exclude <patterns>    Gitignore-style patterns to skip in both the directory
+                          and the manifest, comma-separated or repeated
+
+Reports every changed, missing and extra file, and exits with 2 unless all
+files match. Unlike "checksums" and "zip", verify doesn't read .distignore,
+so that an ignore file inside the checked directory can't hide added files.
+Use --exclude to skip files that aren't part of the release. A file matches when its SHA-256 equals the manifest, or its MD5
+for manifests without SHA-256.`,
+    options: {
+        checksums: { type: 'string' },
+        ...sourceDirArgs,
+        exclude: { type: 'string', multiple: true },
+    },
+    async run({ values, positionals, cwd, logger }) {
+        const sourceDir = resolve(cwd, getSourceDirArg(values, positionals));
+        const checksums = getString(values, 'checksums');
+        if (!checksums) {
+            throw new ValidationError('Pass the checksums manifest with --checksums <file>.');
+        }
+        await checkDirectory(sourceDir);
+        const checksumsPath = resolve(cwd, checksums);
+        const manifest = await readChecksums(checksumsPath);
+        const rules = ignoreOwnFile(await loadFileRules({
+            exclude: parseExclude(getStrings(values, 'exclude')),
+        }), sourceDir, checksumsPath);
+        const { valid, matched, changed, missing, extra } = await verifyChecksums({ sourceDir, manifest, rules });
+        changed.forEach((file) => logger.error(`Changed: ${file}`));
+        missing.forEach((file) => logger.error(`Missing: ${file}`));
+        extra.forEach((file) => logger.error(`Not in the checksums: ${file}`));
+        logger.info(`${matched.length} files match, ${changed.length} changed, ${missing.length} missing and ${extra.length} extra in ${sourceDir}.`);
+        return {
+            exitCode: valid ? 0 : 2,
+            result: {
+                valid,
+                checksumsPath,
+                matched: matched.length,
+                changed,
+                missing,
+                extra,
+            },
+        };
+    },
+};

package/dist/commands/version-check.d.ts

@@ -0,0 +1,38 @@
+declare const _default: {
+    name: string;
+    usage: string;
+    summary: string;
+    help: string;
+    options: {
+        slug: {
+            type: "string";
+        };
+        version: {
+            type: "string";
+        };
+        'git-tag': {
+            type: "string";
+        };
+        'git-tag-format': {
+            type: "string";
+        };
+        constant: {
+            type: "string";
+            multiple: true;
+        };
+        readme: {
+            type: "string";
+        };
+        'no-stable-tag': {
+            type: "boolean";
+        };
+    };
+    run({ values, positionals, cwd, logger }: import("./command.ts").CommandContext): Promise<{
+        exitCode: number;
+        result: {
+            version: string | null;
+            mismatches: import("../version-check.ts").VersionMismatch[];
+        };
+    }>;
+};
+export default _default;

package/dist/commands/version-check.js

@@ -0,0 +1,80 @@
+import { basename, resolve } from 'node:path';
+import { isTagRef } from "../deploy-options.js";
+import { ValidationError } from "../errors.js";
+import { readPackageMeta } from "../package-meta.js";
+import { GIT_TAG_FORMAT, findVersionMismatches } from "../version-check.js";
+import { checkDirectory, getSourceDirArg, sourceDirArgs } from "./args.js";
+import { getBoolean, getString, getStrings } from "./command.js";
+/**
+ * Get the git tag to compare: --git-tag, or GITHUB_REF when it's a tag.
+ *
+ * @param gitTag The --git-tag value.
+ * @return Tag name or ref, or null without a tag.
+ */
+function getGitTag(gitTag) {
+    const ref = process.env.GITHUB_REF;
+    return gitTag ?? (isTagRef(ref) ? ref ?? null : null);
+}
+export default {
+    name: 'version-check',
+    usage: 'version-check [<source-dir>] [options]',
+    summary: 'Check that the Version header, readme Stable tag, constants and git tag agree.',
+    help: `Arguments:
+  <source-dir>               Plugin or theme directory (default: .), also
+                             accepted as --source-dir <dir>
+
+Options:
+  --slug <slug>              Plugin or theme slug, for {slug} in the tag format
+                             (default: project directory name)
+  --version <version>        Expected version (default: Version header)
+  --git-tag <tag>            Git tag to compare (default: GITHUB_REF when it is a tag)
+  --git-tag-format <format>  Tag format with {slug} and {version} (default: {version}).
+                             A leading "v" in the version is ignored.
+  --constant <NAME>          PHP constant that must equal the version (repeatable)
+  --readme <file>            Readme file (default: readme.txt, then readme.md)
+  --no-stable-tag            Skip the readme Stable tag check
+
+Reports every mismatch and exits with 2 unless all versions agree. Themes have
+no Stable tag, so it's only checked for plugins.`,
+    options: {
+        slug: { type: 'string' },
+        version: { type: 'string' },
+        'git-tag': { type: 'string' },
+        'git-tag-format': { type: 'string' },
+        constant: { type: 'string', multiple: true },
+        readme: { type: 'string' },
+        'no-stable-tag': { type: 'boolean' },
+        ...sourceDirArgs,
+    },
+    async run({ values, positionals, cwd, logger }) {
+        const sourceDir = resolve(cwd, getSourceDirArg(values, positionals));
+        const slug = getString(values, 'slug') ?? basename(cwd);
+        await checkDirectory(sourceDir);
+        const meta = await readPackageMeta({
+            dir: sourceDir,
+            slug,
+            readme: getString(values, 'readme'),
+        });
+        if (!meta) {
+            throw new ValidationError(`No plugin or theme headers found in ${sourceDir}.`);
+        }
+        const { version, mismatches } = await findVersionMismatches({
+            sourceDir,
+            meta,
+            slug,
+            version: getString(values, 'version'),
+            gitTag: getGitTag(getString(values, 'git-tag')),
+            gitTagFormat: getString(values, 'git-tag-format') ?? GIT_TAG_FORMAT,
+            constants: getStrings(values, 'constant'),
+            stableTag: !getBoolean(values, 'no-stable-tag'),
+        });
+        mismatches.forEach((mismatch) => logger.error(mismatch.message));
+        if (!mismatches.length) {
+            logger.info(`All versions match ${version}.`);
+        }
+        return {
+            exitCode: mismatches.length ? 2 : 0,
+            result: { version, mismatches },
+        };
+    },
+};

package/dist/commands/zip.d.ts

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