@orkestrel/scaffold 0.0.77 → 0.0.78

package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts

@@ -0,0 +1,242 @@
+// Work the npm authentication window. Run from the checkout root:
+//   node .agents/skills/orkestrel-publish/scripts/window.ts --whoami [--wait SECONDS]
+//   node .agents/skills/orkestrel-publish/scripts/window.ts --login [--wait SECONDS]
+//   node .agents/skills/orkestrel-publish/scripts/window.ts --publish DIR... --otp CODE [--json]
+//   node .agents/skills/orkestrel-publish/scripts/window.ts --confirm NAME@VERSION... [--wait SECONDS]
+// --whoami reads `npm whoami` once, or polls it every 5 seconds until it answers or the wait ends.
+// --login prints the command the operator runs in a real terminal (npm offers its approval only to a
+// TTY, so no child of this script can hold it), then polls `npm whoami` until it answers or the wait
+// ends. --publish re-reads `npm whoami` immediately before the first upload and refuses when it
+// answers nothing, then runs `npm publish --ignore-scripts --browser=false --otp=CODE` in each
+// directory back to back under captured pipes (npm's non-TTY guard turns a refused code into
+// EOTP with no prompt, so the path needs no TTY), journals each upload to tmp/units/publish-<name>.log, reads the `+ name@version`
+// acceptance line, stops at the first refusal and names the package to resume from, then confirms
+// each accepted version against the registry. --confirm re-reads the registry for each name@version every 5
+// seconds until it serves the version or the wait (default 120 seconds) ends. Exit 0 when the mode
+// succeeded, 3 when it did not, 64 on usage.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+	readList,
+	readMissingFlags,
+	readOption,
+	readString,
+	runNpm,
+} from '../../orkestrel-dispatch/scripts/helpers.ts'
+
+const POLL_MS = 5_000
+const ACCEPTED = /^\+ (\S+)@(\S+)\s*$/mu
+
+interface Upload {
+	readonly directory: string
+	readonly name: string | undefined
+	readonly version: string | undefined
+	readonly exit: number | undefined
+	readonly accepted: boolean
+	readonly confirmed: boolean
+	readonly code: string | undefined
+	readonly journal: string
+}
+
+function waitFor(ms: number): Promise<void> {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms)
+	})
+}
+
+function readWhoami(): string | undefined {
+	const result = runNpm(['whoami'])
+	const user = result.stdout.trim()
+	return result.status === 0 && user !== '' ? user : undefined
+}
+
+async function pollWhoami(waitSeconds: number): Promise<string | undefined> {
+	const started = Date.now()
+	let user = readWhoami()
+	while (user === undefined && Date.now() - started < waitSeconds * 1000) {
+		await waitFor(POLL_MS)
+		user = readWhoami()
+	}
+	return user
+}
+
+function readServed(name: string, version: string): boolean {
+	const result = runNpm(['view', `${name}@${version}`, 'version', '--json'])
+	return result.status === 0 && result.stdout.replace(/["\s]/gu, '') === version
+}
+
+async function confirmServed(name: string, version: string, waitSeconds: number): Promise<boolean> {
+	const started = Date.now()
+	let served = readServed(name, version)
+	while (!served && Date.now() - started < waitSeconds * 1000) {
+		await waitFor(POLL_MS)
+		served = readServed(name, version)
+	}
+	return served
+}
+
+function readErrorCode(text: string): string | undefined {
+	return text.match(/\b(E[A-Z0-9]{3,}|EOTP|E401|E403|E404)\b/u)?.[1]
+}
+
+function readManifestName(directory: string): {
+	readonly name: string | undefined
+	readonly version: string | undefined
+} {
+	const path = join(directory, 'package.json')
+	if (!existsSync(path)) return { name: undefined, version: undefined }
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
+		if (typeof parsed !== 'object' || parsed === null)
+			return { name: undefined, version: undefined }
+		const record = Object.fromEntries(Object.entries(parsed))
+		return { name: readString(record, 'name'), version: readString(record, 'version') }
+	} catch {
+		return { name: undefined, version: undefined }
+	}
+}
+
+async function publishAll(
+	directories: readonly string[],
+	otp: string,
+	waitSeconds: number,
+): Promise<readonly Upload[]> {
+	mkdirSync('tmp/units', { recursive: true })
+	const uploads: Upload[] = []
+	for (const directory of directories) {
+		const manifest = readManifestName(directory)
+		const journal = `tmp/units/publish-${(manifest.name ?? directory).replace(/[^A-Za-z0-9.-]+/gu, '-')}.log`
+		const result = runNpm(
+			['publish', '--ignore-scripts', '--browser=false', `--otp=${otp}`],
+			directory,
+		)
+		writeFileSync(journal, `${result.stdout}\n${result.stderr}\nexit=${result.status ?? 'null'}\n`)
+		const match = `${result.stdout}\n${result.stderr}`.match(ACCEPTED)
+		const accepted = result.status === 0 && match !== null
+		const name = match?.[1] ?? manifest.name
+		const version = match?.[2] ?? manifest.version
+		const upload: Upload = {
+			directory,
+			name,
+			version,
+			exit: result.status ?? undefined,
+			accepted,
+			confirmed: false,
+			code: accepted ? undefined : readErrorCode(result.stderr),
+			journal,
+		}
+		if (!accepted) {
+			uploads.push(upload)
+			console.error(
+				`window: ${name ?? directory} refused (${upload.code ?? `exit ${String(result.status)}`}); resume from it on a fresh code`,
+			)
+			break
+		}
+		console.error(`window: accepted ${name ?? '?'}@${version ?? '?'}`)
+		uploads.push(upload)
+	}
+	const confirmed: Upload[] = []
+	for (const upload of uploads) {
+		if (!upload.accepted || upload.name === undefined || upload.version === undefined) {
+			confirmed.push(upload)
+			continue
+		}
+		confirmed.push({
+			...upload,
+			confirmed: await confirmServed(upload.name, upload.version, waitSeconds),
+		})
+	}
+	return confirmed
+}
+
+async function main(argv: readonly string[]): Promise<number> {
+	const missing = readMissingFlags(argv, ['--wait', '--otp'])
+	if (missing.length > 0) {
+		console.error(`window: ${missing.join(', ')} given with no value`)
+		return 64
+	}
+	const wait = Number(readOption(argv, '--wait') ?? 120)
+	const modes = ['--whoami', '--login', '--publish', '--confirm'].filter((flag) =>
+		argv.includes(flag),
+	)
+	if (modes.length > 1 || (argv.includes('--wait') && (!Number.isFinite(wait) || wait < 0))) {
+		console.error(
+			'usage: window.ts names one mode (--whoami | --login | --publish | --confirm), and --wait takes a number of seconds',
+		)
+		return 64
+	}
+	if (argv.includes('--whoami')) {
+		const user = await pollWhoami(argv.includes('--wait') ? wait : 0)
+		console.log(JSON.stringify({ mode: 'whoami', user, live: user !== undefined }))
+		return user === undefined ? 3 : 0
+	}
+	if (argv.includes('--login')) {
+		const command =
+			process.platform === 'win32'
+				? 'npm login --browser=false'
+				: "script -qfc 'npm login --browser=false' tmp/units/npm-login.log"
+		console.error(
+			`window: run this in a real terminal, then approve the URL it prints on its first line: ${command}`,
+		)
+		const user = await pollWhoami(argv.includes('--wait') ? wait : 300)
+		console.log(JSON.stringify({ mode: 'login', command, user, live: user !== undefined }))
+		return user === undefined ? 3 : 0
+	}
+	if (argv.includes('--publish')) {
+		const directories = readList(argv, '--publish')
+		const otp = readOption(argv, '--otp')
+		if (
+			directories.length === 0 ||
+			otp === undefined ||
+			!/^\d{6,8}$/u.test(otp) ||
+			directories.some((directory) => !existsSync(join(directory, 'package.json')))
+		) {
+			console.error(
+				"usage: window.ts --publish DIR... --otp CODE [--wait SECONDS] [--json]; every DIR carries a package.json and CODE is the account's one-time code",
+			)
+			return 64
+		}
+		// A stored credential expires mid-session, so the session-start answer does not hold here.
+		if (readWhoami() === undefined) {
+			console.error(
+				'window: npm whoami answers nothing immediately before the upload; run --login first',
+			)
+			return 3
+		}
+		const uploads = await publishAll(directories, otp, wait)
+		if (argv.includes('--json')) console.log(JSON.stringify({ mode: 'publish', uploads }))
+		else {
+			for (const upload of uploads) {
+				console.log(
+					`window: ${upload.directory}\t${upload.name ?? '?'}@${upload.version ?? '?'}\t${upload.accepted ? 'accepted' : `refused ${upload.code ?? String(upload.exit)}`}\t${upload.confirmed ? 'confirmed' : 'unconfirmed'}\t${upload.journal}`,
+				)
+			}
+		}
+		return uploads.every((upload) => upload.accepted && upload.confirmed) ? 0 : 3
+	}
+	if (argv.includes('--confirm')) {
+		const targets = readList(argv, '--confirm')
+		if (targets.length === 0 || targets.some((target) => !/^@?[^@]+@\S+$/u.test(target))) {
+			console.error('usage: window.ts --confirm NAME@VERSION... [--wait SECONDS]')
+			return 64
+		}
+		const readings: Array<{ readonly target: string; readonly served: boolean }> = []
+		for (const target of targets) {
+			const at = target.lastIndexOf('@')
+			readings.push({
+				target,
+				served: await confirmServed(target.slice(0, at), target.slice(at + 1), wait),
+			})
+		}
+		console.log(JSON.stringify({ mode: 'confirm', readings }))
+		return readings.every((reading) => reading.served) ? 0 : 3
+	}
+	console.error(
+		'usage: window.ts --whoami [--wait SECONDS] | --login [--wait SECONDS] | --publish DIR... --otp CODE [--json] | --confirm NAME@VERSION... [--wait SECONDS]',
+	)
+	return 64
+}
+
+main(process.argv.slice(2)).then((code) => {
+	process.exitCode = code
+})

package/dist/host/agents/skills/orkestrel-scout/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: orkestrel-scout
+description: >-
+  Map terrain mechanically before anyone reads it: file trees with line counts, Markdown headings, export lines, a term census, the files that name a path, and unresolved `§` cross-references, written once and handed to the lane that reads. Use before writing a brief, before a Grok absorption lane, before a rename or a sweep, when a dispatch names the `scout` role, or whenever a question is "where is", "how big is", "what names this", or "which files carry this term".
+---
+
+# Scout
+
+A map is mechanical; reading is not. Run the map first, hand it to the reader, and let the reader spend its context on judgment.
+
+## Scripts
+
+| Script           | Does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `scripts/map.ts` | `--tree PATH...` files with line counts and sizes; `--headings PATH...` Markdown headings with lines; `--frontmatter PATH...` every key of a frontmatter block, a TOML file, or a YAML file with its whole value, nested keys dotted (`interface.default_prompt`); `--exports PATH...` `export` lines in TypeScript files (a text reading); `--census TERM...` every line carrying a term; `--refs PATH` every line naming a path or its basename; `--anchors PATH...` every `§ Heading` reference whose heading its target lacks. `--paths a,b` narrows a census or refs walk; `--ignore-case`; `--json`; `--out FILE` writes the map instead of printing it. Walks skip `node_modules`, `.git`, `dist`, `tmp`, `.orkestrel`, `.idea`, and `host.json`. |
+
+## Map
+
+1. Name the question and the roots it covers. Refuse an unbounded one.
+2. Run `node .agents/skills/orkestrel-scout/scripts/map.ts` with the modes the question needs, in one call. Write the map to `tmp/units/<unit>-map.txt` (or `.json`) when a lane will read it; print it when you will.
+3. For a rename or a deletion, run `--refs <path>` and `--census <name>` and own every file that comes back.
+4. Before an absorption lane, put the map's path in the brief and strike from the brief every question the map already answers; the lane reads and judges, it does not enumerate.
+5. Before a brief, read `--anchors` over the files the brief names; repair the references that block the brief and report the rest.
+
+## Refuse
+
+- A question that needs reading at depth or a judgment: route it to `grok`, `distiller`, or the reviewer the size gate names, with the map attached.
+- A census over a term shorter than three characters without `--paths`.

package/dist/host/agents/skills/orkestrel-scout/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Scout Orkestrel Terrain'
+  short_description: 'Map files, headings, exports, terms, and references mechanically'
+  default_prompt: 'Use $orkestrel-scout to map the terrain a brief or a lane needs before anyone reads it.'

package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts

@@ -0,0 +1,352 @@
+// Map terrain before a brief, an absorption lane, or a rename. Run from the checkout root:
+//   node .agents/skills/orkestrel-scout/scripts/map.ts --tree PATH... [--headings PATH...] [--frontmatter PATH...] [--exports PATH...] [--census TERM...] [--refs PATH] [--anchors PATH...] [--paths a,b] [--ignore-case] [--json] [--out FILE]
+// --tree lists every file under each path with its line count and size. --headings lists every
+// Markdown heading with its line. --frontmatter lists every key of a Markdown frontmatter block, a
+// TOML file, or a YAML file with its whole value, a nested key dotted under its parents
+// (`interface.default_prompt`) and a TOML key under its table. --exports lists every `export`
+// declaration line in a TypeScript file (a text reading, not the compiler's). --census lists every line carrying a term. --refs lists
+// every line naming a path or its basename. --anchors lists every `§ Heading` reference whose
+// heading the named file, or the same file, does not carry. Walks skip node_modules, .git, dist,
+// tmp, .orkestrel, .idea, and host.json; --paths narrows a census or refs walk. Modes combine, each
+// printing its section; --json prints one object; --out writes the output to FILE instead of the
+// terminal. Give each flag once; a later duplicate is not read. Exit 0, or 64 when no mode is
+// given or --refs names no path.
+import { existsSync, readFileSync, statSync, mkdirSync, writeFileSync } from 'node:fs'
+import { basename, dirname } from 'node:path'
+import {
+	listFiles,
+	normalizeSlashes,
+	readList,
+	readMissingFlags,
+	readOption,
+} from '../../orkestrel-dispatch/scripts/helpers.ts'
+
+const EXPORT =
+	/^export\s+(?:default\s+)?(?:async\s+)?(?:abstract\s+)?(function\*?|const|let|class|interface|type|enum|namespace)\s+([A-Za-z_$][\w$]*)/u
+const HEADING = /^(#{1,6})\s+(.+?)\s*#*\s*$/u
+const ANCHOR =
+	/(?:`([^`\n]+\.md)`\s*)?§\s*"?([^"`\n|;,.)]+?)"?(?=\s*(?:[,.;)|]|\s(?:and|or|names|fixes|owns|states|binds|governs|decides|before|after)\b|$))/gu
+const BINARY = /\.(png|jpg|jpeg|gif|webp|ico|woff2?|ttf|otf|eot|zip|tgz|gz|pdf|wasm)$/u
+
+interface TreeRow {
+	readonly path: string
+	readonly lines: number
+	readonly bytes: number
+}
+
+interface LineRow {
+	readonly path: string
+	readonly line: number
+	readonly text: string
+}
+
+interface TermRows {
+	readonly term: string
+	readonly rows: readonly LineRow[]
+}
+
+interface AnchorRow {
+	readonly path: string
+	readonly line: number
+	readonly target: string
+	readonly heading: string
+}
+
+interface Report {
+	readonly tree?: readonly TreeRow[]
+	readonly headings?: readonly LineRow[]
+	readonly frontmatter?: readonly LineRow[]
+	readonly exports?: readonly LineRow[]
+	readonly census?: readonly TermRows[]
+	readonly refs?: readonly LineRow[]
+	readonly anchors?: readonly AnchorRow[]
+}
+
+function isText(path: string): boolean {
+	return !BINARY.test(path) && basename(path) !== 'host.json'
+}
+
+function expandPaths(paths: readonly string[]): readonly string[] {
+	return paths.flatMap((path) => {
+		if (!existsSync(path)) return []
+		if (statSync(path).isDirectory()) return listFiles(path).map((file) => file.path)
+		return [normalizeSlashes(path)]
+	})
+}
+
+function readLines(path: string): readonly string[] {
+	return readFileSync(path, 'utf8').split(/\r\n|\n/)
+}
+
+function mapTree(paths: readonly string[]): readonly TreeRow[] {
+	return expandPaths(paths)
+		.filter(isText)
+		.map((path) => {
+			const text = readFileSync(path, 'utf8')
+			return {
+				path,
+				lines: text === '' ? 0 : text.split(/\r\n|\n/).length,
+				bytes: Buffer.byteLength(text),
+			}
+		})
+		.sort((left, right) => left.path.localeCompare(right.path))
+}
+
+function mapHeadings(paths: readonly string[]): readonly LineRow[] {
+	const rows: LineRow[] = []
+	for (const path of expandPaths(paths).filter((candidate) => candidate.endsWith('.md'))) {
+		let fenced = false
+		readLines(path).forEach((text, index) => {
+			if (text.startsWith('```')) fenced = !fenced
+			if (fenced) return
+			const match = text.match(HEADING)
+			if (match?.[1] !== undefined && match[2] !== undefined) {
+				rows.push({ path, line: index + 1, text: `${match[1]} ${match[2]}` })
+			}
+		})
+	}
+	return rows
+}
+
+function mapExports(paths: readonly string[]): readonly LineRow[] {
+	const rows: LineRow[] = []
+	for (const path of expandPaths(paths).filter((candidate) => /\.[cm]?ts$/u.test(candidate))) {
+		readLines(path).forEach((text, index) => {
+			const match = text.match(EXPORT)
+			if (match?.[1] !== undefined && match[2] !== undefined) {
+				rows.push({ path, line: index + 1, text: `${match[1]} ${match[2]}` })
+			} else if (/^export\s+\*\s+from\s+/u.test(text)) {
+				rows.push({ path, line: index + 1, text: text.trim() })
+			}
+		})
+	}
+	return rows
+}
+
+function buildMatcher(term: string, ignoreCase: boolean): (text: string) => boolean {
+	const needle = ignoreCase ? term.toLowerCase() : term
+	return (text) => (ignoreCase ? text.toLowerCase() : text).includes(needle)
+}
+
+function mapCensus(
+	terms: readonly string[],
+	roots: readonly string[],
+	ignoreCase: boolean,
+): readonly TermRows[] {
+	const files = expandPaths(roots).filter(isText)
+	return terms.map((term) => {
+		const matches = buildMatcher(term, ignoreCase)
+		const rows: LineRow[] = []
+		for (const path of files) {
+			readLines(path).forEach((text, index) => {
+				if (matches(text)) rows.push({ path, line: index + 1, text: text.trim().slice(0, 160) })
+			})
+		}
+		return { term, rows }
+	})
+}
+
+function mapRefs(target: string, roots: readonly string[]): readonly LineRow[] {
+	const needle = normalizeSlashes(target)
+	const name = basename(needle)
+	const rows: LineRow[] = []
+	for (const path of expandPaths(roots).filter(isText)) {
+		if (path === needle) continue
+		readLines(path).forEach((text, index) => {
+			if (text.includes(needle) || text.includes(name)) {
+				rows.push({ path, line: index + 1, text: text.trim().slice(0, 160) })
+			}
+		})
+	}
+	return rows
+}
+
+function readYamlKeys(path: string, lines: readonly string[], offset: number): readonly LineRow[] {
+	const rows: LineRow[] = []
+	const stack: Array<{ readonly indent: number; readonly key: string }> = []
+	lines.forEach((text, index) => {
+		const content = text.trimStart()
+		if (content === '' || content.startsWith('#')) return
+		const indent = text.length - content.length
+		const match = content.match(/^([A-Za-z_][\w-]*)\s*:(?:\s+(.*))?$/u)
+		if (match?.[1] === undefined) {
+			// A list item, a block scalar line, or a wrapped value extends the key before it.
+			const last = rows.at(-1)
+			if (last !== undefined && indent >= (stack.at(-1)?.indent ?? 0)) {
+				rows[rows.length - 1] = { ...last, text: `${last.text} ${content.trim()}`.trimEnd() }
+			}
+			return
+		}
+		while (stack.length > 0 && (stack.at(-1)?.indent ?? 0) >= indent) stack.pop()
+		const key = [...stack.map((entry) => entry.key), match[1]].join('.')
+		stack.push({ indent, key: match[1] })
+		rows.push({ path, line: index + offset, text: `${key}: ${(match[2] ?? '').trim()}`.trimEnd() })
+	})
+	return rows
+}
+
+function readTomlKeys(path: string, lines: readonly string[], offset: number): readonly LineRow[] {
+	const rows: LineRow[] = []
+	let table = ''
+	let fence: string | undefined
+	lines.forEach((text, index) => {
+		if (fence !== undefined) {
+			// The body of a multi-line string carries no key.
+			if (text.includes(fence)) fence = undefined
+			return
+		}
+		const header = text.match(/^\s*\[\[?([^\]]+)\]\]?\s*$/u)
+		if (header?.[1] !== undefined) {
+			table = header[1].trim()
+			return
+		}
+		const match = text.match(/^\s*([A-Za-z0-9_.-]+|"[^"]+")\s*=\s*(.*)$/u)
+		if (match?.[1] === undefined) return
+		const value = (match[2] ?? '').trim()
+		const opening = value.match(/^("""|''')/u)?.[1]
+		if (opening !== undefined && value.indexOf(opening, 3) === -1) fence = opening
+		rows.push({
+			path,
+			line: index + offset,
+			text: `${table === '' ? '' : `${table}.`}${match[1]}: ${value}`.trimEnd(),
+		})
+	})
+	return rows
+}
+
+function mapFrontmatter(paths: readonly string[]): readonly LineRow[] {
+	const rows: LineRow[] = []
+	for (const path of expandPaths(paths).filter((candidate) =>
+		/\.(md|mdc|toml|ya?ml)$/u.test(candidate),
+	)) {
+		const lines = readLines(path)
+		const markdown = /\.mdc?$/u.test(path)
+		const end = markdown ? lines.indexOf('---', 1) : lines.length
+		if (markdown && (lines[0] !== '---' || end === -1)) continue
+		const body = lines.slice(markdown ? 1 : 0, end)
+		const offset = markdown ? 2 : 1
+		rows.push(
+			...(path.endsWith('.toml')
+				? readTomlKeys(path, body, offset)
+				: readYamlKeys(path, body, offset)),
+		)
+	}
+	return rows
+}
+
+function readHeadingTexts(path: string): ReadonlySet<string> {
+	return new Set(mapHeadings([path]).map((row) => row.text.replace(/^#+\s+/u, '').toLowerCase()))
+}
+
+function mapAnchors(paths: readonly string[]): readonly AnchorRow[] {
+	const headings = new Map<string, ReadonlySet<string>>()
+	const rows: AnchorRow[] = []
+	for (const path of expandPaths(paths).filter((candidate) => candidate.endsWith('.md'))) {
+		readLines(path).forEach((text, index) => {
+			for (const match of text.matchAll(ANCHOR)) {
+				const target = match[1] === undefined ? path : normalizeSlashes(match[1])
+				const heading = (match[2] ?? '').trim()
+				if (heading === '') continue
+				if (!existsSync(target)) {
+					rows.push({ path, line: index + 1, target, heading })
+					continue
+				}
+				const known = headings.get(target) ?? readHeadingTexts(target)
+				headings.set(target, known)
+				if (!known.has(heading.toLowerCase())) rows.push({ path, line: index + 1, target, heading })
+			}
+		})
+	}
+	return rows
+}
+
+function renderReport(report: Report): string {
+	const lines: string[] = []
+	if (report.tree !== undefined) {
+		lines.push('## Tree')
+		for (const row of report.tree) lines.push(`${row.path}\t${row.lines} lines\t${row.bytes} bytes`)
+		lines.push(
+			`total\t${report.tree.length} files\t${report.tree.reduce((sum, row) => sum + row.lines, 0)} lines`,
+		)
+	}
+	if (report.headings !== undefined) {
+		lines.push('## Headings')
+		for (const row of report.headings) lines.push(`${row.path}:${row.line}\t${row.text}`)
+	}
+	if (report.frontmatter !== undefined) {
+		lines.push('## Frontmatter')
+		for (const row of report.frontmatter) lines.push(`${row.path}:${row.line}	${row.text}`)
+	}
+	if (report.exports !== undefined) {
+		lines.push('## Exports (text reading)')
+		for (const row of report.exports) lines.push(`${row.path}:${row.line}\t${row.text}`)
+	}
+	if (report.census !== undefined) {
+		for (const entry of report.census) {
+			lines.push(`## Census: ${entry.term} (${entry.rows.length})`)
+			for (const row of entry.rows) lines.push(`${row.path}:${row.line}\t${row.text}`)
+		}
+	}
+	if (report.refs !== undefined) {
+		lines.push(`## Refs (${report.refs.length})`)
+		for (const row of report.refs) lines.push(`${row.path}:${row.line}\t${row.text}`)
+	}
+	if (report.anchors !== undefined) {
+		lines.push(`## Unresolved anchors (${report.anchors.length})`)
+		for (const row of report.anchors)
+			lines.push(`${row.path}:${row.line}\t${row.target} § ${row.heading}`)
+	}
+	return `${lines.join('\n')}\n`
+}
+
+function main(argv: readonly string[]): number {
+	const missing = readMissingFlags(argv, ['--refs', '--paths', '--out'])
+	if (missing.length > 0) {
+		console.error(`map: ${missing.join(', ')} given with no value`)
+		return 64
+	}
+	const roots = (readOption(argv, '--paths') ?? '.').split(',')
+	const ignoreCase = argv.includes('--ignore-case')
+	const tree = readList(argv, '--tree')
+	const headings = readList(argv, '--headings')
+	const frontmatter = readList(argv, '--frontmatter')
+	const exports = readList(argv, '--exports')
+	const census = readList(argv, '--census')
+	const refs = readOption(argv, '--refs')
+	const anchors = readList(argv, '--anchors')
+	if (
+		tree.length +
+			headings.length +
+			frontmatter.length +
+			exports.length +
+			census.length +
+			anchors.length ===
+			0 &&
+		refs === undefined
+	) {
+		console.error(
+			'usage: map.ts [--tree PATH...] [--headings PATH...] [--frontmatter PATH...] [--exports PATH...] [--census TERM...] [--refs PATH] [--anchors PATH...] [--paths a,b] [--ignore-case] [--json] [--out FILE]',
+		)
+		return 64
+	}
+	const report: Report = {
+		...(tree.length > 0 ? { tree: mapTree(tree) } : {}),
+		...(headings.length > 0 ? { headings: mapHeadings(headings) } : {}),
+		...(frontmatter.length > 0 ? { frontmatter: mapFrontmatter(frontmatter) } : {}),
+		...(exports.length > 0 ? { exports: mapExports(exports) } : {}),
+		...(census.length > 0 ? { census: mapCensus(census, roots, ignoreCase) } : {}),
+		...(refs === undefined ? {} : { refs: mapRefs(refs, roots) }),
+		...(anchors.length > 0 ? { anchors: mapAnchors(anchors) } : {}),
+	}
+	const output = argv.includes('--json') ? `${JSON.stringify(report)}\n` : renderReport(report)
+	const out = readOption(argv, '--out')
+	if (out === undefined) process.stdout.write(output)
+	else {
+		mkdirSync(dirname(out), { recursive: true })
+		writeFileSync(out, output)
+		console.log(`map: wrote ${out}`)
+	}
+	return 0
+}
+
+process.exitCode = main(process.argv.slice(2))