upcontent 0.0.0-stage → 0.1.0

package/src/lib/content-blocklist.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+  readFileSync: vi.fn(),
+}))
+
+import * as fs from 'node:fs'
+import { isBlocked, resolveLabel, toTitleCase } from './content-blocklist'
+import { _resetPortalConfigCache } from './portal-config'
+
+beforeEach(() => {
+  _resetPortalConfigCache()
+  vi.mocked(fs.existsSync).mockReturnValue(false)
+})
+
+describe('toTitleCase', () => {
+  it('deixa o resto da palavra em minúsculo mesmo quando o nome original é tudo maiúsculo', () => {
+    expect(toTitleCase('README')).toBe('Readme')
+  })
+
+  it('capitaliza cada palavra separada por hífen', () => {
+    expect(toTitleCase('gestao-licencas-acessos')).toBe('Gestao Licencas Acessos')
+  })
+})
+
+describe('resolveLabel', () => {
+  it('usa toTitleCase quando não há override configurado', () => {
+    expect(resolveLabel('historico')).toBe('Historico')
+  })
+
+  it('usa o override do .upcontent/config.json quando presente (case-insensitive)', () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ navigation: { labelOverrides: { historico: 'Histórico' } } }),
+    )
+    expect(resolveLabel('historico')).toBe('Histórico')
+    expect(resolveLabel('Historico')).toBe('Histórico')
+  })
+})
+
+describe('isBlocked', () => {
+  it('protects the renderer checkout from external consumer content', () => {
+    expect(isBlocked('.upcontent-renderer/README.md')).toBe(true)
+    expect(isBlocked('.UPCONTENT-RENDERER/README.md')).toBe(true)
+  })
+})

package/src/lib/content-blocklist.ts

@@ -0,0 +1,55 @@
+import { getPortalConfig } from './portal-config'
+
+// Extraído de content.config.ts: precisa ser importável de astro.config.mjs
+// (sidebar.ts) e vitest sem depender de 'astro:content', que só resolve
+// dentro do pipeline do Astro — content.config.ts importa esse módulo em vez
+// de definir a lógica localmente.
+
+// Floor hardcoded: nunca aparecem independentemente do config.json.
+// Comparação sempre case-insensitive — arquivos reais podem usar qualquer
+// caixa (ex: shared/INDEX.md em vez de shared/index.md).
+const FLOOR_EXACT = new Set(['claude.md', 'rules.md', 'shared/index.md'])
+const FLOOR_PREFIXES = ['.claude/', '.github/', '.upcontent/', '.upcontent-renderer/']
+
+const DOCS_BASE = 'src/content/docs/'
+
+// entry.filePath de collections com o loader glob()/docsLoader() é relativo
+// à raiz do projeto (ex: "src/content/docs/RULES.md") — isBlocked() espera
+// o path relativo ao content base (ex: "RULES.md").
+export function toRelativeDocPath(filePath: string): string {
+  return filePath.startsWith(DOCS_BASE) ? filePath.slice(DOCS_BASE.length) : filePath
+}
+
+export function isBlocked(path: string): boolean {
+  const normalizedPath = path.toLowerCase()
+  if (FLOOR_EXACT.has(normalizedPath)) return true
+  if (FLOOR_PREFIXES.some(prefix => normalizedPath.startsWith(prefix.toLowerCase()))) return true
+  const cfg = getPortalConfig()
+  const exact = cfg.navigation?.blocklist?.exact ?? []
+  const prefixes = cfg.navigation?.blocklist?.prefixes ?? []
+  if (exact.some(e => normalizedPath === e.toLowerCase())) return true
+  return prefixes.some(prefix => normalizedPath.startsWith(prefix.toLowerCase()))
+}
+
+export function getBlocklist(): string[] {
+  const cfg = getPortalConfig()
+  const extraExact = cfg.navigation?.blocklist?.exact ?? []
+  const extraPrefixes = cfg.navigation?.blocklist?.prefixes ?? []
+  return [...FLOOR_EXACT, ...FLOOR_PREFIXES, ...extraExact, ...extraPrefixes]
+}
+
+export function toTitleCase(filenameWithoutExt: string): string {
+  const withoutNumericPrefix = filenameWithoutExt.replace(/^\d+[-_]/, '')
+  const words = withoutNumericPrefix.split(/[-_\s]+/).filter(Boolean)
+  if (words.length === 0) return filenameWithoutExt
+  return words.map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join(' ')
+}
+
+// Nomes de pasta/arquivo em ASCII (sem acento) não podem ser recuperados
+// automaticamente pro português — quem conhece o vocabulário é o
+// repositório de conteúdo, via navigation.labelOverrides no .upcontent/config.json.
+// Fallback é sempre toTitleCase(name) quando não há override.
+export function resolveLabel(name: string): string {
+  const override = getPortalConfig().navigation?.labelOverrides?.[name.toLowerCase()]
+  return override ?? toTitleCase(name)
+}

package/src/lib/doc-links.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest'
+import { buildGitHubUrl, resolveRelated } from './doc-links'
+
+describe('buildGitHubUrl', () => {
+  it('retorna undefined quando repoUrl não definido', () => {
+    expect(buildGitHubUrl(undefined, 'domains/foo/bar.md', 'view')).toBeUndefined()
+  })
+
+  it('retorna link view quando repoUrl definido', () => {
+    const url = buildGitHubUrl('https://github.com/org/repo', 'domains/foo/bar.md', 'view')
+    expect(url).toBe('https://github.com/org/repo/blob/main/domains/foo/bar.md')
+  })
+
+  it('retorna link edit quando repoUrl definido', () => {
+    const url = buildGitHubUrl('https://github.com/org/repo', 'domains/foo/bar.md', 'edit')
+    expect(url).toBe('https://github.com/org/repo/edit/main/domains/foo/bar.md')
+  })
+
+  it('não adiciona .md duplo quando entryId já termina em .md', () => {
+    const url = buildGitHubUrl('https://github.com/org/repo', 'domains/foo/bar.md', 'view')
+    expect(url).not.toContain('.md.md')
+  })
+})
+
+describe('resolveRelated', () => {
+  const allDocs = [
+    { id: 'domains/foo/prd.md', data: { title: 'Foo PRD' } },
+    { id: 'shared/glossary.md', data: { title: 'Glossário' } },
+    { id: 'domains/bar/trd.md', data: {} },
+  ]
+
+  it('retorna lista vazia quando related é undefined', () => {
+    expect(resolveRelated(undefined, allDocs as any)).toEqual([])
+  })
+
+  it('retorna lista vazia quando related é array vazio', () => {
+    expect(resolveRelated([], allDocs as any)).toEqual([])
+  })
+
+  it('resolve entry com .md normalizado', () => {
+    const result = resolveRelated(['domains/foo/prd'], allDocs as any)
+    expect(result).toHaveLength(1)
+    expect(result[0].title).toBe('Foo PRD')
+    expect(result[0].slug).toBe('domains/foo/prd')
+  })
+
+  it('resolve entry referenciado com extensão .md', () => {
+    const result = resolveRelated(['shared/glossary.md'], allDocs as any)
+    expect(result).toHaveLength(1)
+    expect(result[0].title).toBe('Glossário')
+  })
+
+  it('ignora referências que não existem na coleção', () => {
+    const result = resolveRelated(['domains/nao-existe'], allDocs as any)
+    expect(result).toHaveLength(0)
+  })
+
+  it('usa o id como título fallback quando title ausente', () => {
+    const result = resolveRelated(['domains/bar/trd'], allDocs as any)
+    expect(result[0].title).toBe('domains/bar/trd')
+  })
+})

package/src/lib/doc-links.ts

@@ -0,0 +1,31 @@
+import type { CollectionEntry } from 'astro:content'
+
+export function buildGitHubUrl(
+  repoUrl: string | undefined,
+  entryId: string,
+  mode: 'view' | 'edit',
+): string | undefined {
+  if (!repoUrl) return undefined
+  const action = mode === 'edit' ? 'edit' : 'blob'
+  return `${repoUrl}/${action}/main/${entryId}`
+}
+
+export interface RelatedDoc {
+  slug: string
+  title: string
+}
+
+export function resolveRelated(
+  related: string[] | undefined,
+  allDocs: CollectionEntry<'docs'>[],
+): RelatedDoc[] {
+  if (!related || related.length === 0) return []
+  return related.flatMap(ref => {
+    const normalized = ref.endsWith('.md') ? ref : `${ref}.md`
+    const entry = allDocs.find(d => d.id === normalized)
+    if (!entry) return []
+    const slug = normalized.replace(/\.md$/, '')
+    const title = (entry.data as Record<string, unknown>).title as string | undefined ?? slug
+    return [{ slug, title }]
+  })
+}

package/src/lib/mermaid-render.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect, vi } from 'vitest'
+import { renderMermaidDiagram, type MermaidLib } from './mermaid-render'
+
+describe('renderMermaidDiagram', () => {
+  it('código válido → retorna o SVG renderizado', async () => {
+    const mermaid: MermaidLib = {
+      render: vi.fn().mockResolvedValue({ svg: '<svg>diagrama</svg>' }),
+    }
+    const result = await renderMermaidDiagram(mermaid, 'flowchart TD\nA-->B')
+    expect(result).toEqual({ status: 'ok', svg: '<svg>diagrama</svg>' })
+  })
+
+  it('código inválido → retorna a fonte original + mensagem de erro, sem lançar', async () => {
+    const mermaid: MermaidLib = {
+      render: vi.fn().mockRejectedValue(new Error('Parse error on line 1')),
+    }
+    const source = 'isso não é mermaid válido'
+    const result = await renderMermaidDiagram(mermaid, source)
+    expect(result).toEqual({ status: 'error', source, message: 'Parse error on line 1' })
+  })
+
+  it('erro que não é instância de Error também vira mensagem string, sem lançar', async () => {
+    const mermaid: MermaidLib = {
+      render: vi.fn().mockRejectedValue('algo deu errado'),
+    }
+    const result = await renderMermaidDiagram(mermaid, 'fonte')
+    expect(result).toEqual({ status: 'error', source: 'fonte', message: 'algo deu errado' })
+  })
+
+  it('cada chamada usa um id único (evita colisão entre diagramas na mesma página)', async () => {
+    const ids: string[] = []
+    const mermaid: MermaidLib = {
+      render: vi.fn().mockImplementation(async (id: string) => {
+        ids.push(id)
+        return { svg: '<svg/>' }
+      }),
+    }
+    await renderMermaidDiagram(mermaid, 'a')
+    await renderMermaidDiagram(mermaid, 'b')
+    expect(ids[0]).not.toBe(ids[1])
+  })
+})

package/src/lib/mermaid-render.ts

@@ -0,0 +1,24 @@
+// Interface mínima da lib mermaid que este módulo precisa — permite mockar
+// em teste sem importar a lib real (que depende de DOM/canvas).
+export interface MermaidLib {
+  render(id: string, source: string): Promise<{ svg: string }>
+}
+
+export type MermaidRenderResult =
+  | { status: 'ok'; svg: string }
+  | { status: 'error'; source: string; message: string }
+
+let renderCounter = 0
+
+// Função pura de parse/render: nunca lança — sintaxe inválida vira um
+// resultado 'error' carregando a fonte original + mensagem, pro caller
+// decidir como exibir (em vez de deixar a página em branco).
+export async function renderMermaidDiagram(mermaid: MermaidLib, source: string): Promise<MermaidRenderResult> {
+  const id = `mermaid-diagram-${renderCounter++}`
+  try {
+    const { svg } = await mermaid.render(id, source)
+    return { status: 'ok', svg }
+  } catch (error) {
+    return { status: 'error', source, message: error instanceof Error ? error.message : String(error) }
+  }
+}

package/src/lib/portal-config.test.ts

@@ -0,0 +1,143 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+// Mock node:fs before importing the module under test
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn(),
+  readFileSync: vi.fn(),
+}))
+
+import * as fs from 'node:fs'
+
+describe('getPortalConfig', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    vi.resetAllMocks()
+  })
+
+  it('retorna config vazia quando config.json não existe', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false)
+    const { getPortalConfig } = await import('./portal-config')
+    const config = getPortalConfig()
+    expect(config).toEqual({})
+  })
+
+  it('retorna config parseada quando config.json existe e é válido', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(
+       JSON.stringify({
+        site: {
+          title: 'Meu Portal',
+          description: 'Documentação do time',
+          url: 'https://docs.example.com',
+          logo: { src: '/logo.svg', alt: 'Meu Portal', replacesTitle: true },
+          favicon: '/favicon.svg',
+        },
+         repo: { url: 'https://github.com/org/repo' },
+         theme: { customCss: ['.upcontent/theme.css'] },
+         starlight: {
+           social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/org/repo' }],
+           tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 },
+           lastUpdated: true,
+           pagination: false,
+           expressiveCode: { styleOverrides: { borderRadius: '8px' } },
+         },
+         navigation: { roots: ['domains', 'shared'] },
+      })
+    )
+    const { getPortalConfig } = await import('./portal-config')
+    const config = getPortalConfig()
+    expect(config.site?.title).toBe('Meu Portal')
+    expect(config.site?.description).toBe('Documentação do time')
+    expect(config.site?.url).toBe('https://docs.example.com')
+    expect(config.site?.logo?.src).toBe('/logo.svg')
+    expect(config.site?.favicon).toBe('/favicon.svg')
+    expect(config.repo?.url).toBe('https://github.com/org/repo')
+     expect(config.theme?.customCss).toEqual(['.upcontent/theme.css'])
+    expect(config.starlight?.social?.[0].icon).toBe('github')
+    expect(config.starlight?.tableOfContents).toEqual({ minHeadingLevel: 2, maxHeadingLevel: 3 })
+    expect(config.starlight?.lastUpdated).toBe(true)
+    expect(config.starlight?.pagination).toBe(false)
+    expect(config.starlight?.expressiveCode).toEqual({ styleOverrides: { borderRadius: '8px' } })
+    expect(config.navigation?.roots).toEqual(['domains', 'shared'])
+  })
+
+  it('retorna config vazia quando config.json é JSON inválido', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue('{ invalid json }')
+    const { getPortalConfig } = await import('./portal-config')
+    const config = getPortalConfig()
+    expect(config).toEqual({})
+  })
+
+  it('normaliza tipos inválidos sem quebrar a configuração do portal', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ site: 'invalid', theme: { customCss: 'invalid' }, navigation: { roots: [1, 'docs'] } }),
+    )
+    const { getPortalConfig } = await import('./portal-config')
+
+    const config = getPortalConfig()
+
+    expect(config.site?.title).toBeUndefined()
+    expect(config.theme?.customCss).toBeUndefined()
+    expect(config.navigation?.roots).toEqual(['docs'])
+  })
+
+  it('navigation.roots com valor customizado sobrepõe default', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ navigation: { roots: ['domains'] } })
+    )
+    const { getPortalConfig } = await import('./portal-config')
+    const config = getPortalConfig()
+    expect(config.navigation?.roots).toEqual(['domains'])
+  })
+
+  it('navigation.blocklist extra é retornado quando definido', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({
+        navigation: {
+          blocklist: { exact: ['rules.md'], prefixes: ['docs/'] },
+        },
+      })
+    )
+    const { getPortalConfig } = await import('./portal-config')
+    const config = getPortalConfig()
+    expect(config.navigation?.blocklist?.exact).toContain('rules.md')
+    expect(config.navigation?.blocklist?.prefixes).toContain('docs/')
+  })
+
+  it('descarta tipos inválidos nas opções curadas do Starlight', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({
+        starlight: {
+          social: [{ icon: 'github' }, { icon: 'github', label: 'GitHub', href: 'https://github.com' }],
+          tableOfContents: { minHeadingLevel: '2', maxHeadingLevel: 7 },
+          lastUpdated: 'yes',
+          pagination: 1,
+          expressiveCode: { styleOverrides: { borderRadius: 8, padding: '1rem' } },
+        },
+      }),
+    )
+    const { getPortalConfig } = await import('./portal-config')
+    const config = getPortalConfig()
+
+    expect(config.starlight?.social).toEqual([{ icon: 'github', label: 'GitHub', href: 'https://github.com' }])
+    expect(config.starlight?.tableOfContents).toEqual({ minHeadingLevel: undefined, maxHeadingLevel: undefined })
+    expect(config.starlight?.lastUpdated).toBeUndefined()
+    expect(config.starlight?.pagination).toBeUndefined()
+    expect(config.starlight?.expressiveCode).toEqual({ styleOverrides: { padding: '1rem' } })
+  })
+
+  it('descarta um intervalo inválido do sumário', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ starlight: { tableOfContents: { minHeadingLevel: 4, maxHeadingLevel: 2 } } }),
+    )
+
+    const { getPortalConfig } = await import('./portal-config')
+    expect(getPortalConfig().starlight?.tableOfContents).toBeUndefined()
+  })
+})

package/src/lib/portal-config.ts

@@ -0,0 +1,176 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface PortalConfigNavigation {
+  roots?: string[]
+  blocklist?: {
+    exact?: string[]
+    prefixes?: string[]
+  }
+  // Sobrescreve o label derivado automaticamente (Title Case, sem acentos)
+  // pro nome de pasta/arquivo indicado — chave em minúsculo, sem extensão
+  // (ex: "historico" -> "Histórico"). Sem isso não há como recuperar
+  // acentuação a partir de um nome de arquivo ASCII.
+  labelOverrides?: Record<string, string>
+}
+
+export interface PortalConfigLogo {
+  src: string
+  alt?: string
+  replacesTitle?: boolean
+}
+
+export interface PortalConfigSite {
+  title?: string
+  description?: string
+  url?: string
+  logo?: PortalConfigLogo
+  favicon?: string
+}
+
+export interface PortalConfigTheme {
+  customCss?: string[]
+}
+
+export interface PortalConfigStarlight {
+  social?: { icon: string; label: string; href: string }[]
+  tableOfContents?: false | { minHeadingLevel?: number; maxHeadingLevel?: number }
+  lastUpdated?: boolean
+  pagination?: boolean
+  expressiveCode?: false | { styleOverrides?: Record<string, string> }
+}
+
+export interface PortalConfig {
+  site?: PortalConfigSite
+  repo?: { url?: string }
+  theme?: PortalConfigTheme
+  starlight?: PortalConfigStarlight
+  navigation?: PortalConfigNavigation
+  content?: { titleField?: string }
+}
+
+const CONFIG_PATH = join(process.cwd(), 'src/content/docs/.upcontent/config.json')
+
+let _cache: PortalConfig | null = null
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+function asStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  const values = value.filter((item): item is string => typeof item === 'string' && item.length > 0)
+  return values.length > 0 ? values : []
+}
+
+function asStringRecord(value: unknown): Record<string, string> | undefined {
+  const record = asRecord(value)
+  const entries: [string, string][] = []
+  for (const [key, item] of Object.entries(record)) {
+    if (typeof item === 'string') entries.push([key, item])
+  }
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined
+}
+
+function asSocialLinks(value: unknown): PortalConfigStarlight['social'] {
+  if (!Array.isArray(value)) return undefined
+  const links = value.flatMap(item => {
+    const link = asRecord(item)
+    const icon = asString(link.icon)
+    const label = asString(link.label)
+    const href = asString(link.href)
+    return icon && label && href ? [{ icon, label, href }] : []
+  })
+  return links.length > 0 ? links : []
+}
+
+function asHeadingLevel(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 6 ? value : undefined
+}
+
+function asTableOfContents(value: unknown): PortalConfigStarlight['tableOfContents'] {
+  if (value === false) return false
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined
+
+  const raw = asRecord(value)
+  const minHeadingLevel = asHeadingLevel(raw.minHeadingLevel)
+  const maxHeadingLevel = asHeadingLevel(raw.maxHeadingLevel)
+  if (minHeadingLevel !== undefined && maxHeadingLevel !== undefined && minHeadingLevel > maxHeadingLevel) {
+    return undefined
+  }
+  return { minHeadingLevel, maxHeadingLevel }
+}
+
+function normalizeConfig(value: unknown): PortalConfig {
+  const raw = asRecord(value)
+  const rawSite = asRecord(raw.site)
+  const rawLogo = asRecord(rawSite.logo)
+  const rawRepo = asRecord(raw.repo)
+  const rawTheme = asRecord(raw.theme)
+  const rawStarlight = asRecord(raw.starlight)
+  const rawExpressiveCode = rawStarlight.expressiveCode
+  const rawExpressive = asRecord(rawExpressiveCode)
+  const rawNavigation = asRecord(raw.navigation)
+  const rawBlocklist = asRecord(rawNavigation.blocklist)
+  const rawContent = asRecord(raw.content)
+
+  const logoSrc = asString(rawLogo.src)
+  const logo = logoSrc
+    ? { src: logoSrc, alt: asString(rawLogo.alt), replacesTitle: rawLogo.replacesTitle === true }
+    : undefined
+
+  return {
+    site: {
+      title: asString(rawSite.title),
+      description: asString(rawSite.description),
+      url: asString(rawSite.url),
+      logo,
+      favicon: asString(rawSite.favicon),
+    },
+    repo: { url: asString(rawRepo.url) },
+    theme: { customCss: asStringArray(rawTheme.customCss) },
+    starlight: {
+      social: asSocialLinks(rawStarlight.social),
+      tableOfContents: asTableOfContents(rawStarlight.tableOfContents),
+      lastUpdated: typeof rawStarlight.lastUpdated === 'boolean' ? rawStarlight.lastUpdated : undefined,
+      pagination: typeof rawStarlight.pagination === 'boolean' ? rawStarlight.pagination : undefined,
+      expressiveCode: rawExpressiveCode === false
+        ? false
+        : rawExpressiveCode && typeof rawExpressiveCode === 'object'
+          ? { styleOverrides: asStringRecord(rawExpressive.styleOverrides) }
+          : undefined,
+    },
+    navigation: {
+      roots: asStringArray(rawNavigation.roots),
+      blocklist: {
+        exact: asStringArray(rawBlocklist.exact),
+        prefixes: asStringArray(rawBlocklist.prefixes),
+      },
+      labelOverrides: asStringRecord(rawNavigation.labelOverrides),
+    },
+    content: { titleField: asString(rawContent.titleField) },
+  }
+}
+
+export function getPortalConfig(): PortalConfig {
+  if (_cache !== null) return _cache
+  if (!existsSync(CONFIG_PATH)) {
+    _cache = {}
+    return _cache
+  }
+  try {
+    _cache = normalizeConfig(JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')))
+  } catch {
+    _cache = {}
+  }
+  return _cache
+}
+
+// Exposed for testing — resets the singleton cache
+export function _resetPortalConfigCache(): void {
+  _cache = null
+}

package/src/lib/product-identity.ts

@@ -0,0 +1,2 @@
+export const PRODUCT_NAME = 'Upcontent'
+export const PRODUCT_TAGLINE = 'Create a beautiful, customizable Starlight portal from your documentation repository.'

package/src/lib/rehype-callouts.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest'
+import { unified } from 'unified'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import rehypeStringify from 'rehype-stringify'
+import { rehypeCallouts } from './rehype-callouts'
+
+function render(markdown: string): string {
+  return unified()
+    .use(remarkParse)
+    .use(remarkRehype)
+    .use(rehypeCallouts)
+    .use(rehypeStringify)
+    .processSync(markdown)
+    .toString()
+}
+
+describe('rehypeCallouts', () => {
+  it('converte [!info] sem texto adicional em callout com título default e ícone', () => {
+    const html = render('> [!info]')
+    expect(html).toContain('class="callout callout-info"')
+    expect(html).toContain('callout-title')
+    expect(html).toContain('ℹ️')
+    expect(html).toContain('Info')
+    expect(html).not.toContain('<blockquote>')
+  })
+
+  // formato real usado no conteúdo: marcador + texto tudo na mesma linha
+  it('converte [!info] com texto na mesma linha (formato usado no conteúdo real)', () => {
+    const html = render('> [!info] SDD — Artefato Plano técnico para a camada frontend')
+    expect(html).toContain('class="callout callout-info"')
+    expect(html).toContain('SDD — Artefato Plano técnico para a camada frontend')
+  })
+
+  it('converte [!warning] com título customizado', () => {
+    const html = render('> [!warning] Cuidado aqui\n> Detalhes do risco')
+    expect(html).toContain('class="callout callout-warning"')
+    expect(html).toContain('Cuidado aqui')
+    expect(html).toContain('⚠️')
+  })
+
+  it('cobre todos os tipos de callout usados no conteúdo', () => {
+    const types = ['info', 'note', 'warning', 'danger', 'tip', 'important', 'caution']
+    for (const type of types) {
+      const html = render(`> [!${type}] Texto`)
+      expect(html).toContain(`class="callout callout-${type}"`)
+    }
+  })
+
+  it('não quebra blockquote comum sem marcador de callout', () => {
+    const html = render('> Só uma citação normal, sem marcador')
+    expect(html).toContain('<blockquote>')
+    expect(html).not.toContain('callout')
+  })
+
+  it('callout dentro de uma lista não quebra a renderização', () => {
+    const html = render('- item 1\n  > [!tip] dica dentro da lista\n- item 2')
+    expect(html).toContain('class="callout callout-tip"')
+    expect(html).toContain('item 1')
+    expect(html).toContain('item 2')
+  })
+
+  it('tipo desconhecido sem texto usa ícone default e title case do tipo', () => {
+    const html = render('> [!custom]')
+    expect(html).toContain('class="callout callout-custom"')
+    expect(html).toContain('Custom')
+    expect(html).toContain('ℹ️')
+  })
+})