@jakobm/peacekeeper 0.13.0 → 0.14.1

package/README.md

@@ -57,7 +57,9 @@ values cause failure without changing the file. Repeating the command on a
 complete valid file leaves it unchanged.
 
 All CLI commands validate configuration before executing, except help,
-`check-project --explain`, and `update-config`. An incomplete existing file fails
+`check-project --explain`, and `update-config`. Checkpoint hooks instead validate
+the event worktree configuration when the event requires instructions or a check.
+An incomplete existing file fails
 with missing field paths and a repair hint. Updates introducing new fields
 therefore require `peacekeeper update-config` before ordinary commands can run.
 
@@ -92,6 +94,8 @@ Complete example:
 
 `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.
 
+Checkpoint hook failures write the cause to stderr and exit with code 2 instead of reporting success. For `Stop`, this requests continued work under the Codex hook protocol. Invocation logging is advisory: a logging failure is reported on stderr, but the checkpoint instructions or check still run and retain their result. Behavior configuration comes from the event's worktree, while log settings come from the primary checkout. A logging warning alone does not change the exit code.
+
 To publish checkpoint branches automatically, set `git.checkpointPushRemotes` (fragment):
 
 ```json
@@ -277,7 +281,8 @@ with **Require branches to be up to date before merging** enabled. Classic branc
 protection must enforce checks for administrators too. Alternatively, active
 rulesets must require strict checks and have no bypass actors. Rules inherited
 from the organization are included. Merge queues are not currently an alternative
-to this strict policy.
+to this strict policy. Repositories must also enable **Automatically delete head
+branches** (`delete_branch_on_merge=true`).
 
 The PR test job runs `peacekeeper verify-release-protection` before its tests.
 The command checks `GITHUB_BASE_REF`, or `git.defaultBranch` outside PR CI.
@@ -291,8 +296,9 @@ jobs in its latest PR workflow run. Manual tags without that PR are rejected.
 API failures, missing permissions, and unverifiable rules stop the commands.
 The workflow expects a `RELEASE_POLICY_TOKEN` Actions secret, exposed to the
 commands as `GH_TOKEN`. Use a fine-grained PAT or GitHub App token with access to
-this repository and Administration read, Contents read, Pull requests read and
-Actions read permissions. GitHub only exposes ruleset bypass actors to callers
+this repository and Administration read, Contents read/write, Pull requests read and
+Actions read permissions. Contents write is required even to read merge-related
+settings such as `delete_branch_on_merge`. GitHub only exposes ruleset bypass actors to callers
 with write access to the ruleset; ruleset users must additionally grant that
 access (Administration write for repository rulesets, or the appropriate access
 for inherited organization rulesets). Missing bypass information also fails.
@@ -303,8 +309,8 @@ by executing fork code with `pull_request_target`.
 
 To set this up for this repository:
 
-1. Open the [token creation form with the required read permissions prefilled](https://github.com/settings/personal-access-tokens/new?name=peacekeeper-release-policy&target_name=jakobmattsson&expires_in=90&administration=read&contents=read&pull_requests=read&actions=read).
-   For repository rulesets, use the [form with Administration write instead](https://github.com/settings/personal-access-tokens/new?name=peacekeeper-release-policy&target_name=jakobmattsson&expires_in=90&administration=write&contents=read&pull_requests=read&actions=read)
+1. Open the [token creation form with the required permissions prefilled](https://github.com/settings/personal-access-tokens/new?name=peacekeeper-release-policy&target_name=jakobmattsson&expires_in=90&administration=read&contents=write&pull_requests=read&actions=read).
+   For repository rulesets, use the [form with Administration write instead](https://github.com/settings/personal-access-tokens/new?name=peacekeeper-release-policy&target_name=jakobmattsson&expires_in=90&administration=write&contents=write&pull_requests=read&actions=read)
    so GitHub exposes bypass actors. For another repository, change the resource
    owner. Select **Only select repositories**, choose `peacekeeper`, review
    the permissions and expiration, and generate the token. If the owner requires

package/bin/peacekeeper.js

@@ -45,7 +45,8 @@ function main() {
   }
   const informational = (args.length === 1 && ['--help', '-h'].includes(args[0]))
     || (command === 'check-project' && args.length === 1 && args[0] === '--explain');
-  if (command !== 'update-config' && !informational) require('../scripts/project-config').projectConfig();
+  const checkpointHook = ['checkpoint-codex-session-start', 'checkpoint-codex-stop'].includes(command);
+  if (command !== 'update-config' && !checkpointHook && !informational) require('../scripts/project-config').projectConfig();
   const script = path.resolve(__dirname, '..', 'scripts', `${command}.js`);
   const result = spawnSync(process.execPath, [script, ...args], {
     cwd: process.cwd(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jakobm/peacekeeper",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Shared repository test, Git worktree, and Codex hook commands",
   "license": "MIT",
   "repository": {

package/scripts/check-project-requirements.txt

@@ -184,6 +184,9 @@ Online release policy and GitHub token setup
   local declarations above. Use verify-release-protection to check the branch
   policy and verify-release before publishing to check the release itself.
 
+  Enable "Automatically delete head branches" (delete_branch_on_merge=true) in
+  the repository settings. The online release policy commands require it.
+
   Configure the default branch from git.defaultBranch with every exact job name
   in git.releaseRequiredChecks mandatory and "Require branches to be up to date
   before merging" enabled. Choose either:
@@ -197,7 +200,7 @@ Online release policy and GitHub token setup
   Create a fine-grained GitHub PAT or GitHub App installation token with access
   to this repository and these repository permissions:
     Administration: read
-    Contents: read
+    Contents: read/write
     Pull requests: read
     Actions: read
   For repository rulesets, Administration: write is additionally needed because

package/scripts/log-script-invocation.js

@@ -78,8 +78,18 @@ function runLoggedCheckpointHook(buildResponse, errorPrefix) {
   let logPath;
   let event;
   let response;
+  function log(action) {
+    try {
+      action();
+    } catch (error) {
+      process.stderr.write(`${errorPrefix}: logging failed: ${error.message}\n`);
+    }
+  }
+  log(() => { logPath = logScriptInvocation(); });
+  function record(value) {
+    if (logPath) log(() => fs.appendFileSync(logPath, `${JSON.stringify(value)}\n`));
+  }
   try {
-    logPath = logScriptInvocation();
     const input = fs.readFileSync(0, 'utf8').trim();
     event = input === '' ? null : JSON.parse(input);
     const details = {
@@ -88,16 +98,20 @@ function runLoggedCheckpointHook(buildResponse, errorPrefix) {
       source: event?.source,
       stopHookActive: event?.stop_hook_active,
     };
-    if (logPath) fs.appendFileSync(logPath, `${JSON.stringify({ event: details })}\n`);
+    record({ event: details });
     if (typeof event?.cwd === 'string') {
       const primaryWorktree = isPrimaryWorktree(event.cwd);
-      if (logPath) fs.appendFileSync(logPath, `${JSON.stringify({ primaryWorktree })}\n`);
+      record({ primaryWorktree });
     }
     response = buildResponse(event);
   } catch (error) {
-    response = { systemMessage: `${errorPrefix}: ${error.message}` };
+    const message = `${errorPrefix}: ${error.message}`;
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 2;
+    record({ error: message });
+    return;
   }
-  if (logPath) fs.appendFileSync(logPath, `${JSON.stringify({ response })}\n`);
+  record({ response });
   process.stdout.write(`${JSON.stringify(response)}\n`);
 }
 

package/scripts/release-protection.js

@@ -11,6 +11,9 @@ 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) {
+    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.`);
+  }
   let protection;
   try {
     protection = api(`${base}/branches/${encodeURIComponent(branch)}/protection`);
@@ -56,7 +59,7 @@ function githubApi(exec, cwd, host) {
   return endpoint => {
     const response = exec('gh', ['api', '--hostname', host, '--method', 'GET', endpoint], { cwd });
     if (response.status !== 0) {
-      const error = new Error(`Cannot verify GitHub release policy (${endpoint}): ${response.stderr?.trim() || 'API request failed'}. Grant the token Administration read, Contents read, Pull requests read and Actions read permissions, then rerun.`);
+      const error = new Error(`Cannot verify GitHub release policy (${endpoint}): ${response.stderr?.trim() || 'API request failed'}. Grant the token Administration read, Contents read/write, Pull requests read and Actions read permissions, then rerun.`);
       error.status = Number(/HTTP (\d{3})/u.exec(response.stderr || '')?.[1]);
       throw error;
     }