@jakobm/peacekeeper 0.17.0 → 0.18.0

package/README.md

@@ -6,6 +6,44 @@ The public npm package is `@jakobm/peacekeeper`; its CLI command is `peacekeeper
 Install it with `npm install --save-exact @jakobm/peacekeeper@<version>`, selecting
 a published version. Replace the example dependency pin below with that version.
 
+## Create a compliant TypeScript project
+
+`create-project` creates a minimal ESM TypeScript library in an existing, completely
+empty GitHub repository. The command version owns the generated project contract,
+all tool pins, and the exact `@jakobm/peacekeeper` development dependency. This
+command additionally requires Volta so generation and verification use those pins.
+
+```sh
+peacekeeper create-project \
+  --repository https://github.com/OWNER/REPOSITORY.git \
+  --directory /absolute/path/to/REPOSITORY \
+  --package-name @scope/REPOSITORY \
+  --author-name "Example Author" \
+  --author-email author@example.com \
+  --publish-to-npm true
+```
+
+All arguments are mandatory. Only `https://github.com/OWNER/REPOSITORY[.git]`
+URLs are accepted. The package basename must equal the repository name. Published
+packages must be scoped; private packages must be unscoped and use
+`--publish-to-npm false`.
+
+Before creating the destination, the command verifies that it does not exist and
+that the remote has no Git refs. It then installs dependencies, builds, typechecks,
+runs the complete Peacekeeper test and project checks, and (for published packages)
+tests the packed package from a temporary consumer. Only after every local check
+passes does it create one initial commit on `main` and push without force.
+
+An argument or preflight failure creates nothing. A later failure leaves the local
+directory for inspection but does not commit or push. A push failure leaves the
+verified local commit. Inspect or remove the directory before retrying.
+
+The generated executable `setup-github-config.sh` is deliberately not run by the
+generator. Run it afterwards and complete the manual checklist at its top. It
+configures applicable GitHub policy through `gh` and prompts for the separate
+`RELEASE_POLICY_TOKEN`. Published projects also document the manual npm trusted
+publishing setup; the generator never registers a publisher or publishes a package.
+
 When moving an existing project to Peacekeeper, update its dependency and lockfile,
 package scripts, and configuration filename together. Replace previous lifecycle
 hook commands with the definitions below before running `peacekeeper install-hooks`.

package/bin/peacekeeper.js

@@ -5,6 +5,7 @@ const path = require('node:path');
 
 const COMMANDS = new Map([
   ['update-config', 'Create or complete project configuration using bundled defaults.'],
+  ['create-project', 'Create and verify a compliant TypeScript library in an empty GitHub repository.'],
   ['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.'],
@@ -47,7 +48,7 @@ function main() {
   const informational = (args.length === 1 && ['--help', '-h'].includes(args[0]))
     || (command === 'check-project' && args.length === 1 && args[0] === '--explain');
   const checkpointHook = ['checkpoint-codex-session-start', 'checkpoint-codex-stop'].includes(command);
-  if (!['update-config', 'assess-release'].includes(command) && !checkpointHook && !informational) require('../scripts/project-config').projectConfig();
+  if (!['update-config', 'assess-release', 'create-project'].includes(command) && !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.17.0",
+  "version": "0.18.0",
   "description": "Shared repository test, Git worktree, and Codex hook commands",
   "license": "MIT",
   "author": "Jakob Mattsson",

package/scripts/create-project-core.js

@@ -0,0 +1,168 @@
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const { planHooks } = require('./install-hooks');
+
+const TOOLCHAIN = Object.freeze({
+  node: '22.14.0',
+  npm: '11.21.0',
+  typescript: '5.9.3',
+  nodeTypes: '24.10.0',
+});
+
+class UsageError extends Error {}
+
+function usage() {
+  return 'Usage: peacekeeper create-project --repository <https://github.com/owner/repo.git> --directory <path> --package-name <name> --author-name <name> --author-email <email> --publish-to-npm <true|false>\n';
+}
+
+function repositoryIdentity(repository) {
+  let url;
+  try { url = new URL(repository); } catch { throw new UsageError('--repository must be a valid GitHub HTTPS URL'); }
+  if (url.protocol !== 'https:' || url.hostname !== 'github.com' || url.username || url.password || url.port || url.search || url.hash) {
+    throw new UsageError('--repository must use https://github.com/owner/repo.git');
+  }
+  const match = /^\/([^/]+)\/([^/]+?)(?:\.git)?$/u.exec(url.pathname);
+  if (!match || !match[1] || !match[2] || match[1] === '.' || match[2] === '.') {
+    throw new UsageError('--repository must use https://github.com/owner/repo.git');
+  }
+  return { owner: match[1], repositoryName: match[2] };
+}
+
+function parseArguments(args) {
+  const names = ['repository', 'directory', 'package-name', 'author-name', 'author-email', 'publish-to-npm'];
+  const values = {};
+  for (let index = 0; index < args.length; index += 2) {
+    const flag = args[index];
+    const name = flag?.startsWith('--') ? flag.slice(2) : '';
+    if (!names.includes(name)) throw new UsageError(`Unknown argument: ${flag || '(missing)'}`);
+    if (Object.hasOwn(values, name)) throw new UsageError(`Duplicate argument: --${name}`);
+    if (index + 1 >= args.length || args[index + 1].startsWith('--')) throw new UsageError(`Missing value for --${name}`);
+    values[name] = args[index + 1];
+  }
+  const missing = names.filter(name => !Object.hasOwn(values, name));
+  if (missing.length) throw new UsageError(`Missing required argument${missing.length === 1 ? '' : 's'}: ${missing.map(name => `--${name}`).join(', ')}`);
+  const identity = repositoryIdentity(values.repository);
+  if (!values.directory.trim()) throw new UsageError('--directory must be nonempty');
+  if (!values['author-name'].trim()) throw new UsageError('--author-name must be nonempty');
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/u.test(values['author-email'])) throw new UsageError('--author-email must be a valid email address');
+  if (!['true', 'false'].includes(values['publish-to-npm'])) throw new UsageError('--publish-to-npm must be true or false');
+  const packageName = values['package-name'];
+  if (packageName.length > 214 || !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u.test(packageName)) {
+    throw new UsageError('--package-name must be a valid lowercase npm package name');
+  }
+  const published = values['publish-to-npm'] === 'true';
+  const scoped = packageName.startsWith('@');
+  if (published !== scoped) throw new UsageError(`--package-name must be ${published ? 'scoped' : 'unscoped'} when --publish-to-npm is ${published}`);
+  if (packageName.split('/').at(-1) !== identity.repositoryName) throw new UsageError('The package basename must exactly match the repository name');
+  return { repository: values.repository, directory: values.directory, packageName,
+    authorName: values['author-name'], authorEmail: values['author-email'], published, ...identity };
+}
+
+function commandRunner(command, args, options = {}) {
+  const result = spawnSync(command, args, { encoding: 'utf8', stdio: options.capture ? 'pipe' : 'inherit', ...options });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    const detail = options.capture ? (result.stderr || result.stdout || '').trim() : '';
+    throw new Error(`${command} ${args.join(' ')} failed${detail ? `: ${detail}` : ` with exit ${result.status}`}`);
+  }
+  return result.stdout || '';
+}
+
+function json(value) { return `${JSON.stringify(value, null, 2)}\n`; }
+function write(root, name, contents, mode = 0o644) {
+  const target = path.join(root, name);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, contents, { mode });
+}
+
+function workflow(published) {
+  return `name: Test\n\non:\n  pull_request:\n    branches: [main]\n\npermissions:\n  contents: read\n\njobs:\n  test:\n    runs-on: ubuntu-24.04\n    steps:\n      - uses: actions/checkout@v7\n      - uses: volta-cli/action@v5\n      - run: npm ci\n      - name: Verify strict release policy\n        env:\n          GH_TOKEN: \${{ secrets.RELEASE_POLICY_TOKEN }}\n        run: peacekeeper verify-release-protection\n      - run: npm test\n${published ? `\n  package:\n    name: Test package\n    runs-on: ubuntu-24.04\n    steps:\n      - uses: actions/checkout@v7\n      - uses: volta-cli/action@v5\n      - run: npm ci\n      - run: npm run test:package\n` : ''}`;
+}
+
+function publishWorkflow() {
+  return `name: Publish\n\non:\n  push:\n    tags: ['v*']\n\npermissions:\n  contents: read\n\njobs:\n  publish:\n    name: Publish to npm\n    runs-on: ubuntu-24.04\n    permissions:\n      contents: read\n      actions: read\n      pull-requests: read\n      id-token: write\n    steps:\n      - uses: actions/checkout@v7\n      - uses: volta-cli/action@v5\n        with:\n          registry-url: https://registry.npmjs.org\n      - run: npm ci\n      - name: Verify release\n        env:\n          GH_TOKEN: \${{ secrets.RELEASE_POLICY_TOKEN }}\n          RELEASE_TAG: \${{ github.ref_name }}\n        run: peacekeeper verify-release\n      - run: npm publish\n`;
+}
+
+function githubSetup({ owner, repositoryName, published }) {
+  const npm = published ? `# - Configure npm trusted publishing for GitHub repository ${owner}/${repositoryName} and workflow publish.yml.\n# - Confirm the npm package scope and access before the first release.\n` : '';
+  return `#!/usr/bin/env bash\n# Manual checklist:\n# - Run this script yourself after the initial project has been pushed.\n# - Create a fine-grained RELEASE_POLICY_TOKEN with the permissions documented by Peacekeeper.\n${npm}set -euo pipefail\n\nrepo=${owner}/${repositoryName}\ngh auth status\ngh repo view "$repo" >/dev/null\ngh api --method PATCH "repos/$repo" -f delete_branch_on_merge=true >/dev/null\ngh api --method PUT "repos/$repo/branches/main/protection" \\\n  -F required_status_checks.strict=true \\\n  -f 'required_status_checks.contexts[]=test' \\\n  -F enforce_admins=true \\\n  -F required_pull_request_reviews=null \\\n  -F restrictions=null >/dev/null\nprintf 'Paste RELEASE_POLICY_TOKEN for %s when prompted.\\n' "$repo"\ngh secret set RELEASE_POLICY_TOKEN --repo "$repo"\nprintf 'GitHub configuration completed for %s.\\n' "$repo"\n`;
+}
+
+function packageTest() {
+  return `'use strict';\nconst assert = require('node:assert/strict');\nconst { execFileSync } = require('node:child_process');\nconst fs = require('node:fs');\nconst os = require('node:os');\nconst path = require('node:path');\nconst root = path.resolve(__dirname, '..');\nconst output = JSON.parse(execFileSync('npm', ['pack', '--json'], { cwd: root, encoding: 'utf8' }));\nconst tarball = path.join(root, output[0].filename);\nconst consumer = fs.mkdtempSync(path.join(os.tmpdir(), 'package-consumer-'));\ntry {\n  fs.writeFileSync(path.join(consumer, 'package.json'), '{"type":"module"}\\n');\n  execFileSync('npm', ['install', '--ignore-scripts', tarball], { cwd: consumer, stdio: 'inherit' });\n  const value = execFileSync(process.execPath, ['--input-type=module', '--eval', "import { hello } from '\${PACKAGE_NAME}'; process.stdout.write(hello())"], { cwd: consumer, encoding: 'utf8' });\n  assert.equal(value, 'hello world');\n} finally {\n  fs.rmSync(consumer, { recursive: true, force: true });\n  fs.rmSync(tarball, { force: true });\n}\n`;
+}
+
+function generate(root, options) {
+  const version = require('../package.json').version;
+  const manifest = {
+    name: options.packageName, version: '0.1.0', description: `${options.repositoryName} TypeScript library`,
+    type: 'module', ...(options.published ? {} : { private: true }),
+    author: { name: options.authorName, email: options.authorEmail },
+    repository: { type: 'git', url: `git+${options.repository}` }, license: 'MIT',
+    engines: { node: '>=20' }, volta: { node: TOOLCHAIN.node, npm: TOOLCHAIN.npm },
+    main: './dist/index.js', types: './dist/index.d.ts', exports: { '.': { types: './dist/index.d.ts', import: './dist/index.js' } },
+    scripts: { build: 'tsc -p tsconfig.json', typecheck: 'tsc -p tsconfig.json --noEmit', test: 'peacekeeper run-tests', 'test:unit': 'node --test test/*.test.js',
+      ...(options.published ? { 'test:package': 'node scripts/test-package.cjs', release: 'peacekeeper release' } : {}) },
+    devDependencies: { '@jakobm/peacekeeper': version, '@types/node': TOOLCHAIN.nodeTypes, typescript: TOOLCHAIN.typescript },
+    ...(options.published ? { files: ['dist/'], publishConfig: { access: 'public', registry: 'https://registry.npmjs.org/' } } : {}),
+  };
+  write(root, 'package.json', json(manifest));
+  write(root, 'tsconfig.json', json({ compilerOptions: { target: 'ES2022', module: 'NodeNext', moduleResolution: 'NodeNext', rootDir: 'src', outDir: 'dist', declaration: true, strict: true, noUncheckedIndexedAccess: true }, include: ['src/**/*.ts'] }));
+  write(root, 'src/index.ts', "export function hello(): string {\n  return 'hello world';\n}\n");
+  write(root, 'test/index.test.js', `import assert from 'node:assert/strict';\nimport test from 'node:test';\nimport { hello } from '../dist/index.js';\ntest('public hello API', () => assert.equal(hello(), 'hello world'));\n`);
+  if (options.published) write(root, 'scripts/test-package.cjs', packageTest().replace('${PACKAGE_NAME}', options.packageName));
+  const defaults = structuredClone(require('./project-config-defaults.json'));
+  defaults.publishesToNpm = options.published;
+  defaults.tests.commands = ['npm run typecheck', 'npm run build', 'npm run test:unit', ...(options.published ? ['npm run test:package'] : [])];
+  defaults.tests.npmTestUsesRunner = true;
+  write(root, 'peacekeeper.config.json', json(defaults));
+  write(root, '.codex/hooks.json', json(planHooks({}).document));
+  const prefix = fs.readFileSync(path.join(__dirname, 'codex-setup-prefix.sh'), 'utf8');
+  write(root, '.codex/environments/environment.toml', `version = 1\nname = ${JSON.stringify(options.repositoryName)}\n\n[setup]\nscript = '''\n${prefix}'''\n`);
+  write(root, '.github/workflows/test.yml', workflow(options.published));
+  if (options.published) write(root, '.github/workflows/publish.yml', publishWorkflow());
+  write(root, '.gitignore', 'node_modules/\n*.tgz\ntmp/\n');
+  write(root, 'README.md', `# ${options.repositoryName}\n\nA TypeScript library generated by Peacekeeper.\n\n## API\n\n\`hello()\` returns \`"hello world"\`.\n`);
+  write(root, 'LICENSE', `MIT License\n\nCopyright (c) ${options.authorName}\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n`);
+  write(root, 'setup-github-config.sh', githubSetup(options), 0o755);
+}
+
+function createProject(options, dependencies = {}) {
+  const run = dependencies.run || commandRunner;
+  const voltaHome = process.env.VOLTA_HOME;
+  const volta = voltaHome && fs.existsSync(path.join(voltaHome, 'bin', 'volta'))
+    ? path.join(voltaHome, 'bin', 'volta') : 'volta';
+  const npm = args => run(volta, ['run', '--node', TOOLCHAIN.node, '--npm', TOOLCHAIN.npm, 'npm', ...args], { cwd: normalized });
+  const target = path.resolve(options.directory);
+  if (fs.existsSync(target)) throw new Error(`Destination already exists: ${target}`);
+  const parent = path.dirname(target);
+  let realParent;
+  try { realParent = fs.realpathSync(parent); } catch { throw new Error(`Destination parent does not exist: ${parent}`); }
+  const normalized = path.join(realParent, path.basename(target));
+  if (fs.existsSync(normalized)) throw new Error(`Destination already exists after path normalization: ${normalized}`);
+  const refs = run('git', ['ls-remote', options.repository], { capture: true }).trim();
+  if (refs) throw new Error('The repository is not empty; refusing to create a project');
+  fs.mkdirSync(normalized);
+  try {
+    run('git', ['init', '--initial-branch=main'], { cwd: normalized });
+    run('git', ['remote', 'add', 'origin', options.repository], { cwd: normalized });
+    generate(normalized, options);
+    npm(['install', '--ignore-scripts']);
+    npm(['run', 'build']);
+    npm(['run', 'typecheck']);
+    npm(['test']);
+    run('bash', ['-n', 'setup-github-config.sh'], { cwd: normalized });
+    if (run('git', ['ls-remote', options.repository], { capture: true }).trim()) throw new Error('The repository gained refs while the project was being created');
+    run('git', ['add', '--all'], { cwd: normalized });
+    run('git', ['-c', `user.name=${options.authorName}`, '-c', `user.email=${options.authorEmail}`, 'commit', '-m', 'Initial project'], { cwd: normalized });
+    run('git', ['push', '--set-upstream', 'origin', 'main:main'], { cwd: normalized });
+  } catch (error) {
+    throw new Error(`${error.message}. Inspect or remove ${normalized} before retrying.`);
+  }
+  return { directory: normalized, packageName: options.packageName };
+}
+
+module.exports = { TOOLCHAIN, UsageError, createProject, generate, parseArguments, repositoryIdentity, usage };

package/scripts/create-project.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+'use strict';
+
+const { createProject, parseArguments, usage, UsageError } = require('./create-project-core');
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+    process.stdout.write(usage());
+    return;
+  }
+  const options = parseArguments(args);
+  const result = createProject(options);
+  process.stdout.write(`Created ${result.packageName} at ${result.directory}\n`);
+  process.stdout.write(`Next: run ${result.directory}/setup-github-config.sh and complete its manual checklist.\n`);
+}
+
+main().catch(error => {
+  if (error instanceof UsageError) {
+    process.stderr.write(`${error.message}\n\n${usage()}`);
+    process.exitCode = 2;
+  } else {
+    process.stderr.write(`Error: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+});

package/scripts/receipt-state.js

@@ -7,9 +7,11 @@ const { repositoryRoot } = require('./project-config');
 
 const ROOT = repositoryRoot;
 const RECEIPT_DIRECTORY = 'peacekeeper-test-receipts';
+const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
 
 function git(root, args) {
-  return execFileSync('git', args, { cwd: root, maxBuffer: 10 * 1024 * 1024 });
+  return execFileSync('git', args, { cwd: root, maxBuffer: 10 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'] });
 }
 
 function pathsFromOutput(output) {
@@ -64,7 +66,15 @@ function environmentFingerprint() {
   });
 }
 
-function snapshot(root = ROOT(), baseCommit = git(root, ['rev-parse', 'HEAD']).toString('utf8').trim()) {
+function currentBase(root) {
+  try { return git(root, ['rev-parse', '--verify', 'HEAD']).toString('utf8').trim(); }
+  catch (error) {
+    if (error.status === 128) return EMPTY_TREE;
+    throw error;
+  }
+}
+
+function snapshot(root = ROOT(), baseCommit = currentBase(root)) {
   return {
     baseCommit,
     environment: environmentFingerprint(),