@agentskit/doc-bridge 0.1.0-alpha.2 → 1.0.0

package/src/doctor/run-doctor.ts

@@ -0,0 +1,286 @@
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { buildDocBridgeIndex } from '../index-builder/build-index.js'
+import { scanAgentCorpus } from '../index-builder/scan-corpus.js'
+import { runGates, type GateRunResult } from '../gates/run-gates.js'
+import { IndexNotFoundError, loadDocBridgeIndex } from '../query/load-index.js'
+import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+import { doctorBadgeMetrics, type DoctorBadgeMetrics } from './badge.js'
+
+export type DoctorIssue = {
+  readonly severity: 'error' | 'warn' | 'info'
+  readonly code: string
+  readonly message: string
+  readonly action?: string
+}
+
+export type DoctorCoverage = {
+  readonly packages: {
+    readonly total: number
+    readonly withAgentDoc: number
+    readonly withHumanDoc: number
+    readonly missingAgentDoc: readonly string[]
+    readonly missingHumanDoc: readonly string[]
+  }
+  readonly agentDocs: {
+    readonly total: number
+    readonly indexed: number
+    readonly unindexed: readonly string[]
+  }
+  readonly freshness: {
+    readonly ok: boolean
+    readonly message: string
+    readonly hasIndex: boolean
+  }
+  readonly gates: GateRunResult
+}
+
+export type DoctorReport = {
+  readonly ok: boolean
+  readonly score: number
+  readonly grade: 'A' | 'B' | 'C' | 'D' | 'F'
+  readonly coverage: DoctorCoverage
+  readonly badge: DoctorBadgeMetrics
+  readonly issues: readonly DoctorIssue[]
+  readonly nextActions: readonly string[]
+}
+
+const gradeForScore = (score: number): DoctorReport['grade'] => {
+  if (score >= 90) return 'A'
+  if (score >= 75) return 'B'
+  if (score >= 60) return 'C'
+  if (score >= 40) return 'D'
+  return 'F'
+}
+
+const agentDocPaths = (index: DocBridgeIndexV1): Set<string> => {
+  const paths = new Set<string>()
+  for (const owner of Object.values(index.lookup?.ownership ?? {})) {
+    if (owner.agentDoc) paths.add(owner.agentDoc)
+  }
+  for (const handoff of Object.values(index.handoffs ?? {})) {
+    if (handoff.startHere) paths.add(handoff.startHere)
+  }
+  return paths
+}
+
+const computeScore = (coverage: DoctorCoverage): number => {
+  let score = 0
+
+  if (coverage.freshness.hasIndex) score += 15
+  if (coverage.freshness.ok) score += 15
+
+  const { total, withAgentDoc, withHumanDoc } = coverage.packages
+  if (total > 0) {
+    score += Math.round((withAgentDoc / total) * 35)
+    score += Math.round((withHumanDoc / total) * 20)
+  } else if (coverage.agentDocs.indexed > 0) {
+    score += 35
+  }
+
+  if (coverage.gates.ok) score += 15
+  else {
+    const passed = coverage.gates.results.filter((gate) => gate.ok).length
+    const totalGates = coverage.gates.results.length || 1
+    score += Math.round((passed / totalGates) * 10)
+  }
+
+  return Math.min(100, Math.max(0, score))
+}
+
+const buildIssues = (coverage: DoctorCoverage): DoctorIssue[] => {
+  const issues: DoctorIssue[] = []
+
+  if (!coverage.freshness.hasIndex) {
+    issues.push({
+      severity: 'error',
+      code: 'index-missing',
+      message: 'No doc-bridge index found.',
+      action: 'ak-docs index',
+    })
+  } else if (!coverage.freshness.ok) {
+    issues.push({
+      severity: 'error',
+      code: 'index-stale',
+      message: coverage.freshness.message,
+      action: 'ak-docs index',
+    })
+  }
+
+  for (const id of coverage.packages.missingAgentDoc) {
+    issues.push({
+      severity: 'warn',
+      code: 'missing-agent-doc',
+      message: `Package "${id}" has no dedicated agent doc.`,
+      action: `ak-docs init --scaffold-workspaces  # or edit docs/for-agents/packages/${id}.md`,
+    })
+  }
+
+  for (const id of coverage.packages.missingHumanDoc) {
+    issues.push({
+      severity: 'info',
+      code: 'missing-human-doc',
+      message: `Package "${id}" has no linked human guide.`,
+      action: 'ak-docs bootstrap agent-docs',
+    })
+  }
+
+  for (const gate of coverage.gates.results.filter((result) => !result.ok)) {
+    issues.push({
+      severity: gate.id === 'index-freshness' ? 'error' : 'warn',
+      code: `gate-${gate.id}`,
+      message: gate.message,
+      action: gate.id === 'index-freshness' ? 'ak-docs index' : 'ak-docs gate run',
+    })
+  }
+
+  return issues
+}
+
+const buildNextActions = (issues: readonly DoctorIssue[], coverage: DoctorCoverage): string[] => {
+  const actions = new Set<string>()
+  for (const issue of issues) {
+    if (issue.action) actions.add(issue.action)
+  }
+
+  if (!coverage.freshness.hasIndex || !coverage.freshness.ok) {
+    actions.add('ak-docs index')
+  }
+  if (coverage.packages.missingHumanDoc.length) {
+    actions.add('ak-docs bootstrap agent-docs')
+  }
+  if (coverage.packages.total > 0) {
+    const sample =
+      coverage.packages.missingAgentDoc[0] ??
+      coverage.packages.missingHumanDoc[0]
+    if (sample) actions.add(`ak-docs query package ${sample} --agent`)
+  }
+  if (!actions.size) {
+    actions.add('ak-docs mcp install --cursor')
+    actions.add('ak-docs gate run')
+  }
+
+  return [...actions].slice(0, 6)
+}
+
+export const runDoctor = (root: string, config: DocBridgeConfigV1): DoctorReport => {
+  let index: DocBridgeIndexV1 | undefined
+  let hasIndex = true
+  let freshnessOk = false
+  let freshnessMessage = 'Index is fresh'
+
+  try {
+    index = loadDocBridgeIndex(root, config)
+    const next = buildDocBridgeIndex({ root, config, write: false }).index.contentHash
+    freshnessOk = index.contentHash === next
+    freshnessMessage = freshnessOk ? 'Index is fresh' : 'Index is stale. Run: ak-docs index'
+  } catch (error) {
+    if (error instanceof IndexNotFoundError) {
+      hasIndex = false
+      freshnessOk = false
+      freshnessMessage = error.message
+      index = buildDocBridgeIndex({ root, config, write: false }).index
+    } else {
+      throw error
+    }
+  }
+
+  const ownership = Object.entries(index.lookup?.ownership ?? {})
+  const missingAgentDoc = ownership
+    .filter(([, owner]) => !owner.agentDoc || owner.agentDoc === config.corpus.agent.index)
+    .map(([id]) => id)
+  const missingHumanDoc = ownership.filter(([, owner]) => !owner.humanDoc).map(([id]) => id)
+
+  const indexedPaths = new Set(index.knowledge.map((entry) => entry.path))
+  const expectedAgentDocs = agentDocPaths(index)
+  const unindexed = [...expectedAgentDocs].filter((path) => !indexedPaths.has(path))
+
+  const corpusDocs = scanAgentCorpus(root, config).filter(
+    (doc) => doc.path !== config.corpus.agent.index,
+  )
+
+  const gates = runGates(root, config)
+
+  const coverage: DoctorCoverage = {
+    packages: {
+      total: ownership.length,
+      withAgentDoc: ownership.length - missingAgentDoc.length,
+      withHumanDoc: ownership.length - missingHumanDoc.length,
+      missingAgentDoc,
+      missingHumanDoc,
+    },
+    agentDocs: {
+      total: corpusDocs.length,
+      indexed: corpusDocs.filter((doc) => indexedPaths.has(doc.path)).length,
+      unindexed: corpusDocs.filter((doc) => !indexedPaths.has(doc.path)).map((doc) => doc.path),
+    },
+    freshness: {
+      ok: freshnessOk,
+      message: freshnessMessage,
+      hasIndex,
+    },
+    gates,
+  }
+
+  const issues = buildIssues(coverage)
+  const score = computeScore(coverage)
+  const nextActions = buildNextActions(issues, coverage)
+
+  const report: DoctorReport = {
+    ok: issues.every((issue) => issue.severity !== 'error') && gates.ok,
+    score,
+    grade: gradeForScore(score),
+    coverage,
+    badge: { handoffPct: 0, bridgePct: 0, score, grade: gradeForScore(score), packages: 0 },
+    issues,
+    nextActions,
+  }
+  return { ...report, badge: doctorBadgeMetrics(report) }
+}
+
+export const formatDoctorText = (report: DoctorReport): string[] => {
+  const { coverage } = report
+  const handoffPct =
+    coverage.packages.total > 0
+      ? Math.round((coverage.packages.withAgentDoc / coverage.packages.total) * 100)
+      : 0
+  const humanPct =
+    coverage.packages.total > 0
+      ? Math.round((coverage.packages.withHumanDoc / coverage.packages.total) * 100)
+      : 0
+
+  const lines = [
+    'doc-bridge doctor',
+    '─'.repeat(40),
+    `Score: ${report.score}/100 (${report.grade})`,
+    '',
+    'Coverage',
+    `  Packages:        ${coverage.packages.total}`,
+    `  Agent docs:      ${coverage.packages.withAgentDoc}/${coverage.packages.total} (${handoffPct}% handoff-ready)`,
+    `  Human guides:    ${coverage.packages.withHumanDoc}/${coverage.packages.total} (${humanPct}% bridged)`,
+    `  Corpus indexed:  ${coverage.agentDocs.indexed}/${coverage.agentDocs.total} agent docs`,
+    `  Index freshness: ${coverage.freshness.ok ? 'fresh' : 'stale or missing'}`,
+    `  Gates:           ${coverage.gates.results.filter((g) => g.ok).length}/${coverage.gates.results.length} passing`,
+    `  Badge:           handoff ${report.badge.handoffPct}% · bridge ${report.badge.bridgePct}%`,
+  ]
+
+  if (coverage.packages.missingHumanDoc.length) {
+    lines.push('', 'Missing humanDoc (bridge gap)', ...coverage.packages.missingHumanDoc.map((id) => `  • ${id}`))
+  }
+  if (coverage.packages.missingAgentDoc.length) {
+    lines.push('', 'Missing agent doc', ...coverage.packages.missingAgentDoc.map((id) => `  • ${id}`))
+  }
+
+  if (report.issues.length) {
+    lines.push('', 'Issues')
+    for (const issue of report.issues.slice(0, 8)) {
+      const icon = issue.severity === 'error' ? '✗' : issue.severity === 'warn' ? '!' : '·'
+      lines.push(`  ${icon} [${issue.code}] ${issue.message}`)
+    }
+    if (report.issues.length > 8) {
+      lines.push(`  … +${report.issues.length - 8} more`)
+    }
+  }
+
+  lines.push('', 'Next actions', ...report.nextActions.map((action) => `  → ${action}`))
+  return lines
+}

package/src/federation/llms.ts

@@ -35,11 +35,15 @@ const sourceText = async (
   root: string,
   source: string,
   fetchText: FetchText,
-): Promise<string> => {
-  if (/^https?:\/\//.test(source)) return fetchText(source)
-  const path = resolve(root, source)
-  if (!existsSync(path)) throw new Error(`Federation source not found: ${source}`)
-  return readFileSync(path, 'utf8')
+): Promise<string | null> => {
+  try {
+    if (/^https?:\/\//.test(source)) return await fetchText(source)
+    const path = resolve(root, source)
+    if (!existsSync(path)) return null
+    return readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
 }
 
 const sameOrigin = (base: string, target: string): boolean => {
@@ -97,9 +101,14 @@ export const loadFederatedChunks = async (
 ): Promise<DocBridgeRetrievedChunk[]> => {
   const fetchText = options.fetchText ?? defaultFetchText
   const chunks: DocBridgeRetrievedChunk[] = []
+  const warnings: string[] = []
   for (const source of config.federation?.sources ?? []) {
     if (source.includeInRetriever === false || !source.llmsTxt) continue
     const llms = await sourceText(root, source.llmsTxt, fetchText)
+    if (!llms) {
+      warnings.push(`federation source skipped (unavailable): ${source.id} → ${source.llmsTxt}`)
+      continue
+    }
     chunks.push(...chunksFromMarkdown(source.id, llms, source.llmsTxt))
     const links = parseLlmsTxtLinks(llms)
     for (const link of links) {
@@ -108,14 +117,14 @@ export const loadFederatedChunks = async (
         : link.url
       if (!/\.(md|txt)(?:$|\?)/.test(url)) continue
       if (!sameOrigin(source.llmsTxt, url)) continue
-      try {
-        const raw = await sourceText(root, url, fetchText)
-        chunks.push(...chunksFromMarkdown(source.id, raw, url))
-      } catch {
-        // ponytail: federation is best-effort; surface-level health belongs in a future diagnostic command.
-      }
+      const raw = await sourceText(root, url, fetchText)
+      if (raw) chunks.push(...chunksFromMarkdown(source.id, raw, url))
     }
   }
+  // Soft-fail: never throw for missing remote sources; one-line warn for agents/humans.
+  if (warnings.length && process.stderr.isTTY) {
+    for (const w of warnings) process.stderr.write(`${w}\n`)
+  }
   return chunks
 }
 

package/src/index-builder/build-handoffs.ts

@@ -103,16 +103,31 @@ const resolveHumanDoc = (
   if (override) return override
   if (fmHuman) return fmHuman
   if (humanDocs[packageId]) return humanDocs[packageId]
-  // common aliases: scoped package name tail, path segments
+
   const aliases = [
     packageId,
     packageId.replace(/^@[^/]+\//, ''),
     packageId.replace(/^os-/, ''),
     packageId.replace(/-pattern$/, ''),
+    `packages/${packageId}`,
+    `reference/packages/${packageId}`,
+    `packages/${packageId}/index`,
   ]
   for (const alias of aliases) {
     if (humanDocs[alias]) return humanDocs[alias]
   }
+
+  // Fuzzy: id is a path segment or suffix of a human doc id
+  for (const [key, url] of Object.entries(humanDocs)) {
+    if (
+      key === packageId ||
+      key.endsWith(`/${packageId}`) ||
+      key.endsWith(`/${packageId}/index`) ||
+      key.endsWith(`-${packageId}`)
+    ) {
+      return url
+    }
+  }
   return undefined
 }
 
@@ -168,6 +183,18 @@ export const buildLookup = (
     }
     ownership[pkg.id] = record
 
+    const bridge = record.humanDoc
+      ? /^https?:\/\//.test(record.humanDoc)
+        ? { humanDoc: 'external' as const }
+        : { humanDoc: 'linked' as const }
+      : config.corpus.human
+        ? {
+            humanDoc: 'missing' as const,
+            action: 'ak-docs bootstrap agent-docs',
+            bootstrap: `docs/for-agents/human/${pkg.id}.md`,
+          }
+        : undefined
+
     handoffs[pkg.id] = {
       type: 'agent-handoff',
       schemaVersion: 1,
@@ -186,7 +213,13 @@ export const buildLookup = (
       editRoots: [record.path],
       checks: [...record.checks],
       ...(record.humanDoc ? { humanDoc: record.humanDoc } : {}),
-      notes: record.purpose ? [record.purpose] : [],
+      ...(bridge ? { bridge } : {}),
+      notes: [
+        ...(record.purpose ? [record.purpose] : []),
+        ...(!record.humanDoc && config.corpus.human
+          ? [`Human guide missing for ${pkg.id}. Run: ak-docs bootstrap agent-docs`]
+          : []),
+      ],
     }
   }
 

package/src/index-builder/scan-corpus.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 
 import type { DocBridgeConfigV1 } from '../config/schema.js'
 import {
+  extractSearchBody,
   firstHeading,
   firstParagraph,
   frontmatterString,
@@ -47,7 +48,9 @@ export const scanAgentCorpus = (root: string, config: DocBridgeConfigV1): Corpus
       frontmatterString(frontmatter, 'package') ??
       slugFromPath(relToCorpus)
     const title = firstHeading(raw) ?? id
-    const description = firstParagraph(raw)
+    const purpose = frontmatterString(frontmatter, 'purpose')
+    const description = purpose ?? firstParagraph(raw, 400)
+    const body = extractSearchBody(raw)
     return {
       id,
       type: 'agent-doc',
@@ -57,6 +60,7 @@ export const scanAgentCorpus = (root: string, config: DocBridgeConfigV1): Corpus
       relPath,
       frontmatter,
       ...(description ? { description } : {}),
+      ...(body ? { body } : {}),
     }
   })
 }

package/src/index-builder/watch-index.ts

@@ -0,0 +1,94 @@
+import { existsSync, watch } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { buildDocBridgeIndex } from './build-index.js'
+
+export type WatchIndexOptions = {
+  readonly root: string
+  readonly config: DocBridgeConfigV1
+  readonly configPath?: string
+  readonly debounceMs?: number
+  readonly onRebuild?: (summary: { knowledgeCount: number; handoffCount: number; hash: string }) => void
+}
+
+const WATCH_PATTERN = /\.(md|mdx|json|ya?ml|mdc)$/i
+
+const collectWatchRoots = (root: string, config: DocBridgeConfigV1, configPath?: string): string[] => {
+  const roots = new Set<string>()
+  roots.add(resolve(root, config.corpus.agent.root))
+  const humanSources = config.corpus.human
+    ? Array.isArray(config.corpus.human)
+      ? config.corpus.human
+      : [config.corpus.human]
+    : []
+  for (const source of humanSources) {
+    const humanOpts = source.options ?? {}
+    for (const key of ['contentDir', 'docsDir', 'root']) {
+      const value = humanOpts[key]
+      if (typeof value === 'string' && value.length) roots.add(resolve(root, value))
+    }
+  }
+  if (configPath) roots.add(dirname(resolve(configPath)))
+  return [...roots].filter((dir) => existsSync(dir))
+}
+
+export const watchDocBridgeIndex = (opts: WatchIndexOptions): Promise<number> => {
+  const debounceMs = opts.debounceMs ?? 350
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let running = false
+
+  const rebuild = (): void => {
+    if (timer) clearTimeout(timer)
+    timer = setTimeout(() => {
+      if (running) return
+      running = true
+      try {
+        const result = buildDocBridgeIndex({ root: opts.root, config: opts.config })
+        const handoffCount = Object.keys(result.index.handoffs ?? {}).length
+        const summary = {
+          knowledgeCount: result.index.knowledge.length,
+          handoffCount,
+          hash: result.index.contentHash.slice(0, 8),
+        }
+        opts.onRebuild?.(summary)
+        process.stdout.write(
+          `[ak-docs] indexed ${summary.knowledgeCount} docs, ${summary.handoffCount} handoffs (${summary.hash}…)\n`,
+        )
+      } catch (error) {
+        process.stderr.write(
+          `[ak-docs] index failed: ${error instanceof Error ? error.message : String(error)}\n`,
+        )
+      } finally {
+        running = false
+      }
+    }, debounceMs)
+  }
+
+  rebuild()
+
+  for (const dir of collectWatchRoots(opts.root, opts.config, opts.configPath)) {
+    watch(dir, { recursive: true }, (_event, filename) => {
+      if (!filename || !WATCH_PATTERN.test(filename)) return
+      rebuild()
+    })
+  }
+
+  const configDir = resolve(opts.root)
+  if (existsSync(configDir)) {
+    watch(configDir, (_event, filename) => {
+      if (!filename || !/doc-bridge\.config/.test(filename)) return
+      rebuild()
+    })
+  }
+
+  process.stdout.write(
+    `[ak-docs] watching ${collectWatchRoots(opts.root, opts.config, opts.configPath).join(', ') || opts.root} (Ctrl+C to stop)\n`,
+  )
+
+  return new Promise((resolvePromise) => {
+    const onSignal = () => resolvePromise(0)
+    process.once('SIGINT', onSignal)
+    process.once('SIGTERM', onSignal)
+  })
+}

package/src/index.ts

@@ -20,7 +20,9 @@ export {
   HandoffTargetTypeSchema,
   HANDOFF_SCHEMA_VERSION,
   normalizeAgentHandoff,
+  HandoffBridgeSchema,
   type AgentHandoffV1,
+  type HandoffBridge,
   type AgentSearchV1,
   type HandoffTarget,
   type HandoffTargetType,
@@ -74,6 +76,22 @@ export {
   type GateRunResult,
 } from './gates/run-gates.js'
 export { MCP_TOOLS, handleMcpRequest, startMcpStdioServer } from './mcp/server.js'
+export { installMcpConfig, mcpSnippet, type McpInstallResult, type McpInstallTarget } from './mcp/install.js'
+export { runDoctor, formatDoctorText, type DoctorReport, type DoctorIssue, type DoctorCoverage } from './doctor/run-doctor.js'
+export {
+  doctorBadgeMetrics,
+  formatDoctorBadgeJson,
+  formatDoctorBadgeMarkdown,
+  type DoctorBadgeMetrics,
+} from './doctor/badge.js'
+export { watchDocBridgeIndex, type WatchIndexOptions } from './index-builder/watch-index.js'
+export {
+  promoteMemoryToGithubPr,
+  writePromotionDraft,
+  defaultPromotionDraftPath,
+  type GithubPrOptions,
+  type GithubPrResult,
+} from './memory/github-pr.js'
 export { sha256NormalizedV1 } from './index-builder/content-hash.js'
 export { IndexNotFoundError, indexFilePath, loadDocBridgeIndex, resolveRoot } from './query/load-index.js'
 export { runQuery, type QueryKind, type QueryRequest, type QueryResult } from './query/query.js'
@@ -118,3 +136,9 @@ export { projectRootFromConfigPath } from './config/load-config.js'
 export { createDocBridgeRag } from './intelligence/rag.js'
 export { runChatOnce, startInkChat } from './intelligence/chat.js'
 export { PeerMissingError, layer1InstallHint } from './intelligence/peers.js'
+export {
+  DOC_BRIDGE_PATTERN_ID,
+  DOC_BRIDGE_PATTERN_META,
+  docBridgePatternMarkdown,
+  docBridgePatternPayload,
+} from './playbook/doc-bridge-pattern.js'

package/src/lib/markdown.ts

@@ -64,7 +64,8 @@ export const firstHeading = (markdown: string): string | undefined => {
   return undefined
 }
 
-export const firstParagraph = (markdown: string): string | undefined => {
+/** Complete first prose block — prefer full sentences, cap length without mid-word cuts. */
+export const firstParagraph = (markdown: string, maxLen = 400): string | undefined => {
   const { body } = parseFrontmatter(markdown)
   const lines = body.split('\n')
   const buf: string[] = []
@@ -76,11 +77,37 @@ export const firstParagraph = (markdown: string): string | undefined => {
     }
     if (t.startsWith('#')) continue
     if (t.startsWith('---')) continue
+    if (t.startsWith('```')) break
+    if (t.startsWith('|') || t.startsWith('- [') || t.startsWith('* [')) {
+      if (buf.length) break
+      continue
+    }
     buf.push(t)
-    if (buf.join(' ').length > 40) break
+    if (buf.join(' ').length >= maxLen) break
   }
-  const text = buf.join(' ').trim()
-  return text || undefined
+  let text = buf.join(' ').replace(/\s+/g, ' ').trim()
+  if (!text) return undefined
+  if (text.length <= maxLen) return text
+  // Prefer ending on sentence boundary
+  const sliced = text.slice(0, maxLen)
+  const sentenceEnd = Math.max(sliced.lastIndexOf('. '), sliced.lastIndexOf('! '), sliced.lastIndexOf('? '))
+  if (sentenceEnd > maxLen * 0.4) return sliced.slice(0, sentenceEnd + 1).trim()
+  const wordEnd = sliced.lastIndexOf(' ')
+  return (wordEnd > 0 ? sliced.slice(0, wordEnd) : sliced).trim()
+}
+
+/** Flatten markdown body for search (strip fences/links noise lightly). */
+export const extractSearchBody = (markdown: string, maxLen = 6_000): string => {
+  const { body } = parseFrontmatter(markdown)
+  const text = body
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/!\[[^\]]*\]\([^)]+\)/g, ' ')
+    .replace(/\[[^\]]*\]\([^)]+\)/g, ' ')
+    .replace(/^#+\s+/gm, '')
+    .replace(/[|>*_`#]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+  return text.length > maxLen ? text.slice(0, maxLen) : text
 }
 
 export const slugFromPath = (relPath: string): string => {