@wpelevator/wp-release 0.13.0 → 0.14.0

package/README.md

@@ -28,8 +28,8 @@ npx wp-release --help
 |---|---|
 | `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. |
-| `wp-release keygen` | Generate a base64 Ed25519 private seed and public key for signing and verification. |
+| `wp-release sign <file>... [options]` | Sign files with Ed25519, writing a detached `<file>.sig` next to each, or minisign and SSH signatures with `--format`. |
+| `wp-release keygen` | Generate a base64 Ed25519 private seed and its public key, also as minisign and SSH public keys. |
 | `wp-release verify [<source-dir>] --checksums <file> [options]` | Check a plugin or theme directory, or a ZIP, 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. |
@@ -67,7 +67,7 @@ Each command also adds a section to the [job summary](https://docs.github.com/en
 | `deploy-git` | Repository, release commit and the pushed branch and tag. |
 | `zip` | ZIP, number of files and checksums manifest. |
 | `checksums` | Manifest and number of files. |
-| `sign` | Signature files and the public key. |
+| `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. |
 | `version-check` | The matching version, or a table of the mismatches with their files and lines. |
 | `changeset-status` | Each changed package with whether it has a changeset. |
@@ -76,7 +76,7 @@ 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.
+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).
 
 ### Changesets support (experimental)
 
@@ -125,13 +125,32 @@ export default defineConfig( {
 } );
 ```
 
-`version.from` selects the current version; `version.to` lists release targets. Package globs support `*`, `?` and `**`; `{path}` in tag templates is relative to `root`. Templates also accept `{type}`, `{name}` and `{slug}`, while `tagType` customizes the type label. Use `phpConstantVersion( { file, constant } )` to sync a PHP constant.
+`version.from` selects the current version; `version.to` lists release targets. Use `phpConstantVersion( { file, constant } )` to sync a PHP constant.
+
+#### Packages and tags
+
+The config describes the repository, so wp-release assumes no directory structure or naming convention of its own:
+
+- **Packages** are the directories that the `glob` of a `packages` entry matches under `root`, with `*`, `?` and `**`, like `plugins/*`, or `.` for a repository with one package at its root. The settings of an entry apply to each of its packages. Discovery never looks inside `.git`, `node_modules`, `vendor` or `dist` directories. A package is identified by its path, or with `idFrom` by the name in its `package.json` or `composer.json`, and commands that take a package accept either.
+- **Templates** name the tags and the deploy targets of a package with these placeholders:
+
+  | Placeholder | Value | `plugins/alpha` | Root package |
+  |---|---|---|---|
+  | `{path}` | Package directory relative to `root`, empty for a package at the root | `plugins/alpha` | (empty) |
+  | `{name}` | Package identifier | `plugins/alpha`, or its manifest name with `idFrom` | the manifest name, or the directory name |
+  | `{version}` | Released version | `1.2.0` | `1.2.0` |
+
+  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.
+- **`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.
 
-Without `--since`, `changeset-status` compares against `origin/<baseBranch>`; fetch that ref or pass `--since` when using a fork or different upstream. `loadChangesetConfig()` discovers a conventional config at the repository root, unless `--config <path>` selects one explicitly.
+Without `--since`, `changeset-status` compares against `<remote>/<baseBranch>`, where `remote` in the config defaults to `origin` and is also the remote that `changeset-tag --push` pushes tags to; fetch that ref or pass `--since` when using a fork or different upstream. `loadChangesetConfig()` discovers a conventional config at the repository root, unless `--config <path>` selects one explicitly.
 
-Add release notes in a feature PR with `npx wp-release changeset-add`. In a terminal, it lists the packages, marks the ones that changed since `origin/<baseBranch>` (or `--since <ref>`) without a changeset, and asks for the packages to release, a `patch`, `minor` or `major` bump for each, and the release note. Choose packages by number, identifier or path, or press Enter to release the changed ones; `none` adds an empty changeset. Changed files include uncommitted and untracked ones, since changesets are usually added before committing.
+Add release notes in a feature PR with `npx wp-release changeset-add`. In a terminal, it lists the packages, marks the ones that changed since `<remote>/<baseBranch>` (or `--since <ref>`) without a changeset, and asks for the packages to release, a `patch`, `minor` or `major` bump for each, and the release note. Choose packages by number, identifier or path, or press Enter to release the changed ones; `none` adds an empty changeset. Changed files include uncommitted and untracked ones, since changesets are usually added before committing.
 
 Without a terminal, or for scripts, pass the changeset as options: `npx wp-release changeset-add --package @vendor/plugin --bump patch --summary "Fix the checkout validation."`. Repeat package and bump flags for multiple packages, or use `--empty` when no release is needed. A package can also be named by its path under `root`, like `plugins/alpha`, and the changeset records its identifier; `changeset-version --package` and `changeset-tag --package` accept paths too. A single `--bump` without `--package` releases every changed package without a changeset, like `changeset-add --bump patch --summary "…"` to fix a failing `changeset-status` check. `--json` and `--github-output` never ask.
 
@@ -310,6 +329,7 @@ wp-release zip dist --slug my-plugin --checksums
 - 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.
+- `--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.
 
 ### Checksums
 
@@ -352,9 +372,9 @@ wp-release verify wp-content/plugins/my-plugin --checksums my-plugin.1.2.0.check
 - 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 `.sig` 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 `.sig`. 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 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 base64 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. See [Sign](#sign).
+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).
 
 ### Manifest inside the plugin
 
@@ -367,7 +387,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 `<name>.sig`, 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. 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.
 - `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:
 
@@ -376,7 +396,7 @@ wp-release deploy-svn build --trunk --svn-tag 1.2.0
     --checksums build/checksums.json --public-key "$PUBLIC_KEY"
   ```
 
-- The manifest can have any name and location, for example `--output build/includes/signatures/checksums.json`, and missing folders are created. Tell `verify` where the shipped copy is with `--embedded <path>`, like `--embedded includes/signatures/checksums.json`. Both the `--checksums` file and its `.sig` must then exist, both copies must be shipped, and they're skipped when comparing files and must be identical to the originals. The manifest can't list the embedded path. Without `--embedded`, `verify` looks for the manifest name at the root, and skips a file only when it exists, the matching original exists and the manifest doesn't list it. Otherwise it's checked like any other file, so a listed file that has the name of the manifest can't be deleted unnoticed, and a shipped `.sig` without an original is reported as not in the checksums.
+- The manifest can have any name and location, for example `--output build/includes/signatures/checksums.json`, and missing folders are created. Tell `verify` where the shipped copy is with `--embedded <path>`, like `--embedded includes/signatures/checksums.json`. Both the `--checksums` file and its signature must then exist, both copies must be shipped, and they're skipped when comparing files and must be identical to the originals. The manifest can't list the embedded path. Without `--embedded`, `verify` looks for the manifest name at the root, and skips a file only when it exists, the matching original exists and the manifest doesn't list it. Otherwise it's checked like any other file, so a listed file that has the name of the manifest can't be deleted unnoticed, and a shipped `.sig` without an original is reported as not in the checksums.
 
 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.
 
@@ -392,10 +412,28 @@ WP_RELEASE_SIGNING_KEY=… wp-release sign my-plugin.1.2.0.zip my-plugin.1.2.0.c
 
 - The signature is the one WordPress core's `verify_file_signature()` checks: a base64 Ed25519 signature of the raw SHA-384 digest of the file. The tests check it against `sodium_crypto_sign_verify_detached()` in PHP. A `.sig` file can hold several signatures, one per line, and a file is valid when any of them match, which allows a key rotation window.
 - 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, which `--json` also returns as `publicKey`. Pass it to `verify --public-key` and to the plugin that checks the signatures.
-- An existing `.sig` file isn't overwritten without `--force`.
+- `--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`.
+
+#### Signature formats
+
+The same key can also sign in formats that tools outside WordPress check, for people who download a release by hand or verify it in other pipelines. Pick them with `--format`, comma-separated or repeated; the default is `wordpress`:
+
+```bash
+wp-release sign my-plugin.1.2.0.zip --format wordpress,minisign,ssh
+```
+
+| Format | File | Checked by |
+|---|---|---|
+| `wordpress` | `<file>.sig` | WordPress core's `verify_file_signature()`, update-client and `wp-release verify` |
+| `minisign` | `<file>.minisig` | [minisign](https://jedisct1.github.io/minisign/) and compatible tools: `minisign -Vm <file> -P <minisign public key>` |
+| `ssh` | `<file>.sshsig` | OpenSSH 8.1 or later: `ssh-keygen -Y verify -f allowed_signers -I <identity> -n file -s <file>.sshsig < <file>` |
 
-Generate a key pair with `wp-release keygen`. It prints the private seed once as `WP_RELEASE_SIGNING_KEY=…` and the matching 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.
+- `minisign` signs the BLAKE2b-512 digest of the file, like `minisign -S` does by default, and adds a trusted comment with the signing time and file name that a second signature covers. minisign generates a random key ID for its keys, but the key here is a plain Ed25519 seed, so wp-release derives the key ID from the public key. `wp-release verify` doesn't compare key IDs, so signatures of keys that minisign generated verify too.
+- `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.
 
 ### Version check
 
@@ -508,11 +546,11 @@ packages: [
 		deploy: {
 			git: [
 				// The release repository of each plugin, with its history.
-				{ repository: 'https://github.com/me/{slug}.git', message: 'Release {path} {ref} from {revision}' },
+				{ repository: ( { package: pkg } ) => `https://github.com/me/${ pkg.path.split( '/' ).pop() }.git`, message: 'Release {path} {ref} from {revision}' },
 				// A mirror that only gets release tags, named v1.2.0.
 				{ repository: ( { package: pkg } ) => `https://gitlab.com/me/${ pkg.path }.git`, branches: false, tag: 'v{version}' },
 			],
-			svn: { slug: 'me-{slug}', assetsDir: '.wordpress-org' },
+			svn: { slug: ( { package: pkg } ) => `me-${ pkg.path.split( '/' ).pop() }`, assetsDir: '.wordpress-org' },
 		},
 	},
 	// A package that isn't versioned, like a Docker image, only deploys branches.
@@ -530,12 +568,13 @@ packages: [
 `deploy-svn` has the same modes. `--release-ref` can't be combined with the options of a single target, like `--git-url`, `--tag` or `--svn-tag`, which come from the config.
 
 - **Git targets** take a `repository` and release both branches and tags by default. `branches` limits the branches, like `[ 'main' ]`, or turns them off with `false`, and `tag` is the tag template in the repository, `{version}` by default, or `false` to not release tags. A release tag is created on top of the default branch of the repository, and a branch is released to the same branch. `history: false` uses the source commit instead of the package history from `git subtree split`, and `message` sets the release commit message, `Release {ref} from {revision}` by default.
-- **SVN targets** only deploy release tags: a stable release syncs `trunk/`, creates its tag and syncs the `assetsDir`, and a pre-release only creates its tag. `slug` defaults to `{slug}`, `url` to the WordPress.org plugin repository, and `message` sets the commit message. Credentials come from `SVN_USERNAME` and `SVN_PASSWORD`, or `--svn-username`.
+- **SVN targets** only deploy release tags: a stable release syncs `trunk/`, creates its tag and syncs the `assetsDir`, and a pre-release only creates its tag. `slug`, the WordPress.org plugin slug, defaults to the name of the package directory, `url` to the WordPress.org plugin repository, and `message` sets the commit message. Credentials come from `SVN_USERNAME` and `SVN_PASSWORD`, or `--svn-username`.
 - **Several targets**: `git` and `svn` each take one target or a list, like a release repository and a mirror on another host. Each target is a separate deploy.
 - **Credentials**: a GitHub repository URL needs no token in it, since `GITHUB_TOKEN` is sent as an authorization header (see above). A callback can still add credentials for other hosts.
-- **Templates and callbacks**: `repository`, `slug` and `message` are templates with `{name}`, `{slug}`, `{path}` and `{type}`, like the `tagFormat`, and `{version}`, `{branch}`, `{ref}` (the tag or branch that the deploy writes in the target) and `{revision}` (the source commit), or callbacks that receive `{ package, version, branch, ref, revision }`, where `package` has the `name`, `directory`, `path` and `type`. A callback can choose another host for some packages, read the environment, or return nothing to skip the target for that package or ref; an empty `message` uses the default one. Credentials in URLs are never printed or listed.
+- **Templates and callbacks**: `repository`, `slug` and `message` are templates with `{name}` and `{path}`, like the `tagFormat`, and `{version}`, `{branch}`, `{ref}` (the tag or branch that the deploy writes in the target) and `{revision}` (the source commit), or callbacks that receive `{ package, version, branch, ref, revision }`, where `package` has the `name`, `directory`, `path` and `type`. A callback can name a target after the package directory, choose another host for some packages, read the environment, or return nothing to skip the target for that package or ref; an empty `message` uses the default one. Credentials in URLs are never printed or listed.
+- **Results**: with `--json` or `--github-output`, the result lists each deploy in `deploys` with its `package`, `label`, `target` (the repository or WordPress.org plugin, with credentials redacted), `targetRef` (the tag or branch written there), `version` or `branch`, and its `result` or `error`. A remote target repository also has its `targetHost`, like `github.com`, and `targetPath`, like `me/my-plugin`, without credentials, for a workflow step that calls the API of the forge that hosts it, such as to create the release of the deployed tag. The targets of `--list` have the same `host` and `path`, and `parseRepositoryUrl()` reads them from an HTTP(S), SSH or scp-like URL. `wp-release` doesn't call forge APIs itself.
 - **Packages without a version**: a package entry without `version`, like a single directory with a `glob` of its path, isn't released with changesets, so changes to it don't need one, and it only deploys branches, since it has no release tags.
-- **Files**: `files.exclude` adds gitignore-style patterns relative to the package directory, and `files.distignore` sets the ignore file relative to it or turns it off with `false`. A `files` at the root of the config applies to every package group, for the rules that all packages share, and the `files` of a group add their patterns after it and can replace its ignore file. Without `files`, each package's `.distignore` applies, like for `zip`; there's no repository-wide `.distignore`, since each one is relative to its package. `getDeployPackages()` lists the packages with their file selection, for example to build a ZIP with the same files.
+- **Files**: `files.exclude` adds gitignore-style patterns relative to the package directory, and `files.distignore` sets the ignore file relative to it or turns it off with `false`. A `files` at the root of the config applies to every package group, for the rules that all packages share, and the `files` of a group add their patterns after it and can replace its ignore file. Without `files`, each package's `.distignore` applies, like for `zip`; there's no repository-wide `.distignore`, since each one is relative to its package. `zip --package <name>` zips a package with the same files, `getPackageFiles()` returns the directory and the file selection of any configured package, and `getDeployPackages()` lists the packages with deploy targets and their file selection.
 
 A deploy releases the files of the working tree, so build the packages first. One job that builds once and runs `deploy-git --release-ref "$GITHUB_REF"` is the simplest setup, also for a branch that releases every package. A matrix with a job for each package from `--list` would build every package in every job, so build once and pass the built tree to the jobs as an artifact if you need one, for example for separate credentials.
 
@@ -710,6 +749,13 @@ The `wpelevator-source` export condition points at `src/index.ts`. The tests and
 
 ### 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.
+
+Nothing assumes a directory structure or naming convention that the config doesn't set.
+
 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:
 
 - **Workflows with steps** are classes, so that their steps share state and dependencies on the instance: `SvnDeploy` shares the temporary working copy across `prepare()`, `checkout()`, `sync()` and `commit()`, `GitDeploy` binds the options and the git runner to its steps, and `ChangesetRelease` binds the repository and the runners to `add()`, `version()` and `tag()`.
@@ -732,7 +778,8 @@ The changeset release modules, from the entry point down:
 | `changelog.ts` | Changelog entries, and the `CHANGELOG.md` and readme changelog sections. |
 | `release-tags.ts` | Choosing the version and previous tag of a release, and building its release notes. |
 | `tag-format.ts` | Formatting tag names from the tag format. |
-| `package-deploy.ts` | Resolving the configured deploys of a ref: the released packages, their targets and file selections, for `deploy-git` and `deploy-svn`. |
+| `package-deploy.ts` | Resolving the configured deploys of a ref: the released packages, their targets and file selections, for `deploy-git` and `deploy-svn`, and the file selection of a package for `zip --package`. |
+| `package-zip.ts` | `zipPackage()`, the ZIP and checksums manifest of the selected files of a package, for `zip` and the snapshot builds of a monorepo. |
 | `release-repository.ts` | `ReleaseRepository`, the git commands of a release: tags, commits and changed files. |
 | `file-journal.ts` | `FileJournal`, which restores every file a failed `changeset-version` run changed. |
 | `versions.ts` | Version checks and SemVer precedence. |

package/dist/changeset-config.d.ts

@@ -62,8 +62,6 @@ export interface ChangesetPackageGroup {
     glob: string;
     /** Package paths excluded from this group, relative to root. */
     exclude?: string[];
-    /** Optional type used by the {type} tag template. */
-    tagType?: string;
     /** Manifest field used as the changeset name; defaults to `path`. */
     idFrom?: PackageIdSource;
     /**
@@ -107,7 +105,7 @@ export interface DeployPackage {
     type: ChangesetPackage['type'];
 }
 /**
- * A deploy setting: a template with {name}, {slug}, {path}, {type},
+ * A deploy setting: a template with {name}, {path},
  * {version}, {branch}, {ref} and {revision}, or a callback that receives the
  * package and its release. An empty repository or slug skips the target, and
  * an empty message uses the default one.
@@ -115,7 +113,7 @@ export interface DeployPackage {
 export type DeployTemplate = string | ((input: DeployTargetInput) => string | undefined | Promise<string | undefined>);
 /** A Git repository that `deploy-git` releases a package to. */
 export interface GitDeployTarget {
-    /** Repository URL, like `https://github.com/me/{slug}.git`. */
+    /** Repository URL, like `https://github.com/me/{path}.git`. */
     repository: DeployTemplate;
     /** Branches released to the same branch of the repository: all with true (the default), none with false, or the listed ones. */
     branches?: boolean | string[];
@@ -128,7 +126,7 @@ export interface GitDeployTarget {
 }
 /** A WordPress.org plugin that `deploy-svn` releases a package to. */
 export interface SvnDeployTarget {
-    /** Plugin slug, defaults to `{slug}`. */
+    /** WordPress.org plugin slug, defaults to the name of the package directory. */
     slug?: DeployTemplate;
     /** SVN repository URL with {slug}, defaults to WordPress.org. */
     url?: string;
@@ -221,11 +219,13 @@ export interface DependentsConfig {
 export interface ChangesetConfig {
     /** Branch receiving ordinary changes. */
     baseBranch?: string;
+    /** Git remote that tags are pushed to and the base branch is compared on, origin by default. */
+    remote?: string;
     /** Directory containing Markdown changesets, relative to the repository root. */
     changesets?: string;
     /** Package groups to discover and release. */
     packages: ChangesetPackageGroup[];
-    /** Git tag template supporting {name}, {slug}, {path}, {type} and {version}. */
+    /** Git tag template supporting {name}, {path} and {version}. */
     tagFormat?: string;
     /** Directory against which package paths in tag formats are calculated. */
     root?: string;
@@ -358,6 +358,8 @@ export declare function defineConfig(config: ChangesetConfig): ChangesetConfig;
 export interface LoadChangesetConfigInput {
     cwd?: string;
     configFile?: string;
+    /** Tag format that replaces the tagFormat of the config, like from --tag-format. */
+    tagFormat?: string;
 }
 /**
  * Load and validate the repository's JavaScript wp-release configuration.

package/dist/changeset-config.js

@@ -138,7 +138,12 @@ export async function loadChangesetConfig(input = {}) {
         ? loaded.default
         : undefined;
     validateChangesetConfig(config, configFile);
-    return { config, file: configFile };
+    return {
+        config: input.tagFormat
+            ? { ...config, tagFormat: input.tagFormat }
+            : config,
+        file: configFile,
+    };
 }
 async function findConfigFile(cwd) {
     for (const fileName of CONFIG_FILES) {
@@ -171,6 +176,7 @@ function validateChangesetConfig(config, configFile) {
     }
     for (const [key, value] of Object.entries({
         baseBranch: candidate.baseBranch,
+        remote: candidate.remote,
         changesets: candidate.changesets,
         changelogInsertAfter: candidate.changelogInsertAfter,
         root: candidate.root,
@@ -268,10 +274,6 @@ function validateChangesetConfig(config, configFile) {
         if ('string' !== typeof group.glob || !group.glob.trim()) {
             throw new ValidationError(`wp-release config ${configFile} packages[${index}].glob must be a non-empty string.`);
         }
-        if ('string' !== typeof group.tagType &&
-            undefined !== group.tagType) {
-            throw new ValidationError(`wp-release config ${configFile} packages[${index}].tagType must be a string.`);
-        }
         if (undefined !== group.exclude &&
             (!Array.isArray(group.exclude) ||
                 group.exclude.some((item) => 'string' !== typeof item))) {

package/dist/changeset-packages.d.ts

@@ -9,8 +9,8 @@ export interface ConfiguredPackage extends ChangesetPackage {
     versionConfig: PackageVersionConfig;
 }
 /**
- * A discovered package of a group with deploy targets, which may have no
- * version configuration.
+ * A discovered package with the configuration of its group, without reading
+ * its version, which may have no version or deploy configuration.
  */
 export interface ConfiguredDeployPackage extends DeployPackage {
     group: ChangesetPackageGroup;
@@ -32,6 +32,16 @@ export interface ChangedPackages {
  * @throws {ValidationError} For a glob without matches or a duplicate package name.
  */
 export declare function discoverPackages(repository: ReleaseRepository, config: ChangesetConfig): Promise<ConfiguredPackage[]>;
+/**
+ * Find the packages of every package group, with or without a version or
+ * deploy configuration, without reading their versions.
+ *
+ * @param  repository Repository the packages are in.
+ * @param  config     Repository release configuration.
+ * @return Packages in the configured order.
+ * @throws {ValidationError} For a glob without matches or a duplicate package name.
+ */
+export declare function discoverConfiguredPackages(repository: ReleaseRepository, config: ChangesetConfig): Promise<ConfiguredDeployPackage[]>;
 /**
  * Find the packages of the package groups with deploy targets, including the
  * groups without a version configuration, without reading their versions.

package/dist/changeset-packages.js

@@ -22,12 +22,24 @@ export async function discoverPackages(repository, config) {
         const versionConfig = pkg.group.version;
         packages.push({
             ...pkg,
-            currentVersion: await readVersion(repository, pkg.directory, versionConfig.from, pkg.path, pkg.group.tagType),
+            currentVersion: await readVersion(repository, pkg.directory, versionConfig.from, pkg),
             versionConfig,
         });
     }
     return packages;
 }
+/**
+ * Find the packages of every package group, with or without a version or
+ * deploy configuration, without reading their versions.
+ *
+ * @param  repository Repository the packages are in.
+ * @param  config     Repository release configuration.
+ * @return Packages in the configured order.
+ * @throws {ValidationError} For a glob without matches or a duplicate package name.
+ */
+export async function discoverConfiguredPackages(repository, config) {
+    return findGroupPackages(repository, config, config.packages);
+}
 /**
  * Find the packages of the package groups with deploy targets, including the
  * groups without a version configuration, without reading their versions.

package/dist/changeset-release.d.ts

@@ -4,6 +4,8 @@ import { ReleaseRepository } from './release-repository.ts';
 export interface ChangesetRepository {
     cwd: string;
     configFile?: string;
+    /** Tag format that replaces the tagFormat of the config. */
+    tagFormat?: string;
 }
 export interface ChangesetReleaseOptions extends ChangesetRepository {
     /** Git runner, spawning git by default. */
@@ -71,7 +73,7 @@ export interface ChangesetTagResult {
     }>;
 }
 export interface ChangesetStatusOptions {
-    /** Base ref to diff against, origin/<baseBranch> by default. */
+    /** Base ref to diff against, <remote>/<baseBranch> by default. */
     since?: string;
     /** Whether to include uncommitted and untracked files, like before adding a changeset. */
     uncommitted?: boolean;
@@ -97,6 +99,7 @@ export interface ChangesetStatusResult {
 export declare class ChangesetRelease {
     readonly cwd: string;
     readonly configFile: string | undefined;
+    readonly tagFormat: string | undefined;
     readonly repository: ReleaseRepository;
     /**
      * @param options Repository root, config file and git runner.
@@ -134,7 +137,7 @@ export declare class ChangesetRelease {
      */
     version(options?: ChangesetVersionOptions): Promise<VersionChangesetsResult>;
     /**
-     * Create missing release tags, optionally pushing them to the origin
+     * Create missing release tags, optionally pushing them to the configured
      * remote. Each tag comes with the title and notes of its release, for a
      * workflow step to create the GitHub Release.
      *

package/dist/changeset-release.js

@@ -9,7 +9,7 @@ import { ValidationError } from "./errors.js";
 import { FileJournal } from "./file-journal.js";
 import { getPreviousTag, getReleaseNotes, getTagVersion, selectTagPackages, } from "./release-tags.js";
 import { ReleaseRepository } from "./release-repository.js";
-import { formatTag } from "./tag-format.js";
+import { DEFAULT_TAG_FORMAT, formatTag } from "./tag-format.js";
 import { verifyVersionTargets, writeVersion } from "./version-files.js";
 import { getPrereleaseVersion, getSnapshotVersion, isPrerelease, } from "./versions.js";
 const MISSING_CONFIG = 'No wp-release config found. Add wp-release.config.js or pass --config <path>.';
@@ -24,6 +24,7 @@ const MISSING_CONFIG = 'No wp-release config found. Add wp-release.config.js or
 export class ChangesetRelease {
     cwd;
     configFile;
+    tagFormat;
     repository;
     /**
      * @param options Repository root, config file and git runner.
@@ -31,6 +32,7 @@ export class ChangesetRelease {
     constructor(options) {
         this.cwd = options.cwd;
         this.configFile = options.configFile;
+        this.tagFormat = options.tagFormat;
         this.repository = new ReleaseRepository({
             cwd: options.cwd,
             runner: options.git,
@@ -144,7 +146,7 @@ export class ChangesetRelease {
         };
     }
     /**
-     * Create missing release tags, optionally pushing them to the origin
+     * Create missing release tags, optionally pushing them to the configured
      * remote. Each tag comes with the title and notes of its release, for a
      * workflow step to create the GitHub Release.
      *
@@ -163,7 +165,7 @@ export class ChangesetRelease {
             : selected;
         const results = [];
         const dryRun = options.dryRun || options.untagged;
-        const tagFormat = context.config.tagFormat ?? '{path}/{version}';
+        const tagFormat = context.config.tagFormat ?? DEFAULT_TAG_FORMAT;
         for (const pkg of packages) {
             const version = await getTagVersion(pkg, options.version);
             if (undefined !== options.version &&
@@ -196,7 +198,7 @@ export class ChangesetRelease {
         // tags when more than three are pushed at once.
         if (options.push && !dryRun) {
             for (const item of results.filter((result) => result.created)) {
-                await this.repository.pushTag(item.tag);
+                await this.repository.pushTag(item.tag, context.config.remote ?? 'origin');
             }
         }
         return {
@@ -216,7 +218,9 @@ export class ChangesetRelease {
         const { config, packages, plan } = await this.requireContext();
         const { changesets, releases } = plan;
         const since = options.since ??
-            (config.baseBranch ? `origin/${config.baseBranch}` : undefined);
+            (config.baseBranch
+                ? `${config.remote ?? 'origin'}/${config.baseBranch}`
+                : undefined);
         const changed = since
             ? await getChangedPackages(this.repository, packages, since, options.uncommitted)
             : { packages: [], filesByPackage: {} };
@@ -266,7 +270,7 @@ export class ChangesetRelease {
      * @throws {ValidationError} For an invalid pre-release or an existing version.
      */
     async toPrereleases(context, releases, prerelease) {
-        const tagFormat = context.config.tagFormat ?? '{path}/{version}';
+        const tagFormat = context.config.tagFormat ?? DEFAULT_TAG_FORMAT;
         return Promise.all(releases.map(async (release) => {
             const configured = context.packages.find((pkg) => pkg.name === release.package.name);
             const versions = configured
@@ -364,6 +368,7 @@ export class ChangesetRelease {
         const loaded = await loadChangesetConfig({
             cwd: this.cwd,
             ...(this.configFile ? { configFile: this.configFile } : {}),
+            ...(this.tagFormat ? { tagFormat: this.tagFormat } : {}),
         });
         if (!loaded) {
             return undefined;
@@ -429,6 +434,7 @@ export class ChangesetRelease {
         const loaded = await loadChangesetConfig({
             cwd: this.cwd,
             ...(this.configFile ? { configFile: this.configFile } : {}),
+            ...(this.tagFormat ? { tagFormat: this.tagFormat } : {}),
         });
         if (!loaded) {
             throw new ValidationError(MISSING_CONFIG);

package/dist/cli.js

@@ -43,6 +43,7 @@ const globalArgs = {
     json: { type: 'boolean' },
     'github-output': { type: 'boolean' },
     config: { type: 'string' },
+    'tag-format': { type: 'string' },
 };
 const globalOptions = `Global options:
   -h, --help               Show help for the command
@@ -55,7 +56,32 @@ const globalOptions = `Global options:
       --json               Print the result as JSON
       --github-output      Set the result as JSON to the "result" output of
                            the GitHub Actions step
-      --config <path>      Path to a JavaScript release config file`;
+      --config <path>      Path to a JavaScript release config file
+      --tag-format <format>
+                           Tag format with {name}, {path} and {version} that
+                           replaces the tagFormat of the config, like
+                           {path}/{version}`;
+/**
+ * Get the config file and the tag format from the global options.
+ *
+ * @param  values Parsed CLI values.
+ * @return The --config and --tag-format values.
+ * @throws {ValidationError} For an empty --config or --tag-format.
+ */
+function getConfigArgs(values) {
+    const configFile = getString(values, 'config');
+    const tagFormat = getString(values, 'tag-format');
+    if ('' === configFile?.trim()) {
+        throw new ValidationError('--config <path> must not be empty.');
+    }
+    if ('' === tagFormat?.trim()) {
+        throw new ValidationError('--tag-format <format> must not be empty.');
+    }
+    return {
+        ...(configFile ? { configFile } : {}),
+        ...(tagFormat ? { tagFormat } : {}),
+    };
+}
 /**
  * Get the top-level help text listing all commands.
  *
@@ -188,10 +214,7 @@ async function runCommand(command, args, io) {
             options: { ...globalArgs, ...command.options },
             allowPositionals: true,
         });
-        const configFile = getString(values, 'config');
-        if ('' === configFile?.trim()) {
-            throw new ValidationError('--config <path> must not be empty.');
-        }
+        const { configFile, tagFormat } = getConfigArgs(values);
         const githubOutputFile = getGitHubOutputFile(values);
         logger = new Logger({
             writer: createLogWriter(values, { stdout, stderr }),
@@ -208,6 +231,7 @@ async function runCommand(command, args, io) {
             positionals,
             cwd,
             ...(configFile ? { configFile } : {}),
+            ...(tagFormat ? { tagFormat } : {}),
             logger,
             ...(interactive
                 ? { terminal: { input: stdin, output: stdout } }
@@ -251,16 +275,16 @@ export async function execute(name, args, context) {
         options: { ...globalArgs, ...command.options },
         allowPositionals: true,
     });
-    const configFile = getString(values, 'config') ?? context.configFile;
-    if ('' === configFile?.trim()) {
-        throw new ValidationError('--config <path> must not be empty.');
-    }
+    const configArgs = getConfigArgs(values);
+    const configFile = configArgs.configFile ?? context.configFile;
+    const { tagFormat } = configArgs;
     // The command table is keyed by name, so the result matches CommandResults.
     return command.run({
         values,
         positionals,
         ...context,
         ...(configFile ? { configFile } : {}),
+        ...(tagFormat ? { tagFormat } : {}),
     });
 }
 /**

package/dist/commands/args.d.ts

@@ -1,5 +1,4 @@
 import type { ParseArgsOptionsConfig } from 'node:util';
-import type { FileRules } from '../file-selection.ts';
 import type { ParsedValues } from './command.ts';
 /**
  * Options shared by the commands that select files with .distignore and
@@ -40,26 +39,6 @@ export declare function checkDirectory(path: string): Promise<void>;
  * @return Whether the path is a directory.
  */
 export declare function isDirectory(path: string): Promise<boolean>;
-/**
- * Ignore a file that the command writes or reads, such as the checksums
- * manifest, when it's inside the selected directory.
- *
- * @param rules     Matcher from loadFileRules().
- * @param sourceDir Selected directory.
- * @param path      Absolute file path.
- * @return The same matcher.
- */
-export declare function ignoreOwnFile(rules: FileRules, sourceDir: string, path: string): FileRules;
-/**
- * Ignore the signature file that "wp-release sign" writes next to a file the
- * command writes, when it's inside the selected directory.
- *
- * @param rules     Matcher from loadFileRules().
- * @param sourceDir Selected directory.
- * @param path      Absolute path of the signed file.
- * @return The same matcher.
- */
-export declare function ignoreOwnSignature(rules: FileRules, sourceDir: string, path: string): FileRules;
 /**
  * Option for the source directory, which can also be the first positional
  * argument.