release-agent-skills 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-10-28
+
+### Added
+
+- `skip-signing.init.gradle.kts` and an `--unsigned-expected` flag for `inspect-artifacts.mjs` and `verify-signatures.mjs`, so check-only runs work on machines without signing keys when the keys live in CI. Missing signatures are then reported as warnings while POMs, sources, javadoc and KMP targets are still checked.
+
+### Changed
+
+- `check-credentials.mjs` reports whether gpg is installed and, without gpg, recommends the in-memory key setup.
+
+### Fixed
+
+- Check-only mode no longer writes `build/release-agent/state.json`, so a later run does not mistake a check for a release in progress.
+
 ## [0.1.0] - 2026-10-28
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "release-agent-skills",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "AI agent skills that publish libraries safely. v0.1: Maven Central through the Sonatype Central Portal, with pre-flight checks, approval gates and manual release by default.",
   "type": "module",
   "bin": {

package/skills/release-maven/SKILL.md

@@ -59,7 +59,7 @@ Settle two decisions before going on. Both appear as `warn` checks when they app
 1. **Release path** (`detect.releaseAutomation`). The project already publishes from CI. A local release would skip whatever else that workflow does (generated files, release assets, tags). Recommend `ci`: run phases 2 to 4 locally as checks, then trigger the workflow in phase 6. Use `local` only if the user chooses it.
 2. **Version strategy** (`detect.versionStrategy`). The committed version is a SNAPSHOT held in a Gradle property. Recommend `override`: leave the file alone and pass `-P<versionProperty>=<new>` to every Gradle command. The alternative is `file`: change the file in phase 3. With `override`, set `VERSION_ARG="-P<versionProperty>=<new>"`; otherwise `VERSION_ARG=""`.
 
-Save both: `state.mjs set releasePath=<ci|local> versionStrategy=<override|file> version=<new>`.
+In `manual` or `automatic` mode, save both: `state.mjs set releasePath=<ci|local> versionStrategy=<override|file> version=<new>`. In `check-only` mode, write no state at all, so that a later run does not mistake the check for a release in progress.
 
 ## Phase 2: Static pre-flight (no build)
 
@@ -98,7 +98,7 @@ node "$SKILL_DIR/../release-agent-shared/scripts/changelog.mjs" --version <new>
 ./gradlew build $VERSION_ARG
 REPO="$PWD/build/release-agent/repo-$(date +%Y%m%d-%H%M%S)"
 ./gradlew publishToMavenLocal $VERSION_ARG -Dmaven.repo.local="$REPO" --no-configuration-cache
-node "$SKILL_DIR/../release-agent-shared/scripts/state.mjs" set stagingRepo="$REPO"
+node "$SKILL_DIR/../release-agent-shared/scripts/state.mjs" set stagingRepo="$REPO"   # not in check-only
 node "$SKILL_DIR/scripts/inspect-artifacts.mjs" --repo "$REPO" --group <g> --version <v> --project .
 node "$SKILL_DIR/scripts/validate-pom.mjs" --repo "$REPO" --version <v>
 node "$SKILL_DIR/scripts/verify-signatures.mjs" --repo "$REPO" --version <v>
@@ -109,7 +109,12 @@ node "$SKILL_DIR/scripts/verify-signatures.mjs" --repo "$REPO" --version <v>
 - If the project already runs a narrower verification in CI (see the release workflow), prefer those tasks over `build`, which can be slow for KMP.
 - `inspect-artifacts.mjs` checks for a POM, main artifact, `-sources.jar`, `-javadoc.jar` and a `.asc` for each file. It also checks that every artifact expected from the build files is staged, and that every target referenced by a KMP root `.module` file is present.
 - `verify-signatures.mjs` checks every `.asc`, verifies with `gpg` when installed, and checks that the public key is on a supported keyserver.
-- If signing is skipped locally because the keys only exist in CI, `inspect-artifacts.mjs` and `verify-signatures.mjs` report missing `.asc` files. With release path `ci` that is expected; report it as such, not as a blocker.
+- **Keys only in CI.** When `check-credentials.mjs` found no signing setup and the release path is `ci` (or the mode is `check-only`), `publishToMavenLocal` fails with "no configured signatory" (errors.md E11). Stage without signing instead, and tell the user the staged files are unsigned on purpose:
+  ```sh
+  ./gradlew publishToMavenLocal $VERSION_ARG -Dmaven.repo.local="$REPO" --no-configuration-cache \
+    --init-script "$SKILL_DIR/scripts/skip-signing.init.gradle.kts"
+  ```
+  Then pass `--unsigned-expected` to `inspect-artifacts.mjs` and `verify-signatures.mjs`, so missing `.asc` files are reported as `warn`. POMs, sources, javadoc and KMP targets are still fully checked. Never use the init script or the flag with release path `local` or with any upload command.
 - In `check-only` mode, stop here and print a go/no-go table: one row per check, with the fix for every failure.
 
 ## Phase 5: Gate 1 (before upload)

package/skills/release-maven/errors.md

@@ -117,7 +117,8 @@ Each entry gives the cause, the fix, and the phase to rerun from. Propose the fi
 
 - **Match:** `Cannot perform signing task ... because it has no configured signatory`
 - **Cause:** Signing is required, but Gradle found none of the signing properties.
-- **Fix:** Configure one of the three setups in `reference/signing-setup.md`. Check the property names with `check-credentials.mjs`. With environment variables, confirm they are exported in the shell that runs Gradle and that the Gradle daemon was started after they were set (`./gradlew --stop` restarts it).
+- **Fix:** Configure one of the three setups in `reference/signing-setup.md`. Check the property names with `check-credentials.mjs`. If it reports `gpgInstalled: false`, use the in-memory key: it is the only setup that works without `gpg`.
+- **Check-only with keys only in CI:** this error is expected on a machine without keys. Stage with `--init-script "$SKILL_DIR/scripts/skip-signing.init.gradle.kts"` and pass `--unsigned-expected` to the checks (SKILL.md, Phase 4). With environment variables, confirm they are exported in the shell that runs Gradle and that the Gradle daemon was started after they were set (`./gradlew --stop` restarts it).
 - **Rerun from:** Phase 4
 
 ## E12 Cannot read the signing key

package/skills/release-maven/reference/signing-setup.md

@@ -38,6 +38,8 @@ Pick one. `check-credentials.mjs` reports which one it found, by property name o
 
 ### 1. In-memory key (recommended, works for local and CI)
 
+This is the only setup that needs no `gpg` on the machine that builds. Use it when `check-credentials.mjs` reports `gpgInstalled: false`. Exporting the key once requires `gpg` on some machine (or an existing CI secret holding the armored key).
+
 | Gradle property | Environment variable | Notes |
 |---|---|---|
 | `signingInMemoryKey` | `ORG_GRADLE_PROJECT_signingInMemoryKey` | ASCII-armored private key |

package/skills/release-maven/scripts/check-credentials.mjs

@@ -18,6 +18,15 @@ function usesGpgCmd(projectDir) {
   return dirs.some((d) => files.some((f) => existsSync(join(d, f)) && /useGpgCmd\s*\(/.test(readFileSync(join(d, f), 'utf8'))));
 }
 
+function gpgInstalled() {
+  try {
+    execFileSync('gpg', ['--version'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function gpgSecretKeyCount() {
   try {
     const out = execFileSync('gpg', ['--batch', '--list-secret-keys', '--with-colons'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
@@ -27,7 +36,7 @@ function gpgSecretKeyCount() {
   }
 }
 
-export function checkCredentials({ setup = 'any', projectDir = '.', env = process.env, home, gpgCount = gpgSecretKeyCount } = {}) {
+export function checkCredentials({ setup = 'any', projectDir = '.', env = process.env, home, gpgCount = gpgSecretKeyCount, hasGpg = gpgInstalled } = {}) {
   if (!['vanniktech', 'maven-publish', 'any'].includes(setup)) throw new UsageError(`Unknown setup "${setup}"`);
   const sources = credentialSources({ projectDir, env, home });
   const checks = [];
@@ -68,9 +77,14 @@ export function checkCredentials({ setup = 'any', projectDir = '.', env = proces
     if (count) signing.push(`gpg agent (useGpgCmd, ${count} secret key(s) in the local keyring)`);
     else checks.push(check('credentials.gpg', 'fail', 'The build uses useGpgCmd() but gpg has no secret keys or is not installed', { fix: 'See reference/signing-setup.md.' }));
   }
+  const gpg = hasGpg();
   checks.push(signing.length
     ? check('credentials.signing', 'pass', `Signing configured: ${signing.join('; ')}`)
-    : check('credentials.signing', 'fail', 'No signing configuration found', { fix: 'Configure one of the setups in reference/signing-setup.md (errors.md E11).' }));
+    : check('credentials.signing', 'fail', `No signing configuration found${gpg ? '' : ' (gpg is not installed)'}`, {
+      fix: gpg
+        ? 'Configure one of the setups in reference/signing-setup.md (errors.md E11).'
+        : 'Use the in-memory key setup (signingInMemoryKey, signingInMemoryKeyPassword); it needs no gpg on this machine. See reference/signing-setup.md (errors.md E11).',
+    }));
 
   // Secrets must not sit in files that are committed.
   for (const key of SECRET_KEYS) {
@@ -84,7 +98,7 @@ export function checkCredentials({ setup = 'any', projectDir = '.', env = proces
     }
   }
 
-  return result(checks, { keys: Object.values(report).map(({ key, found, source }) => ({ key, found, source })) });
+  return result(checks, { gpgInstalled: gpg, keys: Object.values(report).map(({ key, found, source }) => ({ key, found, source })) });
 }
 
 await runCli(import.meta.url, {

package/skills/release-maven/scripts/inspect-artifacts.mjs

@@ -15,7 +15,7 @@ function moduleTargets(dir, artifactId, version) {
   return [...new Set((meta.variants ?? []).map((v) => v['available-at']?.module).filter(Boolean))];
 }
 
-export function inspectArtifacts({ repo, group, version, expected = [] }) {
+export function inspectArtifacts({ repo, group, version, expected = [], unsignedExpected = false }) {
   const checks = [];
   const components = listComponents(repo, group, version);
   if (components.length === 0) {
@@ -52,9 +52,9 @@ export function inspectArtifacts({ repo, group, version, expected = [] }) {
     } else {
       checks.push(check(`artifacts.${artifactId}.files`, 'pass', `${artifactId}: POM, main artifact, sources and javadoc present`));
     }
-    checks.push(unsigned.length
-      ? check(`artifacts.${artifactId}.signatures`, 'fail', `${artifactId}: ${unsigned.length} file(s) without .asc: ${unsigned.join(', ')}`, { fix: 'Signing did not run for these files (errors.md E06).' })
-      : check(`artifacts.${artifactId}.signatures`, 'pass', `${artifactId}: every file has a .asc signature`));
+    if (!unsigned.length) checks.push(check(`artifacts.${artifactId}.signatures`, 'pass', `${artifactId}: every file has a .asc signature`));
+    else if (unsignedExpected) checks.push(check(`artifacts.${artifactId}.signatures`, 'warn', `${artifactId}: ${unsigned.length} file(s) unsigned, as expected: signing runs in CI`));
+    else checks.push(check(`artifacts.${artifactId}.signatures`, 'fail', `${artifactId}: ${unsigned.length} file(s) without .asc: ${unsigned.join(', ')}`, { fix: 'Signing did not run for these files (errors.md E06).' }));
 
     const targets = moduleTargets(dir, artifactId, version);
     const missingTargets = targets.filter((t) => !present.has(t));
@@ -83,10 +83,10 @@ function expectedFromProject(projectDir, group) {
 }
 
 await runCli(import.meta.url, {
-  usage: 'Usage: inspect-artifacts.mjs --repo <dir> --group <groupId> --version <version> [--project <dir>] [--expect a,b,c]',
-  options: { repo: { type: 'string' }, group: { type: 'string' }, version: { type: 'string' }, project: { type: 'string' }, expect: { type: 'string' } },
+  usage: 'Usage: inspect-artifacts.mjs --repo <dir> --group <groupId> --version <version> [--project <dir>] [--expect a,b,c] [--unsigned-expected]',
+  options: { repo: { type: 'string' }, group: { type: 'string' }, version: { type: 'string' }, project: { type: 'string' }, expect: { type: 'string' }, 'unsigned-expected': { type: 'boolean', default: false } },
 }, (v) => {
   required(v, 'repo', 'group', 'version');
   const expected = v.expect ? v.expect.split(',').map((s) => s.trim()).filter(Boolean) : v.project ? expectedFromProject(v.project, v.group) : [];
-  return inspectArtifacts({ repo: v.repo, group: v.group, version: v.version, expected });
+  return inspectArtifacts({ repo: v.repo, group: v.group, version: v.version, expected, unsignedExpected: v['unsigned-expected'] });
 });

package/skills/release-maven/scripts/skip-signing.init.gradle.kts

@@ -0,0 +1,8 @@
+// Gradle init script for check-only staging on a machine without signing keys,
+// for projects whose keys exist only in CI. It disables every Sign task, so the
+// staged artifacts have no .asc files. Never use it with an upload task.
+//
+// ./gradlew publishToMavenLocal --init-script <path to this file> ...
+allprojects {
+    tasks.withType<Sign>().configureEach { enabled = false }
+}

package/skills/release-maven/scripts/verify-signatures.mjs

@@ -57,7 +57,7 @@ export async function keyOnKeyserver(issuer, fetchImpl = fetch) {
   return servers;
 }
 
-export async function verifySignatures({ repo, version, useGpg = gpgAvailable(), checkKeyserver = true, fetchImpl = fetch, verify = gpgVerify }) {
+export async function verifySignatures({ repo, version, useGpg = gpgAvailable(), checkKeyserver = true, unsignedExpected = false, fetchImpl = fetch, verify = gpgVerify }) {
   const checks = [];
   const files = walk(repo).filter((f) => !isAuxiliary(basename(f)) && (!version || f.split(sep).includes(version)));
   if (files.length === 0) return result([check('signatures.files', 'fail', `No artifacts found in ${repo}`)]);
@@ -76,9 +76,10 @@ export async function verifySignatures({ repo, version, useGpg = gpgAvailable(),
       unreadable.push(`${relative(repo, f)}.asc (${err.message})`);
     }
   }
-  checks.push(unsigned.length
-    ? check('signatures.present', 'fail', `${unsigned.length} of ${files.length} file(s) have no .asc`, { files: unsigned.slice(0, 30), fix: 'errors.md E06.' })
-    : check('signatures.present', 'pass', `All ${files.length} file(s) have a .asc signature`));
+  if (!unsigned.length) checks.push(check('signatures.present', 'pass', `All ${files.length} file(s) have a .asc signature`));
+  else if (unsignedExpected) checks.push(check('signatures.present', 'warn', `${unsigned.length} of ${files.length} file(s) unsigned, as expected: signing runs in CI. Signatures are checked by the Portal on upload.`));
+  else checks.push(check('signatures.present', 'fail', `${unsigned.length} of ${files.length} file(s) have no .asc`, { files: unsigned.slice(0, 30), fix: 'errors.md E06.' }));
+  if (issuers.size === 0 && unreadable.length === 0) return result(checks, { fileCount: files.length, keys: [] });
   if (unreadable.length) checks.push(check('signatures.format', 'fail', `${unreadable.length} signature file(s) could not be parsed`, { files: unreadable.slice(0, 30) }));
   if (issuers.size > 1) checks.push(check('signatures.issuer', 'warn', `Files are signed by ${issuers.size} different keys`, { fix: 'Usually a mix of primary key and subkey, or two configured keys. See reference/signing-setup.md.' }));
 
@@ -115,9 +116,9 @@ export async function verifySignatures({ repo, version, useGpg = gpgAvailable(),
 }
 
 await runCli(import.meta.url, {
-  usage: 'Usage: verify-signatures.mjs --repo <dir> [--version <version>] [--no-gpg] [--no-keyserver]',
-  options: { repo: { type: 'string' }, version: { type: 'string' }, 'no-gpg': { type: 'boolean', default: false }, 'no-keyserver': { type: 'boolean', default: false } },
+  usage: 'Usage: verify-signatures.mjs --repo <dir> [--version <version>] [--no-gpg] [--no-keyserver] [--unsigned-expected]',
+  options: { repo: { type: 'string' }, version: { type: 'string' }, 'no-gpg': { type: 'boolean', default: false }, 'no-keyserver': { type: 'boolean', default: false }, 'unsigned-expected': { type: 'boolean', default: false } },
 }, (v) => {
   required(v, 'repo');
-  return verifySignatures({ repo: v.repo, version: v.version, useGpg: v['no-gpg'] ? false : gpgAvailable(), checkKeyserver: !v['no-keyserver'] });
+  return verifySignatures({ repo: v.repo, version: v.version, useGpg: v['no-gpg'] ? false : gpgAvailable(), checkKeyserver: !v['no-keyserver'], unsignedExpected: v['unsigned-expected'] });
 });