@jakobm/peacekeeper 0.12.1 → 0.13.0

package/README.md

@@ -44,27 +44,55 @@ Run `npm install` from the project root and commit the resulting `package-lock.j
 
 ### 2. `peacekeeper.config.json`
 
-Place this required file at the caller's Git root. All fields shown here are required and unknown fields are rejected. `git.checkpointPushRemotes`, `git.releaseMergeMethod`, `git.releaseRequiredChecks`, and `git.releaseTestWorkflow` are optional fields described below; release commands require `git.releaseRequiredChecks`. Optional `projectChecks` settings are described under local project checks. There are no built-in test-command defaults: each caller must define `tests.commands` explicitly for its own toolchain.
+Place this file at the caller's Git root. Every field, including nested fields,
+is required. Unknown fields and invalid values are rejected. If no file exists,
+Peacekeeper uses the complete bundled [defaults](scripts/project-config-defaults.json).
+The defaults contain no test commands; configure those before running tests or
+recording or reusing a test receipt.
+
+Run `peacekeeper update-config` to create the file or recursively fill missing
+fields from the defaults. Existing values, including empty arrays, are preserved.
+Review newly inserted values. Invalid JSON, unknown fields, or invalid existing
+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
+with missing field paths and a repair hint. Updates introducing new fields
+therefore require `peacekeeper update-config` before ordinary commands can run.
+
+Complete example:
 
 ```json
 {
   "git": {
     "remote": "origin",
     "defaultBranch": "main",
-    "branchPrefix": "codex/"
+    "branchPrefix": "codex/",
+    "checkpointPushRemotes": ["origin"],
+    "releaseMergeMethod": "merge",
+    "releaseRequiredChecks": ["test"],
+    "releaseTestWorkflow": "test.yml"
   },
   "tests": {
     "commands": ["eslint .", "node --test"],
     "receiptMaxAgeMinutes": 60,
     "npmTestUsesRunner": true
   },
-  "loggingDirectory": "tmp/logs"
+  "loggingDirectory": "tmp/logs",
+  "loggingEnabled": true,
+  "projectChecks": {
+    "testWorkflow": "test.yml",
+    "requiredJobs": ["test"]
+  }
 }
 ```
 
 `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.
 
-To publish checkpoint branches automatically, add `checkpointPushRemotes` to `git`:
+`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.
+
+To publish checkpoint branches automatically, set `git.checkpointPushRemotes` (fragment):
 
 ```json
 {
@@ -75,11 +103,9 @@ To publish checkpoint branches automatically, add `checkpointPushRemotes` to `gi
 }
 ```
 
-Each name must identify a Git remote configured in the calling repository. With this
-setting, checkpoints push to exactly those remotes, creating the task branch if
-needed. An empty list disables checkpoint pushes. When the field is omitted,
-checkpoints keep the previous behavior: push only when the branch already exists
-on `git.remote`. Pushes never use force. Only a push to `git.remote` sets the
+Each name must identify a Git remote configured in the calling repository. Checkpoints push to exactly those remotes, creating the task branch if
+needed. An empty list disables checkpoint pushes and is the bundled default.
+The field must be present; there is no implicit push fallback. Pushes never use force. Only a push to `git.remote` sets the
 branch's upstream. If a push fails, earlier pushes are kept and the checkpoint
 records a failure; fix the cause and rerun the checkpoint command to retry without
 creating another commit when there are no new changes.
@@ -167,7 +193,7 @@ The installed file contains these definitions (other existing hooks are retained
 }
 ```
 
-The commands resolve the package from the current Git worktree. Install dependencies in each worktree where the hooks will run; the commands need that worktree's `node_modules/@jakobm/peacekeeper`. The checkpoint hooks apply only to linked worktrees. `SessionStart` supplies the checkpoint instructions before work begins, including on resume, fork, and after compaction; no matcher is needed. `Stop` uses the same package-owned instructions as a fallback. You do not need to copy checkpoint rules into each project's `AGENTS.md`. Explicit user instructions not to commit or push take precedence: the agent must skip the checkpoint command when they conflict, even if `Stop` requests it. The hook checks Git state and cannot determine user intent itself. When uncommitted changes remain, the `Stop` hook asks the agent to review the diff and run `checkpoint-codex-changes` with a descriptive English commit message. That command stages all changes and commits them on a task branch; it refuses the configured default branch. With `git.checkpointPushRemotes`, it pushes without force to each listed remote, including new branches. Without that setting, it pushes only if the branch already exists on `git.remote`, otherwise the branch stays local.
+The commands resolve the package from the current Git worktree. Install dependencies in each worktree where the hooks will run; the commands need that worktree's `node_modules/@jakobm/peacekeeper`. The checkpoint hooks apply only to linked worktrees. `SessionStart` supplies the checkpoint instructions before work begins, including on resume, fork, and after compaction; no matcher is needed. `Stop` uses the same package-owned instructions as a fallback. You do not need to copy checkpoint rules into each project's `AGENTS.md`. Explicit user instructions not to commit or push take precedence: the agent must skip the checkpoint command when they conflict, even if `Stop` requests it. The hook checks Git state and cannot determine user intent itself. When uncommitted changes remain, the `Stop` hook asks the agent to review the diff and run `checkpoint-codex-changes` with a descriptive English commit message. That command stages all changes and commits them on a task branch; it refuses the configured default branch. With `git.checkpointPushRemotes`, it pushes without force to each listed remote, including new branches. An empty array keeps the branch local.
 
 `SessionEnd` starts a detached worker to clean up the session worktree and branch only if the captured branch tip is still unchanged and fully merged into the remote default branch. Dirty or locked worktrees are kept. Worker output is appended to `cleanup-ended-session.log` in the shared Git directory. Cleanup does not require the primary worktree to have the default branch checked out. A local default branch that can fast-forward is updated before cleanup: a branch not checked out in any worktree is moved atomically, while a checked-out branch is merged in its clean worktree so its files and index stay synchronized. A dirty or diverged default branch is left unchanged. Codex loads project hooks only after the project hook source is trusted; review them with `/hooks`. The three-second `SessionEnd` timeout is the maximum documented for that event. See the [Codex hooks reference](https://learn.chatgpt.com/docs/hooks) for hook loading, trust, and timeout behavior.
 
@@ -319,13 +345,13 @@ 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, optional `git.releaseMergeMethod` selects
+- 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.
-- Without a preference, merge commit is chosen first, then rebase.
+- The bundled preference is `"merge"`.
 
-For example, add `"releaseMergeMethod": "rebase"` inside the existing `git` object.
-A caller without a merge preference uses the same defaults.
+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.
 
@@ -371,9 +397,8 @@ publish job. Add `peacekeeper verify-release-protection` to a required PR
 test job and `peacekeeper verify-release` before publishing, with `GH_TOKEN`
 and `RELEASE_TAG` set for release verification. Both commands are shipped with
 the package; no verifier script or artifact upload needs to be copied.
-Set optional `git.releaseTestWorkflow` to the PR workflow filename (for this
-repository: `"test.yml"`). If omitted, verification uses the publish workflow
-filename for compatibility with combined workflows. All configured check names
+Set `git.releaseTestWorkflow` to the PR workflow filename (for this
+repository: `"test.yml"`). For combined workflows, explicitly set the publish workflow filename. All configured check names
 must be jobs in the selected PR workflow's run.
 The `publish` job must contain a step whose command is exactly `npm publish`.
 Its `if` can be omitted when the workflow triggers only on pushes of
@@ -381,3 +406,11 @@ Its `if` can be omitted when the workflow triggers only on pushes of
 For combined workflows or other triggers, the job must use the exact condition
 `${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }}`.
 Explicit alternative job conditions are not supported. Workspaces are not supported.
+
+Configuration migration: previously optional fields must now be declared. Run
+`peacekeeper update-config`, review the inserted defaults, and commit the result.
+In particular, set `git.checkpointPushRemotes` explicitly to retain automatic
+pushes. Empty `git.releaseRequiredChecks` is valid configuration but blocks release
+policy verification; empty `tests.commands` blocks test execution and receipts.
+`projectChecks` always explicitly selects the workflow and jobs. This change does
+not add online GitHub verification to `check-project`.

package/bin/peacekeeper.js

@@ -4,6 +4,7 @@ const { spawnSync } = require('node:child_process');
 const path = require('node:path');
 
 const COMMANDS = new Map([
+  ['update-config', 'Create or complete project configuration using bundled defaults.'],
   ['check-project', 'Validate local toolchain, hooks, CI and publication conventions.'],
   ['install-hooks', 'Install or update project Codex hooks while preserving other hooks.'],
   ['verify-release', 'Verify release versions, required CI and strict branch protection.'],
@@ -42,6 +43,9 @@ function main() {
     process.exitCode = 2;
     return;
   }
+  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 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.12.1",
+  "version": "0.13.0",
   "description": "Shared repository test, Git worktree, and Codex hook commands",
   "license": "MIT",
   "repository": {

package/scripts/check-project-requirements.txt

@@ -13,13 +13,16 @@ Purpose and scope
   --explain prints this entire document without loading or checking a project.
 
 Project configuration
-  A valid peacekeeper.config.json is required at the Git root, along with
-  package.json. The normal configuration schema still applies.
-
-  Select the PR workflow by filename, in this order:
-    projectChecks.testWorkflow -> git.releaseTestWorkflow -> test.yml
-  Select required job names in this order:
-    projectChecks.requiredJobs -> git.releaseRequiredChecks -> ["test"]
+  package.json is required at the Git root. Without peacekeeper.config.json,
+  bundled defaults apply. An existing configuration must declare every schema
+  field, including nested fields; unknown fields and invalid values fail.
+  Run peacekeeper update-config to create or complete it without overwriting
+  existing values. Review inserted defaults. Empty tests.commands blocks tests
+  and receipts. Help, --explain and update-config bypass completeness checking.
+
+  projectChecks.testWorkflow selects the PR workflow filename.
+  projectChecks.requiredJobs selects required job names.
+  Defaults are test.yml and ["test"], respectively.
   For published packages, git.releaseRequiredChecks is mandatory and its names
   are always added to the required jobs. Set git.releaseTestWorkflow to the
   selected PR workflow for release verification. Published projects cannot
@@ -34,8 +37,7 @@ Project configuration
       "testWorkflow": "package.yml",
       "requiredJobs": ["test"]
     }
-  projectChecks is optional; when present it requires both testWorkflow and
-  requiredJobs. Omit it when release settings already select the desired jobs.
+  projectChecks and both its fields are mandatory in an existing configuration.
 
 Toolchain: package.json and all Node-based CI jobs
   Pin exact versions in package.json with:

package/scripts/check-project.js

@@ -140,11 +140,11 @@ function checkProject(cwd = process.cwd()) {
   });
 
   const published = manifest.private !== true;
-  const filename = config.projectChecks?.testWorkflow || config.git.releaseTestWorkflow || 'test.yml';
-  const required = [...new Set([...(config.projectChecks?.requiredJobs || config.git.releaseRequiredChecks || ['test']), ...(published ? config.git.releaseRequiredChecks || [] : [])])];
+  const filename = config.projectChecks.testWorkflow;
+  const required = [...new Set([...(config.projectChecks.requiredJobs), ...(published ? config.git.releaseRequiredChecks : [])])];
   check('CI', () => {
     const workflow = workflows.get(filename);
-    if (!requireThat(workflow, `${filename}: configured PR workflow is missing (selected by ${config.projectChecks?.testWorkflow ? 'projectChecks.testWorkflow' : config.git.releaseTestWorkflow ? 'git.releaseTestWorkflow' : 'default test.yml'}). Set projectChecks.testWorkflow${published ? ' and git.releaseTestWorkflow to the same existing file' : ' to an existing file'} in peacekeeper.config.json. PR checks are blocked until it can be read.`)) return;
+    if (!requireThat(workflow, `${filename}: configured PR workflow is missing (selected by projectChecks.testWorkflow). Set projectChecks.testWorkflow${published ? ' and git.releaseTestWorkflow to the same existing file' : ' to an existing file'} in peacekeeper.config.json. PR checks are blocked until it can be read.`)) return;
     const on = workflow.on;
     const simpleTrigger = on === 'pull_request' || (Array.isArray(on) && on.includes('pull_request'));
     requireThat(simpleTrigger || (on && typeof on === 'object' && Object.hasOwn(on, 'pull_request')), `${filename}: declare an on.pull_request trigger.`);
@@ -179,7 +179,7 @@ function checkProject(cwd = process.cwd()) {
 
   if (published) check('publication', () => {
     requireThat(config.git.releaseRequiredChecks?.length, 'Configure git.releaseRequiredChecks for a published package.');
-    requireThat(!config.git.releaseTestWorkflow || config.git.releaseTestWorkflow === filename,
+    requireThat(config.git.releaseTestWorkflow === filename,
       'projectChecks.testWorkflow must match git.releaseTestWorkflow.');
     requireThat(semver.valid(manifest.version) === manifest.version && !semver.prerelease(manifest.version), 'package.json: published packages need an exact stable version.');
     requireThat(['package-lock.json', 'npm-shrinkwrap.json'].some(file => fs.existsSync(path.join(root, file))), 'Commit a package lockfile before publishing.');
@@ -205,7 +205,7 @@ function checkProject(cwd = process.cwd()) {
     const permissions = job.permissions || workflow.permissions;
     requireThat(permissions && permissions['id-token'] === 'write' && ['read', 'write'].includes(permissions.contents),
       `${publishing.path}: declare contents: read and id-token: write for publishing.`);
-    const selected = config.git.releaseTestWorkflow || path.basename(publishing.path);
+    const selected = config.git.releaseTestWorkflow;
     requireThat(selected === filename, 'Configure git.releaseTestWorkflow to select the checked PR workflow.');
   });
   return { errors, published };

package/scripts/check-test-receipt.js

@@ -2,7 +2,7 @@
 
 const fs = require('node:fs');
 const { ROOT, environmentFingerprint, receiptPath, snapshot } = require('./receipt-state');
-const { projectConfig } = require('./project-config');
+const { projectConfig, requireTestCommands } = require('./project-config');
 function successMessage(root = ROOT()) {
   const command = projectConfig(root).tests.npmTestUsesRunner
     ? 'npm test -- rerun'
@@ -20,6 +20,7 @@ function matchesReceipt(receipt, root = ROOT()) {
 }
 
 function checkReceipt(root = ROOT()) {
+  requireTestCommands(root);
   let receipt;
   try {
     receipt = JSON.parse(fs.readFileSync(receiptPath(root), 'utf8'));

package/scripts/checkpoint-codex-changes.js

@@ -176,14 +176,10 @@ function checkpoint(repositoryRoot, message, log = console.log) {
       return { committed: false, pushed: false };
     }
 
-    const pushRemotes = checkpointPushRemotes ?? (
-      remoteBranchExists(repositoryRoot, branch) ? [remote] : []
-    );
+    const pushRemotes = checkpointPushRemotes;
     if (pushRemotes.length === 0) {
       clearFailureMarker(repositoryRoot);
-      log(checkpointPushRemotes === undefined
-        ? `Kept ${branch} local because ${remote}/${branch} does not exist.`
-        : `Kept ${branch} local because checkpoint push is disabled.`);
+      log(`Kept ${branch} local because checkpoint push is disabled.`);
       return { committed: status !== '', pushed: false };
     }
 

package/scripts/checkpoint-codex-session-start.js

@@ -1,9 +1,8 @@
 #!/usr/bin/env node
 
-const fs = require('node:fs');
 const { checkpointInstructions } = require('./checkpoint-instructions');
 const { projectConfig } = require('./project-config');
-const { isPrimaryWorktree, logScriptInvocation } = require('./log-script-invocation');
+const { isPrimaryWorktree, runLoggedCheckpointHook } = require('./log-script-invocation');
 
 function buildResponse(event) {
   if (event?.hook_event_name !== 'SessionStart' || typeof event.cwd !== 'string') {
@@ -18,20 +17,8 @@ function buildResponse(event) {
   };
 }
 
-function main() {
-  logScriptInvocation();
-  const input = fs.readFileSync(0, 'utf8').trim();
-  process.stdout.write(`${JSON.stringify(buildResponse(input === '' ? null : JSON.parse(input)))}\n`);
-}
-
 if (require.main === module) {
-  try {
-    main();
-  } catch (error) {
-    process.stdout.write(`${JSON.stringify({
-      systemMessage: `Codex checkpoint instructions failed: ${error.message}`,
-    })}\n`);
-  }
+  runLoggedCheckpointHook(buildResponse, 'Codex checkpoint instructions failed');
 }
 
 module.exports = { buildResponse };

package/scripts/checkpoint-codex-stop.js

@@ -14,7 +14,7 @@ const { projectConfig } = require('./project-config');
 const { checkpointInstructions } = require('./checkpoint-instructions');
 const {
   isPrimaryWorktree,
-  logScriptInvocation,
+  runLoggedCheckpointHook,
 } = require('./log-script-invocation.js');
 
 function runGit(args, cwd) {
@@ -79,21 +79,8 @@ function buildResponse(event) {
   };
 }
 
-function main() {
-  logScriptInvocation();
-  const input = fs.readFileSync(0, 'utf8').trim();
-  const event = input === '' ? null : JSON.parse(input);
-  process.stdout.write(`${JSON.stringify(buildResponse(event))}\n`);
-}
-
 if (require.main === module) {
-  try {
-    main();
-  } catch (error) {
-    process.stdout.write(`${JSON.stringify({
-      systemMessage: `Codex checkpoint check failed: ${error.message}`,
-    })}\n`);
-  }
+  runLoggedCheckpointHook(buildResponse, 'Codex checkpoint check failed');
 }
 
 module.exports = { buildResponse };

package/scripts/cleanup-ended-session.js

@@ -267,8 +267,9 @@ function runWorker(target) {
 }
 
 function launchWorker(target) {
-  const logPath = path.join(target.commonGitDirectory, 'cleanup-ended-session.log');
-  const logFile = fs.openSync(logPath, 'a');
+  const loggingEnabled = projectConfig(target.repositoryRoot).loggingEnabled !== false;
+  const logPath = loggingEnabled ? path.join(target.commonGitDirectory, 'cleanup-ended-session.log') : null;
+  const logFile = loggingEnabled ? fs.openSync(logPath, 'a') : 'ignore';
   const payload = Buffer.from(JSON.stringify(target)).toString('base64url');
   const child = spawn(process.execPath, [__filename, '--worker', payload], {
     cwd: target.repositoryRoot,
@@ -277,7 +278,7 @@ function launchWorker(target) {
   });
 
   child.unref();
-  fs.closeSync(logFile);
+  if (loggingEnabled) fs.closeSync(logFile);
   return { logPath, pid: child.pid };
 }
 

package/scripts/log-script-invocation.js

@@ -60,18 +60,49 @@ function logScriptInvocation(options = {}) {
   const date = options.date || new Date();
   const processId = options.processId || process.pid;
   const repositoryRoot = sourceRepositoryRoot(cwd);
-  const logDirectory = path.join(repositoryRoot, projectConfig(repositoryRoot).loggingDirectory);
+  const config = projectConfig(repositoryRoot);
+  if (config.loggingEnabled === false) return null;
+  const logDirectory = path.join(repositoryRoot, config.loggingDirectory);
   const scriptName = path.basename(argv[1] || 'unknown-script');
   const fileName = `${filesystemTimestamp(date)}-${scriptName}-${processId}.log`;
   const commandLine = argv.map(shellQuote).join(' ');
 
   fs.mkdirSync(logDirectory, { recursive: true });
   const logPath = path.join(logDirectory, fileName);
-  fs.writeFileSync(logPath, `${commandLine}\n`, { flag: 'wx' });
+  fs.writeFileSync(logPath, `${commandLine}\n${JSON.stringify({ cwd })}\n`, { flag: 'wx' });
   return logPath;
 }
 
+// Only allowlisted event fields are recorded; hook payloads can contain user content.
+function runLoggedCheckpointHook(buildResponse, errorPrefix) {
+  let logPath;
+  let event;
+  let response;
+  try {
+    logPath = logScriptInvocation();
+    const input = fs.readFileSync(0, 'utf8').trim();
+    event = input === '' ? null : JSON.parse(input);
+    const details = {
+      hookEventName: event?.hook_event_name,
+      eventCwd: event?.cwd,
+      source: event?.source,
+      stopHookActive: event?.stop_hook_active,
+    };
+    if (logPath) fs.appendFileSync(logPath, `${JSON.stringify({ event: details })}\n`);
+    if (typeof event?.cwd === 'string') {
+      const primaryWorktree = isPrimaryWorktree(event.cwd);
+      if (logPath) fs.appendFileSync(logPath, `${JSON.stringify({ primaryWorktree })}\n`);
+    }
+    response = buildResponse(event);
+  } catch (error) {
+    response = { systemMessage: `${errorPrefix}: ${error.message}` };
+  }
+  if (logPath) fs.appendFileSync(logPath, `${JSON.stringify({ response })}\n`);
+  process.stdout.write(`${JSON.stringify(response)}\n`);
+}
+
 module.exports = {
+  runLoggedCheckpointHook,
   filesystemTimestamp,
   isPrimaryWorktree,
   logScriptInvocation,

package/scripts/project-config-defaults.json

@@ -0,0 +1,26 @@
+{
+  "git": {
+    "remote": "origin",
+    "defaultBranch": "main",
+    "branchPrefix": "codex/",
+    "checkpointPushRemotes": [],
+    "releaseMergeMethod": "merge",
+    "releaseRequiredChecks": [
+      "test"
+    ],
+    "releaseTestWorkflow": "test.yml"
+  },
+  "tests": {
+    "commands": [],
+    "receiptMaxAgeMinutes": 60,
+    "npmTestUsesRunner": false
+  },
+  "loggingEnabled": true,
+  "loggingDirectory": "tmp/logs",
+  "projectChecks": {
+    "testWorkflow": "test.yml",
+    "requiredJobs": [
+      "test"
+    ]
+  }
+}

package/scripts/project-config.js

@@ -11,15 +11,29 @@ function repositoryRoot(cwd = process.cwd()) {
   }).trim();
 }
 
-function requireExactKeys(value, keys, location, file, optionalKeys = []) {
+// Kept independent of the defaults so additions require an explicit default.
+const CONFIG_SCHEMA = {
+  git: { remote: true, defaultBranch: true, branchPrefix: true,
+    checkpointPushRemotes: true, releaseMergeMethod: true,
+    releaseRequiredChecks: true, releaseTestWorkflow: true },
+  tests: { commands: true, receiptMaxAgeMinutes: true, npmTestUsesRunner: true },
+  loggingDirectory: true,
+  loggingEnabled: true,
+  projectChecks: { testWorkflow: true, requiredJobs: true },
+};
+
+function validateShape(value, schema, location, errors) {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-    throw new Error(`${file}: ${location} must be an object`);
+    errors.push(`${location} must be an object`);
+    return;
   }
   for (const key of Object.keys(value)) {
-    if (!keys.includes(key) && !optionalKeys.includes(key)) throw new Error(`${file}: unknown field ${location}.${key}`);
+    if (!Object.hasOwn(schema, key)) errors.push(`unknown field ${location}.${key}`);
   }
-  for (const key of keys) {
-    if (!Object.hasOwn(value, key)) throw new Error(`${file}: missing field ${location}.${key}`);
+  for (const [key, child] of Object.entries(schema)) {
+    const name = location === 'config' ? key : `${location}.${key}`;
+    if (!Object.hasOwn(value, key)) errors.push(`missing field ${name}`);
+    else if (child !== true) validateShape(value[key], child, name, errors);
   }
 }
 
@@ -30,51 +44,44 @@ function requireNonemptyString(value, location, file) {
 }
 
 function validateConfig(config, file) {
-  requireExactKeys(config, ['git', 'tests', 'loggingDirectory'], 'config', file, ['projectChecks']);
-  if (Object.hasOwn(config, 'projectChecks')) {
-    requireExactKeys(config.projectChecks, ['testWorkflow', 'requiredJobs'], 'projectChecks', file);
-    if (typeof config.projectChecks.testWorkflow !== 'string' || !/^[A-Za-z0-9_-]+\.ya?ml$/u.test(config.projectChecks.testWorkflow)) {
-      throw new Error(`${file}: projectChecks.testWorkflow must be a workflow filename`);
-    }
-    const jobs = config.projectChecks.requiredJobs;
-    if (!Array.isArray(jobs) || !jobs.length || jobs.some(job => typeof job !== 'string' || !job.trim() || job !== job.trim()) || new Set(jobs).size !== jobs.length) {
-      throw new Error(`${file}: projectChecks.requiredJobs must contain unique nonempty job names`);
-    }
-  }
-  requireExactKeys(config.git, ['remote', 'defaultBranch', 'branchPrefix'], 'git', file, ['checkpointPushRemotes', 'releaseMergeMethod', 'releaseRequiredChecks', 'releaseTestWorkflow']);
-  requireExactKeys(config.tests, ['commands', 'receiptMaxAgeMinutes', 'npmTestUsesRunner'], 'tests', file);
+  const errors = [];
+  validateShape(config, CONFIG_SCHEMA, 'config', errors);
+  if (errors.length) throw new Error(`${file}: ${errors.join('; ')}. Run peacekeeper update-config to add missing fields.`);
+  if (typeof config.projectChecks.testWorkflow !== 'string' || !/^[A-Za-z0-9_-]+\.ya?ml$/u.test(config.projectChecks.testWorkflow)) {
+    throw new Error(`${file}: projectChecks.testWorkflow must be a workflow filename`);
+  }
+  const jobs = config.projectChecks.requiredJobs;
+  if (!Array.isArray(jobs) || jobs.some(job => typeof job !== 'string' || !job.trim() || job !== job.trim()) || new Set(jobs).size !== jobs.length) {
+    throw new Error(`${file}: projectChecks.requiredJobs must contain unique nonempty job names`);
+  }
 
   for (const field of ['remote', 'defaultBranch', 'branchPrefix']) {
     requireNonemptyString(config.git[field], `git.${field}`, file);
   }
-  if (Object.hasOwn(config.git, 'checkpointPushRemotes')) {
-    const remotes = config.git.checkpointPushRemotes;
-    if (!Array.isArray(remotes)
-        || remotes.some((remote) => typeof remote !== 'string' || remote.trim() === ''
-          || remote !== remote.trim() || remote.startsWith('-'))
-        || new Set(remotes).size !== remotes.length) {
-      throw new Error(`${file}: git.checkpointPushRemotes must be an array of unique remote names`);
-    }
-  }
-  if (Object.hasOwn(config.git, 'releaseTestWorkflow')) {
-    if (typeof config.git.releaseTestWorkflow !== 'string' || !/^[A-Za-z0-9_-]+\.ya?ml$/u.test(config.git.releaseTestWorkflow)) {
-      throw new Error(`${file}: git.releaseTestWorkflow must be a workflow filename ending in .yml or .yaml`);
-    }
-  }
-  if (Object.hasOwn(config.git, 'releaseRequiredChecks')) {
-    const checks = config.git.releaseRequiredChecks;
-    if (!Array.isArray(checks) || !checks.length || checks.some(check => typeof check !== 'string' || !check.trim() || check !== check.trim()) || new Set(checks).size !== checks.length) {
-      throw new Error(`${file}: git.releaseRequiredChecks must be a nonempty array of unique check names`);
-    }
-  }
-  if (Object.hasOwn(config.git, 'releaseMergeMethod')
-      && !['merge', 'squash', 'rebase'].includes(config.git.releaseMergeMethod)) {
+  const remotes = config.git.checkpointPushRemotes;
+  if (!Array.isArray(remotes)
+      || remotes.some((remote) => typeof remote !== 'string' || remote.trim() === ''
+        || remote !== remote.trim() || remote.startsWith('-'))
+      || new Set(remotes).size !== remotes.length) {
+    throw new Error(`${file}: git.checkpointPushRemotes must be an array of unique remote names`);
+  }
+  if (typeof config.git.releaseTestWorkflow !== 'string' || !/^[A-Za-z0-9_-]+\.ya?ml$/u.test(config.git.releaseTestWorkflow)) {
+    throw new Error(`${file}: git.releaseTestWorkflow must be a workflow filename ending in .yml or .yaml`);
+  }
+  const checks = config.git.releaseRequiredChecks;
+  if (!Array.isArray(checks) || checks.some(check => typeof check !== 'string' || !check.trim() || check !== check.trim()) || new Set(checks).size !== checks.length) {
+    throw new Error(`${file}: git.releaseRequiredChecks must be an array of unique check names`);
+  }
+  if (!['merge', 'squash', 'rebase'].includes(config.git.releaseMergeMethod)) {
     throw new Error(`${file}: git.releaseMergeMethod must be merge, squash, or rebase`);
   }
+  if (typeof config.loggingEnabled !== 'boolean') {
+    throw new Error(`${file}: loggingEnabled must be a boolean`);
+  }
   requireNonemptyString(config.loggingDirectory, 'loggingDirectory', file);
-  if (!Array.isArray(config.tests.commands) || config.tests.commands.length === 0
+  if (!Array.isArray(config.tests.commands)
       || config.tests.commands.some((command) => typeof command !== 'string' || command.trim() === '')) {
-    throw new Error(`${file}: tests.commands must be a nonempty array of command strings`);
+    throw new Error(`${file}: tests.commands must be an array of command strings`);
   }
   if (!Number.isSafeInteger(config.tests.receiptMaxAgeMinutes)
       || config.tests.receiptMaxAgeMinutes < 1) {
@@ -88,12 +95,17 @@ function validateConfig(config, file) {
 function projectConfig(cwd = process.cwd()) {
   const root = repositoryRoot(cwd);
   const file = path.join(root, CONFIG_FILE);
-  if (!fs.existsSync(file)) {
-    throw new Error(`${file}: configuration file is required; define tests.commands explicitly`);
-  }
-  const config = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const config = fs.existsSync(file)
+    ? JSON.parse(fs.readFileSync(file, 'utf8'))
+    : structuredClone(require('./project-config-defaults.json'));
   validateConfig(config, file);
   return { root, ...config };
 }
 
-module.exports = { CONFIG_FILE, projectConfig, repositoryRoot };
+function requireTestCommands(root) {
+  if (!projectConfig(root).tests.commands.length) {
+    throw new Error('Configure tests.commands before running tests or using a test receipt.');
+  }
+}
+
+module.exports = { CONFIG_FILE, CONFIG_SCHEMA, validateConfig, projectConfig, repositoryRoot, requireTestCommands };

package/scripts/receipt-state.js

@@ -43,7 +43,7 @@ function fileFingerprint(root, relative) {
 
 function sharedScriptsFingerprint() {
   const hash = crypto.createHash('sha256');
-  for (const name of fs.readdirSync(__dirname).filter((file) => file.endsWith('.js')).sort()) {
+  for (const name of fs.readdirSync(__dirname).filter((file) => file.endsWith('.js') || file === 'project-config-defaults.json').sort()) {
     hash.update(name);
     hash.update('\0');
     hash.update(fs.readFileSync(path.join(__dirname, name)));

package/scripts/record-test-receipt.js

@@ -2,9 +2,11 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { requireTestCommands } = require('./project-config');
 const { ROOT, receiptPath, snapshot } = require('./receipt-state');
 
 function recordReceipt(root = ROOT(), testedSnapshot) {
+  requireTestCommands(root);
   const current = snapshot(root, testedSnapshot?.baseCommit);
   if (testedSnapshot && JSON.stringify(current) !== JSON.stringify(testedSnapshot)) {
     throw new Error('Files or environment changed while tests ran; rerun tests before recording a receipt.');

package/scripts/release-core.js

@@ -4,7 +4,7 @@ const os = require('node:os');
 const path = require('node:path');
 const yaml = require('yaml');
 const { githubApi, requiredChecks, verifyProtection } = require('./release-protection');
-const { CONFIG_FILE, projectConfig } = require('./project-config');
+const { projectConfig } = require('./project-config');
 const requiredCondition = "${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }}";
 const stableVersion = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u;
 const pollIntervalMs = 5_000;
@@ -223,13 +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 = fs.existsSync(path.join(cwd, CONFIG_FILE))
-        ? projectConfig(cwd).git.releaseMergeMethod : undefined;
+    const configured = projectConfig(cwd).git.releaseMergeMethod;
     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 || allowed[0];
+    const mergeMethod = allowed.length === 1 ? allowed[0] : configured;
     if (!allowed.includes(mergeMethod))
         throw new ReleaseError(`Configured release merge method ${mergeMethod} is not enabled on GitHub.`);
     const defaultBranch = repository.default_branch;

package/scripts/run-tests.js

@@ -4,7 +4,7 @@ const { spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const { checkReceipt, successMessage } = require('./check-test-receipt');
 const { recordReceipt } = require('./record-test-receipt');
-const { projectConfig } = require('./project-config');
+const { projectConfig, requireTestCommands } = require('./project-config');
 const { receiptPath, snapshot } = require('./receipt-state');
 
 function run(command, root) {
@@ -23,6 +23,7 @@ function hasReusableReceipt() {
 }
 
 function main() {
+  requireTestCommands();
   const config = projectConfig();
   const force = process.argv.length === 3 && ['rerun', '--force'].includes(process.argv[2]);
   if (process.argv.length !== 2 && !force) {

package/scripts/update-config.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { isDeepStrictEqual } = require('node:util');
+const { CONFIG_FILE, repositoryRoot, validateConfig } = require('./project-config');
+
+function complete(value, defaults) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return value;
+  const result = { ...value };
+  for (const [key, fallback] of Object.entries(defaults)) {
+    if (!Object.hasOwn(value, key)) result[key] = structuredClone(fallback);
+    else if (fallback !== null && typeof fallback === 'object' && !Array.isArray(fallback)) {
+      result[key] = complete(value[key], fallback);
+    }
+  }
+  return result;
+}
+
+function updateConfig(cwd = process.cwd()) {
+  const file = path.join(repositoryRoot(cwd), CONFIG_FILE);
+  const defaults = require('./project-config-defaults.json');
+  validateConfig(defaults, 'bundled defaults');
+  const exists = fs.existsSync(file);
+  const original = exists ? JSON.parse(fs.readFileSync(file, 'utf8')) : {};
+  const updated = complete(original, defaults);
+  validateConfig(updated, file);
+  if (!exists || !isDeepStrictEqual(original, updated)) {
+    fs.writeFileSync(file, `${JSON.stringify(updated, null, 2)}\n`);
+    console.log(`Updated ${file}. Review defaults before using project commands.`);
+  } else console.log(`Configuration already complete: ${file}`);
+}
+if (require.main === module) {
+  try {
+    const args = process.argv.slice(2);
+    if (args.length === 1 && ['--help', '-h'].includes(args[0])) console.log('Usage: peacekeeper update-config');
+    else if (args.length) throw new Error('Usage: peacekeeper update-config');
+    else updateConfig();
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}
+module.exports = { updateConfig };

package/scripts/verify-release.js

@@ -17,9 +17,9 @@ try {
   const api = githubApi((command, args, options) => spawnSync(command, args, { ...options, encoding: 'utf8' }), cwd, host);
   const tag = process.env.RELEASE_TAG;
   const sha = execFileSync('git', ['rev-parse', 'HEAD'], { encoding: 'utf8' }).trim();
-  const publishWorkflow = inspectWorkflow(cwd, tag);
+  inspectWorkflow(cwd, tag);
   verifyRelease({ api, slug, sha, tag, branch: config.git.defaultBranch,
-    checks: requiredChecks(cwd), workflow: config.git.releaseTestWorkflow || path.basename(publishWorkflow.path) });
+    checks: requiredChecks(cwd), workflow: config.git.releaseTestWorkflow });
 } catch (error) {
   console.error(error.message);
   process.exitCode = 1;