@wpelevator/wp-release 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaspars Dambis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,317 @@
-# Temporary Holding Version
+# WP Release
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Package, checksum, verify and version-check WordPress plugins and themes, and deploy plugins to the WordPress.org plugin SVN repository. Usable as a CLI, as a library, and through the [`wp-release-deploy-svn`](../../actions/wp-release-deploy-svn) GitHub Action.
+
+Themes are released by uploading a ZIP on WordPress.org, so `deploy-svn` is for plugins only; use `zip` to build the theme upload.
+
+**Status:** first release (0.x). All commands are implemented and tested against local SVN repositories, but `deploy-svn` hasn't been used for a WordPress.org deploy yet, so try it with `--dry-run` first. Signing checksums manifests is planned.
+
+Option names follow the existing community tools (10up WordPress.org actions, `wp dist-archive`, `wp-scripts plugin-zip`, `grunt-wp-deploy`) so that migrating needs few or no renames. See [Comparison with existing tools](#comparison-with-existing-tools) for the differences.
+
+## Install
+
+```bash
+npm install --save-dev @wpelevator/wp-release
+```
+
+Requires Node.js 22.12 or later. `deploy-svn` also needs the `svn` command line client.
+
+The package is an ES module with TypeScript type definitions. CommonJS projects can load it with `require( '@wpelevator/wp-release' )`, which Node.js supports for ES modules without top-level `await` since 22.12.
+
+## CLI
+
+```bash
+npx wp-release --help
+```
+
+| Command | Description |
+|---|---|
+| `wp-release zip [<source-dir>] [options]` | Create a ZIP archive with a `{slug}/` root folder, respecting `.distignore`. |
+| `wp-release checksums [<source-dir>] [options]` | Write the MD5 and SHA-256 hashes of every distributed file to a checksums manifest. |
+| `wp-release verify [<source-dir>] --checksums <file> [options]` | Check a plugin or theme directory against a checksums manifest. |
+| `wp-release version-check [<source-dir>] [options]` | Check that the `Version` header, readme `Stable tag`, PHP constants and git tag agree. |
+| `wp-release deploy-svn [<source-dir>] [options]` | Deploy a plugin to the WordPress.org plugin SVN repository. |
+
+Run `npx wp-release <command> --help` for the options of each command. Every command reads the plugin or theme directory from the first argument or `--source-dir`, defaulting to the current directory, and prints its result as JSON with `--json`.
+
+### Naming convention
+
+`@wpelevator/wp-release` is the suite of release tools and `wp-release` is its CLI. "Release" is the whole workflow; each command is one operation in it. Commands are flat: a single word or dashed words like `version-check` and `deploy-svn`, without command groups or aliases. Each GitHub Action is named `wp-release-` followed by the command name, so the CLI command and the `uses:` name always match:
+
+| Capability | CLI command | GitHub Action |
+|---|---|---|
+| Build a ZIP | `wp-release zip` | |
+| Create a checksums manifest | `wp-release checksums` | |
+| Verify files against a manifest | `wp-release verify` | |
+| Check that the versions agree | `wp-release version-check` | |
+| Deploy to WordPress.org SVN | `wp-release deploy-svn` | [`wpelevator/wp-release-deploy-svn`](../../actions/wp-release-deploy-svn) |
+
+Each concept has one name, written in the syntax of each interface:
+
+| Concept | CLI | GitHub Action | Library | Meaning |
+|---|---|---|---|---|
+| Plugin or theme directory | `<source-dir>` argument or `--source-dir` | `source-dir` | `sourceDir` | Directory that a command reads, whether it's the repository or a build directory. |
+| Generated file | `--output <file>` | | `outputPath` | File written by `zip` or `checksums`. |
+| ZIP to deploy | `--from-zip <file>` | `from-zip` | `fromZip` | Existing ZIP read as the deploy source. |
+| Git tag to compare | `--git-tag <tag>` | | `gitTag` | Git tag checked by `version-check`. |
+| SVN tag to create | `--svn-tag <version>` | `svn-tag` | `svnTag` | Tag written by `deploy-svn`, distinct from a git tag. |
+| SVN repository | `--svn-url <url>` | `svn-url` | `svnUrl` | Deploy destination. |
+| Assets sync | `--no-assets` to skip | `assets: false` to skip | `assets` | Booleans are positive in the library and the action; `--no-assets` is only the CLI negation, never `noAssets` or a `no-assets` input. |
+
+CLI JSON results use camelCase keys like `zipPath`, and GitHub Action outputs use kebab-case like `zip-path`. Library classes are named after the capability (`SvnDeploy`, `Svn`) without repeating "release".
+
+### File selection
+
+`zip`, `checksums` and `deploy-svn` select files the same way:
+
+| Option | Description |
+|---|---|
+| `--distignore <file>` | Path to the ignore file. Defaults to `.distignore` in the source directory when present; an explicitly passed file must exist. |
+| `--no-distignore` | Don't read any ignore file. |
+| `--exclude <patterns>` | Extra gitignore-style patterns, comma-separated or repeated, like `--exclude build/,assets/*,images/**/*`. They're applied after the ignore file, so a `!` pattern can also re-include a file. |
+
+Both use full gitignore syntax, including `!` negation. Version control metadata (`.git`, `.svn` and `.hg`, at any depth, including the `.git` files of worktrees and submodules) is always left out, also without an ignore file and when deploying from a ZIP, and no `!` pattern can re-include it. This keeps a repository's history out of ZIPs and SVN deploys when the source directory is the repository root. The comma-separated `--exclude` list works like `--exclude` in `wp i18n make-pot`. `deploy-svn --from-zip` ignores both options, since the ZIP is already filtered. Symbolic links that aren't excluded are an error, since ZIP archives and WordPress.org SVN don't support them.
+
+### Plugin and theme headers
+
+The commands read the same headers as WordPress. The main plugin file is the top-level `.php` file with a `Plugin Name:` header in its first 8 KB, preferring `{slug}.php` when several files have one. A directory without a plugin file and with `Theme Name:` in `style.css` is a theme. The readme headers (`Stable tag`, `Tested up to`, …) come from `readme.txt`, or `readme.md` when there's no `readme.txt`.
+
+`--version` defaults to the `Version` header in `zip`, `checksums` and `version-check`, and `checksums --type` defaults to the detected package type.
+
+### ZIP
+
+`zip` writes `{slug}.{version}.zip` to the current directory, or to `--output <file>`, with the selected files in a `{slug}/` root folder:
+
+```bash
+wp-release zip dist --slug my-plugin --checksums
+```
+
+- `--root-folder <name>` changes the root folder and `--no-root-folder` puts the files at the root of the ZIP.
+- `--filename-format` changes the name, like `--filename-format {slug}` for `my-plugin.zip`.
+- Entries are sorted and use a fixed timestamp and file mode, so the same files always give the same ZIP.
+- `--checksums` also writes the [checksums manifest](#checksums) of the archived files next to the ZIP, with `.checksums.json` instead of `.zip`.
+- An existing ZIP or manifest isn't overwritten without `--force`. A ZIP or manifest written inside the source directory is never archived.
+
+### Checksums
+
+`checksums` writes a manifest with the MD5 and SHA-256 hash of every selected file, in the format of the WordPress.org plugin checksums API (`https://downloads.wordpress.org/plugin-checksums/{slug}/{version}.json`). Paths are relative to the plugin or theme folder, sorted, and use forward slashes:
+
+```json
+{
+	"plugin": "my-plugin",
+	"version": "1.2.0",
+	"files": {
+		"my-plugin.php": {
+			"md5": "…",
+			"sha256": "…"
+		}
+	}
+}
+```
+
+Themes use a `theme` key instead of `plugin`, and the version is left out when it's unknown. The manifest is named `{slug}.{version}.checksums.json` after `--filename-format`, the same name as the ZIP with `.checksums.json` instead of `.zip`, so the two are published side by side; `--output <file>` writes it elsewhere. A manifest written inside `<source-dir>` is never listed in itself.
+
+```bash
+# Hash the build that is zipped and deployed
+wp-release checksums dist --version 1.2.0
+```
+
+Because the manifest lists the files and not the ZIP, it stays valid for any copy of the same files: the GitHub release ZIP, the ZIP that WordPress.org builds from SVN, or an installed plugin on a site.
+
+### Verify
+
+`verify` checks a directory against a manifest from `checksums` or from the WordPress.org checksums API, and reports every changed, missing and extra file. It exits with `2` unless all files match:
+
+```bash
+wp-release verify wp-content/plugins/my-plugin --checksums my-plugin.1.2.0.checksums.json
+```
+
+- A file matches when its SHA-256 equals the manifest. Manifests without SHA-256 fall back to MD5, and a hash can also be a list of accepted values.
+- `verify` doesn't read `.distignore`, so that an ignore file inside the checked directory can't hide added files. `--exclude <patterns>` skips paths in both the directory and the manifest, for files that aren't part of the release, such as caches.
+- Manifest paths outside the package folder (absolute or with `..`) are rejected.
+
+A checksums manifest proves only that the files match the manifest. Signing the manifest, so that the manifest itself can be trusted, is planned.
+
+### Version check
+
+`version-check` compares the versions that have to agree before a release, and reports every mismatch with exit code `2`:
+
+```bash
+wp-release version-check --constant MY_PLUGIN_VERSION --git-tag v1.2.0
+```
+
+- The expected version is `--version`, or the `Version` header.
+- The readme `Stable tag` must match for plugins; `--no-stable-tag` skips it, and themes have no Stable tag.
+- `--constant NAME` (repeatable) checks `define( 'NAME', '1.2.0' )` or `const NAME = '1.2.0'` in every PHP file outside `vendor/`, `node_modules/` and dot directories. A constant that isn't defined is a mismatch.
+- `--git-tag` defaults to `GITHUB_REF` when it's a tag. `--git-tag-format` (default `{version}`) can have a prefix or the slug, like `v{version}` or `{slug}-{version}`; a leading `v` in the version is ignored, like for SVN tags.
+
+### Deploy to SVN
+
+`deploy-svn` syncs a plugin to the WordPress.org plugin SVN repository. Each SVN write is a separate flag and nothing is written unless requested. All writes go into one commit.
+
+| Flag | Default | Writes |
+|---|---|---|
+| `--trunk` | off | Sync the full source directory to `trunk/` |
+| `--readme-only` | off | Sync only the readme to `trunk/`, for updates between releases such as bumping `Tested up to` |
+| `--svn-tag <version>` | off | Copy `trunk/` to `tags/<version>`; requires `--trunk`. A leading `v` is stripped, so `v1.2.0` creates `tags/1.2.0`. |
+| `--assets-dir <dir>` | not set | Sync this directory with banners, icons and screenshots to the SVN `assets/` directory. There's no default directory, so assets are only deployed when this is set, and it must exist. |
+| `--no-assets` | | Skip the `--assets-dir` sync for one run, for example when a config always passes `--assets-dir`. |
+
+Typical runs:
+
+```bash
+# Deploy 1.2.0 to trunk and the tag, and update the assets
+wp-release deploy-svn dist --trunk --svn-tag 1.2.0 --assets-dir .wordpress-org
+
+# Update only the readme between releases
+wp-release deploy-svn dist --readme-only
+
+# Update only the assets
+wp-release deploy-svn --assets-dir .wordpress-org
+
+# Deploy exactly the files of a ZIP built earlier
+wp-release deploy-svn --from-zip my-plugin.1.2.0.zip --trunk --svn-tag 1.2.0
+```
+
+How a deploy works:
+
+1. The options are validated, including the slug, version and readme name, before they're used in URLs or paths.
+2. With `--trunk`, the files must be a plugin whose `Version` header matches the version, and with `--svn-tag` the readme `Stable tag` must match too. `--readme-only` needs the readme. Nothing is checked out when a check fails.
+3. The repository is checked out sparsely into a new temporary directory, with only the directories that the flags write to. A missing `assets/` (or `trunk/`, `tags/`) directory is created. The deploy stops when `tags/<version>` exists, unless `--force` replaces it.
+4. The files are synced in Node.js, without `rsync`: new and changed files are copied, files that are no longer selected are deleted, and `svn add` and `svn delete` stage them, including files that svn ignores by default. `trunk/` is then copied to the tag with `svn copy`.
+5. Asset images get `svn:mime-type` set for PNG, JPEG, GIF and SVG, the formats that WordPress.org documents for plugin assets. Other formats keep the type that svn assigns.
+6. When `svn status` is empty, the deploy ends without a commit. A dry run logs the status and stops before the commit. Otherwise the changes are committed, and the temporary directory is always removed.
+
+`--from-zip` reads the files from a ZIP instead of `<source-dir>`. The ZIP is checked before it's extracted: entries with absolute paths, `..` segments or symbolic links, and entries outside a single `{slug}/` root folder, are rejected.
+
+Credentials are only needed for the commit, not for dry runs, no-op runs or `file://` repositories. Pass the username with `--svn-username` or `SVN_USERNAME` and the password in `SVN_PASSWORD`. svn always runs non-interactively without caching credentials, and the password is passed on the standard input with `--password-from-stdin`, never on the command line or in the logs.
+
+Validation:
+
+- `--trunk` and `--readme-only` can't be combined.
+- `--readme-only` is rejected when `GITHUB_REF` is a tag, since a readme-only update from a release tag usually means the build was forgotten.
+- Pre-release versions like `1.0.0-rc.1` are never tagged.
+- `--version` defaults to `--svn-tag`, then the `Version` header of the deployed files; when `--version` and `--svn-tag` are both set they must match.
+- `--trunk` without `--svn-tag` works but warns, because trunk then differs from the stable tag that WordPress.org serves downloads from.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success, dry run, no changes, or help |
+| `1` | Unexpected failure, such as a failed svn command |
+| `2` | Invalid options, failed release checks, an existing SVN tag, or files that don't match the checksums |
+| `3` | Missing SVN credentials, or credentials that SVN rejected |
+
+## Library
+
+```js
+import { Logger, SvnDeploy, resolveDeployOptions } from '@wpelevator/wp-release';
+
+const options = resolveDeployOptions( {
+	slug: 'my-plugin',
+	sourceDir: 'dist',
+	trunk: true,
+	svnTag: '1.2.0',
+	dryRun: true,
+} );
+
+const { committed, revision, version, changes } = await new SvnDeploy(
+	options,
+	new Logger()
+).run();
+```
+
+`resolveDeployOptions()` applies the defaults and throws a `ValidationError` (with `exitCode` `2`) for invalid combinations. `SvnDeploy` exposes each step (`prepare()`, `checkVersions()`, `checkout()`, `sync()`, `commit()` and `cleanup()`) separately so CI wrappers can run and report them one by one; `run()` runs all of them, or nothing when there's nothing to write. `getPlan()` lists the planned SVN changes. The `Svn` class wraps the svn command line, and takes the command runner as a dependency so that tests can replace it.
+
+ZIP files and metadata:
+
+```js
+import {
+	createZip,
+	findVersionMismatches,
+	loadFileRules,
+	readPackageMeta,
+	resolveFileSelection,
+	selectFiles,
+} from '@wpelevator/wp-release';
+
+const rules = await loadFileRules(
+	resolveFileSelection( { cwd: process.cwd(), sourceDir: 'dist' } )
+);
+const meta = await readPackageMeta( { dir: 'dist', slug: 'my-plugin' } );
+
+await createZip( {
+	sourceDir: 'dist',
+	files: await selectFiles( 'dist', rules ),
+	zipPath: `my-plugin.${ meta.version }.zip`,
+	rootFolder: 'my-plugin',
+} );
+
+const { mismatches } = await findVersionMismatches( {
+	sourceDir: 'dist',
+	meta,
+	slug: 'my-plugin',
+	constants: [ 'MY_PLUGIN_VERSION' ],
+} );
+```
+
+Checksums:
+
+```js
+import {
+	createChecksums,
+	loadFileRules,
+	readChecksums,
+	resolveFileSelection,
+	verifyChecksums,
+	writeChecksums,
+} from '@wpelevator/wp-release';
+
+const rules = await loadFileRules(
+	resolveFileSelection( { cwd: process.cwd(), sourceDir: 'dist' } )
+);
+const manifest = await createChecksums( {
+	sourceDir: 'dist',
+	rules,
+	slug: 'my-plugin',
+	version: '1.2.0',
+} );
+
+await writeChecksums( 'my-plugin.1.2.0.checksums.json', manifest );
+
+const { valid, changed, missing, extra } = await verifyChecksums( {
+	sourceDir: 'wp-content/plugins/my-plugin',
+	manifest: await readChecksums( 'my-plugin.1.2.0.checksums.json' ),
+	rules: await loadFileRules( {} ),
+} );
+```
+
+`loadFileRules()` reads the ignore file and `--exclude` patterns into a gitignore matcher and `selectFiles()` lists the files it doesn't ignore. `compareChecksums()` compares two hash maps without reading any files, and `parseChecksums()` validates manifest JSON. `extractZip()` extracts a ZIP after the same checks as `deploy-svn --from-zip`.
+
+## Development
+
+The source is TypeScript in `src/`, with tests next to the files they test (`*.test.ts`). The published package contains only the compiled `dist/` with JavaScript and `.d.ts` files.
+
+```bash
+npm run build --workspace @wpelevator/wp-release
+npm test --workspace @wpelevator/wp-release
+npm run lint --workspace @wpelevator/wp-release
+```
+
+- `build` compiles `src/` to `dist/` with `tsc`, leaving out the tests.
+- `test` runs the `.ts` tests directly with `node --test`, using Node.js type stripping, so it needs Node.js 22.18 or later but no build. The SVN integration tests in `svn-deploy.integration.test.ts` create repositories with `svnadmin` and deploy to their `file://` URLs; they're skipped when `svn` or `svnadmin` isn't installed.
+- `lint` runs ESLint and a `tsc` type check.
+
+The `wpelevator-source` export condition points at `src/index.ts`. The tests and the `wp-release-deploy-svn` action build use it to work with the source instead of a `dist/` build. It's not set by other tools, so the published package always resolves to `dist/`.
+
+## Comparison with existing tools
+
+| Tool | What it does | How `wp-release` differs |
+|---|---|---|
+| [10up WordPress.org plugin deploy](https://github.com/10up/action-wordpress-plugin-deploy) and [readme/asset update](https://github.com/10up/action-wordpress-plugin-asset-update) actions | Two separate GitHub Actions configured through env vars. A deploy always syncs the build to `trunk/` and copies it to the tag; readme and asset updates need the second action. Assets come from `.wordpress-org` by default, and files are selected with `.distignore` or `.gitattributes`. Files are synced with `rsync`. | One `deploy-svn` command with independent write flags, so a release, a readme-only update and an assets-only update are the same command with different flags. Runs locally and in any CI, not only GitHub Actions, and syncs in Node.js without `rsync`. Checks that the `Version` header, readme `Stable tag` and SVN tag agree before writing, which the 10up actions don't. Assets are deployed only when `--assets-dir` is passed, instead of always syncing `.wordpress-org` when it exists, so a plugin's own `assets/` folder is never uploaded by accident. Adds `--exclude` for patterns without an ignore file and `--from-zip` to deploy the exact files of a ZIP. |
+| [`grunt-wp-deploy`](https://github.com/stephenharris/grunt-wp-deploy) | Grunt task with `deploy_trunk` and `deploy_tag` booleans, interactive password prompts and a `Stable tag` check. | No Grunt dependency and never interactive. `--readme-only` is a separate flag, where `grunt-wp-deploy` can only update trunk with the full build. Assets are independent of trunk writes. |
+| [codeinwp theme deploy](https://github.com/codeinwp/action-wordpress-theme-deploy) | Fork of the 10up plugin action that commits themes to the themes SVN repository. | Doesn't deploy themes. Theme releases are ZIP uploads on WordPress.org; `zip` builds the upload with the theme folder as the root. |
+| [`wp dist-archive`](https://github.com/wp-cli/dist-archive-command) | WP-CLI command that zips a project using `.distignore`, with `--plugin-dirname` and `--filename-format`. | Same `.distignore` file and `{name}.{version}` style filename format, but needs only Node.js instead of PHP and WP-CLI. `.distignore` is matched with full gitignore syntax, including `!` negation, and `--distignore` / `--exclude` let you point at another ignore file or add patterns on the command line. Builds are reproducible, and `--checksums` writes a manifest next to the ZIP. |
+| [`wp plugin verify-checksums`](https://developer.wordpress.org/cli/commands/plugin/verify-checksums/) | WP-CLI command that checks installed plugins against the WordPress.org checksums API. | Reads the same manifest format, but from a file, so it also works for plugins and themes that aren't hosted on WordPress.org and for build directories in CI. `checksums` writes the manifest that WordPress.org generates for its own plugins. |
+| [`wp-scripts plugin-zip`](https://github.com/WordPress/gutenberg/tree/trunk/packages/scripts#plugin-zip) | Zips files from `package.json` `files` or a fixed allowlist, named after the npm package, with `--root-folder` / `--no-root-folder`. | Reuses the root folder flags, selects files with `.distignore` instead of an allowlist, puts the version from the plugin headers in the filename and streams the archive instead of building it in memory. |

package/dist/bin/wp-release.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/wp-release.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "../cli.js";
+process.exitCode = await run(process.argv.slice(2));

package/dist/checksums.d.ts

@@ -0,0 +1,138 @@
+import type { FileRules } from './file-selection.ts';
+export declare const CHECKSUMS_EXTENSION = ".checksums.json";
+/**
+ * Hash algorithms in each file entry. MD5 is kept for compatibility with the
+ * WordPress.org checksums format; verification prefers SHA-256.
+ */
+export declare const CHECKSUM_ALGORITHMS: readonly ["md5", "sha256"];
+export type ChecksumAlgorithm = (typeof CHECKSUM_ALGORITHMS)[number];
+export type PackageType = 'plugin' | 'theme';
+/**
+ * Hex digests of a file by algorithm.
+ */
+export type FileHashes = Record<ChecksumAlgorithm, string>;
+/**
+ * Expected hashes of a file in a manifest. The WordPress.org checksums API
+ * can list several accepted values for a hash.
+ */
+export type ExpectedHashes = Partial<Record<ChecksumAlgorithm, string | string[]>>;
+/**
+ * Checksums manifest in the WordPress.org plugin checksums format.
+ */
+export interface ChecksumsManifest {
+    plugin?: string;
+    theme?: string;
+    version?: string;
+    files: Record<string, ExpectedHashes>;
+}
+export interface CreateChecksumsInput {
+    /** Directory with the files. */
+    sourceDir: string;
+    /** Matcher from loadFileRules(). */
+    rules: FileRules;
+    /** Plugin or theme slug. */
+    slug: string;
+    /** Version, if known. */
+    version?: string | null;
+    /** Package type, plugin or theme. */
+    type?: string;
+}
+export interface ChecksumsComparison {
+    /** Whether every file matches and none are missing or extra. */
+    valid: boolean;
+    /** Paths with matching hashes. */
+    matched: string[];
+    /** Paths with different hashes. */
+    changed: string[];
+    /** Paths in the manifest that are missing from the directory. */
+    missing: string[];
+    /** Paths in the directory that aren't in the manifest. */
+    extra: string[];
+}
+export interface VerifyChecksumsInput {
+    /** Plugin or theme directory. */
+    sourceDir: string;
+    /** Manifest from readChecksums() or createChecksums(). */
+    manifest: ChecksumsManifest;
+    /** Matcher from loadFileRules(). */
+    rules: FileRules;
+}
+/**
+ * Hash a file with every checksum algorithm in a single read.
+ *
+ * @param path File path.
+ * @return Hex digests keyed by algorithm.
+ */
+export declare function hashFile(path: string): Promise<FileHashes>;
+/**
+ * Hash files one at a time, so that large plugins don't run out of file
+ * descriptors.
+ *
+ * @param sourceDir Directory the paths are relative to.
+ * @param files     Relative file paths.
+ * @return Digests keyed by relative path, in the order of `files`.
+ */
+export declare function hashFiles(sourceDir: string, files: string[]): Promise<Record<string, FileHashes>>;
+/**
+ * Create a checksums manifest for the selected files of a directory.
+ *
+ * The manifest uses the format of the WordPress.org plugin checksums API
+ * (downloads.wordpress.org/plugin-checksums/{slug}/{version}.json), with
+ * paths relative to the plugin or theme folder:
+ *
+ *     { "plugin": "my-plugin", "version": "1.2.0", "files": { "my-plugin.php": { "md5": "…", "sha256": "…" } } }
+ *
+ * Themes use a "theme" key instead of "plugin". The version is left out when
+ * it's unknown.
+ *
+ * @param input Directory, file rules and package details.
+ * @return Checksums manifest.
+ */
+export declare function createChecksums(input: CreateChecksumsInput): Promise<ChecksumsManifest>;
+/**
+ * Write a checksums manifest as JSON.
+ *
+ * @param  path     Target file path.
+ * @param  manifest Manifest from createChecksums().
+ * @param  force    Overwrite an existing file.
+ * @throws {ValidationError} If the file exists and force isn't set.
+ */
+export declare function writeChecksums(path: string, manifest: ChecksumsManifest, force?: boolean): Promise<void>;
+/**
+ * Read and validate a checksums manifest. Accepts manifests from
+ * createChecksums() and the WordPress.org checksums API, where a hash can
+ * also be a list of accepted values.
+ *
+ * @param  path Manifest file path.
+ * @return Checksums manifest.
+ * @throws {ValidationError} If the file isn't a valid manifest.
+ */
+export declare function readChecksums(path: string): Promise<ChecksumsManifest>;
+/**
+ * Parse and validate checksums manifest JSON.
+ *
+ * @param  contents Manifest JSON.
+ * @param  source   Name of the manifest for error messages.
+ * @return Checksums manifest.
+ * @throws {ValidationError} If the JSON isn't a valid manifest.
+ */
+export declare function parseChecksums(contents: string, source?: string): ChecksumsManifest;
+/**
+ * Compare expected file hashes with actual ones. A file matches when its
+ * SHA-256 is one of the expected values, or its MD5 for manifests without
+ * SHA-256.
+ *
+ * @param expected Expected hashes keyed by relative path.
+ * @param actual   Actual hashes keyed by relative path.
+ * @return Sorted lists of matched, changed, missing and extra paths, and whether all match.
+ */
+export declare function compareChecksums(expected: Record<string, ExpectedHashes>, actual: Record<string, Partial<FileHashes>>): ChecksumsComparison;
+/**
+ * Verify the files of a directory against a checksums manifest. Paths that
+ * the rules ignore are skipped on both sides, so files created after the
+ * install (such as caches) can be excluded.
+ *
+ * @param input Directory, manifest and file rules.
+ * @return Result from compareChecksums().
+ */
+export declare function verifyChecksums(input: VerifyChecksumsInput): Promise<ChecksumsComparison>;