@aperant/framework 0.6.2

package/src/cli/terminal/socket-client.mjs

@@ -0,0 +1,127 @@
+/**
+ * cli/terminal/socket-client.mjs — JSON-line client for AperantIpcServer.
+ *
+ * Pure node:net + node:readline. No external deps. Used by the apt-tools
+ * `terminal` subcommand to talk to the Electron main process's
+ * AperantIpcServer over the per-user, per-pid Unix-domain socket.
+ *
+ * Each request gets a UUID id and is correlated to the response on the
+ * same id. The default timeout is 10 s — on timeout the client destroys
+ * the underlying socket and rejects the request with `{ code: 'timeout' }`.
+ *
+ * Usage:
+ *   const client = await connectSocket('/tmp/aperant-andre-12345.sock')
+ *   const res = await client.request('health', {})
+ *   client.close()
+ */
+
+import { randomUUID } from 'node:crypto'
+import { createConnection } from 'node:net'
+import { createInterface } from 'node:readline'
+
+/**
+ * Open a connection to the given Unix-domain socket and return a thin
+ * request/response wrapper. Resolves once the underlying socket has
+ * emitted `connect`. Rejects on connect failure (ENOENT, ECONNREFUSED).
+ *
+ * @param {string} socketPath
+ * @returns {Promise<{ request: (cmd: string, payload?: any, timeoutMs?: number) => Promise<any>, close: () => void }>}
+ */
+export function connectSocket(socketPath) {
+	return new Promise((resolve, reject) => {
+		if (typeof socketPath !== 'string' || socketPath.length === 0) {
+			reject(new Error('connectSocket: socketPath must be a non-empty string'))
+			return
+		}
+
+		const sock = createConnection(socketPath)
+		/** @type {Map<string, { resolve: (v: any) => void, reject: (e: any) => void, timer: NodeJS.Timeout }>} */
+		const pending = new Map()
+		let connected = false
+		let closed = false
+
+		const onConnect = () => {
+			connected = true
+			sock.off('error', onConnectError)
+			const rl = createInterface({ input: sock, crlfDelay: Infinity })
+			rl.on('line', (line) => {
+				const trimmed = line.trim()
+				if (!trimmed) return
+				let msg
+				try {
+					msg = JSON.parse(trimmed)
+				} catch {
+					return // ignore garbage
+				}
+				const id = msg && typeof msg.id === 'string' ? msg.id : null
+				if (!id) return
+				const slot = pending.get(id)
+				if (!slot) return
+				clearTimeout(slot.timer)
+				pending.delete(id)
+				slot.resolve(msg)
+			})
+			resolve({
+				request(cmd, payload = {}, timeoutMs = 10000) {
+					if (closed) return Promise.reject(new Error('socket closed'))
+					const id = randomUUID()
+					const envelope = JSON.stringify({ id, cmd, payload })
+					return new Promise((rs, rj) => {
+						const timer = setTimeout(() => {
+							pending.delete(id)
+							try {
+								sock.destroy()
+							} catch {
+								/* ignore */
+							}
+							rj({ code: 'timeout', message: `request '${cmd}' timed out after ${timeoutMs}ms` })
+						}, timeoutMs)
+						pending.set(id, { resolve: rs, reject: rj, timer })
+						try {
+							sock.write(`${envelope}\n`)
+						} catch (err) {
+							clearTimeout(timer)
+							pending.delete(id)
+							rj({
+								code: 'write_failed',
+								message: err instanceof Error ? err.message : String(err),
+							})
+						}
+					})
+				},
+				close() {
+					closed = true
+					for (const [, slot] of pending) {
+						clearTimeout(slot.timer)
+						slot.reject({ code: 'closed', message: 'socket closed by caller' })
+					}
+					pending.clear()
+					try {
+						sock.destroy()
+					} catch {
+						/* ignore */
+					}
+				},
+			})
+		}
+
+		const onConnectError = (err) => {
+			if (connected) return
+			reject(err)
+		}
+
+		sock.once('connect', onConnect)
+		sock.once('error', onConnectError)
+		// If the server side disconnects after we are connected, fail every
+		// pending request with a `disconnected` code.
+		sock.once('close', () => {
+			if (!connected) return
+			for (const [, slot] of pending) {
+				clearTimeout(slot.timer)
+				slot.reject({ code: 'disconnected', message: 'socket closed by server' })
+			}
+			pending.clear()
+			closed = true
+		})
+	})
+}

package/src/cli/util/agent-runtime.mjs

@@ -0,0 +1,28 @@
+/**
+ * agent-runtime.mjs — pure env-var sniff used by `init` to label which
+ * agent CLI is at the prompt. Spec R4 calls this out as messaging-only:
+ * the result NEVER changes which codepath runs, only what gets surfaced
+ * in the `requires_input` envelope's `agent_runtime` field and in the
+ * `why` strings.
+ *
+ * Deterministic precedence (claude-code > cursor > aider > unknown) so
+ * concurrent envs (e.g. CLAUDECODE + CURSOR_TRACE_ID both set) resolve
+ * to a single stable label.
+ */
+
+/** @typedef {'claude-code'|'cursor'|'aider'|'unknown'} AgentRuntimeId */
+
+/**
+ * Inspect `env` (defaults to process.env) and return the detected agent.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {AgentRuntimeId}
+ */
+export function detectAgentRuntime(env = process.env) {
+	if (env.CLAUDECODE) return 'claude-code'
+	for (const k of Object.keys(env)) {
+		if (k.startsWith('CURSOR_')) return 'cursor'
+		if (k.startsWith('AIDER_')) return 'aider'
+	}
+	return 'unknown'
+}

package/src/cli/util/args.mjs

@@ -0,0 +1,26 @@
+/**
+ * args.mjs — flag parsing extracted from apt-tools.mjs (C29).
+ */
+
+/**
+ * Parse flags from an args array. Supports both `--flag value` pairs and
+ * bare boolean `--flag` forms (value becomes `true` when the flag has no
+ * following non-flag argument).
+ * Returns a Map of flag name (without --) to string | true.
+ */
+export function parseFlags(args) {
+	const flags = new Map()
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i]
+		if (!arg.startsWith('--')) continue
+		const key = arg.slice(2)
+		const next = args[i + 1]
+		if (next !== undefined && !next.startsWith('--')) {
+			flags.set(key, next)
+			i++ // skip value
+		} else {
+			flags.set(key, true)
+		}
+	}
+	return flags
+}

package/src/cli/util/atomic-write.mjs

@@ -0,0 +1,147 @@
+/**
+ * atomic-write.mjs — hardened atomic JSON + JSONL writers (R3).
+ *
+ * Split out from util/io.mjs so the primitive can be reasoned about in
+ * isolation. `util/io.mjs` re-exports `atomicWriteJson` byte-for-byte so every
+ * existing `import { atomicWriteJson } from '../util/io.mjs'` call site keeps
+ * working.
+ *
+ * atomicWriteJson hardens the write with an explicit fsync on the tmp fd
+ * before rename. Without fsync, a SIGKILL between writeFileSync's return and
+ * renameSync can leave the tmp file zero-length or partially flushed; with
+ * fsync, the tmp file is durable before the rename publishes it as the new
+ * target.
+ *
+ * appendJsonl provides an O_APPEND-based append for the R10 per-day event log.
+ * On POSIX, small O_APPEND writes (well under PIPE_BUF) are atomic across
+ * processes — two agents appending concurrently cannot interleave bytes. On
+ * Windows, we guard the append with withFileLock as a conservative fallback.
+ */
+
+import {
+	closeSync,
+	fsyncSync,
+	mkdirSync,
+	openSync,
+	renameSync,
+	unlinkSync,
+	writeSync,
+} from 'node:fs'
+import { dirname } from 'node:path'
+import { withFileLock } from './fs-lock.mjs'
+
+/**
+ * Atomic JSON write: open tmp with `wx` (exclusive), write, fsync, close,
+ * rename. The tmp name includes pid + high-resolution timestamp so two writes
+ * from the same PID to the same target cannot collide (important for R10's
+ * event log where the caller may issue successive appends in the same tick).
+ *
+ * Public contract: same signature as the legacy util/io.mjs version. Throws
+ * on I/O errors (callers already handle via try/catch or let the CLI fail).
+ */
+export function atomicWriteJson(targetPath, data) {
+	const tmpPath = `${targetPath}.tmp.${process.pid}.${Date.now()}.${Math.random()
+		.toString(36)
+		.slice(2, 8)}`
+	mkdirSync(dirname(targetPath), { recursive: true })
+	const payload = JSON.stringify(data, null, 2) + '\n'
+	let fd = null
+	try {
+		// `wx` refuses to overwrite an existing tmp file — the uuid-ish suffix
+		// makes collisions statistically impossible but we still fail loud if
+		// one does occur.
+		fd = openSync(tmpPath, 'wx')
+		writeSync(fd, payload, 0, 'utf-8')
+		fsyncSync(fd)
+	} catch (err) {
+		if (fd !== null) {
+			try {
+				closeSync(fd)
+			} catch {
+				/* already closed or invalid */
+			}
+		}
+		try {
+			unlinkSync(tmpPath)
+		} catch {
+			/* tmp may not exist */
+		}
+		throw err
+	}
+	closeSync(fd)
+	renameSync(tmpPath, targetPath)
+}
+
+/**
+ * Atomically write a UTF-8 string to `targetPath`. Creates parent dirs as
+ * needed. Same crash-safety contract as atomicWriteJson: tmp file with `wx`
+ * (exclusive create), write, fsync, rename to target.
+ *
+ * @param {string} targetPath
+ * @param {string} content
+ */
+export function atomicWriteText(targetPath, content) {
+	mkdirSync(dirname(targetPath), { recursive: true })
+	const tmpPath = `${targetPath}.tmp.${process.pid}.${Date.now()}.${Math.random()
+		.toString(36)
+		.slice(2, 8)}`
+	let fd = null
+	try {
+		fd = openSync(tmpPath, 'wx')
+		writeSync(fd, content, 0, 'utf-8')
+		fsyncSync(fd)
+	} catch (err) {
+		if (fd !== null) {
+			try {
+				closeSync(fd)
+			} catch {
+				/* ignore */
+			}
+		}
+		try {
+			unlinkSync(tmpPath)
+		} catch {
+			/* ignore */
+		}
+		throw err
+	}
+	closeSync(fd)
+	renameSync(tmpPath, targetPath)
+}
+
+/**
+ * Append a single JSON-encoded line (+ trailing `\n`) to `targetPath`.
+ *
+ * POSIX: open with `a` (O_APPEND) so the OS serializes the seek+write; small
+ * writes under PIPE_BUF are atomic across concurrent writers, which is exactly
+ * the guarantee the R10 event log needs (multiple agents writing to the same
+ * day's JSONL).
+ *
+ * Windows: `a` is not guaranteed atomic across processes, so wrap the append
+ * in withFileLock — slower but correct.
+ */
+export function appendJsonl(targetPath, obj) {
+	mkdirSync(dirname(targetPath), { recursive: true })
+	const line = `${JSON.stringify(obj)}\n`
+
+	if (process.platform === 'win32') {
+		withFileLock(targetPath, () => {
+			const fd = openSync(targetPath, 'a')
+			try {
+				writeSync(fd, line, null, 'utf-8')
+				fsyncSync(fd)
+			} finally {
+				closeSync(fd)
+			}
+		})
+		return
+	}
+
+	const fd = openSync(targetPath, 'a')
+	try {
+		writeSync(fd, line, null, 'utf-8')
+		fsyncSync(fd)
+	} finally {
+		closeSync(fd)
+	}
+}

package/src/cli/util/banner.mjs

@@ -0,0 +1,57 @@
+/**
+ * util/banner.mjs — Aperant install masthead.
+ *
+ * Prints the APERANT wordmark in the brand's antique-gold palette
+ * (#C5A94E and siblings from dove-banner.svg) above the clack
+ * multiselect. We use the `ANSI Shadow` figlet shape — same style
+ * GSD uses — because it's the most legible at 58 cols and degrades
+ * cleanly when copy-pasted (all chars are in the Unicode Box Drawing
+ * and Block Elements ranges, no emoji).
+ *
+ * Honors NO_COLOR (https://no-color.org) and falls back to plain
+ * text when stdout is not a TTY so piped output stays parseable.
+ */
+
+/** ANSI 256 gold — closest preset to #C5A94E without needing truecolor. */
+const GOLD = '\x1b[38;5;178m'
+/** Dimmer gold for subtitle text. */
+const GOLD_DIM = '\x1b[38;5;136m'
+const RESET = '\x1b[0m'
+
+/** Six-row ANSI-Shadow wordmark. Exactly one leading space per row. */
+const APERANT_LINES = [
+	' █████╗ ██████╗ ███████╗██████╗  █████╗ ███╗   ██╗████████╗',
+	'██╔══██╗██╔══██╗██╔════╝██╔══██╗██╔══██╗████╗  ██║╚══██╔══╝',
+	'███████║██████╔╝█████╗  ██████╔╝███████║██╔██╗ ██║   ██║   ',
+	'██╔══██║██╔═══╝ ██╔══╝  ██╔══██╗██╔══██║██║╚██╗██║   ██║   ',
+	'██║  ██║██║     ███████╗██║  ██║██║  ██║██║ ╚████║   ██║   ',
+	'╚═╝  ╚═╝╚═╝     ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝   ╚═╝   ',
+]
+
+/**
+ * Whether to emit ANSI color escape codes.
+ * @returns {boolean}
+ */
+function colorsEnabled() {
+	if (process.env.NO_COLOR) return false
+	if (!process.stdout.isTTY) return false
+	return true
+}
+
+/**
+ * Render the install masthead as a single multi-line string suitable
+ * for clack.intro(). Includes version + tagline.
+ *
+ * @param {string} version  Framework semver (e.g. "0.1.4").
+ * @returns {string}
+ */
+export function aperantBanner(version) {
+	const color = colorsEnabled()
+	const gold = color ? GOLD : ''
+	const dim = color ? GOLD_DIM : ''
+	const reset = color ? RESET : ''
+
+	const lines = APERANT_LINES.map((l) => `${gold}${l}${reset}`).join('\n')
+	const tagline = `${dim}framework v${version} · AI coding for the full lifecycle${reset}`
+	return `${lines}\n\n${tagline}`
+}

package/src/cli/util/bin-path.mjs

@@ -0,0 +1,72 @@
+/**
+ * bin-path.mjs — D-03 single source of truth for the apt-tools binary path.
+ *
+ * Several Layer 1 commands re-spawn `apt-tools <subcommand>` (worktree,
+ * worktree-install, task) and historically each call site had its own
+ * `process.argv[1]` heuristic + fallback chain. After D-03 they all go
+ * through `resolveAptToolsBin(projectDir)` so the resolution lives in one
+ * place and tests can override it via `APT_TOOLS_BIN_PATH`.
+ *
+ * Resolution order (5-step fallback chain):
+ *
+ *   1. process.env.APT_TOOLS_BIN_PATH      — explicit override (test seam).
+ *   2. process.argv[1]                     — when invoked as the CLI entrypoint
+ *                                            and the path ends with
+ *                                            `apt-tools.mjs`. Vitest workers,
+ *                                            REPLs, and `node -e ...` invocations
+ *                                            do NOT match this branch.
+ *   3. <projectDir>/packages/framework/bin/apt-tools.mjs   — monorepo path.
+ *   4. <projectDir>/.aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs
+ *      — consumer-install (bootstrap-script) path.
+ *   5. 'apt-tools'                         — last-resort, relies on $PATH.
+ *
+ * Layer 1 commands MUST NOT read `process.argv[1]` directly; this module is
+ * the only sanctioned consumer of that signal.
+ */
+
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+/**
+ * @param {string} projectDir
+ * @returns {string} absolute path to apt-tools.mjs, or 'apt-tools' as a
+ *   $PATH fallback. Never throws — callers spawn the returned path; if it
+ *   doesn't resolve at exec time the spawn fails with the usual ENOENT.
+ */
+export function resolveAptToolsBin(projectDir) {
+	// Step 1 — explicit override (used by tests and integration harnesses).
+	const override = process.env.APT_TOOLS_BIN_PATH
+	if (override && override.length > 0) {
+		return override
+	}
+
+	// Step 2 — process.argv[1] when it points at our binary. Vitest worker
+	// argv[1] is the runner, not apt-tools.mjs; REPL argv[1] is empty; only
+	// real CLI invocations have argv[1] ending with `apt-tools.mjs`.
+	const argv1 = process.argv[1]
+	if (typeof argv1 === 'string' && argv1.endsWith('apt-tools.mjs')) {
+		return argv1
+	}
+
+	// Step 3 — monorepo path under the supplied project directory.
+	if (typeof projectDir === 'string' && projectDir.length > 0) {
+		const monorepoBin = resolve(projectDir, 'packages/framework/bin/apt-tools.mjs')
+		if (existsSync(monorepoBin)) {
+			return monorepoBin
+		}
+
+		// Step 4 — consumer-install path (bootstrap script lays this layout out
+		// under <projectDir>/.aperant/deps/).
+		const consumerBin = resolve(
+			projectDir,
+			'.aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs',
+		)
+		if (existsSync(consumerBin)) {
+			return consumerBin
+		}
+	}
+
+	// Step 5 — last-resort: rely on $PATH. The caller will surface ENOENT if
+	// `apt-tools` is not on PATH.
+	return 'apt-tools'
+}

package/src/cli/util/common-flags.mjs

@@ -0,0 +1,37 @@
+/**
+ * common-flags.mjs — shared argument-parsing helpers for new subcommand
+ * modules (bootstrap, personas, create-docs). Extracted to eliminate the
+ * three byte-identical copies that previously lived in each command file.
+ *
+ * These helpers are intentionally minimal — no option parsing library
+ * required for a well-scoped CLI surface.
+ */
+
+import { resolve } from 'node:path'
+
+/**
+ * Resolve the first positional argument as a project directory, defaulting to
+ * `process.cwd()`. Flag arguments (prefixed `--`) are skipped.
+ *
+ * @param {string[]} args
+ * @returns {string}
+ */
+export function resolveProjectDir(args) {
+	const positional = args.find((a) => !a.startsWith('--'))
+	return resolve(positional && positional.length > 0 ? positional : '.')
+}
+
+/**
+ * Pull the string value that follows a named flag, e.g. `--mode extend` → `'extend'`.
+ * Returns `null` when the flag is absent or has no following argument.
+ *
+ * @param {string[]} args
+ * @param {string} flag
+ * @returns {string | null}
+ */
+export function getFlagValue(args, flag) {
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === flag && args[i + 1] !== undefined) return args[i + 1]
+	}
+	return null
+}

package/src/cli/util/copy.mjs

@@ -0,0 +1,95 @@
+/**
+ * copy.mjs — filesystem copy + instruction-file injection helpers (C29).
+ *
+ * `copyDirRecursive` is a pure leaf; `injectInstructionFile` owns the
+ * CLAUDE.md / AGENTS.md "<!-- APT:framework-* -->" section template.
+ */
+
+import {
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	writeFileSync,
+} from 'node:fs'
+import { join } from 'node:path'
+
+export function copyDirRecursive(src, dest) {
+	mkdirSync(dest, { recursive: true })
+	for (const entry of readdirSync(src, { withFileTypes: true })) {
+		const srcPath = join(src, entry.name)
+		const destPath = join(dest, entry.name)
+		if (entry.isDirectory()) {
+			copyDirRecursive(srcPath, destPath)
+		} else {
+			copyFileSync(srcPath, destPath)
+		}
+	}
+}
+
+const APT_SECTION = `<!-- APT:framework-start -->
+## Aperant Framework
+
+This project uses the [Aperant Framework](https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework) for AI-assisted development.
+
+### Available Skills
+| Skill | Description |
+|-------|-------------|
+| \`/apt\` | Smart router — auto-detects context, routes to the right skill |
+| \`/apt:quick\` | Fast task execution — skip planning, go straight to implementation |
+| \`/apt:discuss\` | Interactive decision-making — assumptions, gray areas, power mode |
+| \`/apt:debug\` | Systematic debugging with persistent state across context resets |
+| \`/apt:scan\` | Scan codebase to build/refresh the feature registry (recommended after setup) |
+| \`/apt:plan\` | Analyze a task, investigate codebase, produce spec + implementation plan |
+| \`/apt:execute\` | Implement subtasks from a plan with atomic commits |
+| \`/apt:verify\` | Score implementation on 4 dimensions (correctness, completeness, quality, coverage) |
+| \`/apt:verify-proof\` | Visual proof verification — screenshots, video, HTML report with feature checklists |
+| \`/apt:review\` | 6-pass inline code review (logic / security / quality / architecture / performance / docs-coherence) with auto-fix pipeline |
+| \`/apt:pr-review\` | Multi-agent PR review — 6 parallel specialists, validator, fixer, self-reviewer (owned / external authorship) |
+| \`/apt:run\` | Full pipeline: plan → execute → verify → review |
+| \`/apt:roundtable\` | 10-agent structured debate for complex decisions |
+| \`/apt:stress-test\` | Scenario simulation to catch gaps in plans |
+| \`/apt:ship\` | Create PR with QA scores and decision traceability |
+| \`/apt:pause\` | Human-initiated session handoff — save state when YOU need to stop (not for agent-initiated bailouts) |
+| \`/apt:resume\` | Restore context from a paused session and route to next action |
+| \`/apt:docs\` | Generate/update documentation verified against the actual codebase |
+| \`/apt:setup\` | Change framework preferences (verification style, multi-model, branching) |
+
+### Feature Registry
+The feature registry (\`.aperant/features/\`) is a living inventory of every interactive
+feature in the app. It's the source of truth for what to verify and review.
+
+- **Created by:** \`/apt:scan\` (initial scan or full refresh)
+- **Updated by:** \`/apt:execute\` post-step (\`apt-tools features-audit --apply-stubs\` auto-registers new UI/core/hook/IPC files per the docs-coherence policy)
+- **Consumed by:** \`/apt:verify-proof\` (generates test cases from registry)
+- **Checked by:** \`/apt:review\` Pass 6 (flags unregistered new components, applies stubs for auto-update policies)
+
+Run \`/apt:scan\` after setting up Aperant on a brownfield project, or after major changes.
+
+### Config
+- Settings: \`.aperant/config.json\` (run \`/apt:setup\` to change)
+- Features: \`.aperant/features/\` (feature registry -- run \`/apt:scan\` to create)
+- State: \`.aperant/state.json\` (execution state)
+- Evidence: \`.aperant/proof/\` (proof reports and screenshots)
+- Prompts: \`.aperant/prompts/\` (agent prompt templates)
+<!-- APT:framework-end -->`
+
+export function injectInstructionFile(filePath) {
+	const existing = existsSync(filePath) ? readFileSync(filePath, 'utf-8') : ''
+
+	if (existing.includes('<!-- APT:framework-start -->')) {
+		// Update existing section in-place
+		const updated = existing.replace(
+			/<!-- APT:framework-start -->[\s\S]*?<!-- APT:framework-end -->/,
+			APT_SECTION,
+		)
+		writeFileSync(filePath, updated, 'utf-8')
+		return 'updated'
+	}
+
+	// Append
+	const separator = existing.length > 0 ? '\n\n' : ''
+	writeFileSync(filePath, existing + separator + APT_SECTION + '\n', 'utf-8')
+	return 'created'
+}

package/src/cli/util/duration.mjs

@@ -0,0 +1,67 @@
+/**
+ * @internal
+ * duration.mjs — parse human-friendly duration strings into milliseconds (C56 A4).
+ *
+ * Accepted format: `<N><unit>` where `N` is a non-negative integer and
+ * `unit ∈ {s, h, d, w, m, y}` for seconds, hours, days, weeks, months, years.
+ *
+ * Month and year use canonical approximations (30d and 365d respectively) —
+ * they are *retention* thresholds, not clock arithmetic, so fixed-step values
+ * are safer than locale-dependent calendar math.
+ *
+ * Examples:
+ *   parseDuration('30d')  → 2_592_000_000
+ *   parseDuration('2w')   → 1_209_600_000
+ *   parseDuration('6m')   → 15_552_000_000
+ *   parseDuration('0d')   → 0
+ *   parseDuration('1h')   → 3_600_000
+ *   parseDuration('30')   → throws (missing unit)
+ *   parseDuration('30x')  → throws (unknown unit)
+ *   parseDuration('')     → throws (empty)
+ */
+
+/**
+ * @param {string} str
+ * @returns {number} milliseconds (integer, >= 0)
+ * @throws {Error} with `code: 'invalid-duration'` on malformed input
+ * @internal
+ */
+export function parseDuration(str) {
+	if (typeof str !== 'string') {
+		const err = new Error(`parseDuration: expected string, got ${typeof str}`)
+		err.code = 'invalid-duration'
+		throw err
+	}
+	const trimmed = str.trim()
+	if (trimmed.length === 0) {
+		const err = new Error('parseDuration: empty string')
+		err.code = 'invalid-duration'
+		throw err
+	}
+	const match = /^(\d+)([shdwmy])$/i.exec(trimmed)
+	if (!match) {
+		const err = new Error(
+			`parseDuration: invalid duration "${str}" (expected "<N><unit>" where unit ∈ s/h/d/w/m/y)`,
+		)
+		err.code = 'invalid-duration'
+		throw err
+	}
+	const n = Number.parseInt(match[1], 10)
+	if (!Number.isFinite(n) || n < 0) {
+		const err = new Error(`parseDuration: invalid magnitude "${match[1]}"`)
+		err.code = 'invalid-duration'
+		throw err
+	}
+	const unit = match[2].toLowerCase()
+	const ms = n * UNIT_MS[unit]
+	return ms
+}
+
+const UNIT_MS = Object.freeze({
+	s: 1000,
+	h: 60 * 60 * 1000,
+	d: 24 * 60 * 60 * 1000,
+	w: 7 * 24 * 60 * 60 * 1000,
+	m: 30 * 24 * 60 * 60 * 1000,
+	y: 365 * 24 * 60 * 60 * 1000,
+})