@wpelevator/wp-release 0.14.0 → 0.16.0

package/README.md

@@ -1,11 +1,9 @@
 # WP Release
 
-Package, checksum, verify and version-check WordPress plugins and themes, deploy plugins to the WordPress.org plugin SVN repository, and deploy plugins, themes and packages to Git repositories. Usable as a CLI, as a library, and through the [`wp-release-zip`](https://github.com/wpelevator/wp-release-zip), [`wp-release-checksums`](https://github.com/wpelevator/wp-release-checksums), [`wp-release-sign`](https://github.com/wpelevator/wp-release-sign) and [`wp-release-deploy-svn`](https://github.com/wpelevator/wp-release-deploy-svn) GitHub Actions.
+Package, checksum, sign, verify and version-check WordPress plugins and themes, deploy plugins to the WordPress.org plugin SVN repository, and deploy plugins, themes and packages to Git repositories. Usable as a CLI, as a library, and through the [`wp-release-zip`](https://github.com/wpelevator/wp-release-zip), [`wp-release-checksums`](https://github.com/wpelevator/wp-release-checksums), [`wp-release-sign`](https://github.com/wpelevator/wp-release-sign) and [`wp-release-deploy-svn`](https://github.com/wpelevator/wp-release-deploy-svn) GitHub Actions.
 
 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). Signatures are tested against libsodium, but haven't been used for a real release yet.
-
 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
@@ -14,7 +12,7 @@ Option names follow the existing community tools (10up WordPress.org actions, `w
 npm install --save-dev @wpelevator/wp-release
 ```
 
-Requires Node.js 22.12 or later. `deploy-svn` also needs the `svn` command line client; the optional `--exclude-gitattributes` flag needs Git.
+Requires Node.js 22.12 or later. `deploy-svn` also needs the `svn` command line client. Git deployments, changeset commands and the optional `--exclude-gitattributes` flag need Git.
 
 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.
 
@@ -26,6 +24,7 @@ npx wp-release --help
 
 | Command | Description |
 |---|---|
+| `wp-release build [<source-dir>] --output <dir> [options]` | Copy selected release files into a directory. |
 | `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 sign <file>... [options]` | Sign files with Ed25519, writing a detached `<file>.sig` next to each, or minisign and SSH signatures with `--format`. |
@@ -41,7 +40,11 @@ npx wp-release --help
 | `wp-release changeset-version [options]` | Apply version bumps and changelog entries. |
 | `wp-release changeset-tag [options]` | Create missing package release tags. |
 
-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`. In GitHub Actions, `--github-output` sets the result as JSON to the `result` output of the step instead, for later steps and jobs to read with `fromJSON( steps.<id>.outputs.result )`.
+Run `npx wp-release <command> --help` for the options of each command. Directory-based commands accept a first `<source-dir>` argument or `--source-dir`, defaulting to the current directory. `sign` takes file arguments, `keygen` generates keys, and changeset commands operate on the configured repository. Every command prints its result as JSON with `--json`.
+
+In GitHub Actions, `--github-output` writes the complete result as JSON to `steps.<id>.outputs.result` and exposes each top-level string, number or boolean as a plain output. Use `steps.zip.outputs.zipPath` for a ZIP path, for example. Arrays and objects remain in `result`: tag metadata is read with `fromJSON( steps.tag.outputs.result ).tags[0].tag`, even when only one package is selected. There is no plain `steps.tag.outputs.tag` output.
+
+Prefer plain outputs in steps that run conditionally, since a skipped step has empty outputs. When reading JSON from a step that may be skipped, use a fallback such as `fromJSON( steps.tag.outputs.result || '{"tags":[]}' ).tags[0].tag`. For several tags or deploys, read the arrays in `result` to build a job matrix or process each item.
 
 ### GitHub Actions annotations and job summaries
 
@@ -65,7 +68,8 @@ Each command also adds a section to the [job summary](https://docs.github.com/en
 |---|---|
 | `deploy-svn` | Plugin, linked to its WordPress.org page, version, written SVN paths, the commit linked to its WordPress.org changeset (or the dry run or no-op result), and the SVN changes in a collapsed table. |
 | `deploy-git` | Repository, release commit and the pushed branch and tag. |
-| `zip` | ZIP, number of files and checksums manifest. |
+| `build` | Output directory, number of copied files and optional manifest; requested signatures and public keys. |
+| `zip` | ZIP, number of files and checksums manifest; with `--sign`, signature files and the public key of each written format. |
 | `checksums` | Manifest and number of files. |
 | `sign` | Signature files and the public key of each written format. |
 | `verify` | That all files match, or the counts and a table of the changed, missing and extra files. |
@@ -76,11 +80,63 @@ Each command also adds a section to the [job summary](https://docs.github.com/en
 
 A failed command adds its error to the summary, or a table of its problems with their files and lines, listing up to 100 and counting the rest. The Markdown of the summaries isn't part of the library API. File paths are relative to `GITHUB_WORKSPACE`, or the current directory without it. Files outside it, like those of an extracted ZIP, get an annotation without a file. Multi-line messages stay one annotation.
 
-Use global `--config <path>` to select a config; relative paths resolve from the current directory. Otherwise, Changesets commands discover `wp-release.config.js`, `.mjs` or `.cjs` there. Global `--tag-format <format>` replaces the `tagFormat` of the config for one command, see [Packages and tags](#packages-and-tags).
+Use global `--config <path>` to select a config; relative paths resolve from the current directory. Otherwise, commands using the config discover `wp-release.config.js`, `.mjs` or `.cjs` at the repository root. Global `--tag-format <format>` replaces the `tagFormat` of the config for one command, see [Packages and tags](#packages-and-tags).
+
+### Changesets support
+
+The changeset commands manage versioning, changelogs and release tags for single-package repositories and monorepos, including this repository. They read Changesets-style Markdown and load JavaScript configs with descriptors for npm and Composer manifests, plugin and theme headers, readme Stable tags, PHP constants, and Git tags. Use JavaScript configs with ESM (`export default`) or CommonJS (`module.exports`). Frontmatter uses `package-name: patch|minor|major` entries. For pre-releases, use the built-in [pre-release workflow](#pre-releases); the parser supports this simple frontmatter format rather than general YAML or the Changesets pre mode.
+
+#### Single-project repositories without a config file
+
+The `changeset-*` commands can release one project at the repository root without a `wp-release.config.*` file. Run them from the root directory. With no version descriptor flags, they detect a root `package.json` or `composer.json` with a version, a plugin entry PHP file with a `Plugin Name` header, or a theme `style.css` with a `Theme Name` header. A detected plugin also updates the Stable tag in `readme.txt`, or `readme.md` when no Stable tag is found in `readme.txt`. Multiple version sources, multiple plugin entry files and npm workspaces require explicit descriptors or a config; files belonging to different projects aren't silently synchronized. A directory without a recognized version source still requires a config or explicit descriptors.
+
+For a root npm package, the complete workflow needs no project flags:
+
+```bash
+npx wp-release changeset-add --bump minor --summary "Add a new feature."
+npx wp-release changeset-status --since origin/main
+npx wp-release changeset-version --dry-run
+npx wp-release changeset-version
+# Review and commit the updated version and changelog files.
+npx wp-release changeset-tag --push
+```
+
+A single root package is selected automatically for `changeset-add --bump` when `--since` isn't supplied, and for `changeset-tag --version`; `--since` still selects changed packages. npm and Composer projects use their root manifest's name as the changeset identifier when that manifest supplies the version; other projects use the root directory's basename. Keep that directory name consistent between local checkouts and CI, or use a config with a manifest-based `idFrom`. The fallback uses `.changeset/`, `CHANGELOG.md`, tags named `v{version}`, and the `origin` remote. There is no default comparison branch: pass `--since` or `--base-branch` when status checks should compare changes. Readme changelog updates are opt-in.
+
+Explicit descriptors replace automatic detection and define the entire version target list. For a plugin whose version appears in its header, readme and a PHP constant:
 
-### Changesets support (experimental)
+```bash
+npx wp-release changeset-version \
+  --version-from wordpress-plugin \
+  --version-wordpress-plugin my-plugin.php \
+  --version-wordpress-stable-tag readme.txt \
+  --version-php-constant 'my-plugin.php#MY_PLUGIN_VERSION'
+```
 
-Changesets support is experimental. It reads Changesets-style Markdown and loads JavaScript configs with descriptors for npm and Composer manifests, plugin and theme headers, readme Stable tags, PHP constants, and Git tags. Use ESM (`export default`) or CommonJS (`module.exports`); TypeScript configs are not supported. Frontmatter accepts `package-name: patch|minor|major` entries; advanced YAML and the Changesets pre mode are unsupported (see [pre-releases](#pre-releases) for the alternative).
+The same project flags belong on `changeset-add`, `changeset-status`, `changeset-version` and `changeset-tag`. Keep them consistent across all four commands, for example in command-specific npm scripts. An accompanying `package.json` used for build tools isn't changed unless it is included explicitly.
+
+| Flag | Version descriptor |
+|---|---|
+| `--version-package-json <file>` | npm manifest version source and target |
+| `--version-composer-json <file>` | Composer manifest version source and target; a target without a `version` field is skipped, while a source must have one |
+| `--version-wordpress-plugin <file>` | WordPress plugin Version header source and target |
+| `--version-wordpress-theme <file>` | WordPress theme Version header source and target |
+| `--version-wordpress-stable-tag <file>` | WordPress readme Stable tag source and target; keeps its stable version during pre-releases and snapshots |
+| `--version-php-constant <file>#<constant>` | PHP `define()` or `const` version source and target |
+| `--version-git-tag <pattern>` | Current version from existing stable Git tags, with a pattern such as `v{version}`; source-only, never a version target |
+
+File descriptor flags are repeatable. The source is inferred from a sole descriptor, or a unique descriptor other than a Stable tag. Otherwise use `--version-from <kind>`, where kind is `package-json`, `composer-json`, `wordpress-plugin`, `wordpress-theme`, `wordpress-stable-tag`, `php-constant` or `git-tag`. For repeated kinds, qualify the selector with the exact descriptor value: `--version-from package-json:package.json` or `--version-from 'php-constant:my-plugin.php#MY_PLUGIN_VERSION'`. Argument order doesn't select the source. A Git source requires a matching existing stable tag; its pattern selects the tags to read, while `--tag-format` controls tags to create. With multiple descriptors, explicitly select `git-tag` if it is the authoritative source.
+
+| Shared option | Config equivalent |
+|---|---|
+| `--base-branch <branch>` | `baseBranch`, used with the remote for the default comparison ref |
+| `--remote <name>` | `remote`, used for comparisons and pushing release tags |
+| `--changesets-dir <dir>` | `changesets`, relative to the repository root |
+| `--readme-changelog` / `--no-readme-changelog` | `readmeChangelog`, independent of updating the readme Stable tag |
+| `--changelog-insert-after <marker>` | `changelogInsertAfter`; must exist in `CHANGELOG.md` and, with readme changelog updates, the plugin readme |
+| `--tag-format <format>` | `tagFormat`, replacing the default `v{version}` |
+
+An explicit `--config` must load successfully. Otherwise a discovered config takes precedence over the single-project fallback. Single-project descriptor and settings flags cannot be mixed with a config file; put those settings in the config instead. The existing global `--tag-format` override works in both modes. Config files remain the place for package layouts, dependents, custom version and changelog callbacks, deployment destinations and distribution settings. Packaging and deployment commands retain their existing config requirements.
 
 Typical release flow, from a feature pull request to the publish workflows triggered by release tags:
 
@@ -127,6 +183,23 @@ export default defineConfig( {
 
 `version.from` selects the current version; `version.to` lists release targets. Use `phpConstantVersion( { file, constant } )` to sync a PHP constant.
 
+#### Single-project checks in GitHub Actions
+
+There are no dedicated build or changeset wrapper actions. Install the CLI in your project and run it directly. A root npm package can check a pull request with:
+
+```yaml
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+      - run: npm ci
+      - run: npx --no-install wp-release changeset-status --since origin/main
+```
+
+For a plugin with several version targets, put the same descriptor flags in npm scripts for all four changeset commands. Full Git history and tags are needed for comparisons, Git version sources and release notes. Keep the checkout directory name consistent when it supplies the changeset identifier. Directory artifacts use `npx --no-install wp-release build --output dist/my-plugin --github-output`; upload that directory with your artifact action. `build` writes manifest sidecars outside the directory and does not accept the ZIP-only embedding, codec or manifest-filename flags.
+
 #### Packages and tags
 
 The config describes the repository, so wp-release assumes no directory structure or naming convention of its own:
@@ -143,7 +216,7 @@ The config describes the repository, so wp-release assumes no directory structur
   Deploy templates also have `{branch}`, `{ref}` and `{revision}` (see [Deploy configured packages](#deploy-configured-packages)), and any template can be a callback that receives the package, for names that the placeholders don't cover, like the last directory of the path.
 - **`tagFormat`** names the release tags, `{path}/{version}` by default, like `plugins/alpha/1.2.0`. Empty placeholders leave no leading or repeated slashes in a tag, so a package at the root gets plain version tags, like `1.2.0`, from the same default. Deploy templates, like repository URLs, are filled in as they are. A `gitTagVersion()` version source reads the tags with its own `pattern`, also `{path}/{version}` by default, so set both when you change the format.
 - **`--tag-format <format>`** replaces the `tagFormat` of the config for one command, for a workflow or job that names its tags differently, like `--tag-format '{name}@{version}'`. Every command that creates or reads the same tags needs the same format: `changeset-tag`, which creates them and finds the previous tag for the release notes, `changeset-version --prerelease`, which numbers pre-releases from them, and `deploy-git` and `deploy-svn --release-ref`, which read the package and version of a tag.
-- **Slugs** are a WordPress concept: the folder of a plugin or theme. Only the commands that produce something for WordPress use one: the `{slug}/` root folder and name of a `zip`, the `checksums` manifest, the WordPress.org slug of `deploy-svn`, and `version-check`. Each takes `--slug`, which defaults to the name of the current directory, or of the package directory with `zip --package`, and an SVN deploy target takes `slug`, which defaults to the name of the package directory. Tags and Git deploy targets don't have a slug.
+- **Slugs** are a WordPress concept: the folder of a plugin or theme. Only the commands that produce something for WordPress use one: the `{slug}/` root folder and name of a `zip`, the `checksums` manifest, the WordPress.org slug of `deploy-svn`, and `version-check`. Each takes `--slug`, which defaults to the name of the working directory, or of the package directory with `zip --package`, and an SVN deploy target takes `slug`, which defaults to the name of the package directory. Tags and Git deploy targets don't have a slug.
 - **`remote`** is the git remote that `changeset-tag --push` pushes tags to and that the base branch is compared on, `origin` by default.
 
 The default strategy bumps stable `x.y.z` versions with SemVer rules, and the `x.y` and `x.y.z.w` versions common in WordPress plugins the same way: the bumped part is raised, the parts after it reset to `0`, and the version keeps its number of parts. A minor bump of `2.1` is `2.2` and a major bump is `3.0`, while a patch bump adds the third part, `2.1.1`. A patch bump of `1.2.3.4` is `1.2.4.0`, so raising only the fourth part needs a custom strategy. Configure `nextVersion( { package, bump, currentVersion, changesets } )` for other formats; changeset bumps remain `patch`, `minor` or `major`. Pre-releases are added to the next version with `--prerelease`, described below.
@@ -215,7 +288,7 @@ The `changeset-version` result lists each release with its `package`, `bump`, `c
 
 After merging the release PR, `changeset-tag --since <merge-commit>^1 --push` pushes tags only for packages changed by that release. It pushes one tag at a time because GitHub doesn't trigger workflows for a push of more than three tags. wp-release doesn't create GitHub Releases: with `--json` or `--github-output`, each entry of `tags` has the `tag`, a `title` like `plugins/alpha@1.2.0`, the release `notes` and a `prerelease` flag, for a workflow step like [`softprops/action-gh-release`](https://github.com/softprops/action-gh-release) to create the release (see the example below). For initial adoption, preview all missing tags with `changeset-tag --dry-run` (without `--since`), then push if needed. To release each package with a separate workflow instead, `changeset-tag --since <merge-commit>^1 --untagged --github-output` lists the releases that don't have a tag yet, without creating any. Tag pushes need Git write credentials.
 
-To release a single package, for example from a manual workflow, pass `--package <name>`, repeatable, and with one package `--version <version>` to fail unless the package is at that version. Packages versioned by git tags have no version file, so for them `--version` is the version to tag. Before a tag is created, every `version.to` target must match the version, so a plugin `Version` header that disagrees with its readme `Stable tag` blocks the tag. Versions with a pre-release part, like `1.0.0-rc.1`, have `prerelease` set, so their GitHub Releases can be marked as pre-releases:
+To release a single package, for example from a manual workflow, pass `--package <name>`, repeatable, and with one package `--version <version>` to fail unless the package is at that version. Packages versioned by git tags have no version file, so for them `--version` is the version to tag. Before a tag is created, every `version.to` target must match the version, so a plugin `Version` header that disagrees with its readme `Stable tag` blocks the tag. Versions with a pre-release part, like `1.0.0-rc.1`, have `prerelease` set, so their GitHub Releases can be marked as pre-releases. This example selects one package, so `tags[0]` is its release; these fields are nested in the JSON result:
 
 ```yaml
 - name: Tag a release
@@ -268,6 +341,7 @@ npm publish --workspace packages/library --tag pr-251
 
 | Capability | CLI command | GitHub Action |
 |---|---|---|
+| Build a directory | `wp-release build` | |
 | Build a ZIP | `wp-release zip` | [`wpelevator/wp-release-zip`](https://github.com/wpelevator/wp-release-zip) |
 | Create a checksums manifest | `wp-release checksums` | [`wpelevator/wp-release-checksums`](https://github.com/wpelevator/wp-release-checksums) |
 | Sign files | `wp-release sign` | [`wpelevator/wp-release-sign`](https://github.com/wpelevator/wp-release-sign) |
@@ -276,12 +350,15 @@ npm publish --workspace packages/library --tag pr-251
 | Deploy to WordPress.org SVN | `wp-release deploy-svn` | [`wpelevator/wp-release-deploy-svn`](https://github.com/wpelevator/wp-release-deploy-svn) |
 | Deploy to a Git repository | `wp-release deploy-git` | |
 
-Each concept has one name, written in the syntax of each interface:
+The names below are scoped to their commands. `--output` selects the primary artifact of each command; ZIP packaging uses `--checksums-file` for its accompanying manifest:
 
 | 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`. |
+| Build directory | `build --output <dir>` | — | `outputDir` | Directory written by `build`; files go directly inside it. |
+| ZIP file | `zip --output <file>` | `output` in ZIP action | `zipPath` | Destination passed to `zipPackage()`; also returned as `zipPath`. |
+| Standalone checksums file | `checksums --output <file>` | `output` in checksums action | first argument of `writeChecksums()` | Manifest destination relative to the working directory; the CLI returns its absolute path as `checksumsPath`. |
+| Checksums filename when zipping | `zip --checksums-file <file>` | `checksums-file` in ZIP action | `checksumsFile` | Relative manifest filename beside the ZIP or inside its package root when embedded. |
 | 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. |
@@ -291,13 +368,20 @@ Each concept has one name, written in the syntax of each interface:
 | Source history | `--split-prefix <dir>` | | `splitPrefix` | Directory of a monorepo package whose history, from `git subtree split`, becomes the source history of `deploy-git` releases. |
 | SVN credentials | `--svn-username <name>`, `SVN_USERNAME` and `SVN_PASSWORD` env vars | `svn-username`, `svn-password` | `svnUsername`, `svnPassword` | Needed only to commit. There's no password flag, since it would show in the process list; the action inputs and library options fall back to the env vars. |
 | Log format | `--log-format <text\|github>`, `--ci` for `github` | always `github` | `writer: new TextWriter()` or `new GitHubActionsWriter()` | How the log is printed: plain text, or GitHub Actions annotations and job summaries. Each name matches the start of its writer class. |
+| Release config | `--config <path>` | `config` in ZIP, checksums and SVN actions | `configFile` | Explicit JavaScript config path for package selection, integrity settings or deployment. |
+| Release tag format | `--tag-format <format>` | `tag-format` in SVN action | `tagFormat` | How `release-ref` identifies a package and its version. |
+| Release ref to deploy | `--release-ref <ref>` | `release-ref` in SVN action | `ref` | Read configured packages and deployment targets from a release ref. |
 | 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`, `GitDeploy`) without repeating "release".
+CLI JSON results use camelCase keys like `zipPath`, and GitHub Action outputs use kebab-case like `zip-path`. The ZIP action supports `package` and `config`, the checksums action supports `config` for codec selection, and the SVN action supports `release-ref`, repeated `package` values as newline-separated input, `list`, `config` and `tag-format`.
+
+The ZIP CLI result uses `checksumsEmbedded` for the package-relative embedded manifest path. Its `signatures` array includes external absolute paths and embedded package-relative paths, while `checksumsSignatures` contains only manifest signatures. The ZIP action exposes those locations as `checksums-embedded`, `signatures` for external signatures, and `signatures-embedded` for embedded signatures, so asset uploads receive local files. With CLI `--github-output`, signature arrays remain in the JSON `result` output.
+
+Library classes are named after the capability (`SvnDeploy`, `Svn`, `GitDeploy`) without repeating "release".
 
 ### File selection
 
-`zip`, `checksums`, `deploy-svn` and `deploy-git` select files the same way:
+`build`, `zip`, `checksums`, `deploy-svn` and `deploy-git` select files the same way:
 
 | Option | Description |
 |---|---|
@@ -314,6 +398,25 @@ The commands read the same headers as WordPress. The main plugin file is the top
 
 `--version` defaults to the `Version` header in `zip`, `checksums` and `version-check`, and `checksums --type` defaults to the detected package type.
 
+### Build a directory
+
+`build` and `zip` use the same internal helper to load file rules, exclude their outputs, select release files and reject an empty selection. `build` copies the selected files directly into `--output <dir>`, without a slug wrapper or ZIP. Checksums and manifest signatures are optional. It supports the shared file selection flags above and `--package <name>` with `--config <path>` for configured package rules. A configured package cannot be combined with a source directory or file selection flags.
+
+```sh
+wp-release build --output dist/code-prettify
+wp-release build --package plugins/alpha --output dist/alpha
+```
+
+The destination is required and automatically excluded when it is inside the source. It cannot be the source directory or an ancestor, including through symlinked parents. Existing destinations require `--force`, which replaces the directory and removes stale files; existing files and symbolic links are rejected. Files are copied to a temporary directory before the existing build is replaced. Selected symbolic links are rejected as with ZIP packaging. `--json` returns `outputDir`, `files` and, for configured builds, `package`; it also returns `checksumsPath` when a manifest is generated, and `signatures` and `publicKey` when signing is requested. `--github-output` exposes these results too.
+
+`--checksums` writes `<output-dir>.checksums.json` beside the directory and hashes the copied build files. `--sign-checksums` generates and signs that manifest, implying `--checksums`. Use `--slug` and `--version` to override its metadata. The manifest and its signatures are excluded from the source selection, so rebuilding with `--force` does not package previous sidecars. Existing manifests and requested signature files also require `--force`; signing keys, formats and signature destinations are validated before creating or replacing the build. `--sign` is unsupported because a directory has no single file to sign.
+
+```sh
+wp-release build --output dist/code-prettify --sign-checksums
+```
+
+In the Deploy workflow, a directory build can be deployed with `wp-release deploy-svn dist/code-prettify --slug code-prettify --trunk --svn-tag "$GITHUB_REF_NAME" --no-distignore`. Keep `--from-zip` when the SVN deployment must match the attached ZIP exactly. Run dependency installation and compilation before `build`; it only selects and copies files.
+
 ### ZIP
 
 The [`wp-release-zip`](https://github.com/wpelevator/wp-release-zip) GitHub Action runs this command.
@@ -326,11 +429,37 @@ 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.
+- Entries are sorted and use a fixed timestamp and file mode. Built-in metadata is deterministic except for embedded minisign signatures, which include their signing timestamp; custom codec callbacks control their own encoded bytes.
 - `--checksums` also writes the [checksums manifest](#checksums) of the archived files next to the ZIP, with `.checksums.json` instead of `.zip`.
+- `--sign` signs only the ZIP with `WP_RELEASE_SIGNING_KEY`. `--sign-checksums` generates and signs only the checksums manifest, implying `--checksums`. Use both flags to sign both files. External signatures are written alongside their files; embedded manifest signatures are written inside the package. The default format is WordPress `.sig`, unless integrity configuration selects another format.
+- `--sign-format` selects formats for requested signatures, such as `--sign-format wordpress,minisign,ssh`. It requires `--sign` or `--sign-checksums` and never enables signing by itself. Signing keys, formats and existing signature destinations are validated before writing the ZIP or manifest. `--force` also overwrites requested signatures. Job summaries include signatures and public keys; JSON results include `signatures` and `publicKey`.
 - An existing ZIP or manifest isn't overwritten without `--force`. A ZIP or manifest written inside the source directory is never archived.
 - `--package <name>` zips a package of the [configured packages](#deploy-configured-packages), by identifier or path under the configured root like `plugins/alpha`, instead of a source directory: its directory with the `files` config of its package group, the same files that its deploys select. The slug defaults to the directory name and the version to the `Version` header, and `--slug` and `--version` still set them. Any package of the config works, with or without a version or deploy targets. To zip what a deploy just released, pass the `package` and `version` of the `deploy-git --release-ref` result, in the same job and from the same build, so the ZIP has exactly the files of the release tag in the release repository. It can't be combined with `<source-dir>` or the file selection options. The `--json` result has the `package`, `slug` and `version`. `zipPackage()` builds the same ZIP from a script, with `getPackageFiles()` for the directory and the files of a package.
 
+To embed a signed manifest with a stable filename, use:
+
+```bash
+wp-release zip dist --checksums-file checksums.json --embed-checksums --sign-checksums
+```
+
+See [Checksums](#checksums) for filenames, placement, formats and configuration.
+
+### Signing targets for builds and ZIPs
+
+| Flag | `zip` | `build` |
+|---|---|---|
+| `--checksums` | Generate an unsigned manifest beside the ZIP. | Generate an unsigned manifest beside the directory. |
+| `--sign` | Sign only the ZIP. | Unsupported. |
+| `--sign-checksums` | Generate and sign the manifest. | Generate and sign the manifest. |
+| `--sign-format` | Choose formats for explicitly requested signatures. | Same; requires `--sign-checksums`. |
+
+```sh
+wp-release zip --slug code-prettify --sign --sign-checksums
+wp-release build --output dist/code-prettify --sign-checksums --sign-format minisign
+```
+
+These flags deliberately replace the former implicit signing behavior: `zip --checksums --sign` now leaves the manifest unsigned, and `--sign-format` alone is rejected. Add `--sign-checksums` to sign a manifest and `--sign` to sign a ZIP. The standalone `checksums` and `sign` commands remain available for workflows that write and sign a manifest inside the source before packaging it.
+
 ### Checksums
 
 The [`wp-release-checksums`](https://github.com/wpelevator/wp-release-checksums) GitHub Action runs this command.
@@ -359,26 +488,92 @@ 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
+#### Filenames, embedding and signing
 
-`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:
+`--checksums-file <file>` enables checksums and sets a relative filename independently of the ZIP name. Without `--embed-checksums`, it resolves against the ZIP output directory; with embedding, it resolves against the package root inside the ZIP (the archive root with `--no-root-folder`). Nested paths are supported, but absolute paths, backslashes, drive letters, control characters and dot segments are rejected. Embedding emits no external manifest and never modifies the source directory. Embedded minisign signatures contain a signing timestamp, so ZIP bytes can differ across signing times; unsigned metadata and WordPress/SSH signatures remain deterministic. Selected source files must not collide with generated manifest or signature entries.
 
 ```bash
-wp-release verify wp-content/plugins/my-plugin --checksums my-plugin.1.2.0.checksums.json
+# External manifest beside releases/my-plugin.1.5.1.zip.
+wp-release zip dist --output releases/my-plugin.1.5.1.zip --checksums-file checksums.json --sign-checksums
+
+# Signed manifest inside the package, with a stable filename.
+wp-release zip dist --output releases/my-plugin.1.5.1.zip --checksums-file checksums.json --embed-checksums --sign-checksums
+
+# Sign the completed downloadable archive separately.
+wp-release sign releases/my-plugin.1.5.1.zip
+
+# Verify installed files or an archive using its embedded manifest.
+wp-release verify installed-plugin --public-key "$PUBLIC_KEY"
+wp-release verify --zip releases/my-plugin.1.5.1.zip --public-key "$PUBLIC_KEY"
 ```
 
-- 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.
-- `--zip <file|url>` checks the files of a ZIP instead of a directory. The ZIP can be a URL, such as the one that WordPress.org builds for a release, and its single root folder is found automatically (or set `--root-folder`). The ZIP is extracted to a temporary directory after the same safety checks as `deploy-svn --from-zip`.
-- The version in the manifest must match the `Version` header of the checked files, so that an older release with its own valid manifest can't pass as a newer one.
-- A manifest can't list itself. A copy of the manifest and of its signature inside the checked files, at the root with the same names as the `--checksums` file or at the path of `--embedded`, is skipped when comparing files, but it must be identical to the `--checksums` file and its signature. The signature is the `.sig` file, or the file of `--signature-format`. A path that the manifest lists is never skipped, and a file that isn't a matching copy is reported as not in the checksums. See [Manifest inside the plugin](#manifest-inside-the-plugin).
+`--sign-checksums` enables checksums and signs only the manifest, before embedding when requested. It reads `WP_RELEASE_SIGNING_KEY` and uses `--sign-format wordpress,minisign,ssh` to select formats; each signature travels with the manifest. `--sign-format` selects formats for explicitly requested signing targets and never enables signing. `--sign` signs only the final ZIP; `--sign-checksums` controls the manifest in either placement mode. Use both flags to sign both targets. `--force` permits replacing external output files and signatures. `--json` reports external manifests in `checksumsPath`, embedded package-relative paths in `checksumsEmbedded`, and manifest signatures in `checksumsSignatures`.
 
-A checksums manifest proves only that the files match the manifest. With `--public-key <key>`, `verify` first checks `<checksums>.sig` against the Ed25519 public key and fails with exit code `2` before comparing any file when the signature is missing or invalid, so that the manifest itself can be trusted. `--signature-format minisign` or `ssh` checks `<checksums>.minisig` or `<checksums>.sshsig` instead. The key can be the base64 key, the minisign public key or the `ssh-ed25519` public key, since they're forms of the same key. See [Sign](#sign).
+The default WordPress filename remains the ZIP basename with `.checksums.json` instead of `.zip`, in either placement mode. Choose `--checksums-file checksums.json` for a stable name. The version remains in the JSON content.
+
+#### Formats
+
+`--checksums-format` chooses the manifest format. `wordpress-json` (default) uses the WordPress-compatible structure shown above. `sha256sum` uses GNU-compatible SHA-256 lines and escaping, with `SHA256SUMS` as its default filename. It carries no package identity or version, and standard `sha256sum --check` checks listed files without rejecting additional files; `wp-release verify` also checks for extra files.
+
+```bash
+wp-release zip dist --embed-checksums --checksums-format sha256sum --sign-checksums --sign-format minisign
+wp-release verify --zip my-plugin.1.5.1.zip --checksums-format sha256sum --public-key "$MINISIGN_PUBLIC_KEY" --signature-format minisign
+# From the extracted package directory:
+minisign -Vm SHA256SUMS -P "$MINISIGN_PUBLIC_KEY"
+sha256sum --check SHA256SUMS
+```
+
+`--checksums-algorithms md5,sha256` selects JSON digest fields; lists replace configured lists. Supported algorithms are MD5 (for compatibility) and SHA-256. The `sha256sum` codec requires SHA-256. The standalone `checksums` command also accepts `--checksums-format`, keeping `--output` relative to the working directory.
+
+#### Configuration and custom codecs
+
+The optional top-level `integrity` configuration maps to these flags. Explicit CLI values override configuration; `--no-embed-checksums` and `--no-sign-checksums` disable their configured behaviors. Existing release configurations retain their `packages` array; use `packages: []` for a configuration containing only integrity settings.
+
+```js
+export default {
+  packages: [],
+  integrity: {
+    codec: 'wordpress-json', // --checksums-format
+    algorithms: ['md5', 'sha256'], // --checksums-algorithms
+    file: 'checksums.json', // --checksums-file
+    embed: true, // --embed-checksums
+    sign: { formats: ['wordpress'] }, // --sign-checksums and --sign-format
+  },
+};
+```
 
-### Manifest inside the plugin
+Use `codec: 'sha256sum'`, `algorithms: ['sha256']`, `file: 'SHA256SUMS'` and `sign: { formats: ['minisign'] }` for the GNU setup. Custom codecs provide `id`, a default `filename`, and `encode`/`decode` callbacks, which may be asynchronous. Generation validates the round trip before writing artifacts: codecs must preserve all selected file paths, represented digests and any represented package identity. They receive and return the existing WordPress-compatible `ChecksumsManifest` model (`plugin` or `theme`, optional `version`, and a `files` map of relative paths to digest fields), keeping format customization separate from selection, hashing and signing.
 
-A release can ship its signed manifest inside the plugin, so that an installed copy can be checked later with the public key, and also publish the same two files as release assets. Both use the same files:
+```js
+export default {
+  packages: [],
+  integrity: {
+    file: 'metadata/integrity.json',
+    embed: true,
+    sign: { formats: ['wordpress'] },
+    codec: {
+      id: 'custom-v1',
+      filename: 'integrity.json',
+      encode(manifest) {
+        return Buffer.from(JSON.stringify({ schema: 'custom-v1', payload: manifest }) + '\n');
+      },
+      decode(bytes) {
+        const document = JSON.parse(Buffer.from(bytes).toString('utf8'));
+        if (document.schema !== 'custom-v1') {
+          throw new Error('Unknown integrity schema.');
+        }
+        return document.payload;
+      },
+    },
+  },
+};
+```
+
+`zip` and `checksums` read the caller's release configuration. For verification of custom codecs or configured filenames, pass `--config wp-release.config.mjs` explicitly. See [Verify](#verify).
+
+#### Manifest inside the plugin
+
+For a manifest that is also published as a separate release asset or deployed directly from a source directory, write and sign it in that directory before packaging. Use `zip --embed-checksums` as described [above](#filenames-embedding-and-signing) when only the archive should contain the generated metadata. The source-directory workflow uses the same manifest for installed copies and release assets:
 
 ```bash
 wp-release checksums build --slug my-plugin --output build/checksums.json
@@ -387,7 +582,7 @@ wp-release zip build --slug my-plugin
 wp-release deploy-svn build --trunk --svn-tag 1.2.0
 ```
 
-- Write the manifest into the directory that is zipped and deployed. It lists every file except itself, and `checksums`, `zip` and `verify` also skip its signatures (`<name>.sig`, `<name>.minisig` and `<name>.sshsig`), so running `checksums` again on a build that already has the pair gives the same manifest. Sign it last, since the signature covers the exact bytes of the manifest.
+- Write the manifest into the directory that is zipped and deployed. The `checksums` command leaves its output manifest and its signatures (`<name>.sig`, `<name>.minisig` and `<name>.sshsig`) out of the hashes, so running it again with the same output path and `--force` gives the same manifest. `verify` checks matching copies as described below. Sign it last, since the signature covers the exact bytes of the manifest.
 - `zip` and `deploy-svn` carry the pair like any other file. Don't use `zip --checksums` here, since it would write a second manifest that lists the first one. Attach `build/checksums.json` and `build/checksums.json.sig` to the GitHub release as they are.
 - The signature covers file hashes and not a ZIP, so it stays valid for the ZIP that WordPress.org builds from SVN. Check what WordPress.org serves after a deploy, with the manifest and public key from your build:
 
@@ -400,6 +595,25 @@ wp-release deploy-svn build --trunk --svn-tag 1.2.0
 
 The public key has to come from somewhere other than the plugin that it checks, because someone who can overwrite the plugin files can also replace a key and a signature inside them. A copy of the manifest also doesn't prevent a downgrade to an older release that was signed too, so the installing side has to enforce a minimum version.
 
+### 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.
+- `--zip <file|url>` checks the files of a ZIP instead of a directory. The ZIP can be a URL, such as the one that WordPress.org builds for a release, and its single root folder is found automatically (or set `--root-folder`). The ZIP is extracted to a temporary directory after the same safety checks as `deploy-svn --from-zip`.
+- The version in the manifest must match the `Version` header of the checked files, so that an older release with its own valid manifest can't pass as a newer one.
+- A manifest can't list itself. A copy of the manifest and of its signature inside the checked files, at the root with the same names as the `--checksums` file or at the path of `--embedded`, is skipped when comparing files, but it must be identical to the `--checksums` file and its signature. The signature is the `.sig` file, or the file of `--signature-format`. A path that the manifest lists is never skipped, and a file that isn't a matching copy is reported as not in the checksums. See [Manifest inside the plugin](#manifest-inside-the-plugin).
+
+A checksums manifest proves only that the files match the manifest. With `--public-key <key>`, `verify` first checks `<checksums>.sig` against the Ed25519 public key and fails with exit code `2` before comparing any file when the signature is missing or invalid, so that the manifest itself can be trusted. `--signature-format minisign` or `ssh` checks `<checksums>.minisig` or `<checksums>.sshsig` instead. The key can be the base64 key, the minisign public key or the `ssh-ed25519` public key, since they're forms of the same key. See [Sign](#sign).
+
+Verification never executes configuration from inside a downloaded package. Without `--checksums`, `verify` reads the embedded filename selected by `--checksums-file`, explicit configuration, or the codec default. For a versioned embedded filename, pass that filename explicitly. With a public key, signatures are checked before decoding; the selected signature format must exist (WordPress `.sig` by default; pass `--signature-format minisign` or `ssh` for those formats), and all other present supported signature formats are also authenticated when verifying the embedded manifest. Without a public key, checksums detect changes but do not authenticate the publisher. Trusted public keys must come from outside the package.
+
 ### Sign
 
 The [`wp-release-sign`](https://github.com/wpelevator/wp-release-sign) GitHub Action runs this command.
@@ -414,6 +628,7 @@ WP_RELEASE_SIGNING_KEY=… wp-release sign my-plugin.1.2.0.zip my-plugin.1.2.0.c
 - The key is read from the `WP_RELEASE_SIGNING_KEY` environment variable only, as a base64 32-byte Ed25519 seed or a 64-byte libsodium secret key, the formats that `sodium_crypto_sign_seed_keypair()` and the update-pilot-server package signing key take. There's no flag for it, since it would show in the process list, and it's never logged.
 - `--verbose` prints the public key of the signing key in the form of each written format. `--json` returns it as `publicKey`, and in every form as `publicKeys`. Pass it to `verify --public-key` and to the plugin that checks the signatures.
 - An existing signature file isn't overwritten without `--force`.
+- `zip --sign` signs only the ZIP; add `--sign-checksums` to sign its manifest too. `signFiles()` signs files from a script.
 
 #### Signature formats
 
@@ -433,7 +648,7 @@ wp-release sign my-plugin.1.2.0.zip --format wordpress,minisign,ssh
 - `ssh` is the armored `SSHSIG` format that `ssh-keygen -Y sign` writes, with a SHA-512 digest and the `file` namespace, so that the signature can't pass as one for commits or another namespace. It's written to `.sshsig` instead of the `.sig` of `ssh-keygen`, which the `wordpress` format uses. Put the SSH public key in an `allowed_signers` file as `<identity> ssh-ed25519 AAAA…`.
 - All formats are Ed25519 signatures by the same key, so one key and one secret cover all of them. The tests check each format with `minisign`, `ssh-keygen` and libsodium, and check the signatures that `minisign` and `ssh-keygen` write with `wp-release verify`.
 
-Generate a key pair with `wp-release keygen`. It prints the private seed once as `WP_RELEASE_SIGNING_KEY=…` and the matching public key, also as a minisign public key and an `ssh-ed25519` public key. Store the private seed securely; never commit it or put it in a workflow log. Don't run `keygen` in CI or with `--github-output`, since those outputs can expose the private seed. The public key can be distributed to verifiers.
+Generate a key pair with `wp-release keygen`. It prints the private seed once as `WP_RELEASE_SIGNING_KEY=…` and the matching public key, also as a minisign public key and an `ssh-ed25519` public key. Generate keys locally and store the private seed in your secret manager or CI secrets. Distribute the public key to verifiers. `keygen --github-output` is rejected to keep the private seed out of workflow outputs; regular and `--json` output both include the seed.
 
 ### Version check
 
@@ -499,7 +714,7 @@ Validation:
 - `--readme-only` can't be combined with `--svn-tag`, since a tag is a release snapshot that a readme update never changes.
 - `--version` defaults to `--svn-tag`, then the `Version` header of the deployed files; when `--version` and `--svn-tag` are both set they must match.
 - Pre-release versions like `1.0.0-rc.1` can be tagged, but syncing one to `trunk/` warns, since trunk is for the development version.
-- `--trunk` without `--svn-tag` works but warns, because trunk then differs from the stable tag that WordPress.org serves downloads from.
+- `--trunk` without `--svn-tag` works but warns, to remind you that updating trunk alone doesn't create a version tag for stable downloads.
 - A version mismatch throws a `VersionMismatchError`, a `ValidationError` with the `mismatches` and a problem for each, with its file and line. See [Logging](#logging).
 
 ### Deploy to Git
@@ -640,7 +855,7 @@ const { releases } = await release.version( { dryRun: true } );
 const { tags } = await release.tag( { dryRun: true } );
 ```
 
-`ChangesetRelease` runs the `changeset-*` commands: `add()`, `getStatus()`, `version()` and `tag()`, plus `getPlan()` and `getPackages()`. Each call reads the configuration, packages and pending changesets again, so one instance can version and then tag. It takes a git runner from `createGitRunner()` as `git`, so that tests can replace it. The functions `addChangeset()`, `getChangesetStatus()`, `versionChangesets()`, `tagChangesets()`, `getChangesetReleasePlan()` and `getChangesetPackages()` do the same with the default runners, in one call.
+`ChangesetRelease` runs the `changeset-*` commands: `add()`, `getStatus()`, `version()` and `tag()`, plus `getPlan()` and `getPackages()`. Each call reads the configuration, packages and pending changesets again, so one instance can version and then tag. It takes a git runner from `createGitRunner()` as `git`, so that tests can replace it. Without a config file, it detects a single root project. Its optional `singleProject` settings accept `versions` (the existing version descriptors), `versionFrom` (the same selector as `--version-from`), `baseBranch`, `remote`, `changesets`, `readmeChangelog` and `changelogInsertAfter`; `tagFormat` remains a repository option. The functions `addChangeset()`, `getChangesetStatus()`, `versionChangesets()`, `tagChangesets()`, `getChangesetReleasePlan()` and `getChangesetPackages()` do the same with the default runners, in one call.
 
 ### Logging
 
@@ -745,16 +960,20 @@ npm run lint --workspace @wpelevator/wp-release
 - `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/`.
+The `wpelevator-source` export condition points at `src/index.ts`. The wp-release tests and monorepo CLI scripts use it to work with the source instead of a `dist/` build. Action builds use the declared dependency's default export, which resolves to `dist/` for the workspace copy and the published package. Build wp-release before building the actions.
+
+`execute( 'deploy-svn', args, { cwd, logger, svnRunner } )` runs a single-plugin deployment or a configured plan or deployment. The optional `svnRunner` replaces the external command runner in both modes; without it, the command uses its normal runner.
 
 ### Architecture
 
 wp-release has two layers, so that it fits any repository layout:
 
-- **Primitives** work on the directory, file or values they're given and know nothing about the repository: `zip <dir>`, `checksums`, `sign`, `verify`, `version-check`, `deploy-git <dir>` and `deploy-svn <dir>`.
-- **The config layer** reads `wp-release.config.js` for everything about the repository: where packages are (`root` and the package globs), how their versions and tags are named (`version`, `tagFormat`), which files they ship (`files`), where they deploy (`deploy`) and the git `remote`. The changeset commands, `deploy-git` and `deploy-svn --release-ref`, and `zip --package` belong to it, and the global `--config` and `--tag-format` options select or adjust the config. Only `--release-ref` reads which package and version a ref releases. A primitive with a config mode, like `deploy-git --release-ref` beside `deploy-git <dir>` or `zip --package` beside `zip <dir>`, only takes the package directory, its files and its targets from the config there, and otherwise works the same.
+- **Primitives** work on the directory, file or values they're given and know nothing about the repository: `build <dir>`, `zip <dir>`, `checksums`, `sign`, `verify`, `version-check`, `deploy-git <dir>` and `deploy-svn <dir>`.
+- **The config layer** reads `wp-release.config.js` for everything about the repository: where packages are (`root` and the package globs), how their versions and tags are named (`version`, `tagFormat`), which files they ship (`files`), where they deploy (`deploy`) and the git `remote`. The changeset commands (with a single-project fallback when no config exists), `deploy-git` and `deploy-svn --release-ref`, and `build --package` and `zip --package` belong to it, and the global `--config` and `--tag-format` options select or adjust the config. `zip` and `checksums` also read caller configuration for integrity settings even without `--package`; verification reads it only when explicitly selected. Only `--release-ref` reads which package and version a ref releases. A primitive with a config mode, like `deploy-git --release-ref` beside `deploy-git <dir>` or `zip --package` beside `zip <dir>`, only takes the package directory, its files and its targets from the config there, and otherwise works the same.
+
+Configured repositories use the layout and naming conventions their config sets. Config-free changeset releases use the root-only detection and defaults described above.
 
-Nothing assumes a directory structure or naming convention that the config doesn't set.
+The GitHub Actions are adapters to these commands: they use the same flag names and `execute()` entry point, with secrets supplied through environment variables. The SVN action injects a command runner that checks or installs SVN only when a deployment runs its first SVN command; config planning and deployment behavior remain in `wp-release`.
 
 The package uses ES modules as its unit of encapsulation, like most Node.js CLI tools: a module exports a few functions and keeps its helpers private, so there's no class to wrap them in. A class is used only when it holds state across steps or binds dependencies, so that callers and tests can replace them:
 
@@ -769,6 +988,7 @@ The changeset release modules, from the entry point down:
 | Module | Responsibility |
 |---|---|
 | `changeset-release.ts` | `ChangesetRelease`, which plans releases and runs `add()`, `getStatus()`, `version()` and `tag()`, and the function form of each operation. |
+| `single-project.ts` | Resolving the config-free root project, its version source and targets, and shared release settings. |
 | `changeset-config.ts` | Loading and validating `wp-release.config.js`, and the version source and target helpers. |
 | `changeset-packages.ts` | Discovering the packages of the configured globs, with or without a version, and finding the changed ones. |
 | `changeset-files.ts` | Reading, writing and consuming changeset files. |

package/dist/changeset-config.d.ts

@@ -1,3 +1,4 @@
+import type { IntegrityConfig } from './integrity.ts';
 import type { Changeset, ChangesetBump, ChangesetPackage } from './changesets.ts';
 export type PackageVersionSource = {
     kind: 'package-json';
@@ -217,6 +218,8 @@ export interface DependentsConfig {
 }
 /** JavaScript configuration for changeset-aware releases. */
 export interface ChangesetConfig {
+    /** Default checksum format, placement and manifest signing for ZIPs. */
+    integrity?: IntegrityConfig;
     /** Branch receiving ordinary changes. */
     baseBranch?: string;
     /** Git remote that tags are pushed to and the base branch is compared on, origin by default. */

package/dist/changeset-release.d.ts

@@ -1,9 +1,12 @@
+import type { SingleProjectOptions } from './single-project.ts';
 import type { Changeset, ChangesetBump, ChangesetPackage, ChangesetReleasePlan, PackageRelease, VersionedRelease } from './changesets.ts';
 import type { GitRunner } from './git.ts';
 import { ReleaseRepository } from './release-repository.ts';
 export interface ChangesetRepository {
     cwd: string;
     configFile?: string;
+    /** Single-project fallback settings, used only without a release config. */
+    singleProject?: SingleProjectOptions;
     /** Tag format that replaces the tagFormat of the config. */
     tagFormat?: string;
 }
@@ -99,6 +102,7 @@ export interface ChangesetStatusResult {
 export declare class ChangesetRelease {
     readonly cwd: string;
     readonly configFile: string | undefined;
+    readonly singleProject: SingleProjectOptions | undefined;
     readonly tagFormat: string | undefined;
     readonly repository: ReleaseRepository;
     /**
@@ -109,7 +113,7 @@ export declare class ChangesetRelease {
      * Discover configured packages, pending changesets, and their proposed
      * versions.
      *
-     * @return A release plan; `undefined` when no config is present.
+     * @return A release plan; `undefined` without a config or a recognized root project.
      */
     getPlan(): Promise<ChangesetReleasePlan | undefined>;
     /**
@@ -200,7 +204,7 @@ export declare class ChangesetRelease {
      * Load the configuration, discover the packages and plan the releases of
      * the pending changesets, including the releases of their dependents.
      *
-     * @return Release context, undefined without a config.
+     * @return Release context, undefined without a config or a recognized root project.
      * @throws {ValidationError} For an invalid config, plan or changeset.
      */
     private loadContext;
@@ -218,6 +222,8 @@ export declare class ChangesetRelease {
      * @throws {ValidationError} Without a config.
      */
     private requireConfig;
+    /** Load an explicit/discovered config, otherwise resolve one root project. */
+    private loadConfig;
     /**
      * Get the directory of the changeset files.
      *
@@ -230,7 +236,7 @@ export declare class ChangesetRelease {
  * Discover configured packages, pending changesets, and their proposed versions.
  *
  * @param input Repository root and optional explicit config file.
- * @return A release plan; `undefined` when no config is present.
+ * @return A release plan; `undefined` without a config or a recognized root project.
  */
 export declare function getChangesetReleasePlan(input: ChangesetRepository): Promise<ChangesetReleasePlan | undefined>;
 /**