@wpelevator/wp-release 0.14.0 → 0.16.0

package/dist/package-build.js

@@ -0,0 +1,112 @@
+import { CHECKSUMS_EXTENSION, createChecksums, writeChecksums, } from "./checksums.js";
+import { checkOutputFiles } from "./output-files.js";
+import { copyFile, lstat, mkdir, mkdtemp, realpath, rename, rm, } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve, } from 'node:path';
+import { ValidationError } from "./errors.js";
+import { isErrorCode } from "./file-selection.js";
+import { getPackageFilesToRelease } from "./package-files.js";
+/**
+ * Get the manifest path alongside a build directory.
+ *
+ * @param outputDir Build directory path.
+ * @return Absolute manifest path.
+ */
+export function getBuildChecksumsPath(outputDir) {
+    return resolve(outputDir) + CHECKSUMS_EXTENSION;
+}
+/**
+ * Resolve existing ancestors too, so symlinked parents cannot overlap the source.
+ *
+ * @param path Directory path.
+ * @return Canonical path, including any missing child directories.
+ */
+async function resolveDirectoryPath(path) {
+    try {
+        return await realpath(path);
+    }
+    catch (error) {
+        if (isErrorCode(error, 'ENOENT')) {
+            return join(await resolveDirectoryPath(dirname(path)), basename(path));
+        }
+        throw error;
+    }
+}
+/**
+ * Copy the release selection into a directory, replacing an existing build only with force.
+ *
+ * @param input Source selection, destination and overwrite option.
+ * @return Destination and number of copied files.
+ */
+export async function buildPackage(input) {
+    const sourceDir = await realpath(input.sourceDir);
+    const outputDir = resolve(input.outputDir);
+    const canonicalOutput = await resolveDirectoryPath(outputDir);
+    const sourceFromOutput = relative(canonicalOutput, sourceDir);
+    const outputContainsSource = !sourceFromOutput ||
+        (!isAbsolute(sourceFromOutput) &&
+            sourceFromOutput !== '..' &&
+            !sourceFromOutput.startsWith('../'));
+    if (outputContainsSource) {
+        throw new ValidationError('The build output must not be the source directory or an ancestor of it.');
+    }
+    const existing = await lstat(outputDir).catch((error) => {
+        if (isErrorCode(error, 'ENOENT')) {
+            return null;
+        }
+        throw error;
+    });
+    if (existing && (!input.force || !existing.isDirectory())) {
+        throw new ValidationError(`${outputDir} already exists; use --force to replace an existing directory.`);
+    }
+    const checksumsPath = input.checksums
+        ? getBuildChecksumsPath(outputDir)
+        : null;
+    if (checksumsPath) {
+        checkOutputFiles([checksumsPath], input.force ?? false);
+    }
+    const { files, rules } = await getPackageFilesToRelease({
+        sourceDir,
+        selection: input.selection,
+        outputs: [
+            canonicalOutput,
+            ...(checksumsPath
+                ? [canonicalOutput + CHECKSUMS_EXTENSION]
+                : []),
+        ],
+        excludeSignatures: !!checksumsPath,
+        operation: 'build',
+    });
+    await mkdir(dirname(outputDir), { recursive: true });
+    const staging = await mkdtemp(join(dirname(outputDir), '.wp-release-build-'));
+    try {
+        for (const file of files) {
+            const target = join(staging, file);
+            await mkdir(dirname(target), { recursive: true });
+            await copyFile(join(sourceDir, file), target);
+        }
+        const manifest = checksumsPath
+            ? await createChecksums({
+                sourceDir: staging,
+                rules,
+                slug: input.slug ?? basename(sourceDir),
+                version: input.version,
+                type: input.type,
+            })
+            : null;
+        if (existing) {
+            await rm(outputDir, { recursive: true });
+        }
+        await rename(staging, outputDir);
+        if (checksumsPath && manifest) {
+            await writeChecksums(checksumsPath, manifest, input.force);
+        }
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+    return {
+        outputDir,
+        files: files.length,
+        ...(checksumsPath ? { checksumsPath } : {}),
+    };
+}

package/dist/package-files.d.ts

@@ -0,0 +1,25 @@
+import type { FileRules, FileSelection } from './file-selection.ts';
+interface PackageFilesInput {
+    /** Directory whose release files are selected. */
+    sourceDir: string;
+    /** Resolved ignore file and exclusion options. */
+    selection: FileSelection;
+    /** Absolute output paths to leave out of the release. */
+    outputs: string[];
+    /** Also exclude signatures of the output files. */
+    excludeSignatures?: boolean;
+    /** Operation name used in an empty-selection error. */
+    operation: 'build' | 'archive';
+}
+/**
+ * Prepare the release file selection shared by directory builds and ZIPs.
+ *
+ * @param  input Source, file selection and output exclusions.
+ * @return Sorted file paths and the rules used to select them.
+ * @throws {ValidationError} When no release files are selected.
+ */
+export declare function getPackageFilesToRelease(input: PackageFilesInput): Promise<{
+    files: string[];
+    rules: FileRules;
+}>;
+export {};

package/dist/package-files.js

@@ -0,0 +1,24 @@
+import { ValidationError } from "./errors.js";
+import { ignoreOwnFile, ignoreOwnSignature, loadFileRules, selectFiles, } from "./file-selection.js";
+/**
+ * Prepare the release file selection shared by directory builds and ZIPs.
+ *
+ * @param  input Source, file selection and output exclusions.
+ * @return Sorted file paths and the rules used to select them.
+ * @throws {ValidationError} When no release files are selected.
+ */
+export async function getPackageFilesToRelease(input) {
+    const { sourceDir, selection, outputs, excludeSignatures, operation } = input;
+    const rules = await loadFileRules(selection);
+    outputs.forEach((path) => {
+        ignoreOwnFile(rules, sourceDir, path);
+        if (excludeSignatures) {
+            ignoreOwnSignature(rules, sourceDir, path);
+        }
+    });
+    const files = await selectFiles(sourceDir, rules);
+    if (!files.length) {
+        throw new ValidationError(`No files to ${operation} in ${sourceDir}.`);
+    }
+    return { files, rules };
+}

package/dist/package-zip.d.ts

@@ -1,3 +1,5 @@
+import type { IntegrityConfig } from './integrity.ts';
+import type { SignFilesResult, SignatureFormat } from './signing.ts';
 import type { PackageType } from './checksums.ts';
 import type { FileSelection } from './file-selection.ts';
 export interface ZipPackageInput {
@@ -15,8 +17,13 @@ export interface ZipPackageInput {
     version?: string | null;
     /** Package type for the checksums manifest. */
     type?: PackageType;
-    /** Also write the checksums manifest next to the archive. */
+    /** Generate a checksums manifest beside the archive or embedded in it. */
     checksums?: boolean;
+    checksumsFile?: string;
+    embedChecksums?: boolean;
+    integrity?: IntegrityConfig;
+    /** Sign the manifest only, before embedding it. */
+    signChecksums?: SignatureFormat[];
     /** Overwrite existing output files. */
     force?: boolean;
 }
@@ -24,8 +31,13 @@ export interface ZipPackageInput {
 export interface ZipPackageResult {
     /** Absolute path of the ZIP. */
     zipPath: string;
-    /** Absolute path of the checksums manifest, set with checksums. */
+    /** Absolute path of the external manifest; absent when disabled or embedded. */
     checksumsPath?: string;
+    /** Relative path inside the package, only in embedded mode. */
+    checksumsEmbedded?: string;
+    /** Manifest signatures, external paths or package-relative embedded paths. */
+    checksumsSignatures?: string[];
+    checksumsSigning?: SignFilesResult;
     /** Number of archived files. */
     files: number;
 }

package/dist/package-zip.js

@@ -1,8 +1,13 @@
-import { existsSync } from 'node:fs';
-import { CHECKSUMS_EXTENSION, createChecksums, writeChecksums, } from "./checksums.js";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { checkChecksumsFile, resolveManifestCodec, encodeIntegrity, } from "./integrity.js";
+import { checkSigningInput, signFiles, getSignaturePath } from "./signing.js";
+import { CHECKSUMS_EXTENSION, createChecksums } from "./checksums.js";
 import { ValidationError } from "./errors.js";
-import { ignoreOwnFile, ignoreOwnSignature, loadFileRules, selectFiles, } from "./file-selection.js";
-import { createZip } from "./zip.js";
+import { checkOutputFiles } from "./output-files.js";
+import { getPackageFilesToRelease } from "./package-files.js";
+import { createZip, isValidRootFolder } from "./zip.js";
 const ZIP_EXTENSION = '.zip';
 /**
  * Get the checksums manifest path next to an archive, with .checksums.json
@@ -17,19 +22,6 @@ export function getChecksumsPath(zipPath) {
         : zipPath;
     return name + CHECKSUMS_EXTENSION;
 }
-/**
- * Fail before writing anything when an output file exists.
- *
- * @param  paths Output paths.
- * @param  force Whether existing files are overwritten.
- * @throws {ValidationError} If a file exists and force isn't set.
- */
-function checkOverwrite(paths, force) {
-    const existing = paths.filter((path) => !force && existsSync(path));
-    if (existing.length) {
-        throw new ValidationError(`${existing.join(' and ')} already exists, pass --force to overwrite it.`);
-    }
-}
 /**
  * Write a ZIP of the selected files of a plugin, theme or package, and
  * optionally the checksums manifest of the same files next to it. The zip
@@ -44,35 +36,134 @@ function checkOverwrite(paths, force) {
  */
 export async function zipPackage(input) {
     const { sourceDir, zipPath, force = false } = input;
-    const checksumsPath = input.checksums ? getChecksumsPath(zipPath) : null;
-    const outputs = [zipPath, checksumsPath].filter((path) => null !== path);
-    const rules = await loadFileRules(input.selection);
-    outputs.forEach((path) => ignoreOwnSignature(ignoreOwnFile(rules, sourceDir, path), sourceDir, path));
-    const files = await selectFiles(sourceDir, rules);
-    if (!files.length) {
-        throw new ValidationError(`No files to archive in ${sourceDir}.`);
+    if (input.rootFolder && !isValidRootFolder(input.rootFolder)) {
+        throw new ValidationError(`Invalid root folder "${input.rootFolder}", use a single folder name.`);
+    }
+    const enabled = input.checksums ||
+        input.checksumsFile ||
+        input.embedChecksums ||
+        input.signChecksums;
+    const codec = resolveManifestCodec(input.integrity?.codec);
+    const file = checkChecksumsFile(input.checksumsFile ??
+        (codec.id === 'wordpress-json'
+            ? basename(getChecksumsPath(zipPath))
+            : codec.filename));
+    const checksumsPath = enabled && !input.embedChecksums
+        ? resolve(dirname(zipPath), file)
+        : null;
+    if (checksumsPath === resolve(zipPath)) {
+        throw new ValidationError('The ZIP and checksums file must have different destinations.');
     }
-    checkOverwrite(outputs, force);
-    await createZip({
+    if (input.signChecksums) {
+        checkSigningInput({
+            paths: checksumsPath ? [checksumsPath] : [],
+            formats: input.signChecksums,
+            force,
+        });
+    }
+    const outputs = [zipPath, checksumsPath].filter((path) => null !== path);
+    const { files, rules } = await getPackageFilesToRelease({
         sourceDir,
-        files,
-        zipPath,
-        rootFolder: input.rootFolder,
-        force,
+        selection: input.selection,
+        outputs,
+        excludeSignatures: true,
+        operation: 'archive',
     });
-    if (checksumsPath) {
-        const manifest = await createChecksums({
+    checkOutputFiles(outputs, force);
+    const entries = {};
+    let checksumsSigning;
+    let stage;
+    const metadata = [
+        file,
+        ...['wordpress', 'minisign', 'ssh'].map((format) => getSignaturePath(file, format)),
+    ];
+    if (enabled &&
+        input.embedChecksums &&
+        metadata.some((path) => files.some((selected) => selected === path ||
+            selected.startsWith(path + '/') ||
+            path.startsWith(selected + '/')))) {
+        throw new ValidationError('Embedded checksums collide with selected source files. Remove the generated metadata or exclude it from the payload.');
+    }
+    try {
+        if (enabled) {
+            const manifest = await createChecksums({
+                sourceDir,
+                rules,
+                slug: input.slug,
+                version: input.version ?? null,
+                type: input.type,
+            });
+            const algorithms = input.integrity?.algorithms;
+            if (algorithms) {
+                if (!algorithms.length ||
+                    algorithms.some((algorithm) => !['md5', 'sha256'].includes(algorithm))) {
+                    throw new ValidationError('Checksums algorithms must be md5 and/or sha256.');
+                }
+                Object.values(manifest.files).forEach((hashes) => {
+                    if (!algorithms.includes('md5')) {
+                        delete hashes.md5;
+                    }
+                    if (!algorithms.includes('sha256')) {
+                        delete hashes.sha256;
+                    }
+                });
+            }
+            const bytes = await encodeIntegrity(codec, manifest);
+            stage = await mkdtemp(join(tmpdir(), 'wp-release-integrity-'));
+            const stagedFile = join(stage, file);
+            await mkdir(dirname(stagedFile), { recursive: true });
+            await writeFile(stagedFile, bytes);
+            if (input.signChecksums) {
+                checksumsSigning = await signFiles({
+                    paths: [stagedFile],
+                    formats: input.signChecksums,
+                });
+            }
+            if (input.embedChecksums) {
+                entries[file] = bytes;
+                for (const format of input.signChecksums ?? []) {
+                    entries[getSignaturePath(file, format)] =
+                        await readFile(getSignaturePath(stagedFile, format));
+                }
+            }
+            else if (checksumsPath) {
+                await mkdir(dirname(checksumsPath), { recursive: true });
+                await writeFile(checksumsPath, bytes, {
+                    flag: force ? 'w' : 'wx',
+                });
+                for (const format of input.signChecksums ?? []) {
+                    await writeFile(getSignaturePath(checksumsPath, format), await readFile(getSignaturePath(stagedFile, format)), { flag: force ? 'w' : 'wx' });
+                }
+            }
+        }
+        await mkdir(dirname(zipPath), { recursive: true });
+        await createZip({
             sourceDir,
-            rules,
-            slug: input.slug,
-            version: input.version ?? null,
-            type: input.type,
+            files,
+            entries,
+            zipPath,
+            rootFolder: input.rootFolder,
+            force,
         });
-        await writeChecksums(checksumsPath, manifest, force);
     }
+    finally {
+        if (stage) {
+            await rm(stage, { recursive: true, force: true });
+        }
+    }
+    const signatures = (input.signChecksums ?? []).map((format) => getSignaturePath(checksumsPath ?? file, format));
     return {
         zipPath,
         ...(checksumsPath ? { checksumsPath } : {}),
-        files: files.length,
+        ...(enabled && input.embedChecksums
+            ? { checksumsEmbedded: file }
+            : {}),
+        ...(checksumsSigning
+            ? {
+                checksumsSigning: { ...checksumsSigning, signatures },
+                checksumsSignatures: signatures,
+            }
+            : {}),
+        files: files.length + Object.keys(entries).length,
     };
 }

package/dist/release-tags.js

@@ -12,6 +12,12 @@ import { compareVersions, isPrerelease, isVersion } from "./versions.js";
  * @throws {ValidationError} For unknown packages, or an expected version without a single package.
  */
 export function selectTagPackages(packages, names, version) {
+    if (undefined !== version &&
+        !names.length &&
+        1 === packages.length &&
+        '.' === packages[0]?.path) {
+        names = [packages[0].name];
+    }
     if (undefined !== version && 1 !== names.length) {
         throw new ValidationError('An expected version requires exactly one package.');
     }

package/dist/signing.d.ts

@@ -119,6 +119,42 @@ export declare function getPublicKeys(key: KeyObject): Record<SignatureFormat, s
  * @throws {ValidationError} If the signature file exists and force isn't set.
  */
 export declare function writeSignature(path: string, privateKey: KeyObject, force?: boolean, format?: SignatureFormat): Promise<string>;
+export interface SignFilesInput {
+    /** Absolute paths of the files to sign. */
+    paths: string[];
+    /** Signature formats to write, the WordPress .sig by default. */
+    formats?: SignatureFormat[];
+    /** Base64 signing key, from the WP_RELEASE_SIGNING_KEY environment variable by default. */
+    key?: string;
+    /** Overwrite existing signature files. */
+    force?: boolean;
+}
+export interface SignFilesResult {
+    /** Absolute paths of the written signature files. */
+    signatures: string[];
+    /** Base64 public key of the signing key. */
+    publicKey: string;
+    /** Public key of the signing key in the form of each signature format. */
+    publicKeys: Record<SignatureFormat, string>;
+}
+/**
+ * Validate the signing key and destinations before writing files. The input
+ * files need not exist yet, so zip can check before creating its artifacts.
+ *
+ * @param  input Files, formats, key and whether to overwrite.
+ * @return Parsed signing key.
+ * @throws {ValidationError} Without a valid key or when a signature already exists without force.
+ */
+export declare function checkSigningInput(input: SignFilesInput): KeyObject;
+/**
+ * Sign files with a signature file of each format next to each, in order,
+ * so that a failure leaves a predictable set of files.
+ *
+ * @param  input Files, formats, key and whether to overwrite.
+ * @return The written signature files and the public keys.
+ * @throws {ValidationError} Without a key, for an invalid key, a missing file or an existing signature file without force.
+ */
+export declare function signFiles(input: SignFilesInput): Promise<SignFilesResult>;
 /**
  * Check a file against a signature file. A wordpress .sig file can hold one
  * signature per line, and is valid when any of them match, so that a file

package/dist/signing.js

@@ -1,5 +1,6 @@
 import { createPrivateKey, generateKeyPairSync, sign, verify, } from 'node:crypto';
-import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { readFile, stat, writeFile } from 'node:fs/promises';
 import { PUBLIC_KEY_BYTES, createRawPublicKey, digestFile, getRawPublicKey, } from "./ed25519.js";
 import { ValidationError } from "./errors.js";
 import { MINISIGN_EXTENSION, createMinisignSignature, getMinisignPublicKey, parseMinisignPublicKey, verifyMinisignSignature, } from "./minisign.js";
@@ -214,6 +215,56 @@ export async function writeSignature(path, privateKey, force = false, format = D
     });
     return signaturePath;
 }
+/**
+ * Validate the signing key and destinations before writing files. The input
+ * files need not exist yet, so zip can check before creating its artifacts.
+ *
+ * @param  input Files, formats, key and whether to overwrite.
+ * @return Parsed signing key.
+ * @throws {ValidationError} Without a valid key or when a signature already exists without force.
+ */
+export function checkSigningInput(input) {
+    const encoded = input.key ?? process.env[SIGNING_KEY_ENV];
+    const formats = input.formats ?? [DEFAULT_SIGNATURE_FORMAT];
+    if (!encoded?.trim()) {
+        throw new ValidationError(`Set the ${SIGNING_KEY_ENV} environment variable to the base64 Ed25519 signing key.`);
+    }
+    const privateKey = parseSigningKey(encoded);
+    const existing = input.paths
+        .flatMap((path) => formats.map((format) => getSignaturePath(path, format)))
+        .filter((path) => !input.force && existsSync(path));
+    if (existing.length) {
+        throw new ValidationError(`${existing.join(' and ')} already exists, pass --force to overwrite it.`);
+    }
+    return privateKey;
+}
+/**
+ * Sign files with a signature file of each format next to each, in order,
+ * so that a failure leaves a predictable set of files.
+ *
+ * @param  input Files, formats, key and whether to overwrite.
+ * @return The written signature files and the public keys.
+ * @throws {ValidationError} Without a key, for an invalid key, a missing file or an existing signature file without force.
+ */
+export async function signFiles(input) {
+    const formats = input.formats ?? [DEFAULT_SIGNATURE_FORMAT];
+    const privateKey = checkSigningInput(input);
+    await Promise.all(input.paths.map(async (path) => {
+        if (!(await stat(path).catch(() => null))?.isFile()) {
+            throw new ValidationError(`${path} is not a file.`);
+        }
+    }));
+    const signatures = [];
+    const jobs = input.paths.flatMap((path) => formats.map((format) => ({ path, format })));
+    for (const { path, format } of jobs) {
+        signatures.push(await writeSignature(path, privateKey, input.force, format));
+    }
+    return {
+        signatures,
+        publicKey: getPublicKey(privateKey),
+        publicKeys: getPublicKeys(privateKey),
+    };
+}
 /**
  * Check a file against a signature file. A wordpress .sig file can hold one
  * signature per line, and is valid when any of them match, so that a file

package/dist/single-project.d.ts

@@ -0,0 +1,32 @@
+import type { ChangesetConfig, PackageVersionSource } from './changeset-config.ts';
+/** Options used only when changesets have no JavaScript release config. */
+export interface SingleProjectOptions {
+    /** Explicit descriptors replace automatic version detection. Git tags are source-only. */
+    versions?: PackageVersionSource[];
+    /** Descriptor kind, optionally qualified with :file or :file#constant. */
+    versionFrom?: string;
+    baseBranch?: string;
+    remote?: string;
+    changesets?: string;
+    readmeChangelog?: boolean;
+    changelogInsertAfter?: string;
+}
+/** CLI names of version descriptor kinds. */
+export declare const VERSION_KINDS: {
+    readonly 'package-json': "package-json";
+    readonly 'composer-json': "composer-json";
+    readonly 'wordpress-plugin': "wordpress-plugin-header";
+    readonly 'wordpress-theme': "wordpress-theme-header";
+    readonly 'wordpress-stable-tag': "wordpress-stable-tag";
+    readonly 'php-constant': "php-constant";
+    readonly 'git-tag': "git-tag";
+};
+/**
+ * Build the root package config, without creating a configuration file.
+ *
+ * @param cwd       Project root directory.
+ * @param options   Explicit descriptors and shared release settings.
+ * @param tagFormat Tag format override, otherwise v{version}.
+ * @return Root package config, or undefined without a version source.
+ */
+export declare function resolveSingleProjectConfig(cwd: string, options?: SingleProjectOptions, tagFormat?: string): Promise<ChangesetConfig | undefined>;