upcontent 0.0.0-stage → 0.1.1

package/guides/validate-your-site.md

@@ -0,0 +1,58 @@
+---
+title: Validate your site
+description: Check content, configuration, generated output, and browser behavior before publishing.
+sidebar:
+  order: 2
+---
+
+Use this checklist before opening a pull request or publishing a consumer repository.
+
+## Run the build contract
+
+```sh
+pnpm test
+pnpm check
+make build CONTENT_PATH=.
+make check-golden
+make check-external
+git diff --check
+```
+
+The tests cover content loading, title fallback, navigation, blocklists, wiki links, callouts, Mermaid transformation, and structured previews. The external build confirms that a separate consumer repository works too.
+
+## Check the browser
+
+Start the portal locally:
+
+```sh
+make dev CONTENT_PATH=.
+```
+
+Open the pages listed in the [capability showcase](../showcase/) and check:
+
+- The logo appears once and the site name is clear.
+- The sidebar groups are understandable and the active page is easy to find.
+- Search, internal links, and the table of contents work.
+- Light and dark themes remain readable.
+- Callouts, Mermaid, JSON, YAML, and CSV examples render correctly.
+- The layout works at desktop and mobile widths.
+- The browser console has no required-asset errors.
+- Each indexable page has a useful title, description, canonical URL, and one top-level heading.
+- `dist/robots.txt` points to the generated sitemap.
+- The page source contains JSON-LD and uses the intended `SITE_URL` and `BASE_PATH`.
+- `seo.enabled` matches the intended portal policy; disabled SEO must produce `noindex, nofollow` and `Disallow: /`.
+
+## Check content boundaries
+
+The build should not publish:
+
+- `.upcontent/` files
+- Protected repository internals
+- Consumer blocklisted paths
+- Documents with malformed or traversal wiki links
+
+When a change affects blocklists or navigation roots, verify both the generated route list and the sidebar. Hiding a link is not enough; excluded content must be absent before parsing.
+
+## Record the result
+
+If a check fails, record the source page, route, and browser or build output in the relevant engineering ticket. Do not mark a documentation change complete based only on a successful local page load.

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "upcontent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "version": "0.1.1",
+  "packageManager": "pnpm@10.20.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lumamontes/upcontent.git"
+  },
+  "bin": {
+    "upcontent": "scripts/upcontent-cli.mjs"
+  },
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "check": "astro check",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@astrojs/markdown-remark": "^7.3.1",
+    "@astrojs/sitemap": "^3.7.4",
+    "@astrojs/starlight": "^0.42.1",
+    "@fontsource/poppins": "^5.3.0",
+    "astro": "^7.3.3",
+    "js-yaml": "^4.3.2",
+    "mermaid": "^11.0.0",
+    "papaparse": "^5.7.0",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.0.0",
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.10",
+    "@types/js-yaml": "^4.0.9",
+    "@types/papaparse": "^5.5.2",
+    "rehype-stringify": "^10.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  }
+}

package/scripts/upcontent-cli.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+
+const command = process.argv[2] ?? 'help'
+const force = process.argv.includes('--force')
+const root = process.cwd()
+const rendererRoot = dirname(dirname(fileURLToPath(import.meta.url)))
+
+const config = `{
+  "site": {
+    "title": "Documentation",
+    "description": "Project documentation.",
+    "logo": {
+      "src": ".upcontent/logo.svg",
+      "alt": "Documentation"
+    },
+    "favicon": ".upcontent/favicon.svg"
+  },
+  "repo": {
+    "url": "https://github.com/ORG/REPOSITORY"
+  },
+  "theme": {
+    "customCss": [".upcontent/theme.css"]
+  }
+}
+`
+
+const theme = `:root {
+  --sl-color-accent: #0f766e;
+  --sl-color-accent-high: #115e59;
+}
+`
+
+const logo = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 72 72">
+  <rect width="56" height="56" x="8" y="8" rx="16" fill="#0f766e"/>
+  <path d="M20 24h32v8H20zm0 16h24v8H20z" fill="#fff"/>
+</svg>
+`
+
+const favicon = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="16" fill="#0f766e"/>
+  <path d="M18 20h28v8H18zm0 16h21v8H18z" fill="#fff"/>
+</svg>
+`
+
+const workflow = `name: Publish documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    uses: lumamontes/upcontent/.github/workflows/reusable-pages.yml@main
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+`
+
+function init() {
+  const files = [
+    ['.upcontent/config.json', config],
+    ['.upcontent/theme.css', theme],
+    ['.upcontent/logo.svg', logo],
+    ['.upcontent/favicon.svg', favicon],
+    ['.github/workflows/deploy-docs.yml', workflow],
+  ]
+  const collisions = files.filter(([relativePath]) => existsSync(join(root, relativePath)))
+  if (collisions.length > 0 && !force) {
+    for (const [relativePath] of collisions) {
+      console.error(`Refusing to overwrite ${relativePath}. Use --force to replace generated files.`)
+    }
+    process.exitCode = 1
+    return
+  }
+  for (const [relativePath, content] of files) {
+    const absolutePath = join(root, relativePath)
+    mkdirSync(dirname(absolutePath), { recursive: true })
+    writeFileSync(absolutePath, content)
+    console.log(`created ${relativePath}`)
+  }
+  console.log('\nNext steps:')
+  console.log('1. Replace ORG/REPOSITORY in .upcontent/config.json.')
+  console.log('2. Review the generated identity and theme files.')
+  console.log('3. Run `pnpm dlx upcontent dev` to preview locally.')
+  console.log('4. Push to main to publish through GitHub Actions.')
+}
+
+function run(name, args) {
+  const result = spawnSync(name, args, { cwd: rendererRoot, stdio: 'inherit' })
+  if (result.error) throw result.error
+  return result.status === 0
+}
+
+if (command === 'init') init()
+else if (command === 'dev') {
+  process.exitCode = run('make', ['dev', `CONTENT_PATH=${root}`]) ? 0 : 1
+}
+else if (command === 'check') {
+  const passed = run('make', ['build', `CONTENT_PATH=${root}`])
+  process.exitCode = passed ? 0 : 1
+}
+else {
+  console.log('Usage: upcontent <init|dev|check> [--force]')
+}

package/scripts/verify-external-build.mjs

@@ -0,0 +1,32 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+
+const html = readFileSync('dist/index.html', 'utf8')
+const required = [
+  'External Consumer',
+  'https://github.com/example/external-consumer',
+  '/upcontent-assets/favicon.svg',
+]
+
+for (const value of required) {
+  if (!html.includes(value)) throw new Error(`External consumer artifact is missing: ${value}`)
+}
+
+if (!existsSync('dist/upcontent-assets/favicon.svg')) throw new Error('External consumer favicon was not copied')
+if (!html.includes('alt="External Consumer"')) throw new Error('External consumer logo was not rendered')
+if (!html.includes('application/ld+json')) throw new Error('External consumer JSON-LD metadata is missing')
+if (!existsSync('dist/robots.txt')) throw new Error('External consumer robots.txt is missing')
+if (!existsSync('dist/sitemap-index.xml')) throw new Error('External consumer sitemap is missing')
+if (!readFileSync('dist/noindex/index.html', 'utf8').includes('noindex, nofollow')) throw new Error('External consumer noindex page is not marked noindex')
+const sitemap = readFileSync('dist/sitemap-0.xml', 'utf8')
+if (!sitemap.includes('<loc>https://docs.example.com/</loc>')) throw new Error('External consumer root route is missing from sitemap')
+if (sitemap.includes('/noindex/')) throw new Error('External consumer noindex page leaked into sitemap')
+if (existsSync('dist/forbidden/index.html')) throw new Error('External consumer blocklist leaked forbidden.md')
+if (existsSync('dist/assets/readme')) throw new Error('Golden README assets leaked into external consumer build')
+if (existsSync('dist/upcontent-renderer/readme/index.html')) {
+  throw new Error('External consumer build leaked renderer checkout content')
+}
+if (!existsSync('dist/pagefind/pagefind.js')) throw new Error('External consumer Pagefind output is missing')
+
+const cssFiles = readdirSync('dist/_astro').filter(file => file.endsWith('.css'))
+const hasConsumerCss = cssFiles.some(file => readFileSync(`dist/_astro/${file}`, 'utf8').includes('#0f766e'))
+if (!hasConsumerCss) throw new Error('External consumer CSS was not included')

package/scripts/verify-golden-build.mjs

@@ -0,0 +1,9 @@
+import { existsSync, readFileSync } from 'node:fs'
+
+const html = readFileSync('dist/index.html', 'utf8')
+const requiredAssets = ['assets/readme/portal-home.png', 'assets/readme/portal-showcase.png']
+
+for (const asset of requiredAssets) {
+  if (!existsSync(`dist/${asset}`)) throw new Error(`Golden build is missing: dist/${asset}`)
+  if (!html.includes(asset)) throw new Error(`Golden build does not reference: ${asset}`)
+}

package/src/components/MermaidLoader.astro

@@ -0,0 +1,304 @@
+---
+---
+
+<script>
+  import { renderMermaidDiagram } from '../lib/mermaid-render'
+
+  function mermaidTheme() {
+    return document.documentElement.dataset.theme === 'dark' ? 'dark' : 'default'
+  }
+
+  let mermaidPromise: Promise<typeof import('mermaid').default> | undefined
+
+  function loadMermaid() {
+    mermaidPromise ??= import('mermaid').then(({ default: mermaid }) => {
+      mermaid.initialize({ startOnLoad: false, theme: mermaidTheme() })
+      return mermaid
+    })
+    return mermaidPromise
+  }
+
+  let scale = 1
+  let translateX = 0
+  let translateY = 0
+  let dialogEl: HTMLDialogElement | null = null
+  let contentEl: HTMLDivElement | null = null
+
+  function applyTransform() {
+    if (contentEl) contentEl.style.transform = `translate(${translateX}px, ${translateY}px) scale(${scale})`
+  }
+
+  function resetTransform() {
+    scale = 1
+    translateX = 0
+    translateY = 0
+    applyTransform()
+  }
+
+  function ensureDialog() {
+    if (dialogEl) return
+
+    dialogEl = document.createElement('dialog')
+    dialogEl.className = 'mermaid-fullscreen-dialog'
+
+    const closeBtn = document.createElement('button')
+    closeBtn.type = 'button'
+    closeBtn.className = 'mermaid-fullscreen-close'
+    closeBtn.setAttribute('aria-label', 'Fechar')
+    closeBtn.textContent = '✕'
+    closeBtn.addEventListener('click', () => dialogEl?.close())
+
+    const viewport = document.createElement('div')
+    viewport.className = 'mermaid-fullscreen-viewport'
+
+    contentEl = document.createElement('div')
+    contentEl.className = 'mermaid-fullscreen-content'
+    viewport.appendChild(contentEl)
+
+    dialogEl.append(closeBtn, viewport)
+    document.body.appendChild(dialogEl)
+
+    dialogEl.addEventListener('click', e => {
+      if (e.target === dialogEl) dialogEl?.close()
+    })
+    dialogEl.addEventListener('close', resetTransform)
+
+    viewport.addEventListener(
+      'wheel',
+      e => {
+        e.preventDefault()
+        const delta = e.deltaY > 0 ? -0.1 : 0.1
+        scale = Math.min(Math.max(scale + delta, 0.2), 5)
+        applyTransform()
+      },
+      { passive: false },
+    )
+
+    let dragging = false
+    let lastX = 0
+    let lastY = 0
+    viewport.addEventListener('pointerdown', e => {
+      dragging = true
+      lastX = e.clientX
+      lastY = e.clientY
+      viewport.setPointerCapture(e.pointerId)
+    })
+    viewport.addEventListener('pointermove', e => {
+      if (!dragging) return
+      translateX += e.clientX - lastX
+      translateY += e.clientY - lastY
+      lastX = e.clientX
+      lastY = e.clientY
+      applyTransform()
+    })
+    viewport.addEventListener('pointerup', () => { dragging = false })
+    viewport.addEventListener('pointerleave', () => { dragging = false })
+  }
+
+  function openFullscreen(svg: string) {
+    ensureDialog()
+    if (!dialogEl || !contentEl) return
+    contentEl.innerHTML = svg
+    resetTransform()
+    dialogEl.showModal()
+  }
+
+  async function copyToClipboard(button: HTMLButtonElement, text: string) {
+    await navigator.clipboard.writeText(text)
+    const original = button.textContent
+    button.textContent = 'Copiado!'
+    setTimeout(() => { button.textContent = original }, 2000)
+  }
+
+  async function processDiagrams() {
+    const nodes = Array.from(document.querySelectorAll<HTMLElement>('div.mermaid'))
+    if (nodes.length === 0) return
+
+    const mermaid = await loadMermaid()
+    for (const node of nodes) {
+      // <br/> inside a div becomes a DOM element before textContent reads it — não deveria
+      // acontecer (remarkMermaid já normaliza), mas o replace aqui é defensivo.
+      const source = (node.textContent ?? '').replace(/ /g, ' ')
+      const result = await renderMermaidDiagram(mermaid, source)
+
+      if (result.status === 'ok') {
+        const container = document.createElement('div')
+        container.className = 'mermaid-container'
+        container.dataset.mermaidSource = source
+
+        const copyBtn = document.createElement('button')
+        copyBtn.type = 'button'
+        copyBtn.className = 'mermaid-copy-btn'
+        copyBtn.textContent = 'Copiar'
+        copyBtn.setAttribute('aria-label', 'Copiar código-fonte do diagrama')
+        copyBtn.addEventListener('click', e => {
+          e.stopPropagation()
+          void copyToClipboard(copyBtn, source)
+        })
+
+        const diagram = document.createElement('div')
+        diagram.className = 'mermaid-diagram'
+        diagram.innerHTML = result.svg
+        diagram.setAttribute('role', 'button')
+        diagram.setAttribute('tabindex', '0')
+        diagram.setAttribute('aria-label', 'Abrir diagrama em tela cheia')
+        diagram.addEventListener('click', () => openFullscreen(diagram.innerHTML))
+        diagram.addEventListener('keydown', e => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault()
+          openFullscreen(diagram.innerHTML)
+          }
+        })
+
+        container.append(copyBtn, diagram)
+        node.replaceWith(container)
+      } else {
+        const errorBox = document.createElement('div')
+        errorBox.className = 'mermaid-error'
+        errorBox.dataset.mermaidSource = source
+
+        const message = document.createElement('p')
+        message.className = 'mermaid-error-message'
+        message.textContent = `Erro ao renderizar diagrama Mermaid: ${result.message}`
+
+        const pre = document.createElement('pre')
+        pre.className = 'mermaid-error-source'
+        pre.textContent = result.source
+
+        errorBox.append(message, pre)
+        node.replaceWith(errorBox)
+      }
+    }
+  }
+
+  async function rerenderExistingDiagrams() {
+    const containers = Array.from(document.querySelectorAll<HTMLElement>('[data-mermaid-source]'))
+    if (containers.length === 0) return
+
+    const mermaid = await loadMermaid()
+    mermaid.initialize({ startOnLoad: false, theme: mermaidTheme() })
+    for (const container of containers) {
+      const source = container.dataset.mermaidSource
+      if (!source) continue
+      const result = await renderMermaidDiagram(mermaid, source)
+      if (result.status === 'ok') {
+        const diagram = container.querySelector('.mermaid-diagram')
+        if (diagram) diagram.innerHTML = result.svg
+      }
+    }
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => void processDiagrams())
+  } else {
+    void processDiagrams()
+  }
+
+  new MutationObserver(() => void rerenderExistingDiagrams()).observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ['data-theme'],
+  })
+</script>
+
+<style is:global>
+  .mermaid-container {
+    position: relative;
+  }
+
+  .mermaid-diagram {
+    cursor: zoom-in;
+  }
+
+  .mermaid-diagram:focus-visible {
+    outline: 2px solid var(--sl-color-accent);
+    outline-offset: 0.25rem;
+  }
+
+  .mermaid-copy-btn {
+    position: absolute;
+    top: 0.5rem;
+    right: 0.5rem;
+    padding: 0.25rem 0.5rem;
+    font-size: var(--sl-text-2xs, 0.75rem);
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.25rem;
+    background: var(--sl-color-gray-6);
+    color: var(--sl-color-gray-2);
+    cursor: pointer;
+    opacity: 0;
+    transition: opacity 0.15s;
+  }
+  .mermaid-container:hover .mermaid-copy-btn,
+  .mermaid-copy-btn:focus-visible {
+    opacity: 1;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .mermaid-copy-btn {
+      transition: none;
+    }
+  }
+
+  .mermaid-error {
+    border: 1px solid var(--sl-color-red, #c53434);
+    border-radius: 0.5rem;
+    padding: 1rem;
+  }
+  .mermaid-error-message {
+    color: var(--sl-color-red, #c53434);
+    font-weight: 600;
+    margin: 0 0 0.5rem;
+  }
+  .mermaid-error-source {
+    white-space: pre-wrap;
+    overflow-x: auto;
+    margin: 0;
+  }
+
+  .mermaid-fullscreen-dialog {
+    padding: 0;
+    border: none;
+    width: 100vw;
+    height: 100vh;
+    max-width: 100vw;
+    max-height: 100vh;
+    background: var(--sl-color-bg, var(--sl-color-black));
+  }
+  .mermaid-fullscreen-dialog::backdrop {
+    background-color: var(--sl-color-backdrop-overlay, rgba(0, 0, 0, 0.6));
+  }
+
+  .mermaid-fullscreen-close {
+    position: absolute;
+    top: 1rem;
+    right: 1rem;
+    z-index: 1;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.375rem;
+    background: var(--sl-color-gray-6);
+    color: var(--sl-color-gray-2);
+    width: 2.5rem;
+    height: 2.5rem;
+    cursor: pointer;
+  }
+
+  .mermaid-fullscreen-viewport {
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    touch-action: none;
+    cursor: grab;
+  }
+  .mermaid-fullscreen-viewport:active {
+    cursor: grabbing;
+  }
+
+  .mermaid-fullscreen-content {
+    width: 100%;
+    height: 100%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transform-origin: center center;
+  }
+</style>

package/src/components/PaletteShowcase.astro

@@ -0,0 +1,122 @@
+---
+const palettes = {
+  quiet: { label: 'Quiet / default', accent: '#334155', surface: '#f8fafc', ink: '#0f172a' },
+  river: { label: 'River', accent: '#0f766e', surface: '#f0fdfa', ink: '#134e4a' },
+  signal: { label: 'Signal', accent: '#be123c', surface: '#fff1f2', ink: '#4c0519' },
+}
+---
+
+<div class="palette-showcase" data-palette="quiet" data-palettes={JSON.stringify(palettes)}>
+  <div class="palette-controls" role="group" aria-label="Preview palettes">
+    {Object.entries(palettes).map(([id, palette], index) => (
+      <button
+        type="button"
+        class="palette-button"
+        data-palette-button={id}
+        aria-pressed={index === 0 ? 'true' : 'false'}
+      >
+        {palette.label}
+      </button>
+    ))}
+  </div>
+  <div class="palette-preview" aria-live="polite">
+    <div class="palette-swatch" data-swatch="accent"></div>
+    <div class="palette-swatch" data-swatch="surface"></div>
+    <div class="palette-swatch" data-swatch="ink"></div>
+    <div class="palette-preview-copy">
+    <strong data-palette-label>{palettes.quiet.label}</strong>
+      <span>One configuration seam, many possible identities.</span>
+    </div>
+  </div>
+</div>
+
+<script>
+  document.querySelectorAll<HTMLElement>('.palette-showcase').forEach(showcase => {
+    const palettes: Record<string, { accent: string; surface: string; ink: string; label: string }> = JSON.parse(
+      showcase.dataset.palettes ?? '{}',
+    )
+    const label = showcase.querySelector('[data-palette-label]')
+
+    showcase.querySelectorAll<HTMLButtonElement>('[data-palette-button]').forEach(button => {
+      button.addEventListener('click', () => {
+        const paletteId = button.dataset.paletteButton
+        const palette = paletteId ? palettes[paletteId] : undefined
+        if (!palette) return
+        showcase.dataset.palette = paletteId
+        showcase.style.setProperty('--palette-accent', palette.accent)
+        showcase.style.setProperty('--palette-surface', palette.surface)
+        showcase.style.setProperty('--palette-ink', palette.ink)
+        if (label) label.textContent = palette.label
+        showcase.querySelectorAll('[data-palette-button]').forEach(control => {
+          control.setAttribute('aria-pressed', String(control === button))
+        })
+      })
+    })
+
+    showcase.querySelector('[data-palette-button]')?.dispatchEvent(new Event('click'))
+  })
+</script>
+
+<style>
+  .palette-showcase {
+    --palette-accent: #334155;
+    --palette-surface: #f8fafc;
+    --palette-ink: #0f172a;
+    margin: 2rem 0;
+  }
+
+  .palette-controls {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+    margin-bottom: 1rem;
+  }
+
+  .palette-button {
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 999px;
+    background: transparent;
+    color: var(--sl-color-text);
+    cursor: pointer;
+    padding: 0.45rem 0.75rem;
+  }
+
+  .palette-button[aria-pressed='true'] {
+    border-color: var(--sl-color-accent);
+    background: var(--sl-color-accent);
+    color: var(--sl-color-bg);
+  }
+
+  .palette-preview {
+    display: grid;
+    grid-template-columns: repeat(3, 3rem) 1fr;
+    gap: 0.75rem;
+    align-items: center;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.5rem;
+    padding: 1rem;
+    background: var(--palette-surface);
+    color: var(--palette-ink);
+  }
+
+  .palette-swatch {
+    width: 3rem;
+    height: 3rem;
+    border: 1px solid color-mix(in srgb, var(--palette-ink), transparent 70%);
+    border-radius: 0.35rem;
+  }
+
+  .palette-swatch[data-swatch='accent'] { background: var(--palette-accent); }
+  .palette-swatch[data-swatch='surface'] { background: var(--palette-surface); }
+  .palette-swatch[data-swatch='ink'] { background: var(--palette-ink); }
+
+  .palette-preview-copy {
+    display: grid;
+    gap: 0.25rem;
+  }
+
+  @media (max-width: 560px) {
+    .palette-preview { grid-template-columns: repeat(3, 2.25rem) 1fr; }
+    .palette-swatch { width: 2.25rem; height: 2.25rem; }
+  }
+</style>