@jakobm/peacekeeper 0.14.1 → 0.16.0

package/README.md

@@ -90,7 +90,7 @@ Complete example:
 }
 ```
 
-`git.remote` and `git.defaultBranch` identify the branch used for checkpointing and cleanup. `git.branchPrefix` names new task branches. `tests.commands` are complete shell commands, run in order from the caller's Git root; install any executables they use. The test runner stops on the first failure and records a receipt only after every command succeeds. `receiptMaxAgeMinutes` controls how long a receipt can be reused. Set `npmTestUsesRunner` to `true` only when the caller's `npm test` script invokes `peacekeeper run-tests`; this makes the rerun hint `npm test -- rerun`. Otherwise the hint uses the explicit package path. `loggingDirectory` stores hook invocation logs relative to the primary Git worktree's root.
+`git.remote` and `git.defaultBranch` identify the branch used for checkpointing and cleanup. `git.branchPrefix` names new task branches. `run-tests` always runs the local `check-project` validation first, even when reusing a test receipt. Explicit `check-project` invocations in `tests.commands` are rejected as redundant. The configured commands are complete shell commands, run in order from the caller's Git root; install any executables they use. The test runner stops on the first failure and records a receipt only after every command succeeds. `receiptMaxAgeMinutes` controls how long a receipt can be reused. Set `npmTestUsesRunner` to `true` only when the caller's `npm test` script invokes `peacekeeper run-tests`; this makes the rerun hint `npm test -- rerun`. Otherwise the hint uses the explicit package path. `loggingDirectory` stores hook invocation logs relative to the primary Git worktree's root.
 
 `loggingEnabled` has the bundled default `true`; set it to `false` to disable invocation logs and the background cleanup worker's log file. Existing logs are kept. The setting is read from the primary checkout's configuration, including for linked worktrees. SessionStart and Stop logs include the process and event working directories, event type, primary-checkout classification, and hook response or error. Only selected event fields are logged, never the full incoming payload. These logs require the Peacekeeper script to start; a missing Node.js executable or package must be diagnosed in Codex's own logs.
 
@@ -244,6 +244,9 @@ does not grant trust automatically.
 ## Check project conventions locally
 
 Run `peacekeeper check-project` to check the local project configuration.
+All projects must declare nonblank `author` and `repository` values in
+`package.json`. npm object forms are supported with nonblank `author.name`
+and `repository.url` strings.
 Run `peacekeeper check-project --explain` for the complete expected
 architecture, requirements, configuration examples, and verification limits.
 The command prints the bundled [formal requirements](scripts/check-project-requirements.txt),
@@ -284,8 +287,39 @@ from the organization are included. Merge queues are not currently an alternativ
 to this strict policy. Repositories must also enable **Automatically delete head
 branches** (`delete_branch_on_merge=true`).
 
+The default branch must require pull requests (zero required reviewer approvals
+is allowed), and only merge commits may be used. Either disable squash and rebase
+in repository settings, or restrict the default branch's pull-request ruleset to
+`allowed_merge_methods: ["merge"]`. Other branches are outside this policy.
+Required linear history and any applicable PR rule excluding merge commits fail
+verification. PR and strict-check rules must enforce the policy without bypass.
+Enable `allow_auto_merge` in repository settings: this permits opting in per PR;
+Peacekeeper never enables auto-merge on individual PRs.
+
+`check-project` makes no network requests. It runs implicitly before
+`tests.commands`, including when reusing a receipt, and checks that the configured
+PR workflow covers the default branch and runs `verify-release-protection` with `GH_TOKEN` after `npm ci` and
+before tests in a job listed in `git.releaseRequiredChecks`. The job and step must
+not skip verification or ignore failures. The online verifier then checks that
+all those configured check names are mandatory on GitHub, including its own job.
+For example, in a required `test` job:
+
+```yaml
+- run: npm ci
+- run: peacekeeper verify-release-protection
+  env:
+    GH_TOKEN: ${{ secrets.RELEASE_POLICY_TOKEN }}
+- run: npm test
+```
+
+This creates a local-to-CI chain: missing workflows are detected on the next local
+`npm test`; incorrect GitHub settings are detected on the next PR run. It is not
+continuous monitoring. Removing both CI and the local invocation prevents this
+chain from running. No central scheduled audit is required by this setup.
+
 The PR test job runs `peacekeeper verify-release-protection` before its tests.
-The command checks `GITHUB_BASE_REF`, or `git.defaultBranch` outside PR CI.
+The command reads the actual default branch from GitHub, regardless of the PR
+base. Other release commands require their configured branch to match it.
 `peacekeeper release` checks the default branch before preparing a release
 and again immediately before each merge attempt. Before publishing,
 `peacekeeper verify-release` checks the policy, matching package/tag/lockfile
@@ -347,19 +381,10 @@ not retain historical proof of the tested file tree if administrators change
 settings between CI and merge. Keep the `package.yml` filename unchanged: npm
 trusted publishing is configured for that workflow file.
 
-Release merge selection reads the calling repository's root
-`peacekeeper.config.json`, not the installed package's configuration:
-
-- If GitHub allows only one merge method, that method is used regardless of the preference.
-- If multiple methods are allowed, `git.releaseMergeMethod` selects
-  `"merge"` (merge commit), `"rebase"`, or `"squash"`. A configured method that
-  GitHub disallows causes the release to stop before creating a branch or PR.
-- The bundled preference is `"merge"`.
-
-For example, set `"releaseMergeMethod": "rebase"` inside the existing `git` object.
-A caller without a configuration file uses the bundled defaults.
-The chosen method is saved with release state and reused on retries; unfinished
-releases created by older versions retain their original squash behavior.
+Releases use merge commits on the default branch, including retries of legacy
+state without a merge method. Saved unfinished releases that explicitly select
+squash or rebase must be restarted. `git.releaseMergeMethod` remains accepted for
+configuration compatibility, but no longer selects the default-branch merge method.
 
 From a clean repository root, run `npm run release -- patch`, `minor`, or `major`.
 The command fetches the default branch and uses a temporary detached worktree to

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@jakobm/peacekeeper",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "description": "Shared repository test, Git worktree, and Codex hook commands",
   "license": "MIT",
+  "author": "Jakob Mattsson",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jakobmattsson/peacekeeper.git"
@@ -19,7 +20,6 @@
     "scripts/"
   ],
   "scripts": {
-    "pretest": "node bin/peacekeeper.js check-project",
     "test": "node bin/peacekeeper.js run-tests",
     "release": "node bin/peacekeeper.js release",
     "cleanup:branches": "node bin/peacekeeper.js cleanup-merged-branches",

package/scripts/check-project-requirements.txt

@@ -39,6 +39,13 @@ Project configuration
     }
   projectChecks and both its fields are mandatory in an existing configuration.
 
+Package metadata: all projects, including private packages
+  package.json must declare author and repository.
+  author must be a nonblank string or an object with a nonblank string name.
+  repository must be a nonblank string (including npm repository shorthand)
+  or an object with a nonblank string url. Whitespace-only values fail.
+  These checks validate presence, not repository reachability or author identity.
+
 Toolchain: package.json and all Node-based CI jobs
   Pin exact versions in package.json with:
     volta pin node@<exact-version> npm@<exact-version>
@@ -325,7 +332,31 @@ What a passing check does and does not establish
   online verification; verify-release handles the release checks it supports.
 
 Using this check in the test chain
-  Add "pretest": "peacekeeper check-project" to package.json, prepending it
-  to any existing pretest command. This also runs before cached test receipts
-  can skip the test runner. Putting the check only in tests.commands does not
-  guarantee it runs when a cached receipt is reused.
+  run-tests always runs check-project as an implicit first step before
+  tests.commands, including when a valid receipt skips the configured commands.
+  Explicit check-project invocations in tests.commands are rejected as redundant
+  because the runner always includes this step automatically. Supported direct
+  peacekeeper, npm exec, npx and node CLI forms are checked, including commands
+  separated by shell control operators. Failure stops the run and invalidates any
+  existing receipt. This check remains entirely local.
+
+Default-branch GitHub policy chain
+  The configured PR workflow must run verify-release-protection with step GH_TOKEN
+  after npm ci and before tests in at least one job in git.releaseRequiredChecks.
+  Verification must be unconditional and must not allow failure. The existing
+  required-job validation applies to that job and its dependencies.
+  This applies to private projects too; configure nonempty releaseRequiredChecks.
+
+  Online verification reads the actual GitHub default branch and requires PRs,
+  strict mandatory configured checks without bypass, and merge commits only.
+  Zero reviewer approvals is allowed. Enable repository allow_auto_merge; this
+  only offers per-PR opt-in and does not activate auto-merge for any PR.
+  Restrict merge methods either repository-wide (merge enabled, squash and rebase
+  disabled) or with a default-branch PR ruleset allowing only merge. Other branches
+  are not checked. Linear-history rules or PR rules excluding merge are errors.
+  Ruleset PR requirements, like status checks, require active rules without bypass.
+  Existing automatic head-branch deletion requirements still apply.
+
+  Missing CI is detected on the next local npm test. GitHub settings are checked
+  on the next PR run, before release merges and before publication. This is not
+  continuous monitoring and cannot run if both local checks and CI are removed.

package/scripts/check-project.js

@@ -40,6 +40,21 @@ function checkProject(cwd = process.cwd()) {
     try { action(); } catch (error) { errors.push(`[${category}] ${error.message}`); }
     finally { category = previous; }
   };
+  check('tests', () => {
+    const projectCheck = /(?:^|&&|\|\||;|\n)\s*(?:peacekeeper|npm\s+exec\s+--no\s+--\s+peacekeeper|npx\s+--no-install\s+peacekeeper|node\s+(?:\.\/)?(?:node_modules\/@jakobm\/peacekeeper\/)?bin\/peacekeeper\.js)\s+check-project(?=\s|$|;|&|\|)/u;
+    for (const [index, command] of config.tests.commands.entries()) {
+      requireThat(!projectCheck.test(command),
+        `tests.commands[${index}]: remove check-project; it is redundant because Peacekeeper always includes it automatically before the configured test commands, even when reusing a test receipt.`);
+    }
+  });
+  check('package', () => {
+    const nonblank = value => typeof value === 'string' && value.trim().length > 0;
+    requireThat(nonblank(manifest.author) || nonblank(manifest.author?.name),
+      'package.json: author must be a nonblank string or an object with a nonblank name.');
+    requireThat(nonblank(manifest.repository) || nonblank(manifest.repository?.url),
+      'package.json: repository must be a nonblank string or an object with a nonblank url.');
+  });
+
   const workflows = new Map();
   check('CI', () => {
     const directory = path.join(root, '.github/workflows');
@@ -153,6 +168,7 @@ function checkProject(cwd = process.cwd()) {
       && !['paths', 'paths-ignore', 'branches-ignore', 'types'].some(key => Object.hasOwn(filters, key))
       && (!filters.branches || (Array.isArray(filters.branches) && filters.branches.includes(config.git.defaultBranch)))),
     `${filename}: PR filters must include the default branch and must not skip required checks by path or event type.`);
+    let policyJobs = 0;
     const checked = new Set();
     function requiredJob(id, job, testsRequired) {
       if (!requireThat(job && typeof job === 'object', `${filename}/${id}: required job is missing; checks for this job are blocked.`)) return;
@@ -166,6 +182,9 @@ function checkProject(cwd = process.cwd()) {
       const steps = job.steps || [];
       const installed = steps.findIndex(step => directCommand(step, installCommand) && unconditional(step.if) && !step['continue-on-error']);
       const tested = steps.findIndex(step => directCommand(step, testCommand) && unconditional(step.if) && !step['continue-on-error']);
+      const policy = steps.findIndex(step => directCommand(step, /^(?:peacekeeper|npm exec --no -- peacekeeper|node (?:\.\/)?(?:node_modules\/@jakobm\/peacekeeper\/)?bin\/peacekeeper\.js) verify-release-protection$/u)
+        && unconditional(step.if) && !step['continue-on-error'] && step.env?.GH_TOKEN);
+      if (policy > installed && installed >= 0 && policy < tested && config.git.releaseRequiredChecks.includes(job.name || id)) policyJobs += 1;
       requireThat(installed >= 0 && tested > installed, `${filename}/${id}: run unconditional npm ci before npm test, npm run test:<name>, or npm pack --dry-run (without continue-on-error).`);
     }
     for (const name of required) {
@@ -175,6 +194,7 @@ function checkProject(cwd = process.cwd()) {
       checked.clear();
       requiredJob(...matching[0], true);
     }
+    requireThat(policyJobs > 0, `${filename}: a job in git.releaseRequiredChecks must run unconditional verify-release-protection with GH_TOKEN after npm ci and before tests.`);
   });
 
   if (published) check('publication', () => {
@@ -227,7 +247,7 @@ function main() {
   if (errors.length) {
     for (const error of errors) console.error(`FAIL ${error}`);
     process.exitCode = 1;
-  } else console.log(`Project checks passed: tools, hooks, CI${published ? ', publication' : ' (private package; publication skipped)'}.`);
+  } else console.log(`Project checks passed: package, tools, hooks, CI${published ? ', publication' : ' (private package; publication skipped)'}.`);
 }
 if (require.main === module) {
   try { main(); } catch (error) { console.error(`FAIL ${error.message}`); process.exitCode = 1; }

package/scripts/release-core.js

@@ -223,12 +223,12 @@ function prepare(exec, cwd, bump, log) {
     const remote = checked(exec, 'git', ['remote', 'get-url', 'origin'], cwd);
     const { host, slug } = originRepository(remote);
     const repository = github(exec, cwd, host, `repos/${slug}`, {});
-    const configured = projectConfig(cwd).git.releaseMergeMethod;
+    projectConfig(cwd);
     const allowed = ['merge', 'rebase', 'squash'].filter((method) =>
         repository[{ merge: 'allow_merge_commit', rebase: 'allow_rebase_merge', squash: 'allow_squash_merge' }[method]] === true);
     if (!allowed.length)
         throw new ReleaseError('No supported PR merge method is enabled.');
-    const mergeMethod = allowed.length === 1 ? allowed[0] : configured;
+    const mergeMethod = 'merge';
     if (!allowed.includes(mergeMethod))
         throw new ReleaseError(`Configured release merge method ${mergeMethod} is not enabled on GitHub.`);
     const defaultBranch = repository.default_branch;
@@ -374,10 +374,11 @@ async function mergeRelease(exec, cwd, details, now, sleep, log) {
             throw new ReleaseError(`Release PR #${details.pr} has conflicts; inspect it before continuing.`);
         verifyProtection({ api: githubApi(exec, cwd, details.host), slug: details.slug,
             branch: details.defaultBranch, checks: requiredChecks(cwd) });
+        if (details.mergeMethod && details.mergeMethod !== 'merge') throw new ReleaseError('Release must use merge commits on the default branch; restart this release.');
         // GitHub enforces required checks, reviews, and branch freshness on this request.
         const result = exec('gh', ['api', '--hostname', details.host, '--method', 'PUT',
             `repos/${details.slug}/pulls/${details.pr}/merge`,
-            '-f', `merge_method=${details.mergeMethod || 'squash'}`, '-f', `sha=${details.sha}`], { cwd });
+            '-f', `merge_method=${details.mergeMethod || 'merge'}`, '-f', `sha=${details.sha}`], { cwd });
         if (result.status === 0) {
             const merged = JSON.parse(result.stdout);
             if (merged.merged)

package/scripts/release-protection.js

@@ -11,9 +11,12 @@ function requiredChecks(cwd) {
 // other API failures, including permission failures, must propagate.
 function verifyProtection({ api, slug, branch, checks }) {
   const base = `repos/${slug}`;
-  if (api(base)?.delete_branch_on_merge !== true) {
+  const repository = api(base);
+  if (repository?.delete_branch_on_merge !== true) {
     throw new Error(`Repository ${slug} must enable delete_branch_on_merge. Run gh api --method PATCH ${base} -F delete_branch_on_merge=true, then rerun.`);
   }
+  if (repository.allow_auto_merge !== true) throw new Error('Repository must enable allow_auto_merge; this only makes auto-merge available per PR.');
+  if (repository.default_branch !== branch) throw new Error(`Verify the actual default branch (${repository.default_branch}), not ${branch}.`);
   let protection;
   try {
     protection = api(`${base}/branches/${encodeURIComponent(branch)}/protection`);
@@ -27,6 +30,33 @@ function verifyProtection({ api, slug, branch, checks }) {
     rules.push(...batch);
     if (batch.length < 100) break;
   }
+  if (protection?.required_linear_history?.enabled || rules.some(rule => rule.type === 'required_linear_history')) {
+    throw new Error('Default branch must allow merge commits; disable required linear history.');
+  }
+  const pullRules = rules.filter(rule => rule.type === 'pull_request');
+  let requiresPullRequest = Boolean(protection?.required_pull_request_reviews && protection.enforce_admins?.enabled === true
+    && !(protection.required_pull_request_reviews.bypass_pull_request_allowances?.users?.length)
+    && !(protection.required_pull_request_reviews.bypass_pull_request_allowances?.teams?.length)
+    && !(protection.required_pull_request_reviews.bypass_pull_request_allowances?.apps?.length));
+  let branchMergeOnly = false;
+  const verifiedRulesets = new Set();
+  function verifyRuleset(rule) {
+    if (!Number.isInteger(rule.ruleset_id)) throw new Error('GitHub did not identify the policy ruleset.');
+    if (verifiedRulesets.has(rule.ruleset_id)) return;
+    const ruleset = api(`${base}/rulesets/${rule.ruleset_id}`);
+    if (ruleset.enforcement !== 'active' || !Array.isArray(ruleset.bypass_actors)) {
+      throw new Error('Cannot verify active ruleset bypass settings; grant write access to the ruleset so GitHub exposes bypass actors, then rerun.');
+    }
+    if (ruleset.bypass_actors.length) throw new Error('Default branch rulesets must not allow bypass actors.');
+    verifiedRulesets.add(rule.ruleset_id);
+  }
+  for (const rule of pullRules) {
+    verifyRuleset(rule);
+    requiresPullRequest = true;
+    const methods = rule.parameters?.allowed_merge_methods;
+    if (methods && !methods.includes('merge')) throw new Error('Default branch PR rules must allow merge commits.');
+    if (Array.isArray(methods) && methods.length === 1 && methods[0] === 'merge') branchMergeOnly = true;
+  }
   const strictChecks = new Set();
   const classic = protection?.required_status_checks;
   if (classic?.strict === true && protection.enforce_admins?.enabled === true) {
@@ -35,24 +65,20 @@ function verifyProtection({ api, slug, branch, checks }) {
   }
   // Ruleset bypass actors are not included in the effective-rules response.
   // Read every contributing ruleset and require that it has no bypass actors.
-  const checkedRulesets = new Set();
   for (const rule of rules.filter(rule => rule.type === 'required_status_checks')) {
     if (rule.parameters?.strict_required_status_checks_policy !== true) continue;
-    if (!Number.isInteger(rule.ruleset_id)) throw new Error('GitHub did not identify the status-check ruleset.');
-    if (!checkedRulesets.has(rule.ruleset_id)) {
-      const ruleset = api(`${base}/rulesets/${rule.ruleset_id}`);
-      if (ruleset.enforcement !== 'active' || !Array.isArray(ruleset.bypass_actors)) {
-        throw new Error('Cannot verify active ruleset bypass settings; grant write access to the ruleset so GitHub exposes bypass actors, then rerun.');
-      }
-      if (ruleset.bypass_actors.length) throw new Error('Strict release rulesets must not allow bypass actors.');
-      checkedRulesets.add(rule.ruleset_id);
-    }
+    verifyRuleset(rule);
     for (const check of rule.parameters.required_status_checks || []) strictChecks.add(check.context);
   }
   const missing = checks.filter(check => !strictChecks.has(check));
   if (!checks.length || missing.length) {
     throw new Error(`Branch ${branch} must require strict status checks without bypass for: ${missing.join(', ') || '(no checks configured)'}. Enable strict checks and enforce them for administrators, or use an active ruleset without bypass actors; then rerun.`);
   }
+  if (!requiresPullRequest) throw new Error('Default branch must require pull requests without bypass.');
+  if (repository.allow_merge_commit !== true || (!branchMergeOnly
+      && (repository.allow_squash_merge !== false || repository.allow_rebase_merge !== false))) {
+    throw new Error('Default branch must allow only merge commits: restrict its pull request ruleset to merge, or disable repository squash and rebase merging.');
+  }
 }
 
 function githubApi(exec, cwd, host) {

package/scripts/run-tests.js

@@ -31,6 +31,15 @@ function main() {
     process.exitCode = 2;
     return;
   }
+  const projectStatus = spawnSync(process.execPath, [require.resolve('./check-project.js')], {
+    cwd: config.root, stdio: 'inherit',
+  });
+  if (projectStatus.error) throw projectStatus.error;
+  if (projectStatus.status !== 0) {
+    fs.rmSync(receiptPath(config.root), { force: true });
+    process.exitCode = projectStatus.status ?? 1;
+    return;
+  }
   if (!force && !process.env.CI && hasReusableReceipt()) {
     console.log(successMessage(config.root));
     return;

package/scripts/verify-release-protection.js

@@ -12,7 +12,7 @@ try {
   if (remote.status !== 0) throw new Error(remote.stderr);
   const { host, slug } = originRepository(remote.stdout.trim());
   const api = githubApi((command, args, options) => spawnSync(command, args, { ...options, encoding: 'utf8' }), cwd, host);
-  verifyProtection({ api, slug, branch: process.env.GITHUB_BASE_REF || config.git.defaultBranch, checks: requiredChecks(cwd) });
+  verifyProtection({ api, slug, branch: api(`repos/${slug}`).default_branch, checks: requiredChecks(cwd) });
 } catch (error) {
   console.error(error.message);
   process.exitCode = 1;