@aperant/framework 0.6.2

package/src/cli/util/fs-lock.mjs

@@ -0,0 +1,119 @@
+/**
+ * fs-lock.mjs — file-lock helpers extracted from apt-tools.mjs (C29).
+ *
+ * Depends on project.mjs (findProjectRootFromPath) and the `proper-lockfile`
+ * dependency. Behavior must match the originals byte-for-byte.
+ */
+
+import { closeSync, existsSync, mkdirSync, openSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import properLockfileImport from 'proper-lockfile'
+import { findProjectRootFromPath } from './project.mjs'
+
+// proper-lockfile exposes lock/unlock/check on the default export in CJS.
+const properLockfile = properLockfileImport?.default ?? properLockfileImport
+
+/**
+ * Acquire an exclusive file lock via `proper-lockfile`, run `fn`, then
+ * release. Kept synchronous to match the existing call sites (atomic JSON
+ * writers) that expect a value back from the callback.
+ *
+ * proper-lockfile manages its own `.lock` sidecar and handles stale locks
+ * via mtime polling, so C28 retires the ad-hoc `writeFileSync(...wx)`
+ * pattern. On acquisition failure we emit a structured event to
+ * `.aperant/events/lock_timeout_*.json` so operators can spot contention.
+ */
+export function withFileLock(targetPath, fn, options = {}) {
+	const maxRetries = options.maxRetries ?? 20
+	const retryDelayMs = options.retryDelayMs ?? 50
+	const maxRetryDelayMs = options.maxRetryDelayMs ?? 500
+	const stale = options.stale ?? 5000
+	const realpath = options.realpath ?? false
+	mkdirSync(dirname(targetPath), { recursive: true })
+	if (!existsSync(targetPath)) {
+		writeFileSync(targetPath, '', { flag: 'a' })
+	}
+	// proper-lockfile's sync API does not accept the full retries object —
+	// only a number. Implement our own retry loop around lockSync.
+	let release = null
+	let lastErr = null
+	for (let attempt = 0; attempt <= maxRetries; attempt++) {
+		try {
+			release = properLockfile.lockSync(targetPath, {
+				stale,
+				realpath,
+			})
+			break
+		} catch (err) {
+			lastErr = err
+			// Retry only on "already locked" style errors. Fatal errors (bad path,
+			// permission) should fail fast.
+			const msg = String(err?.message ?? err)
+			if (!/lock|ELOCKED|already held|EEXIST/i.test(msg) || attempt === maxRetries) {
+				break
+			}
+			const jitter =
+				retryDelayMs + Math.random() * Math.min(maxRetryDelayMs, retryDelayMs * (attempt + 1))
+			// Block this thread without spinning the CPU. Atomics.wait on a
+			// non-shared int just parks the event loop for the duration.
+			try {
+				Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, jitter)
+			} catch {
+				// Fallback for runtimes without SharedArrayBuffer — fall back to
+				// a spin with a short bound so we don't burn CPU indefinitely.
+				const startedAt = Date.now()
+				while (Date.now() - startedAt < Math.min(jitter, 100)) {
+					/* spin */
+				}
+			}
+		}
+	}
+	if (!release) {
+		recordLockTimeoutEvent(targetPath, options.projectRoot, lastErr)
+		throw new Error(`Could not acquire lock at ${targetPath}.lock: ${lastErr?.message ?? lastErr}`)
+	}
+	try {
+		return fn()
+	} finally {
+		try {
+			release?.()
+		} catch {
+			/* already released or stale */
+		}
+	}
+}
+
+export function recordLockTimeoutEvent(targetPath, projectRoot, err) {
+	try {
+		const root = projectRoot ? resolve(projectRoot) : findProjectRootFromPath(targetPath)
+		if (!root) return
+		const eventsDir = join(root, '.aperant', 'events')
+		mkdirSync(eventsDir, { recursive: true })
+		const ts = new Date().toISOString().replace(/[:.]/g, '-')
+		const file = join(eventsDir, `lock_timeout_${ts}_${process.pid}.json`)
+		writeFileSync(
+			file,
+			JSON.stringify(
+				{
+					type: 'lock_timeout',
+					target: targetPath,
+					reason: err?.message ?? String(err),
+					pid: process.pid,
+					at: new Date().toISOString(),
+				},
+				null,
+				2,
+			),
+		)
+	} catch {
+		/* best-effort only */
+	}
+}
+
+export function openSyncExclusive(path) {
+	return openSync(path, 'wx')
+}
+
+export function closeSyncFd(fd) {
+	closeSync(fd)
+}

package/src/cli/util/init-hints.mjs

@@ -0,0 +1,91 @@
+/**
+ * init-hints.mjs — one-time UX hints emitted at the tail of fresh
+ * `apt-tools init` and first `apt-tools pr-review init-pr` invocations,
+ * explaining which `.aperant/` files are intentionally team-shared
+ * (committed) vs gitignored (ephemeral).
+ *
+ * Why: users routinely see `M .aperant/config.json` in `git status` after a
+ * `/apt:setup` run and assume the framework forgot to gitignore it. They
+ * are correct that it shows up — but wrong about the cause: `config.json`
+ * is intentionally committable team-level prefs (per
+ * `packages/framework/docs/artifact-lifecycle.md`'s classification table),
+ * sitting next to ephemeral siblings like `state.json` and `team-status/`
+ * that ARE gitignored. This printer closes that documented confusion with
+ * a single stderr line at the right moment in each workflow.
+ *
+ * Stderr (not stdout) so the existing machine-readable JSON envelope from
+ * `output()` stays parseable. Same channel as the gitignore-drift warning
+ * (see `gitignore-drift.mjs` precedent).
+ *
+ * Suppressible via `APT_SUPPRESS_INIT_HINTS=1` for scripted/CI runs that
+ * already understand the model — mirrors the
+ * `APT_SUPPRESS_GITIGNORE_DRIFT=1` precedent.
+ *
+ * Callers are responsible for the "first-time only" gate (e.g. only call
+ * `emitInitConfigHint` when `.aperant/config.json` was actually just
+ * created — not on a noop re-install).
+ *
+ * @internal — consumed only from init.mjs and pr-review.mjs.
+ */
+
+/**
+ * Returns true when the suppress env var is set to `'1'`. Centralized so
+ * callers don't repeat the comparison.
+ *
+ * @returns {boolean}
+ */
+function isSuppressed() {
+	return process.env.APT_SUPPRESS_INIT_HINTS === '1'
+}
+
+/**
+ * One-time hint after a real `apt-tools init` (when `config.json` was
+ * actually written fresh — NOT on noop re-install). Caller MUST gate on
+ * the genuine "config created" signal.
+ *
+ * Single stderr line. Never throws. No-op when suppressed.
+ *
+ * @internal
+ */
+export function emitInitConfigHint() {
+	if (isSuppressed()) return
+	try {
+		process.stderr.write(
+			'[apt-tools init] Note: .aperant/config.json is intentionally committed (team-shared framework prefs).\n' +
+				'                       Commit it alongside your work. .aperant/state.json + team-status/ are gitignored\n' +
+				'                       and never travel.\n',
+		)
+	} catch {
+		/* never block init on a hint write */
+	}
+}
+
+/**
+ * One-time hint after a real `apt-tools pr-review init-pr` (when
+ * `pr-state.json` was just seeded — NOT on subsequent calls where the file
+ * already exists / `rounds_completed > 0`). Caller MUST gate on the
+ * genuine "state created" signal.
+ *
+ * Since 2026-04 the artifact is **ephemeral** (local framework coordination,
+ * not a git artifact). The hint exists so users seeing the file under
+ * `.aperant/pr-reviews/` know it's intentional local state and not stray
+ * scratch — and so they don't try to commit it.
+ *
+ * Single stderr block. Never throws. No-op when suppressed.
+ *
+ * @param {number|string} prNumber  PR number, used for path-templating the
+ *                                   hint so users can copy-paste the path.
+ * @internal
+ */
+export function emitInitPrStateHint(prNumber) {
+	if (isSuppressed()) return
+	try {
+		process.stderr.write(
+			`[apt-tools pr-review init-pr] Note: .aperant/pr-reviews/pr-${prNumber}/pr-state.json is local-only\n` +
+				'                                    (per-PR coordination — authorship pin, round counters, lock).\n' +
+				'                                    Gitignored; auto-pruned by close-round on PR merge.\n',
+		)
+	} catch {
+		/* never block init-pr on a hint write */
+	}
+}

package/src/cli/util/io.mjs

@@ -0,0 +1,47 @@
+/**
+ * io.mjs — layer-0 I/O + process-exit helpers extracted from apt-tools.mjs (C29).
+ *
+ * These are pure leaf helpers with zero internal dependencies. Behavior must
+ * match the originals byte-for-byte; the CLI snapshot harness enforces this.
+ */
+
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// Re-export the hardened atomic-write primitives so every existing call site
+// (import { atomicWriteJson } from '../util/io.mjs') keeps working. See
+// atomic-write.mjs for the fsync + tmp-file semantics.
+export { appendJsonl, atomicWriteJson, atomicWriteText } from './atomic-write.mjs'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+/**
+ * Read framework package.json and return a "<name> <version>" identity string.
+ * Resolves relative to this module's location so the CLI keeps its own
+ * package.json as source of truth regardless of cwd.
+ */
+export function getVersion() {
+	// src/cli/util/io.mjs → up three levels → packages/framework/package.json
+	const pkgPath = resolve(__dirname, '..', '..', '..', 'package.json')
+	const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+	return `${pkg.name} ${pkg.version}`
+}
+
+/**
+ * Write a JSON-stringified value to stdout, followed by a trailing newline.
+ * Everything apt-tools prints to stdout goes through this.
+ */
+export function output(data) {
+	process.stdout.write(JSON.stringify(data, null, 2) + '\n')
+}
+
+/**
+ * Print a structured error envelope to stdout and exit the process with
+ * status 1. Used for all fatal-from-CLI conditions.
+ */
+export function fail(message) {
+	output({ error: message })
+	process.exit(1)
+}

package/src/cli/util/project.mjs

@@ -0,0 +1,46 @@
+/**
+ * project.mjs — project-root + shared-lock-dir helpers (C29).
+ *
+ * As of subtask 03 `detectWorktree` lives in `src/cli/git/worktree-detect.mjs`
+ * so this module imports it directly. Earlier call sites that passed the
+ * detector as an explicit argument no longer need to — callers can invoke
+ * `getSharedLockDir(projectDir)` with a single argument.
+ */
+
+import { existsSync, mkdirSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { detectWorktree } from '../git/worktree-detect.mjs'
+
+/**
+ * Walk upward from the target path until we find a `.aperant/` directory.
+ * Returns the containing project root, or null if none is found within
+ * 8 parent levels.
+ */
+export function findProjectRootFromPath(filePath) {
+	let cur = resolve(filePath)
+	for (let i = 0; i < 8; i++) {
+		const parent = dirname(cur)
+		if (parent === cur) return null
+		if (existsSync(join(parent, '.aperant'))) return parent
+		cur = parent
+	}
+	return null
+}
+
+/**
+ * Get the shared lock directory — uses git common dir so locks coordinate
+ * across worktrees. Falls back to local .aperant/locks/ if not in git.
+ */
+export function getSharedLockDir(projectDir) {
+	const wt = detectWorktree(projectDir)
+	if (wt.is_worktree && wt.main_repo_root) {
+		// Use main repo's .aperant/locks/ so all worktrees share the same locks
+		const sharedDir = join(wt.main_repo_root, '.aperant', 'locks')
+		mkdirSync(sharedDir, { recursive: true })
+		return sharedDir
+	}
+	// Not a worktree — use local
+	const localDir = join(resolve(projectDir), '.aperant', 'locks')
+	mkdirSync(localDir, { recursive: true })
+	return localDir
+}

package/src/cli/util/result.mjs

@@ -0,0 +1,112 @@
+/**
+ * result.mjs — D-01 (d) command-result helpers.
+ *
+ * Every Layer 1 cmdX(opts) function returns one of two `CommandResult` shapes:
+ *
+ *     { envelope: { status, command?, ... }, exitCode: number }   ← JSON cmds
+ *     { rawText: string, exitCode: number }                       ← non-JSON cmds
+ *
+ * The Layer 2 wrapper (`wrap()` in dispatch.mjs) routes both:
+ *   - JSON shape   → output(envelope) + (exitCode !== 0 ? process.exit(exitCode))
+ *   - rawText shape → process.stdout.write(rawText) + (exitCode !== 0 ? process.exit(exitCode))
+ *
+ * The transport metadata (exitCode) lives OUTSIDE the envelope — the envelope
+ * shape is exactly the pre-refactor JSON contract callers parse from stdout.
+ * There is intentionally NO `_exitCode` (or other transport field) on the
+ * envelope; D-01 (d) was adopted specifically to keep the public JSON contract
+ * clean.
+ *
+ * Helpers:
+ *
+ *   ok(envelope)               — JSON path, exit 0, envelope unchanged.
+ *   err(msg, exitCode = 1, x)  — JSON path, exit `exitCode`, synthesizes a
+ *                                 { status: 'error', error: msg, ...x } envelope.
+ *   exitWith(envelope, code)   — JSON path, exit `code`, envelope unchanged.
+ *                                 Used for the documented exit-2 semantics
+ *                                 (pr-review busy/mismatch/exhausted, audit
+ *                                 pending-artifacts --fail-on-dirty,
+ *                                 state-artifacts secrets-found).
+ *   rawText(text, code = 0)    — Non-JSON path, exit `code`, raw text on stdout.
+ *                                 Used by template, effects list, consistency
+ *                                 check --format human, precompact-hook.
+ *
+ * The CommandResult typedef is JSDoc-only (no TypeScript here — Layer 1 lives
+ * in .mjs). Tests assert on `result.envelope`/`result.rawText` and
+ * `result.exitCode` separately.
+ */
+
+/**
+ * Sentinel base class for helper-level usage failures inside Layer 1 cmds.
+ * Subclass per-cmd (`class FooUsageError extends UsageError { ... }`) so
+ * each cmd's catch boundary can remain narrowly scoped via `instanceof`.
+ * The dispatcher's catch block converts any UsageError into `err(e.message)`.
+ */
+export class UsageError extends Error {
+	constructor(message) {
+		super(message)
+		this.name = 'UsageError'
+	}
+}
+
+/**
+ * @typedef {Object} CommandResult
+ * @property {{ status: string, command?: string, [k: string]: unknown }} envelope
+ * @property {number} exitCode
+ *
+ * @typedef {Object} RawCommandResult
+ * @property {string} rawText
+ * @property {number} exitCode
+ */
+
+/**
+ * Success path — pass envelope through verbatim, exit 0.
+ *
+ * @param {{ status: string, command?: string, [k: string]: unknown }} envelope
+ * @returns {CommandResult}
+ */
+export function ok(envelope) {
+	return { envelope, exitCode: 0 }
+}
+
+/**
+ * Generic error path — synthesize a standard error envelope at the requested
+ * exit code. `extra` merges in additional envelope fields (e.g. command name).
+ *
+ * @param {string} msg
+ * @param {number} [exitCode=1]
+ * @param {Record<string, unknown>} [extra]
+ * @returns {CommandResult}
+ */
+export function err(msg, exitCode = 1, extra = {}) {
+	return {
+		envelope: { status: 'error', error: msg, ...extra },
+		exitCode,
+	}
+}
+
+/**
+ * Pre-built envelope + explicit exit code. Used when the command has its own
+ * domain-shaped envelope (e.g. pr-review's busy/mismatch envelopes) and only
+ * needs to set the exit code.
+ *
+ * @param {{ status: string, command?: string, [k: string]: unknown }} envelope
+ * @param {number} exitCode
+ * @returns {CommandResult}
+ */
+export function exitWith(envelope, exitCode) {
+	return { envelope, exitCode }
+}
+
+/**
+ * Raw-text output path — for cmds that emit non-JSON content (template dump,
+ * effects list, consistency check --format human, precompact-hook). The wrap()
+ * helper routes this through `process.stdout.write(text)` instead of
+ * `output(envelope)`, then sets the exit code.
+ *
+ * @param {string} text
+ * @param {number} [exitCode=0]
+ * @returns {RawCommandResult}
+ */
+export function rawText(text, exitCode = 0) {
+	return { rawText: text, exitCode }
+}

package/src/cli/util/skill-installs.mjs

@@ -0,0 +1,37 @@
+/**
+ * skill-installs.mjs — shared skill install surfaces per host.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+export function getSkillInstallSurfaces(projectDir) {
+	const root = resolve(projectDir)
+	return [
+		{
+			host: 'claude-code',
+			skills_dir: join(root, '.claude', 'skills'),
+		},
+		{
+			host: 'codex',
+			skills_dir: join(root, '.agents', 'skills'),
+		},
+	].map((surface) => ({
+		...surface,
+		version_file: join(surface.skills_dir, '.apt-version'),
+	}))
+}
+
+export function readSkillInstallState(projectDir, frameworkVersion) {
+	return getSkillInstallSurfaces(projectDir).map((surface) => {
+		const installed_version = existsSync(surface.version_file)
+			? readFileSync(surface.version_file, 'utf-8').trim()
+			: null
+		return {
+			...surface,
+			installed: installed_version !== null,
+			installed_version,
+			stale: installed_version !== null && installed_version !== frameworkVersion,
+		}
+	})
+}

package/src/cli/variant/gallery.mjs

@@ -0,0 +1,170 @@
+/**
+ * variant/gallery.mjs — render the side-by-side picker HTML (C1, Wave 2).
+ *
+ * Pure function.  Takes a list of variant entries and returns the gallery
+ * HTML string.  The CLI layer writes it to disk; this module has no I/O
+ * so tests can diff the output directly.
+ *
+ * Design constraints (from overview.md §10.2):
+ *   - Zero runtime deps.  Everything inlined.  Tailwind loaded from the
+ *     CDN only.  The gallery must open via `file://` with no dev server.
+ *   - No JS event handlers that try to write back to disk (file:// has
+ *     no privilege for that).  Picking happens by running a terminal
+ *     command — the gallery's job is to make the letter obvious and the
+ *     command copy-pasteable.
+ *   - Responsive grid: 1 column on narrow, 2 on medium, N on wide.
+ *   - Each variant iframe is rendered at full device-width-feel, not a
+ *     thumbnail, so the user can actually read the content.
+ */
+
+/**
+ * @typedef {{ letter: string, filename: string, style?: string, description?: string }} GalleryVariant
+ * @typedef {{ feature: string, iteration: string, variants: GalleryVariant[], taskDir: string }} GalleryInput
+ */
+
+// "N" colors come from the DESIGN.md scaffold palette so the gallery
+// chrome matches the tokens the variants are rendering against.  Keep
+// tailwind utilities — no custom CSS beyond the frame layout.
+const GALLERY_BG = 'bg-slate-950'
+const GALLERY_TEXT = 'text-slate-100'
+const ACCENT = 'text-indigo-400'
+
+/**
+ * Escape user-supplied strings that land inside HTML attribute values or
+ * text nodes.  This is the only place raw input touches the rendered
+ * document, so it's the only place we escape.
+ */
+function escapeHtml(s) {
+	if (typeof s !== 'string') return ''
+	return s
+		.replace(/&/g, '&')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&#39;')
+}
+
+/**
+ * Build the gallery HTML.
+ *
+ * @param {GalleryInput} input
+ * @returns {string}
+ */
+export function renderGallery(input) {
+	const { feature, iteration, variants, taskDir } = input
+	if (!Array.isArray(variants) || variants.length === 0) {
+		throw new Error('renderGallery: variants must be a non-empty array')
+	}
+
+	// grid-cols scales with variant count, capped at 4 columns on ultrawide
+	// (even N=5 runs get the 5th variant onto a second row for readability).
+	const cols = Math.min(variants.length, 4)
+	const gridCols = `xl:grid-cols-${cols}`
+
+	const cards = variants
+		.map((v) => {
+			const letter = escapeHtml(String(v.letter).toUpperCase())
+			const style = escapeHtml(v.style ?? '')
+			const description = escapeHtml(v.description ?? '')
+			const filename = escapeHtml(v.filename)
+
+			// Each iframe uses a relative src so the gallery works from
+			// anywhere (the browser resolves against the gallery file's URL).
+			return [
+				'      <article class="group overflow-hidden rounded-xl border border-slate-800 bg-slate-900 shadow-xl">',
+				'        <header class="flex items-center justify-between gap-3 border-b border-slate-800 px-4 py-3">',
+				'          <div class="flex items-center gap-3">',
+				`            <span class="inline-flex h-9 w-9 items-center justify-center rounded-md bg-indigo-500/10 text-lg font-bold ${ACCENT}">${letter}</span>`,
+				'            <div class="min-w-0">',
+				`              <div class="truncate text-sm font-semibold text-slate-100">${style || 'Variant'}</div>`,
+				`              <div class="truncate text-xs text-slate-400">${description}</div>`,
+				'            </div>',
+				'          </div>',
+				`          <code class="shrink-0 rounded bg-slate-800 px-2 py-1 text-xs text-slate-300">${filename}</code>`,
+				'        </header>',
+				`        <iframe src="${filename}" title="Variant ${letter}" loading="lazy" class="block h-[720px] w-full bg-white"></iframe>`,
+				'        <footer class="flex items-center justify-between gap-3 border-t border-slate-800 px-4 py-3">',
+				`          <div class="text-xs text-slate-500">Pick this one:</div>`,
+				`          <code class="rounded bg-slate-800 px-2 py-1 text-xs text-slate-100">/apt:mockup --pick ${letter.toLowerCase()}</code>`,
+				'        </footer>',
+				'      </article>',
+			].join('\n')
+		})
+		.join('\n')
+
+	const featureEsc = escapeHtml(feature)
+	const iterationEsc = escapeHtml(iteration)
+	const taskDirEsc = escapeHtml(taskDir)
+
+	return [
+		'<!doctype html>',
+		'<html lang="en">',
+		'  <head>',
+		'    <meta charset="utf-8" />',
+		'    <meta name="viewport" content="width=device-width, initial-scale=1" />',
+		`    <title>Variant gallery — ${featureEsc} (iteration ${iterationEsc})</title>`,
+		'    <script src="https://cdn.tailwindcss.com"></script>',
+		`    <!-- iteration: ${iterationEsc}  task_dir: ${taskDirEsc} -->`,
+		'  </head>',
+		`  <body class="${GALLERY_BG} ${GALLERY_TEXT} antialiased">`,
+		'    <main class="mx-auto max-w-[1600px] space-y-6 p-6 lg:p-8">',
+		'      <header class="flex flex-wrap items-end justify-between gap-4">',
+		'        <div>',
+		`          <div class="text-xs uppercase tracking-[0.2em] text-slate-500">Variant gallery · iteration ${iterationEsc}</div>`,
+		`          <h1 class="mt-1 text-2xl font-semibold text-slate-100">${featureEsc}</h1>`,
+		`          <p class="mt-1 text-sm text-slate-400">${variants.length} parallel generations. Open this page via <code>file://</code>, scan the iframes, pick the letter that lands.</p>`,
+		'        </div>',
+		'        <div class="flex flex-col gap-2 text-xs text-slate-400 sm:items-end">',
+		`          <div>Directory: <code class="text-slate-300">${taskDirEsc}/mockups/</code></div>`,
+		'          <div>Pick: run <code class="rounded bg-slate-800 px-2 py-1 text-slate-100">/apt:mockup --pick &lt;letter&gt;</code> in your terminal.</div>',
+		'        </div>',
+		'      </header>',
+		`      <div class="grid grid-cols-1 gap-4 md:grid-cols-2 ${gridCols}">`,
+		cards,
+		'      </div>',
+		'      <footer class="pt-6 text-center text-xs text-slate-500">',
+		`        Generated by <code>apt-tools variant-gallery</code> · iteration ${iterationEsc} · ${new Date().toISOString()}`,
+		'      </footer>',
+		'    </main>',
+		'  </body>',
+		'</html>',
+		'',
+	].join('\n')
+}
+
+const LETTER_ORDER = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']
+
+/**
+ * Turn a list of variant filenames (e.g.
+ * `iteration-001-variant-a.html`) into the structured GalleryVariant[]
+ * that renderGallery expects.  Filenames missing the `-variant-<letter>`
+ * segment are skipped; caller can surface a warning.
+ *
+ * @param {string[]} filenames — sibling filenames under mockups/
+ * @param {Record<string, { style?: string, description?: string } | undefined>} [styleByLetter]
+ * @returns {{ variants: GalleryVariant[], skipped: string[] }}
+ */
+export function variantEntriesFromFilenames(filenames, styleByLetter = {}) {
+	const re = /iteration-(\d{3})-variant-([a-z])\.html$/i
+	const seen = new Map()
+	const skipped = []
+	for (const raw of filenames) {
+		const m = raw.match(re)
+		if (!m) {
+			skipped.push(raw)
+			continue
+		}
+		const letter = m[2].toLowerCase()
+		const meta = styleByLetter[letter] ?? {}
+		seen.set(letter, {
+			letter,
+			filename: raw,
+			style: meta.style,
+			description: meta.description,
+		})
+	}
+	const variants = LETTER_ORDER.filter((l) => seen.has(l)).map(
+		(l) => /** @type {GalleryVariant} */ (seen.get(l)),
+	)
+	return { variants, skipped }
+}