/**
 * The authoring documentation, assembled from `skill/*.md` at module load.
 *
 * Two things are served from here:
 *  - the always-on MCP server `instructions` (one file per backend mode) —
 *    deliberately small, since every client pays for them on every turn;
 *  - the deep authoring guide, split into TOPICS and served on demand by the
 *    `how_it_works` tool. Nothing here is inlined into a tool schema: a doc
 *    embedded in an input-schema description is paid for on every request
 *    whether or not it's ever relevant.
 *
 * The prose lives in markdown (published via package.json's `files`) so it
 * can be edited without touching code. Paths resolve identically from
 * `src/mcp` (dev) and `lib/mcp` (published) — both are two levels below the
 * package root.
 *
 * Assembly has three steps:
 *  1. `<!-- common: name -->` splices a shared block out of `SKILL.common.md`
 *     (delimited there by `<!-- section: name -->`), so the two mode guides
 *     don't drift on the ~60% of prose that is identical.
 *  2. `%CTX%` expands to the mode's consumer-param namespace — `context.` on
 *     the builder, `context_` on old-devtools. That is the only textual
 *     difference across most shared blocks, so tokenizing it keeps them
 *     shared.
 *  3. `<!-- topic: name -->` splits the result into the units `how_it_works`
 *     serves. Backend-independent topics come from their own files instead.
 */
import assert from 'node:assert'
import { readFileSync } from 'node:fs'
import { fileURLToPath } from 'node:url'

function readSkill(file: string): string {
	const url = new URL(`../../skill/${file}`, import.meta.url)
	return readFileSync(fileURLToPath(url), 'utf8')
		// Strip any leading frontmatter defensively.
		.replace(/^---\n[\s\S]*?\n---\n/, '')
		.trim()
}

export const BUILDER_MODE_INSTRUCTIONS = readSkill('builder-mode.md')
export const OLD_MODE_INSTRUCTIONS = readSkill('old-mode.md')

/** Split `<!-- marker: name -->`-delimited blocks, keeping document order. */
function splitBlocks(text: string, marker: string): Map<string, string> {
	const blocks = new Map<string, string>()
	const re = new RegExp(
		`<!-- ${marker}: (\\S+) -->\\n([\\s\\S]*?)(?=\\n<!-- ${marker}: |$)`,
		'g',
	)
	for(const match of text.matchAll(re)) {
		// Trim blank LINES only, not inline indentation — some blocks are
		// list-continuation text that's intentionally indented on its first line.
		blocks.set(match[1], match[2].replace(/^\n+/, '').replace(/\n+$/, ''))
	}

	return blocks
}

const COMMON_SECTIONS = splitBlocks(readSkill('SKILL.common.md'), 'section')

/** Topics that read the same on both backends, each its own file. */
const SHARED_TOPIC_FILES: Record<string, string> = {
	'user-script': 'user-script.md',
	'interception': 'interception.md',
	'hash-validation': 'hash-validation.md',
}

/** One line per topic, shown in the `how_it_works` index so a caller can pick
 *  the right one without fetching several. Keyed across both modes; only the
 *  topics a mode actually has are listed back to it. */
const TOPIC_SUMMARIES: Record<string, string> = {
	'overview': 'Terminology, your stance, and the whole loop at a glance.',
	'contributions': 'Contributing a public provider as a volunteer: the '
		+ 'candidate-and-review workflow and the extra rules it adds.',
	'auth': 'Signing in to the backend, and which token authorizes what.',
	'devtools-migration': 'Importing a public legacy provider with the same '
		+ 'UUID.',
	'browser': 'Choosing a browser source (local Chrome, the Reclaim runtime in '
		+ 'Docker, a remote Builder browser, or a custom CDP endpoint), '
		+ 'geolocation, live view, and launch troubleshooting.',
	'capture': 'Tabs, login detection, driving the page, and picking an '
		+ 'authenticated request to prove.',
	'draft': 'The OPRF/privacy decision, propose_provider, and the canonical '
		+ 'drafted shape.',
	'params': 'Extracted vs consumer-supplied vs secret params, the URL '
		+ 'character budget, and runtime resolution.',
	'prove': 'replay_request, the mandatory auth-bound check, run_proof, and '
		+ 'diagnosing failures.',
	'publish': 'Creating/reusing a provider, versions, multi-request providers, '
		+ 'and going live.',
	'discover': 'Finding providers, resolving them, and creating a verification '
		+ 'session.',
	'integration': 'Builder Verification Client integration: the `api=2` bridge, '
		+ 'result verification, and optional TEE binding.',
	'user-script': 'Authoring jsUserScripts / customInjection to drive '
		+ 'login-gated pages.',
	'interception': 'injectionType / interceptorType, live interception, the '
		+ 'document-replay flag, and what to do when a site won\'t load or '
		+ 'won\'t let the user sign in.',
	'hash-validation': 'bodySniff, and how verifyProof({ providerId }) gates on '
		+ 'the declared spec hash.',
	'credentials': 'The eth proof-owner key run_proof signs with.',
	'never-do': 'The short list of things that always break a provider.',
	'troubleshooting': 'Expired drafts, browser problems, and where to look '
		+ 'next.',
}

export interface Guide {
	/** Topic name → its markdown, in document order. */
	topics: Map<string, string>
	/** `{ topic, summary }` for every topic this mode has. */
	index: Array<{ topic: string, summary: string }>
	/** Every topic concatenated — the whole guide, as it used to be served. */
	full: string
}

function buildGuide(file: string, ctxPrefix: string): Guide {
	const raw = readSkill(file)
		.replace(/<!-- common: (\S+) -->/g, (_whole, name: string) => {
			const section = COMMON_SECTIONS.get(name)
			assert(section, `${file}: no SKILL.common.md section named "${name}"`)
			return section
		})
		.replaceAll('%CTX%', ctxPrefix)

	const topics = splitBlocks(raw, 'topic')
	assert(topics.size, `${file}: no <!-- topic: … --> sections found`)
	for(const [name, path] of Object.entries(SHARED_TOPIC_FILES)) {
		topics.set(name, readSkill(path))
	}

	const index = [...topics.keys()].map((topic) => {
		const summary = TOPIC_SUMMARIES[topic]
		assert(summary, `${file}: no TOPIC_SUMMARIES entry for "${topic}"`)
		return { topic, summary }
	})

	return { topics, index, full: [...topics.values()].join('\n\n') }
}

export const GUIDE_BUILDER = buildGuide('SKILL.builder.md', 'context.')
export const GUIDE_OLD = buildGuide('SKILL.old.md', 'context_')

export function guideFor(oldMode: boolean): Guide {
	return oldMode ? GUIDE_OLD : GUIDE_BUILDER
}