@kitschpatrol/shared-config 8.12.0 → 8.13.0

package/skills/ksc-update/scripts/production-engines.mjs

@@ -0,0 +1,119 @@
+/**
+ * Prints one sorted row per package in a `pnpm list --prod --depth Infinity
+ * --json` tree: the name, version, and declared `engines.node`, read from each
+ * installed `package.json` instead of trusting the list output. A dependency
+ * whose installed directory is missing, typically a platform-specific optional
+ * dependency not installed on this host, is reported with `installed: false`
+ * and the name and version from the list; review its engines from registry
+ * metadata.
+ *
+ * Usage: `node production-engines.mjs production-tree.json`
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import process from 'node:process'
+
+/**
+ * Narrows an unknown JSON value to a plain object.
+ *
+ * @param {unknown} value - Any parsed JSON value.
+ *
+ * @returns {value is Record<string, unknown>} Whether the value is a non-array
+ *   object.
+ */
+function isRecord(value) {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Returns the value when it is a string.
+ *
+ * @param {unknown} value - Any parsed JSON value.
+ *
+ * @returns {string | undefined} The string, or undefined for any other type.
+ */
+function asString(value) {
+	return typeof value === 'string' ? value : undefined
+}
+
+const inputPath = process.argv[2]
+if (inputPath === undefined) {
+	throw new Error('Usage: node production-engines.mjs <pnpm-list-json-file>')
+}
+
+/** @type {unknown} */
+const parsed = JSON.parse(readFileSync(inputPath, 'utf8'))
+if (!Array.isArray(parsed)) {
+	throw new TypeError(`Expected a JSON array from pnpm list in ${inputPath}`)
+}
+
+/** @type {Set<string>} */
+const visited = new Set()
+/** @type {Set<string>} */
+const rows = new Set()
+
+/**
+ * Records one tree entry and recurses into its production and optional
+ * dependencies, skipping subtrees already walked.
+ *
+ * @param {Record<string, unknown>} entry - A project or dependency node from
+ *   the pnpm list output.
+ */
+function visit(entry) {
+	const installedPath = asString(entry.path)
+	if (installedPath === undefined) {
+		const label = asString(entry.name) ?? asString(entry.version) ?? 'unnamed entry'
+		throw new Error(`Missing path property for ${label}`)
+	}
+
+	if (visited.has(installedPath)) {
+		return
+	}
+
+	visited.add(installedPath)
+
+	const manifestPath = join(installedPath, 'package.json')
+	if (existsSync(manifestPath)) {
+		/** @type {unknown} */
+		const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+		if (!isRecord(manifest)) {
+			throw new TypeError(`Expected an object in ${manifestPath}`)
+		}
+
+		const engines = isRecord(manifest.engines) ? manifest.engines : {}
+		rows.add(
+			JSON.stringify({
+				name: asString(manifest.name),
+				node: asString(engines.node),
+				version: asString(manifest.version),
+			}),
+		)
+	} else {
+		rows.add(
+			JSON.stringify({
+				installed: false,
+				name: asString(entry.name) ?? asString(entry.from),
+				version: asString(entry.version),
+			}),
+		)
+	}
+
+	for (const group of ['dependencies', 'optionalDependencies']) {
+		const children = entry[group]
+		if (isRecord(children)) {
+			for (const [name, child] of Object.entries(children)) {
+				if (isRecord(child)) {
+					visit({ name, ...child })
+				}
+			}
+		}
+	}
+}
+
+for (const root of parsed) {
+	if (isRecord(root)) {
+		visit(root)
+	}
+}
+
+process.stdout.write(`${[...rows].toSorted().join('\n')}\n`)

package/skills/ksc-update/scripts/release-age.mjs

@@ -0,0 +1,174 @@
+/**
+ * Release-age helpers for the exemption policy in configuration.md.
+ *
+ * `inventory` classifies every `minimumReleaseAgeExclude` entry in
+ * `pnpm-workspace.yaml` against the lockfile, the registry publish time, and
+ * the authored-package list, printing the policy action for each. Run it during
+ * Setup before the baseline install and again during step 6 cleanup.
+ *
+ * `new-versions` lists every package version present in the after-lockfile but
+ * not the before-lockfile that is under 24 hours old at the run start, with
+ * whether it is authored and when it becomes installable. Run it after each
+ * resolution to find authored versions that need an exact exemption and
+ * third-party versions that must not get one.
+ *
+ * Usage, from the workspace root:
+ *
+ * ```
+ * node release-age.mjs inventory [--workspace <file>] [--lockfile <file>] [--run-start <iso>] [--authored <file>]
+ * node release-age.mjs new-versions <before-lock> [after-lock] [--run-start <iso>] [--authored <file>]
+ * ```
+ *
+ * `--authored` defaults to `<run directory>/authored-packages.txt`, the
+ * comma-separated ownership list from Setup step 5. `--workspace` and
+ * `--lockfile` default to the files in the current directory; point them at
+ * saved copies to inspect another state without touching the repository. Output
+ * is JSON on stdout with a summary on stderr.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import process from 'node:process'
+import {
+	lockedPackages,
+	mapLimit,
+	MATURITY_MS,
+	publishTimes,
+	readYamlList,
+	runDirectory,
+	splitSpec,
+} from './lib.mjs'
+
+const [mode, ...rest] = process.argv.slice(2)
+/** @type {string[]} */
+const positional = []
+/** @type {Record<string, string>} */
+const options = {}
+for (let index = 0; index < rest.length; index++) {
+	const argument = rest[index] ?? ''
+	if (argument.startsWith('--')) {
+		options[argument.slice(2)] = rest[++index] ?? ''
+	} else {
+		positional.push(argument)
+	}
+}
+
+const runStart = options['run-start'] === undefined ? Date.now() : Date.parse(options['run-start'])
+if (Number.isNaN(runStart)) {
+	throw new TypeError(`Invalid --run-start value: ${options['run-start']}`)
+}
+
+const authoredPath = options.authored ?? join(runDirectory(), 'authored-packages.txt')
+if (!existsSync(authoredPath)) {
+	throw new Error(
+		`Authored package list not found at ${authoredPath}. Run Setup step 5 or pass --authored.`,
+	)
+}
+
+const LIST_SEPARATOR = /[\s,]+/v
+const RANGE_CHARACTERS = /[\s*<=>\|^~]/v
+const authored = new Set(
+	readFileSync(authoredPath, 'utf8')
+		.split(LIST_SEPARATOR)
+		.filter((name) => name !== ''),
+)
+
+/**
+ * @typedef {object} Age
+ * @property {boolean} authored - Whether kitschpatrol owns the package.
+ * @property {string} [installableAt] - When the version turns 24 hours old.
+ * @property {string} [published] - Registry publish time.
+ * @property {boolean} [young] - Under 24 hours old at the run start; undefined
+ *   when the publish time is unknown.
+ */
+
+/**
+ * Looks up a version's publish time and derived maturity facts.
+ *
+ * @param {string} name - Package name.
+ * @param {string} version - Exact version.
+ *
+ * @returns {Promise<Age>} The version's age facts.
+ */
+async function ageOf(name, version) {
+	const times = await publishTimes(name)
+	const published = times[version]
+	if (published === undefined) {
+		return { authored: authored.has(name) }
+	}
+
+	const publishedMs = Date.parse(published)
+	return {
+		authored: authored.has(name),
+		installableAt: new Date(publishedMs + MATURITY_MS).toISOString(),
+		published,
+		young: publishedMs > runStart - MATURITY_MS,
+	}
+}
+
+if (mode === 'inventory') {
+	const locked = lockedPackages(options.lockfile ?? 'pnpm-lock.yaml')
+	const lockedNames = Array.from(locked, (key) => splitSpec(key))
+	const entries = readYamlList(
+		options.workspace ?? 'pnpm-workspace.yaml',
+		'minimumReleaseAgeExclude',
+	)
+	const rows = await mapLimit(entries, 8, async (entry) => {
+		const spec = splitSpec(entry)
+		if (spec === undefined || RANGE_CHARACTERS.test(spec.version) || spec.version === '') {
+			const name = spec?.name ?? entry
+			return {
+				action: 'broad entry: rewrite as exact versions resolved from the lockfile',
+				entry,
+				lockedVersions: lockedNames
+					.filter((part) => part?.name === name)
+					.map((part) => part?.version),
+			}
+		}
+
+		const age = await ageOf(spec.name, spec.version)
+		const isLocked = locked.has(entry)
+		/** @type {string} */
+		let action
+		if (age.published === undefined) {
+			action = 'unknown version: check by hand'
+		} else if (!age.young) {
+			action = 'remove: at least 24 hours old'
+		} else if (age.authored) {
+			action = 'keep if installed or an accepted target'
+		} else if (isLocked) {
+			action = `keep only to avoid a downgrade; removable after ${age.installableAt}`
+		} else {
+			action = 'remove: young third-party version that is not locked'
+		}
+
+		return { action, entry, locked: isLocked, ...age }
+	})
+	process.stdout.write(`${JSON.stringify(rows, undefined, 2)}\n`)
+	for (const row of rows) {
+		process.stderr.write(`${row.entry}: ${row.action}\n`)
+	}
+} else if (mode === 'new-versions') {
+	const [beforePath, afterPath = 'pnpm-lock.yaml'] = positional
+	if (beforePath === undefined) {
+		throw new Error('Usage: node release-age.mjs new-versions <before-lock> [after-lock]')
+	}
+
+	const before = lockedPackages(beforePath)
+	const added = [...lockedPackages(afterPath).difference(before)]
+	const rows = await mapLimit(added, 8, async (key) => {
+		const spec = splitSpec(key)
+		const age = spec === undefined ? { authored: false } : await ageOf(spec.name, spec.version)
+		return { key, ...age }
+	})
+	const flagged = rows.filter((row) => row.young !== false)
+	process.stdout.write(`${JSON.stringify(flagged, undefined, 2)}\n`)
+	process.stderr.write(`${added.length} new versions, ${flagged.length} young or unknown\n`)
+	for (const row of flagged) {
+		const kind = row.authored ? 'authored' : 'third-party'
+		const when =
+			row.installableAt === undefined ? 'publish time unknown' : `installable ${row.installableAt}`
+		process.stderr.write(`  ${row.key} (${kind}): ${when}\n`)
+	}
+} else {
+	throw new Error('Usage: node release-age.mjs <inventory|new-versions> [options]')
+}

package/skills/ksc-update/scripts/run-at-node.mjs

@@ -0,0 +1,108 @@
+/**
+ * Runs a command with an exact Node.js release first in PATH, for the floor
+ * checks in verification.md, and proves which binary every process used.
+ *
+ * The release is downloaded once into `<run directory>/node-<version>/` through
+ * a `devEngines.runtime` fixture, so pnpm verifies the checksum and the user's
+ * default runtime is untouched. A logging `node` shim placed first in PATH
+ * records each invocation's version and arguments, so child processes that
+ * resolve `node` from PATH, such as package bin shims, are covered too. A child
+ * that hard-codes another binary does not appear in the log; treat a
+ * suspiciously low invocation count as unverified.
+ *
+ * Usage:
+ *
+ * ```
+ * node run-at-node.mjs <version> [--cwd <dir>] [--out <dir>] -- <command> [args...]
+ * ```
+ *
+ * Writes `stdout.txt`, `stderr.txt`, `exit-code.txt`, and
+ * `node-invocations.log` to `--out` (default `<run
+ * directory>/node-<version>/last-run/`), prints a summary, and exits with the
+ * command's exit code. The shim needs a POSIX shell, so this does not work on
+ * Windows.
+ */
+import { execFileSync, spawnSync } from 'node:child_process'
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { delimiter, dirname, join, resolve } from 'node:path'
+import process from 'node:process'
+import { runDirectory } from './lib.mjs'
+
+const separator = process.argv.indexOf('--')
+const head = process.argv.slice(2, separator === -1 ? undefined : separator)
+const command = separator === -1 ? [] : process.argv.slice(separator + 1)
+const version = head.shift()
+if (version === undefined || !/^\d+\.\d+\.\d+$/v.test(version) || command.length === 0) {
+	throw new Error(
+		'Usage: node run-at-node.mjs <x.y.z> [--cwd <dir>] [--out <dir>] -- <command> [args...]',
+	)
+}
+
+/** @type {Record<string, string>} */
+const options = {}
+for (let index = 0; index < head.length; index += 2) {
+	options[(head[index] ?? '').replace(/^--/v, '')] = head[index + 1] ?? ''
+}
+
+const runtimeDirectory = join(runDirectory(), `node-${version}`)
+mkdirSync(runtimeDirectory, { recursive: true })
+writeFileSync(
+	join(runtimeDirectory, 'package.json'),
+	`${JSON.stringify({ devEngines: { runtime: { name: 'node', onFail: 'download', version } }, name: `node-runtime-${version}`, private: true }, undefined, 2)}\n`,
+)
+execFileSync('pnpm', ['install'], { cwd: runtimeDirectory, stdio: ['ignore', 'ignore', 'inherit'] })
+const nodeBinary = execFileSync('pnpm', ['exec', 'node', '-p', 'process.execPath'], {
+	cwd: runtimeDirectory,
+	encoding: 'utf8',
+}).trim()
+const reported = execFileSync(nodeBinary, ['--version'], { encoding: 'utf8' }).trim()
+if (reported !== `v${version}`) {
+	throw new Error(`Expected Node.js v${version} at ${nodeBinary}, got ${reported}`)
+}
+
+const out = resolve(options.out ?? join(runtimeDirectory, 'last-run'))
+const shimDirectory = join(out, 'shim')
+const invocations = join(out, 'node-invocations.log')
+mkdirSync(shimDirectory, { recursive: true })
+writeFileSync(invocations, '')
+const shim = join(shimDirectory, 'node')
+writeFileSync(
+	shim,
+	[
+		'#!/bin/sh',
+		String.raw`printf '%s %s\n' '${reported}' "$*" | cut -c1-300 >> '${invocations}'`,
+		`exec '${nodeBinary}' "$@"`,
+		'',
+	].join('\n'),
+)
+chmodSync(shim, 0o755)
+
+const [executable = '', ...args] = command
+const childEnvironment = {
+	...process.env,
+	// eslint-disable-next-line ts/naming-convention -- Environment variable names are uppercase.
+	PATH: [shimDirectory, dirname(nodeBinary), process.env.PATH ?? ''].join(delimiter),
+}
+const result = spawnSync(executable, args, {
+	cwd: options.cwd === undefined ? process.cwd() : resolve(options.cwd),
+	encoding: 'utf8',
+	env: childEnvironment,
+	maxBuffer: 1024 ** 3,
+})
+writeFileSync(join(out, 'stdout.txt'), result.stdout)
+writeFileSync(join(out, 'stderr.txt'), result.stderr)
+const exitCode = result.status ?? 1
+writeFileSync(join(out, 'exit-code.txt'), `${exitCode}\n`)
+
+const lines = existsSync(invocations)
+	? readFileSync(invocations, 'utf8').split('\n').filter(Boolean)
+	: []
+const versions = [...new Set(lines.map((line) => line.split(' ', 1)[0]))]
+process.stdout.write(
+	`${JSON.stringify({ exitCode, invocations: lines.length, nodeBinary, out, versions }, undefined, 2)}\n`,
+)
+if (result.error !== undefined) {
+	throw result.error
+}
+
+process.exitCode = exitCode