@wpelevator/wp-release 0.15.0 → 0.16.0

package/dist/commands/verify.js

@@ -1,8 +1,10 @@
+import { readIntegrity, checkChecksumsFile, resolveManifestCodec, } from "../integrity.js";
+import { loadChangesetConfig } from "../changeset-config.js";
 import { existsSync } from 'node:fs';
 import { mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, isAbsolute, join, posix, resolve } from 'node:path';
-import { readChecksums, verifyChecksums } from "../checksums.js";
+import { verifyChecksums } from "../checksums.js";
 import { downloadFile, isUrl } from "../download.js";
 import { ignoreOwnFile, ignoreOwnSignature, loadFileRules, parseExclude, } from "../file-selection.js";
 import { ValidationError } from "../errors.js";
@@ -105,7 +107,7 @@ function getEmbeddedPath(checksumsPath, embedded) {
             ['.', '..'].includes(path))) {
         throw new ValidationError(`--embedded must be a path inside the plugin with forward slashes, got "${embedded}".`);
     }
-    return embedded || path.endsWith('.json') ? path : null;
+    return path;
 }
 /**
  * Get the manifest and signature pairs to look for inside the checked files.
@@ -180,9 +182,22 @@ async function hasSameContents(original, file) {
  */
 async function checkEmbeddedCopies(input) {
     const { dir, manifest, checksumsPath, embedded, format } = input;
-    const pairs = getCopyPairs(checksumsPath, getEmbeddedPath(checksumsPath, embedded), format);
+    const path = getEmbeddedPath(checksumsPath, embedded);
+    const pairs = getCopyPairs(checksumsPath, path, format).filter((pair) => pair.original !== join(dir, pair.copy) ||
+        existsSync(pair.original));
+    for (const other of Object.keys(SIGNATURE_FORMATS)) {
+        if (other !== format &&
+            path &&
+            existsSync(getSignaturePath(checksumsPath, other))) {
+            pairs.push({
+                original: getSignaturePath(checksumsPath, other),
+                copy: getSignaturePath(path, other),
+            });
+        }
+    }
     if (embedded) {
-        checkExplicitPairs(pairs, manifest);
+        checkExplicitPairs(pairs.filter((pair) => pair.original !== join(dir, pair.copy) ||
+            existsSync(pair.original)), manifest);
     }
     const found = pairs.filter(({ original, copy }) => existsSync(join(dir, copy)) &&
         (embedded ||
@@ -336,8 +351,10 @@ export default {
                           accepted as --source-dir <dir>
 
 Options:
-  --checksums <file>      Checksums manifest from "wp-release checksums" or the
-                          WordPress.org checksums API (required)
+  --checksums-file <file> Relative embedded manifest path (default: checksums.json)
+  --checksums-format <name> wordpress-json or sha256sum; custom codecs via --config
+  --checksums <file>      External checksums manifest from "wp-release checksums" or the
+                          WordPress.org checksums API (optional; otherwise reads embedded manifest)
   --zip <file|url>        Check the files of this ZIP, a local file or an
                           http(s) URL such as the ZIP that WordPress.org
                           builds for a release, instead of <source-dir>
@@ -381,6 +398,8 @@ file that isn't a matching copy is reported as extra. See --embedded for
 where the copies are looked for.`,
     options: {
         checksums: { type: 'string' },
+        'checksums-format': { type: 'string' },
+        'checksums-file': { type: 'string' },
         zip: { type: 'string' },
         'root-folder': { type: 'string' },
         embedded: { type: 'string' },
@@ -389,42 +408,59 @@ where the copies are looked for.`,
         ...sourceDirArgs,
         exclude: { type: 'string', multiple: true },
     },
-    async run({ values, positionals, cwd, logger }) {
+    async run({ values, positionals, cwd, configFile, logger }) {
         const zip = getString(values, 'zip');
         const sourceArg = positionals.length
             ? getSourceDirArg(values, positionals)
             : getString(values, 'source-dir');
         const checksums = getString(values, 'checksums');
-        if (!checksums) {
-            throw new ValidationError('Pass the checksums manifest with --checksums <file>.');
-        }
         if (zip && sourceArg) {
             throw new ValidationError('Pass either --zip or a source directory, not both.');
         }
-        const checksumsPath = resolve(cwd, checksums);
+        // Only load caller-selected configuration, never configuration inside the package.
+        const loaded = configFile
+            ? await loadChangesetConfig({ cwd, configFile })
+            : undefined;
+        const integrity = loaded?.config.integrity;
+        const codec = getString(values, 'checksums-format') ?? integrity?.codec;
+        const file = checkChecksumsFile(getString(values, 'checksums-file') ??
+            integrity?.file ??
+            resolveManifestCodec(codec).filename);
         const publicKey = getString(values, 'public-key');
         const format = getString(values, 'signature-format') ?? DEFAULT_SIGNATURE_FORMAT;
         if (!isSignatureFormat(format)) {
             throw new ValidationError(`Unknown signature format ${format}, use ${Object.keys(SIGNATURE_FORMATS).join(', ')}.`);
         }
-        if (publicKey) {
-            await checkSignature(checksumsPath, publicKey, format);
-            logger.info(`Signature of ${checksumsPath} is valid.`);
-        }
-        const manifest = await readChecksums(checksumsPath);
         const target = await resolveTarget({
             sourceDir: resolve(cwd, sourceArg ?? '.'),
             zip,
             cwd,
             rootFolder: getString(values, 'root-folder'),
         });
+        const checksumsPath = checksums
+            ? resolve(cwd, checksums)
+            : join(target.dir, file);
         try {
+            if (publicKey) {
+                await checkSignature(checksumsPath, publicKey, format);
+                if (!checksums) {
+                    for (const other of Object.keys(SIGNATURE_FORMATS)) {
+                        if (other !== format &&
+                            existsSync(getSignaturePath(checksumsPath, other))) {
+                            await checkSignature(checksumsPath, publicKey, other);
+                        }
+                    }
+                }
+                logger.info(`Signature of ${checksumsPath} is valid.`);
+            }
+            const manifest = await readIntegrity(checksumsPath, codec);
             return await verifyTarget({
                 target,
                 manifest,
                 checksumsPath,
                 exclude: getStrings(values, 'exclude'),
-                embedded: getString(values, 'embedded'),
+                embedded: getString(values, 'embedded') ??
+                    (checksums ? undefined : file),
                 format,
                 logger,
             });

package/dist/commands/zip.d.ts

@@ -8,9 +8,9 @@ export interface ZipResult extends ZipPackageResult {
     version: string | null;
     /** Zipped package, with --package. */
     package?: string;
-    /** Absolute paths of the signatures of the ZIP and the manifest, with --sign. */
+    /** External signature paths and package-relative embedded manifest signature paths. */
     signatures?: string[];
-    /** Base64 public key of the signing key, with --sign. */
+    /** Base64 public key of the signing key, with ZIP or manifest signing. */
     publicKey?: string;
 }
 declare const _default: {
@@ -19,22 +19,34 @@ declare const _default: {
     summary: string;
     help: string;
     options: {
-        package: {
+        'checksums-file': {
+            type: "string";
+        };
+        'checksums-format': {
+            type: "string";
+        };
+        'checksums-algorithms': {
             type: "string";
+            multiple: true;
         };
-        checksums: {
+        'embed-checksums': {
             type: "boolean";
         };
-        sign: {
+        'no-embed-checksums': {
             type: "boolean";
         };
-        'sign-format': {
-            type: "string";
-            multiple: true;
+        'no-sign-checksums': {
+            type: "boolean";
+        };
+        sign: {
+            type: "boolean";
         };
         force: {
             type: "boolean";
         };
+        package: {
+            type: "string";
+        };
         slug: {
             type: "string";
         };

package/dist/commands/zip.js

@@ -1,108 +1,15 @@
-import { basename, resolve } from 'node:path';
+import { checksumSigningArgs, getArtifactSigning } from "./artifact-signing.js";
 import { ValidationError } from "../errors.js";
-import { resolveFileSelection } from "../file-selection.js";
+import { basename, dirname, resolve, sep } from 'node:path';
+import { loadChangesetConfig } from "../changeset-config.js";
+import { resolveManifestCodec, checkChecksumsFile } from "../integrity.js";
+import { getPackageArg, getPackageSource, getDirectorySource, } from "./package-source.js";
 import { FILENAME_FORMAT, formatFilename } from "../filename.js";
-import { getPackageFiles } from "../package-deploy.js";
-import { readPackageMeta } from "../package-meta.js";
 import { getChecksumsPath, zipPackage } from "../package-zip.js";
-import { SIGNING_KEY_ENV, checkSigningInput, signFiles } from "../signing.js";
+import { SIGNING_KEY_ENV, signFiles, getSignaturePath } from "../signing.js";
 import { getSignSummary, getZipSummary } from "../summary.js";
-import { checkDirectory, fileSelectionArgs, getFileSelectionInput, getSourceDirArg, parseSignatureFormats, resolveOutput, sourceDirArgs, } from "./args.js";
+import { fileSelectionArgs, parseSignatureFormats, resolveOutput, sourceDirArgs, } from "./args.js";
 import { getBoolean, getString, getStrings } from "./command.js";
-/** Options of a source directory and its files, which --package takes from the config. */
-const SOURCE_FLAGS = [
-    'source-dir',
-    'distignore',
-    'no-distignore',
-    'exclude',
-    'exclude-gitattributes',
-];
-/**
- * Get the configured package to zip, failing for the options that set the
- * source directory and the files instead.
- *
- * @param  values      Parsed CLI values.
- * @param  positionals Positional arguments.
- * @return The package identifier or path, or undefined without --package.
- * @throws {ValidationError} For an empty --package, or --package with a source directory or file selection option.
- */
-function getPackageArg(values, positionals) {
-    const name = getString(values, 'package')?.trim();
-    const conflicts = SOURCE_FLAGS.filter((flag) => undefined !== getString(values, flag) ||
-        getBoolean(values, flag) ||
-        getStrings(values, flag).length);
-    if ('' === name) {
-        throw new ValidationError('--package <name> must not be empty.');
-    }
-    if (name && (positionals.length || conflicts.length)) {
-        throw new ValidationError(`--package takes the directory and files of the package from the config, so it can't be combined with ${positionals.length
-            ? 'a source directory'
-            : conflicts.map((flag) => `--${flag}`).join(', ')}.`);
-    }
-    return name;
-}
-/**
- * Describe the files of a directory with the slug and the version from the
- * options, or from the plugin or theme headers.
- *
- * @param values    Parsed CLI values.
- * @param sourceDir Directory to zip.
- * @param selection File selection.
- * @param slug      Default slug.
- * @return Source directory, file selection, slug, version and type.
- */
-async function describeSource(values, sourceDir, selection, slug) {
-    const name = getString(values, 'slug') ?? slug;
-    const meta = await readPackageMeta({ dir: sourceDir, slug: name });
-    return {
-        sourceDir,
-        selection,
-        slug: name,
-        version: getString(values, 'version') ?? meta?.version ?? null,
-        ...(meta ? { type: meta.type } : {}),
-    };
-}
-/**
- * Get the files of a source directory from the CLI options.
- *
- * @param values      Parsed CLI values.
- * @param positionals Positional arguments.
- * @param cwd         Working directory.
- * @return Source directory, file selection, slug and version.
- */
-async function getDirectorySource(values, positionals, cwd) {
-    const sourceDir = resolve(cwd, getSourceDirArg(values, positionals));
-    await checkDirectory(sourceDir);
-    return describeSource(values, sourceDir, resolveFileSelection({
-        cwd,
-        sourceDir,
-        ...getFileSelectionInput(values),
-    }), basename(cwd));
-}
-/**
- * Get the directory of a configured package with the files config of its
- * package group, which its deploys use too.
- *
- * @param  values     Parsed CLI values.
- * @param  cwd        Repository root with the wp-release config.
- * @param  name       Package identifier or path under the configured root.
- * @param  configFile Config file, instead of the conventional one.
- * @return Source directory, file selection, slug, version and package.
- * @throws {ValidationError} Without a config or for an unknown package.
- */
-async function getPackageSource(values, cwd, name, configFile) {
-    const pkg = await getPackageFiles({
-        cwd,
-        package: name,
-        ...(configFile ? { configFile } : {}),
-    });
-    const source = await describeSource(values, pkg.directory, resolveFileSelection({
-        cwd,
-        sourceDir: pkg.directory,
-        ...pkg.files,
-    }), basename(pkg.directory));
-    return { ...source, package: pkg.name };
-}
 export default {
     name: 'zip',
     usage: 'zip [<source-dir>] [options] | zip --package <name> [options]',
@@ -135,18 +42,24 @@ Options:
   --checksums                 Also write the checksums manifest of the archived
                               files next to the ZIP, with .checksums.json
                               instead of .zip
-  --sign                      Also sign the ZIP and the checksums manifest with
-                              the ${SIGNING_KEY_ENV} key, like
-                              "wp-release sign", writing a WordPress .sig next
-                              to each
+  --checksums-file <file>      Relative manifest filename; implies checksums.
+                              Beside the ZIP, or inside its package root with
+                              --embed-checksums. No absolute paths or dot segments.
+  --checksums-format <format>  wordpress-json (default) or sha256sum
+  --checksums-algorithms <names> md5,sha256 (default), comma-separated or repeated
+  --embed-checksums            Embed manifest instead of writing it beside ZIP
+  --no-embed-checksums         Override embedding configured in integrity
+  --sign-checksums             Sign the manifest only, before embedding it
+  --no-sign-checksums          Override configured manifest signing
+  --sign                      Sign only the ZIP with the ${SIGNING_KEY_ENV} key
   --sign-format <names>       Signature formats of --sign, comma-separated or
                               repeated, like wordpress,minisign,ssh, as the
                               --format of "wp-release sign" (default:
-                              wordpress); implies --sign
+                              wordpress); requires --sign or --sign-checksums
   --force                     Overwrite existing output files
 
-Entries are sorted and use a fixed timestamp and file mode, so the same files
-always give the same ZIP.
+Entries are sorted and use a fixed timestamp and file mode. Embedded minisign
+signatures include their signing time; other built-in metadata is deterministic.
 
 Examples:
   wp-release zip dist --slug my-plugin --checksums
@@ -163,9 +76,14 @@ Examples:
         ...sourceDirArgs,
         ...fileSelectionArgs,
         package: { type: 'string' },
-        checksums: { type: 'boolean' },
+        ...checksumSigningArgs,
+        'checksums-file': { type: 'string' },
+        'checksums-format': { type: 'string' },
+        'checksums-algorithms': { type: 'string', multiple: true },
+        'embed-checksums': { type: 'boolean' },
+        'no-embed-checksums': { type: 'boolean' },
+        'no-sign-checksums': { type: 'boolean' },
         sign: { type: 'boolean' },
-        'sign-format': { type: 'string', multiple: true },
         force: { type: 'boolean' },
     },
     async run({ values, positionals, cwd, configFile, logger, }) {
@@ -179,21 +97,68 @@ Examples:
             output: getString(values, 'output'),
             filename: `${filename}.zip`,
         });
+        const loaded = await loadChangesetConfig({ cwd, configFile });
+        const configured = loaded?.config.integrity;
+        const algorithms = getStrings(values, 'checksums-algorithms').flatMap((value) => value.split(','));
+        const integrity = {
+            ...configured,
+            codec: getString(values, 'checksums-format') ?? configured?.codec,
+            ...(algorithms.length
+                ? { algorithms: algorithms }
+                : {}),
+        };
+        const codec = resolveManifestCodec(integrity.codec);
+        const embed = !getBoolean(values, 'no-embed-checksums') &&
+            (getBoolean(values, 'embed-checksums') ||
+                Boolean(configured?.embed));
+        const checksumsFile = checkChecksumsFile(getString(values, 'checksums-file') ??
+            configured?.file ??
+            (codec.id === 'wordpress-json'
+                ? basename(getChecksumsPath(zipPath))
+                : codec.filename));
+        const manifestSign = !getBoolean(values, 'no-sign-checksums') &&
+            (getBoolean(values, 'sign-checksums') ||
+                Boolean(configured?.sign));
+        const checksums = getBoolean(values, 'checksums') ||
+            embed ||
+            manifestSign ||
+            Boolean(getString(values, 'checksums-file') ?? configured?.file);
         const signFormats = getStrings(values, 'sign-format');
-        const signing = getBoolean(values, 'sign') || signFormats.length
-            ? {
-                paths: [
-                    zipPath,
-                    ...(getBoolean(values, 'checksums')
-                        ? [getChecksumsPath(zipPath)]
-                        : []),
-                ],
-                formats: parseSignatureFormats(signFormats),
-                force: getBoolean(values, 'force'),
-            }
+        const configuredFormats = configured?.sign
+            ? configured.sign.formats ?? []
+            : [];
+        const formats = parseSignatureFormats(signFormats.length ? signFormats : configuredFormats);
+        if (signFormats.length &&
+            !manifestSign &&
+            !getBoolean(values, 'sign')) {
+            throw new ValidationError('--sign-format requires --sign or --sign-checksums; it does not enable signing.');
+        }
+        const signing = getBoolean(values, 'sign')
+            ? getArtifactSigning({
+                ...values,
+                'sign-checksums': false,
+                'sign-format': formats,
+            }, {
+                artifact: zipPath,
+                checksums: resolve(dirname(zipPath), checksumsFile),
+            })
             : undefined;
-        if (signing) {
-            checkSigningInput(signing);
+        const externalManifest = checksums && !embed
+            ? resolve(dirname(zipPath), checksumsFile)
+            : undefined;
+        const artifacts = [
+            zipPath,
+            ...(externalManifest ? [externalManifest] : []),
+            ...(signing
+                ? formats.map((format) => getSignaturePath(zipPath, format))
+                : []),
+            ...(externalManifest && manifestSign
+                ? formats.map((format) => getSignaturePath(externalManifest, format))
+                : []),
+        ];
+        if (new Set(artifacts).size !== artifacts.length ||
+            artifacts.some((path, index) => artifacts.some((other, otherIndex) => index !== otherIndex && other.startsWith(path + sep)))) {
+            throw new ValidationError('ZIP, manifest and signature destinations must be distinct.');
         }
         const zipped = await zipPackage({
             sourceDir: source.sourceDir,
@@ -205,7 +170,11 @@ Examples:
             slug: source.slug,
             version: source.version,
             ...(source.type ? { type: source.type } : {}),
-            checksums: getBoolean(values, 'checksums'),
+            checksums,
+            checksumsFile: checksums ? checksumsFile : undefined,
+            embedChecksums: embed,
+            integrity,
+            signChecksums: manifestSign ? formats : undefined,
             force: getBoolean(values, 'force'),
         });
         logger.debug(`Archived ${zipped.files} files from ${source.sourceDir}.`);
@@ -219,9 +188,18 @@ Examples:
         signed?.signatures.forEach((path) => logger.info(path));
         const result = {
             ...zipped,
+            ...(zipped.checksumsSigning
+                ? {
+                    signatures: zipped.checksumsSignatures,
+                    publicKey: zipped.checksumsSigning.publicKey,
+                }
+                : {}),
             ...(signed
                 ? {
-                    signatures: signed.signatures,
+                    signatures: [
+                        ...signed.signatures,
+                        ...(zipped.checksumsSignatures ?? []),
+                    ],
                     publicKey: signed.publicKey,
                 }
                 : {}),
@@ -230,6 +208,13 @@ Examples:
             ...(source.package ? { package: source.package } : {}),
         };
         logger.summary((context) => getZipSummary(context, result));
+        const checksumsSigning = zipped.checksumsSigning;
+        if (checksumsSigning) {
+            logger.summary((context) => getSignSummary(context, {
+                ...checksumsSigning,
+                formats,
+            }));
+        }
         if (signed) {
             logger.summary((context) => getSignSummary(context, signed));
         }

package/dist/index.d.ts

@@ -59,3 +59,9 @@ export type { SummaryContext } from './summary.ts';
 export type { CheckoutPath, DeployResult } from './svn-deploy.ts';
 export type { GitCommandInput, GitCommandOutput, GitRunner, RepositoryLocation, } from './git.ts';
 export type { GitDeployInput, GitDeployOptions, GitDeployResult, } from './git-deploy.ts';
+export type { SingleProjectOptions } from './single-project.ts';
+export { buildPackage } from './package-build.ts';
+export type { BuildPackageInput, BuildPackageResult } from './package-build.ts';
+export type { BuildResult } from './commands/build.ts';
+export { wordpressCodec, sha256sumCodec, resolveManifestCodec, readIntegrity, } from './integrity.ts';
+export type { ManifestCodec, IntegrityConfig } from './integrity.ts';

package/dist/index.js

@@ -27,3 +27,5 @@ export { GitDeploy, getDefaultToken, getGitAuthEnv, isValidRefName, resolveGitDe
 export { getGitDeployInputFromArgs } from "./commands/deploy-git.js";
 export { getDeployPackages, getGitDeploys, getPackageFiles, getSvnDeploys, } from "./package-deploy.js";
 export { zipPackage } from "./package-zip.js";
+export { buildPackage } from "./package-build.js";
+export { wordpressCodec, sha256sumCodec, resolveManifestCodec, readIntegrity, } from "./integrity.js";

package/dist/integrity.d.ts

@@ -0,0 +1,33 @@
+import type { ChecksumsManifest, ChecksumAlgorithm } from './checksums.ts';
+import type { SignatureFormat } from './signing.ts';
+/** Custom codecs receive the validated WordPress-compatible integrity model. */
+export interface ManifestCodec {
+    id: string;
+    filename: string;
+    encode: (manifest: ChecksumsManifest) => Uint8Array | Promise<Uint8Array>;
+    decode: (bytes: Uint8Array) => ChecksumsManifest | Promise<ChecksumsManifest>;
+}
+export interface IntegrityConfig {
+    codec?: 'wordpress-json' | 'sha256sum' | ManifestCodec;
+    algorithms?: ChecksumAlgorithm[];
+    file?: string;
+    embed?: boolean;
+    sign?: false | {
+        formats?: SignatureFormat[];
+    };
+}
+export declare const wordpressCodec: ManifestCodec;
+export declare const sha256sumCodec: ManifestCodec;
+export declare function resolveManifestCodec(value?: IntegrityConfig['codec']): ManifestCodec;
+/**
+ * Relative artifact paths cannot escape their destination or use Windows paths.
+ * @param file
+ */
+export declare function checkChecksumsFile(file: string): string;
+export declare function readIntegrity(path: string, codec?: IntegrityConfig['codec']): Promise<ChecksumsManifest>;
+/**
+ * Encode once and ensure the format preserves the selected payload hashes.
+ * @param codec
+ * @param manifest
+ */
+export declare function encodeIntegrity(codec: ManifestCodec, manifest: ChecksumsManifest): Promise<Buffer>;

package/dist/integrity.js

@@ -0,0 +1,115 @@
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { parseChecksums, readChecksums } from "./checksums.js";
+import { ValidationError } from "./errors.js";
+export const wordpressCodec = {
+    id: 'wordpress-json',
+    filename: 'checksums.json',
+    encode: (manifest) => Buffer.from(JSON.stringify(manifest, null, '\t') + '\n'),
+    decode: (bytes) => parseChecksums(Buffer.from(bytes).toString('utf8')),
+};
+export const sha256sumCodec = {
+    id: 'sha256sum',
+    filename: 'SHA256SUMS',
+    encode(manifest) {
+        const lines = Object.entries(manifest.files)
+            .sort()
+            .map(([path, hashes]) => {
+            if ('string' !== typeof hashes.sha256) {
+                throw new ValidationError('sha256sum requires one SHA-256 digest per file.');
+            }
+            const escaped = /[\\\n\r]/.test(path);
+            const name = path
+                .replaceAll('\\', '\\\\')
+                .replaceAll('\n', '\\n')
+                .replaceAll('\r', '\\r');
+            return `${escaped ? '\\' : ''}${hashes.sha256}  ${name}`;
+        });
+        return Buffer.from(lines.join('\n') + '\n');
+    },
+    decode(bytes) {
+        const files = Object.create(null);
+        for (const line of Buffer.from(bytes)
+            .toString('utf8')
+            .split('\n')
+            .filter(Boolean)) {
+            const match = /^(\\?)([a-fA-F0-9]{64}) [ *](.+)$/.exec(line);
+            if (!match) {
+                throw new ValidationError('Invalid SHA256SUMS entry.');
+            }
+            const path = match[1]
+                ? (match[3] ?? '').replace(/\\([\\nr])/g, (_, char) => ({ n: '\n', r: '\r', '\\': '\\' })[char] ?? '')
+                : match[3] ?? '';
+            if (Object.hasOwn(files, path)) {
+                throw new ValidationError(`Duplicate checksum path: ${path}`);
+            }
+            files[path] = { sha256: (match[2] ?? '').toLowerCase() };
+        }
+        return parseChecksums(JSON.stringify({ files }));
+    },
+};
+export function resolveManifestCodec(value = 'wordpress-json') {
+    if (typeof value === 'string') {
+        if (!['wordpress-json', 'sha256sum'].includes(value)) {
+            throw new ValidationError(`Unknown checksums format: ${value}.`);
+        }
+        return value === 'sha256sum' ? sha256sumCodec : wordpressCodec;
+    }
+    if (!value ||
+        typeof value.encode !== 'function' ||
+        typeof value.decode !== 'function' ||
+        !value.id ||
+        !value.filename) {
+        throw new ValidationError('A checksums codec needs id, filename, encode and decode.');
+    }
+    return value;
+}
+/**
+ * Relative artifact paths cannot escape their destination or use Windows paths.
+ * @param file
+ */
+export function checkChecksumsFile(file) {
+    if (!file ||
+        /[\\\x00-\x1f:]/.test(file) ||
+        file
+            .split('/')
+            .some((part) => !part || part === '.' || part === '..')) {
+        throw new ValidationError('--checksums-file must be a relative file path with forward slashes and no dot segments.');
+    }
+    return file;
+}
+export async function readIntegrity(path, codec) {
+    const selected = resolveManifestCodec(codec ??
+        (basename(path) === 'SHA256SUMS'
+            ? 'sha256sum'
+            : 'wordpress-json'));
+    const manifest = selected === wordpressCodec
+        ? await readChecksums(path)
+        : await selected.decode(await readFile(path));
+    return parseChecksums(JSON.stringify(manifest), path);
+}
+/**
+ * Encode once and ensure the format preserves the selected payload hashes.
+ * @param codec
+ * @param manifest
+ */
+export async function encodeIntegrity(codec, manifest) {
+    const bytes = Buffer.from(await codec.encode(manifest));
+    const decoded = parseChecksums(JSON.stringify(await codec.decode(bytes)));
+    const expected = Object.keys(manifest.files);
+    const actual = Object.keys(decoded.files);
+    const preserved = expected.length === actual.length &&
+        actual.every((path) => {
+            const hashes = decoded.files[path];
+            return (Boolean(manifest.files[path]) &&
+                Object.entries(hashes ?? {}).every(([algorithm, digest]) => digest ===
+                    manifest.files[path]?.[algorithm]));
+        });
+    if (!preserved ||
+        ['plugin', 'theme', 'version'].some((key) => decoded[key] !== undefined &&
+            decoded[key] !==
+                manifest[key])) {
+        throw new ValidationError('The checksums codec must preserve payload paths, digests and any represented package identity.');
+    }
+    return bytes;
+}

package/dist/output-files.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Validate generated file destinations before writing release artifacts.
+ *
+ * @param paths Output file paths.
+ * @param force Whether existing regular files can be overwritten.
+ */
+export declare function checkOutputFiles(paths: string[], force: boolean): void;