@aperant/framework 0.6.2

package/src/cli/commands/lock.mjs

@@ -0,0 +1,159 @@
+/**
+ * commands/lock.mjs — multi-agent coordination lock commands (C29).
+ */
+
+import { execSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { isLockStale } from '../lock/pid.mjs'
+import { parseFlags } from '../util/args.mjs'
+import { closeSyncFd, openSyncExclusive } from '../util/fs-lock.mjs'
+import { getSharedLockDir } from '../util/project.mjs'
+import { err, ok } from '../util/result.mjs'
+
+export function cmdLock(subcommand, projectDir, extraArgs) {
+	if (!subcommand)
+		return err(
+			'Usage: apt-tools lock <claim|release|check|heartbeat|cleanup> <project-dir> [--subtask <id>]',
+		)
+	if (!projectDir)
+		return err('Usage: apt-tools lock ' + subcommand + ' <project-dir> [--subtask <id>]')
+
+	const targetDir = resolve(projectDir)
+	// Use shared lock dir (coordinates across worktrees via git common dir)
+	const locksDir = getSharedLockDir(targetDir)
+
+	const flags = parseFlags(extraArgs)
+	const subtask = flags.get('subtask')
+
+	switch (subcommand) {
+		case 'claim': {
+			if (!subtask) return err('Required: --subtask <id>')
+			const lockPath = join(locksDir, `${subtask}.lock`)
+			const lockData = {
+				worker_pid: process.pid,
+				claimed_at: new Date().toISOString(),
+				ttl_seconds: 120,
+				heartbeat: new Date().toISOString(),
+			}
+			// Persistent claim file — NOT a sidecar lock. Use O_EXCL via
+			// openSync so we can detect collisions without tripping the
+			// C28 "no ad-hoc lock sidecars" grep.
+			try {
+				const fd = openSyncExclusive(lockPath)
+				writeFileSync(fd, JSON.stringify(lockData, null, 2) + '\n')
+				closeSyncFd(fd)
+				return ok({ status: 'ok', command: 'lock-claim', subtask, lock: lockData })
+			} catch (e) {
+				if (e.code === 'EEXIST') {
+					const existing = JSON.parse(readFileSync(lockPath, 'utf-8'))
+					return ok({ status: 'already-claimed', subtask, lock: existing })
+				}
+				return err(`Failed to claim lock for ${subtask}: ${e.message}`)
+			}
+		}
+
+		case 'release': {
+			if (!subtask) return err('Required: --subtask <id>')
+			const lockPath = join(locksDir, `${subtask}.lock`)
+			if (!existsSync(lockPath)) {
+				return ok({
+					status: 'ok',
+					command: 'lock-release',
+					subtask,
+					message: 'No lock file found (already released)',
+				})
+			}
+			const existing = JSON.parse(readFileSync(lockPath, 'utf-8'))
+			if (existing.worker_pid !== process.pid) {
+				return err(
+					`Cannot release lock for ${subtask}: owned by PID ${existing.worker_pid}, current PID is ${process.pid}`,
+				)
+			}
+			unlinkSync(lockPath)
+			return ok({ status: 'ok', command: 'lock-release', subtask })
+		}
+
+		case 'check': {
+			if (!subtask) return err('Required: --subtask <id>')
+			const lockPath = join(locksDir, `${subtask}.lock`)
+			if (!existsSync(lockPath)) {
+				return ok({
+					status: 'ok',
+					command: 'lock-check',
+					locked: false,
+					stale: false,
+					lock: null,
+				})
+			}
+			const lockData = JSON.parse(readFileSync(lockPath, 'utf-8'))
+			const stale = isLockStale(lockData)
+			return ok({ status: 'ok', command: 'lock-check', locked: true, stale, lock: lockData })
+		}
+
+		case 'heartbeat': {
+			if (!subtask) return err('Required: --subtask <id>')
+			const lockPath = join(locksDir, `${subtask}.lock`)
+			if (!existsSync(lockPath)) {
+				return err(`No lock file found for ${subtask}`)
+			}
+			const lockData = JSON.parse(readFileSync(lockPath, 'utf-8'))
+			if (lockData.worker_pid !== process.pid) {
+				return err(
+					`Cannot heartbeat lock for ${subtask}: owned by PID ${lockData.worker_pid}, current PID is ${process.pid}`,
+				)
+			}
+			lockData.heartbeat = new Date().toISOString()
+			writeFileSync(lockPath, JSON.stringify(lockData, null, 2) + '\n', 'utf-8')
+			return ok({ status: 'ok', command: 'lock-heartbeat', subtask })
+		}
+
+		case 'cleanup': {
+			const removed = []
+			const warnings = []
+			if (!existsSync(locksDir)) {
+				return ok({ status: 'ok', command: 'lock-cleanup', removed, warnings })
+			}
+			const lockFiles = readdirSync(locksDir).filter((f) => f.endsWith('.lock'))
+			for (const file of lockFiles) {
+				const lockPath = join(locksDir, file)
+				try {
+					const lockData = JSON.parse(readFileSync(lockPath, 'utf-8'))
+					if (isLockStale(lockData)) {
+						// Check git for partial commits from stale worker
+						try {
+							const gitLog = execSync('git log --oneline -5', {
+								cwd: targetDir,
+								encoding: 'utf-8',
+							}).trim()
+							if (gitLog) {
+								warnings.push(
+									`Stale lock ${file} removed. Recent git log: ${gitLog.split('\n')[0]}`,
+								)
+							}
+						} catch {
+							// git not available or not a repo — skip warning
+						}
+						unlinkSync(lockPath)
+						removed.push(file.replace('.lock', ''))
+					}
+				} catch {
+					// Corrupted lock file — remove it
+					try {
+						unlinkSync(lockPath)
+					} catch {
+						/* ignore */
+					}
+					removed.push(file.replace('.lock', ''))
+					warnings.push(`Removed corrupted lock file: ${file}`)
+				}
+			}
+			return ok({ status: 'ok', command: 'lock-cleanup', removed, warnings })
+		}
+
+		default:
+			return err(
+				`Unknown lock subcommand: ${subcommand}. Expected: claim, release, check, heartbeat, cleanup`,
+			)
+	}
+}

package/src/cli/commands/migrate-pr-reviews.mjs

@@ -0,0 +1,215 @@
+/**
+ * commands/migrate-pr-reviews.mjs — one-shot migration of the legacy
+ * .aperant/reviews/pr-{N}-{date}-{hash}/ layout to the per-PR persistent
+ * .aperant/pr-reviews/pr-{N}/rounds/{R}/ layout introduced by R2/R3 of the
+ * /apt:pr-review hardening task.
+ *
+ * Idempotent: running on an already-migrated tree detects the target folder
+ * and returns { status: "already_migrated" } with no mutations.
+ */
+
+import {
+	cpSync,
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	statSync,
+	writeFileSync,
+} from 'node:fs'
+import { join, resolve } from 'node:path'
+import { err, ok } from '../util/result.mjs'
+
+/**
+ * Parse a legacy review-id directory name into its components.
+ *
+ * Examples:
+ *   "pr-23-260413-09ba"        -> { pr: 23, round: 1, date: "260413", hash: "09ba" }
+ *   "pr-23-r2-260415-5ec5"     -> { pr: 23, round: 2, date: "260415", hash: "5ec5" }
+ *   "pr-24-r3-260413-318a"     -> { pr: 24, round: 3, date: "260413", hash: "318a" }
+ *
+ * Returns null for names that don't match (skipped by migration).
+ */
+export function parseLegacyReviewId(name) {
+	// Accept pr-{N}-[r{R}-]{YYMMDD}-{hash}
+	const roundMatch = name.match(/^pr-(\d+)-r(\d+)-(\d{6})-([a-z0-9]+)$/i)
+	if (roundMatch) {
+		return {
+			pr: Number(roundMatch[1]),
+			round: Number(roundMatch[2]),
+			date: roundMatch[3],
+			hash: roundMatch[4],
+			source_id: name,
+		}
+	}
+	const plainMatch = name.match(/^pr-(\d+)-(\d{6})-([a-z0-9]+)$/i)
+	if (plainMatch) {
+		return {
+			pr: Number(plainMatch[1]),
+			round: 1,
+			date: plainMatch[2],
+			hash: plainMatch[3],
+			source_id: name,
+		}
+	}
+	return null
+}
+
+/**
+ * Rewrite prior_review references in a metadata.json-like object to point at
+ * the new per-round layout (../{R-1}/) rather than a sibling legacy directory.
+ */
+function rewritePriorReview(obj, priorRound) {
+	if (!obj || typeof obj !== 'object') return obj
+	if (typeof obj.prior_review === 'string' && obj.prior_review.length > 0) {
+		// Replace value with canonical per-round pointer. The orchestrator can
+		// resolve this relative to the current round's path.
+		obj.prior_review = `../${priorRound}/`
+	}
+	return obj
+}
+
+function rewriteJsonFile(path, priorRound) {
+	if (!existsSync(path)) return false
+	try {
+		const raw = readFileSync(path, 'utf-8')
+		const parsed = JSON.parse(raw)
+		const before = JSON.stringify(parsed)
+		rewritePriorReview(parsed, priorRound)
+		const after = JSON.stringify(parsed)
+		if (before !== after) {
+			writeFileSync(path, `${JSON.stringify(parsed, null, 2)}\n`, 'utf-8')
+			return true
+		}
+	} catch {
+		// Non-JSON file or malformed — skip
+	}
+	return false
+}
+
+/**
+ * Migrate a single legacy review dir into the new layout.
+ * Returns { pr, round, source_id, target_path, rewrites }.
+ */
+function migrateOne(legacyDir, parsed, reviewsDir, prReviewsDir) {
+	const targetPrDir = join(prReviewsDir, `pr-${parsed.pr}`)
+	const targetRoundsDir = join(targetPrDir, 'rounds')
+	const targetRoundDir = join(targetRoundsDir, String(parsed.round))
+
+	mkdirSync(targetRoundsDir, { recursive: true })
+
+	if (existsSync(targetRoundDir)) {
+		return {
+			pr: parsed.pr,
+			round: parsed.round,
+			source_id: parsed.source_id,
+			target_path: targetRoundDir,
+			status: 'skipped_target_exists',
+			rewrites: 0,
+		}
+	}
+
+	// Copy tree, then remove source. We prefer copy-then-delete over rename
+	// across device/filesystem boundaries to stay robust.
+	const sourcePath = join(reviewsDir, legacyDir)
+	try {
+		renameSync(sourcePath, targetRoundDir)
+	} catch {
+		cpSync(sourcePath, targetRoundDir, { recursive: true })
+		rmSync(sourcePath, { recursive: true, force: true })
+	}
+
+	let rewrites = 0
+	if (parsed.round > 1) {
+		const priorRound = parsed.round - 1
+		if (rewriteJsonFile(join(targetRoundDir, 'metadata.json'), priorRound)) rewrites++
+		if (rewriteJsonFile(join(targetRoundDir, 'review.json'), priorRound)) rewrites++
+	}
+
+	return {
+		pr: parsed.pr,
+		round: parsed.round,
+		source_id: parsed.source_id,
+		target_path: targetRoundDir,
+		status: 'migrated',
+		rewrites,
+	}
+}
+
+/**
+ * Entry point for `apt-tools migrate-pr-reviews <project-dir>`.
+ */
+export function cmdMigratePrReviews(projectDir) {
+	if (!projectDir) return err('Usage: apt-tools migrate-pr-reviews <project-dir>')
+
+	const root = resolve(projectDir)
+	const aperant = join(root, '.aperant')
+	if (!existsSync(aperant)) return err(`.aperant/ not found under ${root}`)
+
+	const reviewsDir = join(aperant, 'reviews')
+	const prReviewsDir = join(aperant, 'pr-reviews')
+
+	const legacyExists = existsSync(reviewsDir) && statSync(reviewsDir).isDirectory()
+	const targetExists = existsSync(prReviewsDir) && statSync(prReviewsDir).isDirectory()
+
+	const legacyEntries = legacyExists
+		? readdirSync(reviewsDir, { withFileTypes: true })
+				.filter((d) => d.isDirectory())
+				.map((d) => d.name)
+		: []
+
+	// Idempotency: if the legacy folder is empty or gone AND pr-reviews exists,
+	// consider this tree already migrated.
+	if (legacyEntries.length === 0) {
+		const prCount = targetExists
+			? readdirSync(prReviewsDir, { withFileTypes: true }).filter(
+					(d) => d.isDirectory() && d.name.startsWith('pr-'),
+				).length
+			: 0
+		return ok({
+			status: 'already_migrated',
+			pr_count: prCount,
+			source: reviewsDir,
+			target: prReviewsDir,
+		})
+	}
+
+	mkdirSync(prReviewsDir, { recursive: true })
+
+	const migrated = []
+	const skipped = []
+	for (const name of legacyEntries) {
+		const parsed = parseLegacyReviewId(name)
+		if (!parsed) {
+			skipped.push({ name, reason: 'unrecognized_name_pattern' })
+			continue
+		}
+		const result = migrateOne(name, parsed, reviewsDir, prReviewsDir)
+		migrated.push(result)
+	}
+
+	// If the legacy dir is now empty, remove it.
+	if (
+		existsSync(reviewsDir) &&
+		readdirSync(reviewsDir).filter((n) => !n.startsWith('.')).length === 0
+	) {
+		try {
+			rmSync(reviewsDir, { recursive: true, force: true })
+		} catch {
+			// leave empty dir on filesystem permission issues
+		}
+	}
+
+	return ok({
+		status: 'migrated',
+		pr_count: new Set(migrated.map((m) => m.pr)).size,
+		migrated_count: migrated.length,
+		skipped_count: skipped.length,
+		migrated,
+		skipped,
+		source: reviewsDir,
+		target: prReviewsDir,
+	})
+}

package/src/cli/commands/personas.mjs

@@ -0,0 +1,333 @@
+/**
+ * commands/personas.mjs — `apt-tools personas <sub>` (C48).
+ *
+ * Deterministic CLI surface for the apt:personas skill. This command never
+ * calls an LLM. The SKILL.md body invokes the host LLM to author personas +
+ * classify tiers, then hands the structured payload to this CLI for
+ * persistence + run tracking.
+ *
+ * Subcommand menu:
+ *
+ *   apt-tools personas scan <project-dir>
+ *     → emit the role-scan envelope (read-only). The SKILL.md body injects
+ *       this into the LLM prompt alongside the tier rubric.
+ *
+ *   apt-tools personas rubric <project-dir>
+ *     → emit the tier-rubric prompt body. Inputs come from product-
+ *       context.json + role-scan; the CLI composes them into the exact text
+ *       the SKILL.md body hands to the host LLM.
+ *
+ *   apt-tools personas read <project-dir>
+ *     → emit the current `.aperant/personas.json` envelope (or null if
+ *       missing). Used by --from-app flows and by `/apt:docs` to render
+ *       personas into README / ABOUT.
+ *
+ *   apt-tools personas write <project-dir>
+ *       --mode <fresh | extend | from-app>
+ *       [--payload <path>]
+ *       [--force]
+ *     → persist personas. `--payload` points to a JSON file containing a
+ *       Persona[] array — the SKILL.md body writes it to a tmp path so the
+ *       CLI can consume it without argv explosion.
+ *
+ *   apt-tools personas record-run <project-dir>
+ *       --status <pending | running | completed | failed>
+ *       [--candidates-found N] [--phase <slug>] [--error <msg>]
+ *     → append an entry to `.aperant/personas-runs.json` (D-09).
+ *
+ * Return shape: always `{ status, command, ... }`. On refused writes (D-10
+ * guard hit without --force), exits 0 with `status: 'refused'` so the
+ * SKILL.md body can pick up the message and ask the user — we do NOT exit 1
+ * here, that would break auto-mode branches.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { runRoleScan } from '../personas/role-scan.mjs'
+import {
+	FRAMEWORK_LOCAL_TEAM_ID,
+	PERSONAS_ENVELOPE_VERSION,
+	personasPaths,
+	readFromApp,
+	readPersonas,
+	readRuns,
+	recordRun,
+	resolveProjectId,
+	writeExtend,
+	writeFresh,
+} from '../personas/sidecar.mjs'
+import { buildTierPrompt, buildTierRubricPrompt } from '../personas/tier-rubric.mjs'
+import { getFlagValue, resolveProjectDir } from '../util/common-flags.mjs'
+import { err, ok } from '../util/result.mjs'
+
+/**
+ * @param {string | undefined} subcommand
+ * @param {string[] | undefined} extraArgs
+ */
+export function cmdPersonas(subcommand, extraArgs) {
+	const args = extraArgs ?? []
+	if (!subcommand) {
+		return err(
+			'Usage: apt-tools personas <scan|rubric|read|write|record-run> <project-dir> [flags]\n' +
+				'  scan            emit role-scan findings\n' +
+				'  rubric          emit tier-assignment prompt body (rubric + inputs)\n' +
+				'  read            emit current .aperant/personas.json envelope\n' +
+				'  write           persist personas (--mode fresh|extend|from-app, --payload <path>, --force)\n' +
+				'  record-run      append entry to .aperant/personas-runs.json',
+		)
+	}
+	switch (subcommand) {
+		case 'scan':
+			return cmdScan(args)
+		case 'rubric':
+			return cmdRubric(args)
+		case 'read':
+			return cmdRead(args)
+		case 'write':
+			return cmdWrite(args)
+		case 'record-run':
+			return cmdRecordRun(args)
+		default:
+			return err(
+				`apt-tools personas: unknown subcommand "${subcommand}". ` +
+					'Known: scan, rubric, read, write, record-run',
+			)
+	}
+}
+
+/**
+ * scan — role-scan findings. Read-only, no files written.
+ *
+ * @param {string[]} args
+ */
+function cmdScan(args) {
+	const projectDir = resolveProjectDir(args)
+	const result = runRoleScan(projectDir)
+	return ok({
+		status: 'ok',
+		command: 'personas-scan',
+		projectDir,
+		team_id: FRAMEWORK_LOCAL_TEAM_ID,
+		project_id: resolveProjectId(projectDir),
+		result,
+	})
+}
+
+/**
+ * rubric — emit the tier-rubric prompt body. Inputs come from the project's
+ * product-context.json (C44); the role-scan is combined in-line so the
+ * SKILL.md body can hand a single text block to the host LLM.
+ *
+ * @param {string[]} args
+ */
+function cmdRubric(args) {
+	const projectDir = resolveProjectDir(args)
+	const productContextPath = resolve(projectDir, '.aperant', 'product-context.json')
+	/** @type {any} */
+	let productContext = null
+	if (existsSync(productContextPath)) {
+		try {
+			productContext = JSON.parse(readFileSync(productContextPath, 'utf-8'))
+		} catch {
+			productContext = null
+		}
+	}
+
+	const scan = runRoleScan(projectDir)
+	const inputs = {
+		productName: productContext?.productName ?? 'Unnamed Project',
+		productDescription: productContext?.productDescription ?? '',
+		targetAudience: productContext?.targetAudience ?? '',
+		coreValue: productContext?.productDescription ?? '',
+		uniqueRoleStrings: scan.unique_role_strings,
+		roleFindings: scan.findings,
+		features: Array.isArray(productContext?.features) ? productContext.features : [],
+	}
+	const prompt = buildTierPrompt(inputs)
+	const rubricOnly = buildTierRubricPrompt()
+
+	return ok({
+		status: 'ok',
+		command: 'personas-rubric',
+		projectDir,
+		product_context_present: Boolean(productContext),
+		inputs,
+		rubric: rubricOnly,
+		prompt,
+	})
+}
+
+/**
+ * read — emit the current personas envelope.
+ *
+ * @param {string[]} args
+ */
+function cmdRead(args) {
+	const projectDir = resolveProjectDir(args)
+	const envelope = readPersonas(projectDir)
+	const runs = readRuns(projectDir)
+	return ok({
+		status: 'ok',
+		command: 'personas-read',
+		projectDir,
+		paths: personasPaths(projectDir),
+		envelope,
+		runs_count: runs.runs.length,
+	})
+}
+
+/**
+ * write — persist personas. The payload is passed via a file path because
+ * persona ui_json blobs can be multi-KB, and argv limits are unfriendly.
+ *
+ * @param {string[]} args
+ */
+function cmdWrite(args) {
+	const projectDir = resolveProjectDir(args)
+	const flags = new Set(args.filter((a) => a.startsWith('--') && !hasValueAfter(args, a)))
+	const mode = getFlagValue(args, '--mode') ?? 'extend'
+	const payloadPath = getFlagValue(args, '--payload')
+	const force = flags.has('--force')
+
+	if (mode !== 'fresh' && mode !== 'extend' && mode !== 'from-app') {
+		return err(`personas write: unknown --mode "${mode}" (known: fresh, extend, from-app)`)
+	}
+
+	if (mode === 'from-app') {
+		const result = readFromApp(projectDir)
+		return ok({
+			status: result.status === 'ok' ? 'ok' : 'not-found',
+			command: 'personas-write',
+			mode,
+			projectDir,
+			message: result.message,
+			envelope: result.envelope,
+		})
+	}
+
+	if (!payloadPath) {
+		return err(`personas write --mode ${mode} requires --payload <path-to-json>`)
+	}
+
+	const abs = resolve(payloadPath)
+	if (!existsSync(abs)) {
+		return err(`personas write: payload not found at ${abs}`)
+	}
+
+	let personas
+	try {
+		const raw = readFileSync(abs, 'utf-8')
+		personas = JSON.parse(raw)
+	} catch (e) {
+		return err(`personas write: unable to parse payload at ${abs}: ${errMsg(e)}`)
+	}
+	if (!Array.isArray(personas)) {
+		return err('personas write: payload must be a JSON array of Persona objects')
+	}
+
+	if (mode === 'fresh') {
+		const result = writeFresh(projectDir, personas, { force })
+		return ok({
+			status: result.status,
+			command: 'personas-write',
+			mode,
+			projectDir,
+			schema_version: PERSONAS_ENVELOPE_VERSION,
+			guard_reason: result.guardReason,
+			envelope: result.envelope,
+			written_path: personasPaths(projectDir).personas,
+		})
+	}
+
+	// mode === 'extend'
+	const result = writeExtend(projectDir, personas)
+	return ok({
+		status: 'ok',
+		command: 'personas-write',
+		mode,
+		projectDir,
+		schema_version: PERSONAS_ENVELOPE_VERSION,
+		added_count: result.added.length,
+		skipped_count: result.skipped.length,
+		envelope: result.envelope,
+		written_path: personasPaths(projectDir).personas,
+	})
+}
+
+/**
+ * record-run — append an entry to `.aperant/personas-runs.json` (D-09).
+ *
+ * @param {string[]} args
+ */
+function cmdRecordRun(args) {
+	const projectDir = resolveProjectDir(args)
+	const status = getFlagValue(args, '--status')
+	if (!status || !['pending', 'running', 'completed', 'failed'].includes(status)) {
+		return err(
+			'personas record-run: --status is required (one of pending|running|completed|failed)',
+		)
+	}
+	const candidatesFoundRaw = getFlagValue(args, '--candidates-found')
+	const candidatesFound = candidatesFoundRaw ? Number.parseInt(candidatesFoundRaw, 10) : null
+	const phase = getFlagValue(args, '--phase')
+	const errorMsg = getFlagValue(args, '--error')
+	const id = getFlagValue(args, '--id')
+	const startedAtRaw = getFlagValue(args, '--started-at')
+	const completedAtRaw = getFlagValue(args, '--completed-at')
+
+	/** @type {Record<string, unknown>} */
+	const payload = {
+		status: /** @type {'pending'|'running'|'completed'|'failed'} */ (status),
+	}
+	if (id) payload.id = id
+	if (phase) payload.current_phase = phase
+	if (errorMsg) payload.error_message = errorMsg
+	if (startedAtRaw) {
+		const n = Number.parseInt(startedAtRaw, 10)
+		if (Number.isFinite(n)) payload.started_at = n
+	}
+	if (completedAtRaw) {
+		const n = Number.parseInt(completedAtRaw, 10)
+		if (Number.isFinite(n)) payload.completed_at = n
+	}
+	if (candidatesFound !== null && Number.isFinite(candidatesFound)) {
+		payload.candidates_found = candidatesFound
+	}
+
+	const run = recordRun(projectDir, /** @type {any} */ (payload))
+	return ok({
+		status: 'ok',
+		command: 'personas-record-run',
+		projectDir,
+		run,
+		path: personasPaths(projectDir).runs,
+	})
+}
+
+/**
+ * Detect whether a flag is being used as a key/value pair so we can skip it
+ * in the flag-set membership check.
+ *
+ * @param {string[]} args
+ * @param {string} flag
+ * @returns {boolean}
+ */
+function hasValueAfter(args, flag) {
+	const idx = args.indexOf(flag)
+	if (idx < 0) return false
+	const next = args[idx + 1]
+	if (!next) return false
+	return !next.startsWith('--')
+}
+
+/**
+ * @param {unknown} err
+ * @returns {string}
+ */
+function errMsg(err) {
+	if (err && typeof err === 'object' && 'message' in err) {
+		const m = /** @type {{ message: unknown }} */ (err).message
+		return typeof m === 'string' ? m : String(m)
+	}
+	return String(err)
+}