@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/docs/scripts/check-example-docs.mjs

@@ -0,0 +1,214 @@
+/**
+ * Checks the example docs pages against the examples/ tree they document.
+ *
+ * Every page in docs/src/content/docs/examples/ other than index.mdx must
+ * embed a StackBlitz or CodeSandbox link, and every such link must resolve
+ * inside this repo. Its sandbox root has to exist and hold a package.json,
+ * because StackBlitz has nothing to install or boot without one. The file
+ * named by its `file=` parameter has to exist under that root. Every directory
+ * in examples/ with a package.json at its root or one level down must be
+ * linked from at least one of those pages.
+ *
+ * index.mdx is exempt from the sandbox rules. It is a card grid with no
+ * sandbox link of its own, and a sandbox link added there must not count as
+ * documenting an example that has no page. It must instead carry exactly one
+ * LinkCard per example page. Nothing checked the index before, and the
+ * ckbtc-wallet and icp-reactor cards fell off it while both pages stayed
+ * published.
+ *
+ * This reads the MDX sources and needs no build. check-links.mjs cannot catch
+ * any of this. It skips external links, and fetching a StackBlitz URL would not
+ * help, since a `file=` parameter and a sandbox root's package.json only mean
+ * something against this repo's own tree. A missing card or an undocumented
+ * example is not a broken link at all.
+ */
+import fs from "node:fs"
+import path from "node:path"
+
+// Resolved from this file, not the working directory. `path.resolve("..")` only
+// found the repo when run from docs/. From the repo root it scanned a directory
+// outside the checkout and died with ENOENT.
+const repoRoot = path.resolve(import.meta.dirname, "../..")
+const docsExamplesDir = path.join(repoRoot, "docs/src/content/docs/examples")
+const examplesDir = path.join(repoRoot, "examples")
+// A sandbox opens a branch of the repository. Only `main` is the 4.x line: a
+// link to a version branch (`v3`, or `v4`, which is retired after the 4.0 GA
+// flip) is matched so that it can be refused below.
+const SANDBOX_BRANCH = "main"
+const providerPattern =
+  /https:\/\/(?:stackblitz\.com\/github|codesandbox\.io\/p\/github)\/b3pay\/ic-reactor\/(?:tree\/)?(main|v\d+)(?:\/examples)?\/([^?"\s)]+)[^"\s)]*/g
+
+/**
+ * `target` resolved under `root`, or `undefined` when it leaves `root` or names
+ * `root` itself. Sandbox paths and `file=` parameters are free text in the
+ * pages, and a `../` in either would check a file outside the example the link
+ * actually opens.
+ */
+function resolveInside(root, target) {
+  const resolved = path.resolve(root, target)
+  const relative = path.relative(root, resolved)
+  const escapes =
+    relative === "" ||
+    relative === ".." ||
+    relative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relative)
+  return escapes ? undefined : resolved
+}
+
+function hasPackageJson(dir) {
+  return fs.existsSync(path.join(dir, "package.json"))
+}
+
+function findPackageRoot(exampleDir) {
+  const root = path.join(examplesDir, exampleDir)
+  if (hasPackageJson(root)) return root
+
+  for (const child of fs.readdirSync(root, { withFileTypes: true })) {
+    if (child.isDirectory() && hasPackageJson(path.join(root, child.name))) {
+      return path.join(root, child.name)
+    }
+  }
+
+  return null
+}
+
+function getExampleDirs() {
+  return fs
+    .readdirSync(examplesDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((name) => findPackageRoot(name))
+    .sort()
+}
+
+function getMdxFiles() {
+  return fs
+    .readdirSync(docsExamplesDir)
+    .filter((name) => name.endsWith(".mdx"))
+    .sort()
+}
+
+if (!fs.existsSync(examplesDir)) {
+  console.error(`- examples/ does not exist`)
+  process.exit(1)
+}
+if (!fs.existsSync(docsExamplesDir)) {
+  console.error(
+    `- examples/ exists, but no docs page in ${docsExamplesDir} documents it`
+  )
+  process.exit(1)
+}
+
+const pages = getMdxFiles().filter((file) => file !== "index.mdx")
+const documentedExamples = new Set()
+// A Set, because each page points at the same sandbox twice, once in the
+// "Open in StackBlitz" LinkCard href and again in the iframe src. With an
+// array, one broken link produced two identical findings.
+const errors = new Set()
+
+for (const file of pages) {
+  const fullPath = path.join(docsExamplesDir, file)
+  const content = fs.readFileSync(fullPath, "utf8")
+  const matches = [...content.matchAll(providerPattern)]
+
+  if (matches.length === 0) {
+    errors.add(`${file} has no StackBlitz or CodeSandbox example link`)
+    continue
+  }
+
+  for (const match of matches) {
+    const url = match[0]
+    if (match[1] !== SANDBOX_BRANCH) {
+      errors.add(
+        `${file} opens the ${match[1]} branch (${url}); sandbox links open ${SANDBOX_BRANCH}`
+      )
+      continue
+    }
+    let examplePath
+    try {
+      examplePath = decodeURIComponent(match[2]).replace(/\/+$/, "")
+    } catch {
+      errors.add(`${file} has a sandbox path that is not valid: ${match[2]}`)
+      continue
+    }
+
+    // The documented example is read from the normalized path, so a link to
+    // `new-example/../existing-example` cannot mark new-example as covered.
+    const sandboxRoot = resolveInside(examplesDir, examplePath)
+    const normalized =
+      sandboxRoot && path.relative(examplesDir, sandboxRoot).split(path.sep)
+    if (!normalized || normalized.join("/") !== examplePath) {
+      errors.add(
+        `${file} sandbox root is not a plain path inside examples/: ${examplePath}`
+      )
+      continue
+    }
+    documentedExamples.add(normalized[0])
+
+    if (!fs.existsSync(sandboxRoot)) {
+      errors.add(
+        `${file} links to missing sandbox root: examples/${examplePath}`
+      )
+      continue
+    }
+
+    if (!hasPackageJson(sandboxRoot)) {
+      errors.add(
+        `${file} sandbox root has no package.json: examples/${examplePath}`
+      )
+    }
+
+    const parsedUrl = new URL(url)
+    const focusedFile = parsedUrl.searchParams.get("file")
+    if (focusedFile) {
+      const target = resolveInside(sandboxRoot, focusedFile)
+      if (!target) {
+        errors.add(
+          `${file} focuses a file outside its sandbox root: examples/${examplePath} file=${focusedFile}`
+        )
+      } else if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {
+        errors.add(
+          `${file} focuses missing file: examples/${examplePath}/${focusedFile}`
+        )
+      }
+    }
+  }
+}
+
+for (const exampleDir of getExampleDirs()) {
+  if (!documentedExamples.has(exampleDir)) {
+    errors.add(`examples/${exampleDir} is not linked from an example docs page`)
+  }
+}
+
+// Cards are matched to pages by the last segment of an `/examples/<slug>` href,
+// so the check does not depend on the site's base path. A card whose href is
+// not shaped like that is skipped, and its page then reports a missing card.
+const cardCounts = new Map(pages.map((page) => [page, 0]))
+const index = fs.readFileSync(path.join(docsExamplesDir, "index.mdx"), "utf8")
+for (const [, attributes] of index.matchAll(/<LinkCard\b([\s\S]*?)\/>/g)) {
+  const href = attributes.match(/\bhref="([^"]*)"/)?.[1]
+  const slug = href?.match(/\/examples\/([^/?#]+)\/?$/)?.[1]
+  if (!slug) continue
+
+  const page = `${slug}.mdx`
+  if (cardCounts.has(page)) {
+    cardCounts.set(page, cardCounts.get(page) + 1)
+  } else {
+    errors.add(`index.mdx has a LinkCard for a missing page: ${href}`)
+  }
+}
+
+for (const [page, count] of cardCounts) {
+  if (count === 0) errors.add(`index.mdx has no LinkCard for ${page}`)
+  if (count > 1) errors.add(`index.mdx has ${count} LinkCards for ${page}`)
+}
+
+if (errors.size > 0) {
+  console.error([...errors].map((error) => `- ${error}`).join("\n"))
+  process.exit(1)
+}
+
+console.log(
+  `Checked ${documentedExamples.size} documented examples with sandbox links and ${pages.length} index cards.`
+)

package/docs/scripts/check-links.mjs

@@ -0,0 +1,212 @@
+/**
+ * Crawls the BUILT docs for broken links.
+ *
+ * Runs against `docs/dist` rather than the Markdown sources because the site's
+ * hand-written hrefs are absolute and base-prefixed (`](/v3/...)`) -- they only
+ * resolve once Astro has rendered routes under the configured base. Checking the
+ * sources would miss exactly the links a page rename breaks.
+ *
+ * Astro writes the site to `dist/` root while emitting `/v3/`-prefixed hrefs, so
+ * the crawl needs `dist` mounted AT the base rather than served as the web root.
+ * A staging directory with a symlink gives that without copying 24 MB.
+ *
+ * The base is read from astro.config.mjs rather than hardcoded, so the two
+ * cannot drift.
+ *
+ * The pages also link Candid Core's site, which the deploy serves at
+ * `/candid-core/` from a build of its own repository
+ * (scripts/assemble-docs-site.mjs). `CANDID_CORE_SITE` names that build
+ * (`website/dist` of a B3Pay/Meant checkout, after
+ * `node website/build.mjs`; a relative path is read from docs/, where it runs),
+ * and it is mounted there too: each such link and its `#fragment` are checked
+ * against the real pages, and those pages are crawled as well, as they will be
+ * published. Without it those links are skipped and counted, and in CI (`CI`
+ * set) the check fails instead.
+ */
+import { mkdtemp, readFile, readdir, rm, symlink } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { existsSync } from "node:fs"
+import { join, posix, resolve } from "node:path"
+import { LinkChecker } from "linkinator"
+
+const docsRoot = resolve(import.meta.dirname, "..")
+
+const config = await readFile(join(docsRoot, "astro.config.mjs"), "utf8")
+const baseMatch = config.match(/^\s*base:\s*["'](.+?)["']/m)
+if (!baseMatch) {
+  console.error("Could not read `base` from astro.config.mjs")
+  process.exit(1)
+}
+const base = baseMatch[1].replace(/^\/|\/$/g, "")
+
+// Where the deploy serves Candid Core's site (CANDID_CORE_DIR in
+// scripts/assemble-docs-site.mjs).
+const candidCoreDir = "candid-core"
+const candidCoreSite = process.env.CANDID_CORE_SITE
+  ? resolve(process.env.CANDID_CORE_SITE)
+  : undefined
+if (candidCoreSite && !existsSync(join(candidCoreSite, "index.html"))) {
+  console.error(
+    `CANDID_CORE_SITE=${candidCoreSite} holds no built Candid Core site (no index.html)`
+  )
+  process.exit(1)
+}
+if (!candidCoreSite && process.env.CI) {
+  console.error(
+    `CANDID_CORE_SITE is not set: in CI the links under /${candidCoreDir}/ are checked against a build of B3Pay/Meant's site`
+  )
+  process.exit(1)
+}
+// linkinator matches a skip pattern against the absolute URL, and reports a
+// link of its own server by its path from the server root.
+const candidCoreUrl = new RegExp(
+  `^(https?://(localhost|127\\.0\\.0\\.1)(:\\d+)?/|/)?${candidCoreDir}(/|$)`
+)
+const candidCoreRoot = new RegExp(
+  `^(https?://(localhost|127\\.0\\.0\\.1)(:\\d+)?/|/)?${candidCoreDir}/?$`
+)
+
+const staging = await mkdtemp(join(tmpdir(), "ic-reactor-links-"))
+try {
+  await symlink(join(docsRoot, "dist"), join(staging, base), "dir")
+  if (candidCoreSite) {
+    await symlink(candidCoreSite, join(staging, candidCoreDir), "dir")
+  }
+
+  const options = {
+    // The crawl root must be the DIRECTORY, not index.html. linkinator sets
+    // `rootPath` to the full starting URL and only recurses into links whose
+    // href string-prefixes it (build/src/index.js:271 and :892). With
+    // `${base}/index.html` nothing on the site starts with that string, so the
+    // crawl never leaves the home page: it reported "Checked 191 internal
+    // links" for a 180-page site while visiting exactly one page.
+    path: `${base}/`,
+    serverRoot: staging,
+    recurse: true,
+    // A `#fragment` must name an id on its page, so a reworded heading that
+    // breaks a link like `/v4/guides/ssr/#a-read-...` fails here.
+    checkFragments: true,
+    // linkinator's default concurrency (100) overwhelms its own static server
+    // once the crawl is a few hundred links: requests come back with status 0
+    // (connection dropped, not a 404) and the gate fails intermittently on
+    // whichever page lost the race. Capping concurrency and retrying transport
+    // errors makes it deterministic -- a flaky gate gets ignored, which is the
+    // failure mode this whole gate exists to avoid.
+    concurrency: 25,
+    retryErrors: true,
+    retryErrorsCount: 3,
+    linksToSkip: [
+      // External links are someone else's uptime, not this repo's correctness.
+      // linkinator resolves every internal link against its own server, which
+      // binds 127.0.0.1 -- so this must exempt the local host explicitly or it
+      // skips the entire site and the gate silently checks nothing.
+      "^https?://(?!(localhost|127\\.0\\.0\\.1)[:/])",
+      // Without a build of Candid Core's site, its links cannot be checked.
+      ...(candidCoreSite ? [] : [candidCoreUrl.source]),
+    ],
+  }
+  const result = await new LinkChecker().check(options)
+  // Candid Core's own pages, as they will be published: the crawl above only
+  // follows links under the base, so it stops at their entry links.
+  const candidCoreResult = candidCoreSite
+    ? await new LinkChecker().check({ ...options, path: `${candidCoreDir}/` })
+    : { links: [] }
+
+  // Case-sensitivity pass. linkinator serves the built site from the local
+  // filesystem, so on macOS every href resolves case-insensitively and a link
+  // that is a hard 404 on the Linux host comes back 200. That is not a
+  // hypothetical: `starlight-page-actions` writes each page's `.md` companion
+  // at the SOURCE-cased path while building the href from the lowercased route,
+  // and the mismatch is invisible here without this check. Compare exact
+  // strings against the real file set rather than asking the filesystem.
+  const realFiles = new Set()
+  const walk = async (dir, rel = "") => {
+    for (const e of await readdir(dir, { withFileTypes: true })) {
+      const r = rel ? `${rel}/${e.name}` : e.name
+      if (e.isDirectory()) await walk(join(dir, e.name), r)
+      else realFiles.add(r)
+    }
+  }
+  await walk(join(docsRoot, "dist"))
+
+  const caseBroken = []
+  for (const page of [...realFiles].filter((f) => f.endsWith(".html"))) {
+    const html = await readFile(join(docsRoot, "dist", page), "utf8")
+    const route = `/${base}/${page.replace(/index\.html$/, "")}`
+    for (const [, href] of html.matchAll(/href="([^"]+)"/g)) {
+      if (/^(https?:|mailto:|#|\/\/)/.test(href)) continue
+      const clean = href.split("#")[0].split("?")[0]
+      if (!clean) continue
+      const abs = clean.startsWith("/")
+        ? clean
+        : posix.normalize(posix.join(route, clean))
+      if (!abs.startsWith(`/${base}/`)) continue
+      let f = abs.slice(base.length + 2)
+      if (f === "") f = "index.html"
+      else if (f.endsWith("/")) f += "index.html"
+      else if (!/\.[a-z0-9]+$/i.test(f)) f += "/index.html"
+      if (!realFiles.has(f)) caseBroken.push(`${href}\n      <- ${route}`)
+    }
+  }
+  if (caseBroken.length > 0) {
+    console.error(
+      `\n${caseBroken.length} link(s) resolve only on a case-insensitive filesystem ` +
+        `- these are 404s on the Linux host that serves the site:\n`
+    )
+    for (const b of caseBroken.slice(0, 20)) console.error(`  ${b}`)
+    if (caseBroken.length > 20)
+      console.error(`  ... and ${caseBroken.length - 20} more`)
+    process.exit(1)
+  }
+
+  const broken = [...result.links, ...candidCoreResult.links].filter(
+    (l) => l.state === "BROKEN"
+  )
+  const checked = result.links.filter((l) => l.state !== "SKIPPED")
+  // What the crawl of Candid Core's pages reached past the home page it
+  // started from, which it reports twice (`candid-core`, then `candid-core/`).
+  const candidCoreReached = new Set(
+    candidCoreResult.links
+      .filter((l) => l.state !== "SKIPPED" && !candidCoreRoot.test(l.url))
+      .map((l) => l.url)
+  )
+  // linkinator reports a skipped URL once per page that links it.
+  const candidCoreSkipped = new Set(
+    result.links
+      .filter((l) => l.state === "SKIPPED" && candidCoreUrl.test(l.url))
+      .map((l) => l.url)
+  )
+
+  if (broken.length > 0) {
+    console.error(`\n${broken.length} broken link(s):\n`)
+    for (const link of broken) {
+      console.error(`  [${link.status}] ${link.url}\n      <- ${link.parent}`)
+    }
+    process.exit(1)
+  }
+
+  // A mounted site whose crawl reached nothing past its home page was not
+  // checked.
+  if (candidCoreSite && candidCoreReached.size === 0) {
+    console.error(
+      `The crawl of /${candidCoreDir}/ reached nothing past its home page: is ${candidCoreSite} the site's website/dist?`
+    )
+    process.exit(1)
+  }
+
+  console.log(
+    `Checked ${checked.length} internal links under /${base}/ - no broken links.`
+  )
+  if (candidCoreSite) {
+    const entries = checked.filter((l) => candidCoreUrl.test(l.url)).length
+    console.log(
+      `${entries} of them reach Candid Core's site under /${candidCoreDir}/, and the crawl of its pages reached ${candidCoreReached.size} more, none broken (built at ${candidCoreSite}).`
+    )
+  } else {
+    console.log(
+      `${candidCoreSkipped.size} links under /${candidCoreDir}/ were not checked: set CANDID_CORE_SITE to a build of B3Pay/Meant's site (website/dist).`
+    )
+  }
+} finally {
+  await rm(staging, { recursive: true, force: true })
+}

package/docs/scripts/fix-dist-links.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * Post-`astro build` repairs to the built site, for two things neither Astro
+ * nor the plugins get right on their own.
+ *
+ * 1. PAGE-ACTION MARKDOWN LINKS. `starlight-page-actions` writes each page's
+ *    `.md` companion at the SOURCE-cased path but builds the href from the
+ *    RENDERED ROUTE, which Starlight lowercases. TypeDoc filenames are
+ *    PascalCase, so every such link on a mixed-case page 404s:
+ *
+ *      href  /v3/libs/classes/authenticationmanager.md
+ *      file  dist/libs/classes/AuthenticationManager.md
+ *
+ *    This is invisible on macOS, whose filesystem is case-insensitive, and a
+ *    hard 404 on the Linux host. The home page has a second variant of the same
+ *    bug: its href is `${base}.md`, but the file is served at `${base}/index.md`.
+ *
+ *    We repoint the hrefs at the files that exist rather than emitting
+ *    lowercase duplicates, so the already-deployed source-cased URLs keep
+ *    working and nothing is published twice.
+ *
+ * 2. llms.txt. The plugin builds it from the site origin and drops the base
+ *    path, so every entry points one level above the real page. Setting
+ *    `baseUrl` in astro.config.mjs does not help: the plugin reduces the URL to
+ *    `urlObj.origin`.
+ */
+import {
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  statSync,
+  existsSync,
+} from "node:fs"
+import { join, resolve } from "node:path"
+
+const docsRoot = resolve(import.meta.dirname, "..")
+const DIST = join(docsRoot, "dist")
+
+const astroConfig = readFileSync(join(docsRoot, "astro.config.mjs"), "utf8")
+const base =
+  "/" +
+  (astroConfig.match(/^\s*base:\s*["'](.+?)["']/m)?.[1] ?? "").replace(
+    /^\/|\/$/g,
+    ""
+  )
+const site = astroConfig
+  .match(/^\s*site:\s*["'](.+?)["']/m)?.[1]
+  ?.replace(/\/$/, "")
+if (base === "/" || !site) {
+  console.error(
+    "fix-dist-links: could not read `base`/`site` from astro.config.mjs"
+  )
+  process.exit(1)
+}
+
+function* files(dir, rel = "") {
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name)
+    const r = rel ? `${rel}/${name}` : name
+    if (statSync(full).isDirectory()) yield* files(full, r)
+    else yield [full, r]
+  }
+}
+
+// Two exact sets. `real` is compared by STRING, never with existsSync: macOS
+// resolves paths case-insensitively, so existsSync reports every lowercase
+// page-action href as already valid and this script silently fixes nothing --
+// while the same href is a hard 404 on the Linux host that serves the site.
+const real = new Set()
+const byLower = new Map()
+for (const [, rel] of files(DIST)) {
+  if (!rel.endsWith(".md")) continue
+  real.add(rel)
+  byLower.set(rel.toLowerCase(), rel)
+}
+
+let hrefsFixed = 0
+let pagesTouched = 0
+for (const [full, rel] of files(DIST)) {
+  if (!rel.endsWith(".html")) continue
+  const src = readFileSync(full, "utf8")
+  const out = src.replace(/href="([^"]+\.md)"/g, (whole, href) => {
+    // `${base}.md` on the home page -> the real `${base}/index.md`
+    if (href === `${base}.md`) {
+      if (!real.has("index.md")) return whole
+      hrefsFixed++
+      return `href="${base}/index.md"`
+    }
+    if (!href.startsWith(`${base}/`)) return whole
+    const wanted = href.slice(base.length + 1)
+    if (real.has(wanted)) return whole // exact match; already correct
+    const actual = byLower.get(wanted.toLowerCase())
+    if (!actual) return whole // genuinely missing; leave it for the link gate
+    hrefsFixed++
+    return `href="${base}/${actual}"`
+  })
+  if (out !== src) {
+    writeFileSync(full, out)
+    pagesTouched++
+  }
+}
+
+// llms.txt: `https://host/foo/` -> `https://host/v3/foo/`
+let llmsFixed = 0
+for (const name of ["llms.txt", "llms-full.txt"]) {
+  const p = join(DIST, name)
+  if (!existsSync(p)) continue
+  const src = readFileSync(p, "utf8")
+  const out = src.replace(
+    new RegExp(
+      `${site.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?!${base}/)/`,
+      "g"
+    ),
+    () => {
+      llmsFixed++
+      return `${site}${base}/`
+    }
+  )
+  if (out !== src) writeFileSync(p, out)
+}
+
+console.log(
+  `fix-dist-links: repointed ${hrefsFixed} .md hrefs across ${pagesTouched} pages; ` +
+    `prefixed ${llmsFixed} llms.txt URLs with ${base}`
+)

package/docs/scripts/fix-frontmatter.js

@@ -0,0 +1,71 @@
+import { readdirSync, readFileSync, writeFileSync, statSync } from "fs"
+import { join, extname } from "path"
+
+const DOCS_DIR = "src/content/docs"
+
+function processFile(filePath) {
+  if (extname(filePath) !== ".md" && extname(filePath) !== ".mdx") return
+
+  const content = readFileSync(filePath, "utf-8")
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/)
+
+  if (frontmatterMatch) {
+    const frontmatter = frontmatterMatch[1]
+    if (frontmatter.includes("title:")) return // Already has title
+
+    // Try to find H1
+    const h1Match = content.match(/^# (.*)/m)
+    if (h1Match) {
+      const title = h1Match[1].trim()
+      const newFrontmatter = `title: ${title}\n${frontmatter}`
+      const newContent = content.replace(
+        frontmatterMatch[0],
+        `---\n${newFrontmatter}\n---`
+      )
+      writeFileSync(filePath, newContent)
+      console.log(`Added title to ${filePath}: ${title}`)
+    } else {
+      // Use filename as fallback
+      const filename = filePath
+        .split("/")
+        .pop()
+        .replace(/\.(md|mdx)$/, "")
+      const title = filename.charAt(0).toUpperCase() + filename.slice(1)
+      const newFrontmatter = `title: ${title}\n${frontmatter}`
+      const newContent = content.replace(
+        frontmatterMatch[0],
+        `---\n${newFrontmatter}\n---`
+      )
+      writeFileSync(filePath, newContent)
+      console.log(`Added title (fallback) to ${filePath}: ${title}`)
+    }
+  } else {
+    // No frontmatter at all
+    const h1Match = content.match(/^# (.*)/m)
+    const title = h1Match
+      ? h1Match[1].trim()
+      : filePath
+          .split("/")
+          .pop()
+          .replace(/\.(md|mdx)$/, "")
+    const newContent = `---\ntitle: ${title}\n---\n\n${content}`
+    writeFileSync(filePath, newContent)
+    console.log(`Created frontmatter for ${filePath}: ${title}`)
+  }
+}
+
+function walk(dir) {
+  const files = readdirSync(dir)
+  for (const file of files) {
+    const filePath = join(dir, file)
+    if (statSync(filePath).isDirectory()) {
+      if (file !== "node_modules" && file !== ".astro") {
+        walk(filePath)
+      }
+    } else {
+      processFile(filePath)
+    }
+  }
+}
+
+walk(DOCS_DIR)

package/docs/scripts/remove-redundant-h1.cjs

@@ -0,0 +1,48 @@
+const fs = require("fs")
+const path = require("path")
+
+const docsDir = path.join(__dirname, "../src/content/docs")
+
+function getFiles(dir) {
+  let results = []
+  const list = fs.readdirSync(dir)
+  list.forEach((file) => {
+    const fullPath = path.join(dir, file)
+    const stat = fs.statSync(fullPath)
+    if (stat && stat.isDirectory()) {
+      results = results.concat(getFiles(fullPath))
+    } else if (fullPath.endsWith(".mdx") || fullPath.endsWith(".md")) {
+      results.push(fullPath)
+    }
+  })
+  return results
+}
+
+const files = getFiles(docsDir)
+
+files.forEach((file) => {
+  let content = fs.readFileSync(file, "utf8")
+  const lines = content.split("\n")
+  let hasFrontmatterTitle = content.match(/^title:\s*/m)
+
+  if (hasFrontmatterTitle) {
+    // Find the FIRST H1 in the file that is NOT inside a code block
+    let insideCodeBlock = false
+    for (let i = 0; i < lines.length; i++) {
+      const trimmedLine = lines[i].trim()
+      if (trimmedLine.startsWith("```")) {
+        insideCodeBlock = !insideCodeBlock
+      }
+      if (!insideCodeBlock && trimmedLine.startsWith("# ")) {
+        console.log(`Removing redundant H1 from ${file}: ${lines[i]}`)
+        lines.splice(i, 1)
+        // Remove trailing empty line if it exists
+        if (lines[i] && lines[i].trim() === "") {
+          lines.splice(i, 1)
+        }
+        break
+      }
+    }
+    fs.writeFileSync(file, lines.join("\n"))
+  }
+})