@wpelevator/wp-release 0.14.0 → 0.16.0

package/dist/commands/zip.js

@@ -1,107 +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 { zipPackage } from "../package-zip.js";
-import { getZipSummary } from "../summary.js";
-import { checkDirectory, fileSelectionArgs, getFileSelectionInput, getSourceDirArg, resolveOutput, sourceDirArgs, } from "./args.js";
+import { getChecksumsPath, zipPackage } from "../package-zip.js";
+import { SIGNING_KEY_ENV, signFiles, getSignaturePath } from "../signing.js";
+import { getSignSummary, getZipSummary } from "../summary.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]',
@@ -134,10 +42,24 @@ Options:
   --checksums                 Also write the checksums manifest of the archived
                               files next to the ZIP, with .checksums.json
                               instead of .zip
+  --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); 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
@@ -154,7 +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' },
         force: { type: 'boolean' },
     },
     async run({ values, positionals, cwd, configFile, logger, }) {
@@ -163,21 +92,89 @@ Examples:
             ? await getPackageSource(values, cwd, name, configFile)
             : await getDirectorySource(values, positionals, cwd);
         const filename = formatFilename(getString(values, 'filename-format') ?? FILENAME_FORMAT, { slug: source.slug, version: source.version });
+        const zipPath = resolveOutput({
+            cwd,
+            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 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;
+        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,
             selection: source.selection,
-            zipPath: resolveOutput({
-                cwd,
-                output: getString(values, 'output'),
-                filename: `${filename}.zip`,
-            }),
+            zipPath,
             rootFolder: getBoolean(values, 'no-root-folder')
                 ? null
                 : getString(values, 'root-folder') ?? source.slug,
             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}.`);
@@ -185,13 +182,42 @@ Examples:
         if (zipped.checksumsPath) {
             logger.info(zipped.checksumsPath);
         }
+        const signed = signing
+            ? { ...(await signFiles(signing)), formats: signing.formats }
+            : undefined;
+        signed?.signatures.forEach((path) => logger.info(path));
         const result = {
             ...zipped,
+            ...(zipped.checksumsSigning
+                ? {
+                    signatures: zipped.checksumsSignatures,
+                    publicKey: zipped.checksumsSigning.publicKey,
+                }
+                : {}),
+            ...(signed
+                ? {
+                    signatures: [
+                        ...signed.signatures,
+                        ...(zipped.checksumsSignatures ?? []),
+                    ],
+                    publicKey: signed.publicKey,
+                }
+                : {}),
             slug: source.slug,
             version: source.version,
             ...(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));
+        }
         return { exitCode: 0, result };
     },
 };

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { DISTIGNORE_FILENAME, parseExclude, resolveFileSelection, loadFileRules,
 export { FILENAME_FORMAT, formatFilename } from './filename.ts';
 export { CHECKSUMS_EXTENSION, CHECKSUM_ALGORITHMS, hashFile, hashFiles, createChecksums, writeChecksums, readChecksums, parseChecksums, compareChecksums, verifyChecksums, } from './checksums.ts';
 export { HEADER_BYTES, PLUGIN_HEADERS, THEME_HEADERS, README_HEADERS, README_FILENAMES, parseFileHeaders, parseReadmeHeaders, readFileStart, findFileHeaderLine, findReadmeHeaderLine, findMainPluginFile, readPackageMeta, } from './package-meta.ts';
-export { DEFAULT_SIGNATURE_FORMAT, SIGNATURE_EXTENSION, SIGNATURE_FORMATS, SIGNING_KEY_ENV, parseSigningKey, parsePublicKey, generateSigningKeyPair, getPublicKey, getPublicKeys, getFileDigest, getSignaturePath, isSignatureFormat, signFile, writeSignature, verifyFileSignature, } from './signing.ts';
+export { DEFAULT_SIGNATURE_FORMAT, SIGNATURE_EXTENSION, SIGNATURE_FORMATS, SIGNING_KEY_ENV, parseSigningKey, parsePublicKey, generateSigningKeyPair, getPublicKey, getPublicKeys, getFileDigest, getSignaturePath, isSignatureFormat, signFile, writeSignature, signFiles, verifyFileSignature, } from './signing.ts';
 export type { SignatureFormat, SignatureFormatHandler } from './signing.ts';
 export { MINISIGN_EXTENSION, createMinisignSignature, getMinisignPublicKey, parseMinisignPublicKey, verifyMinisignSignature, } from './minisign.ts';
 export { SSH_SIGNATURE_EXTENSION, SSH_SIGNATURE_NAMESPACE, createSshSignature, getSshPublicKey, parseSshPublicKey, verifySshSignature, } from './ssh-signature.ts';
@@ -34,10 +34,11 @@ export type { PackageDeployOutcome } from './commands/package-deploys.ts';
 export type { CliIo, CommandResults } from './cli.ts';
 export type { ChecksumsResult } from './commands/checksums.ts';
 export type { SignResult } from './commands/sign.ts';
+export type { SignFilesInput, SignFilesResult } from './signing.ts';
 export type { KeygenResult } from './commands/keygen.ts';
 export type { ZipResult } from './commands/zip.ts';
 export type { Command, CommandContext, CommandOutcome, ParsedValues, } from './commands/command.ts';
-export type { DeployArgsInput } from './commands/deploy-svn.ts';
+export type { DeployArgsInput, DeploySvnResult, } from './commands/deploy-svn.ts';
 export type { Annotation, LogEntry, LogLevel, LogWriter, LoggerOptions, OutputStream, SummaryBuilder, TextWriterOptions, } from './logger.ts';
 export type { GitHubActionsWriterOptions } from './github-actions-writer.ts';
 export type { Problem } from './errors.ts';
@@ -58,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

@@ -9,7 +9,7 @@ export { DISTIGNORE_FILENAME, parseExclude, resolveFileSelection, loadFileRules,
 export { FILENAME_FORMAT, formatFilename } from "./filename.js";
 export { CHECKSUMS_EXTENSION, CHECKSUM_ALGORITHMS, hashFile, hashFiles, createChecksums, writeChecksums, readChecksums, parseChecksums, compareChecksums, verifyChecksums, } from "./checksums.js";
 export { HEADER_BYTES, PLUGIN_HEADERS, THEME_HEADERS, README_HEADERS, README_FILENAMES, parseFileHeaders, parseReadmeHeaders, readFileStart, findFileHeaderLine, findReadmeHeaderLine, findMainPluginFile, readPackageMeta, } from "./package-meta.js";
-export { DEFAULT_SIGNATURE_FORMAT, SIGNATURE_EXTENSION, SIGNATURE_FORMATS, SIGNING_KEY_ENV, parseSigningKey, parsePublicKey, generateSigningKeyPair, getPublicKey, getPublicKeys, getFileDigest, getSignaturePath, isSignatureFormat, signFile, writeSignature, verifyFileSignature, } from "./signing.js";
+export { DEFAULT_SIGNATURE_FORMAT, SIGNATURE_EXTENSION, SIGNATURE_FORMATS, SIGNING_KEY_ENV, parseSigningKey, parsePublicKey, generateSigningKeyPair, getPublicKey, getPublicKeys, getFileDigest, getSignaturePath, isSignatureFormat, signFile, writeSignature, signFiles, verifyFileSignature, } from "./signing.js";
 export { MINISIGN_EXTENSION, createMinisignSignature, getMinisignPublicKey, parseMinisignPublicKey, verifyMinisignSignature, } from "./minisign.js";
 export { SSH_SIGNATURE_EXTENSION, SSH_SIGNATURE_NAMESPACE, createSshSignature, getSshPublicKey, parseSshPublicKey, verifySshSignature, } from "./ssh-signature.js";
 export { ZIP_MTIME, ZIP_FILE_MODE, createZip } from "./zip.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;

package/dist/output-files.js

@@ -0,0 +1,25 @@
+import { lstatSync } from 'node:fs';
+import { ValidationError } from "./errors.js";
+import { isErrorCode } from "./file-selection.js";
+/**
+ * Validate generated file destinations before writing release artifacts.
+ *
+ * @param paths Output file paths.
+ * @param force Whether existing regular files can be overwritten.
+ */
+export function checkOutputFiles(paths, force) {
+    for (const path of paths) {
+        let existing;
+        try {
+            existing = lstatSync(path);
+        }
+        catch (error) {
+            if (!isErrorCode(error, 'ENOENT')) {
+                throw error;
+            }
+        }
+        if (existing && (!force || !existing.isFile())) {
+            throw new ValidationError(`${path} already exists, pass --force to overwrite a regular file.`);
+        }
+    }
+}

package/dist/package-build.d.ts

@@ -0,0 +1,33 @@
+import type { PackageType } from './checksums.ts';
+import type { FileSelection } from './file-selection.ts';
+export interface BuildPackageInput {
+    sourceDir: string;
+    selection: FileSelection;
+    outputDir: string;
+    force?: boolean;
+    /** Write a checksums manifest alongside the build directory. */
+    checksums?: boolean;
+    /** Slug and version for the manifest. */
+    slug?: string;
+    version?: string | null;
+    type?: PackageType;
+}
+export interface BuildPackageResult {
+    outputDir: string;
+    files: number;
+    checksumsPath?: string;
+}
+/**
+ * Get the manifest path alongside a build directory.
+ *
+ * @param outputDir Build directory path.
+ * @return Absolute manifest path.
+ */
+export declare function getBuildChecksumsPath(outputDir: string): string;
+/**
+ * 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 declare function buildPackage(input: BuildPackageInput): Promise<BuildPackageResult>;