uniweb 0.8.8 → 0.8.10

package/src/commands/inspect.js

@@ -0,0 +1,358 @@
+/**
+ * uniweb inspect — Show parsed content shape of markdown files.
+ *
+ * Usage:
+ *   uniweb inspect pages/home/hero.md          Single section
+ *   uniweb inspect pages/home/                 All sections in a page folder
+ *   uniweb inspect pages/home/hero.md --raw    ProseMirror AST instead of flat shape
+ *   uniweb inspect pages/home/ --full          Include empty fields (matches runtime)
+ *   uniweb inspect pages/home/ --sequence      Include sequence array
+ */
+
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { resolve, extname, basename } from 'node:path'
+import yaml from 'js-yaml'
+
+// Colors for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  dim: '\x1b[2m',
+}
+
+/**
+ * Parse CLI arguments for inspect command
+ */
+function parseArgs(args) {
+  const flags = {
+    target: null,
+    raw: false,
+    full: false,
+    sequence: false,
+    help: false,
+  }
+
+  for (const arg of args) {
+    if (arg === '--raw') flags.raw = true
+    else if (arg === '--full') flags.full = true
+    else if (arg === '--sequence') flags.sequence = true
+    else if (arg === '--help' || arg === '-h') flags.help = true
+    else if (!arg.startsWith('-')) flags.target = arg
+  }
+
+  return flags
+}
+
+/**
+ * Dynamically import content-reader and semantic-parser.
+ * These are transitive deps of @uniweb/build, available in any project workspace.
+ */
+async function loadDependencies() {
+  try {
+    const [contentReader, semanticParser] = await Promise.all([
+      import('@uniweb/content-reader'),
+      import('@uniweb/semantic-parser'),
+    ])
+    return {
+      markdownToProseMirror: contentReader.markdownToProseMirror,
+      parseContent: semanticParser.parseContent,
+    }
+  } catch {
+    console.error(`${colors.red}✗${colors.reset} Could not load @uniweb/content-reader or @uniweb/semantic-parser.`)
+    console.error(`  These packages must be installed in the workspace (they come with @uniweb/build).`)
+    process.exit(1)
+  }
+}
+
+/**
+ * Extract frontmatter and markdown body from a section file.
+ * Exact match of content-collector lines 634-639.
+ */
+function extractFrontmatter(content) {
+  let frontMatter = {}
+  let markdown = content
+
+  if (content.trim().startsWith('---')) {
+    const parts = content.split('---\n')
+    if (parts.length >= 3) {
+      try {
+        frontMatter = yaml.load(parts[1]) || {}
+      } catch (err) {
+        console.warn(`${colors.yellow}Warning: YAML parse error: ${err.message}${colors.reset}`)
+        frontMatter = {}
+      }
+      markdown = parts.slice(2).join('---\n')
+    }
+  }
+
+  return { frontMatter, markdown }
+}
+
+/**
+ * Split frontmatter into reserved keys and custom params.
+ * Exact match of content-collector line 642.
+ */
+function splitParams(frontMatter) {
+  const { type, component, preset, input, props, fetch, data, id, background, theme, ...params } = frontMatter
+  return {
+    type: type || component || null,
+    preset: preset || null,
+    reserved: { data, id, background, theme, input },
+    params,
+  }
+}
+
+/**
+ * Extract inset references from a ProseMirror document.
+ * Exact match of content-collector lines 192-218.
+ *
+ * @param {object} doc - ProseMirror document (mutated in place)
+ * @returns {Array} Array of { refId, type, params, description }
+ */
+function extractInsets(doc) {
+  if (!doc?.content || !Array.isArray(doc.content)) return []
+
+  const insets = []
+  let refIndex = 0
+
+  for (let i = 0; i < doc.content.length; i++) {
+    const node = doc.content[i]
+    if (node.type === 'inset_ref') {
+      const { component, alt, ...params } = node.attrs || {}
+      const refId = `inset_${refIndex++}`
+      insets.push({
+        refId,
+        type: component,
+        params: Object.keys(params).length > 0 ? params : {},
+        description: alt || null,
+      })
+      // Replace in-place with placeholder
+      doc.content[i] = {
+        type: 'inset_placeholder',
+        attrs: { refId },
+      }
+    }
+  }
+
+  return insets
+}
+
+/**
+ * Guarantee item has flat content structure.
+ * Keep in sync with @uniweb/runtime/src/prepare-props.js
+ */
+function guaranteeItemStructure(item) {
+  return {
+    title: item.title || '',
+    pretitle: item.pretitle || '',
+    subtitle: item.subtitle || '',
+    paragraphs: item.paragraphs || [],
+    links: item.links || [],
+    imgs: item.imgs || [],
+    lists: item.lists || [],
+    icons: item.icons || [],
+    videos: item.videos || [],
+    buttons: item.buttons || [],
+    data: item.data || {},
+    cards: item.cards || [],
+    documents: item.documents || [],
+    forms: item.forms || [],
+    quotes: item.quotes || [],
+    headings: item.headings || [],
+  }
+}
+
+/**
+ * Guarantee content structure exists.
+ * Keep in sync with @uniweb/runtime/src/prepare-props.js
+ */
+function guaranteeContentStructure(parsedContent) {
+  const content = parsedContent || {}
+
+  return {
+    title: content.title || '',
+    pretitle: content.pretitle || '',
+    subtitle: content.subtitle || '',
+    subtitle2: content.subtitle2 || '',
+    alignment: content.alignment || null,
+    paragraphs: content.paragraphs || [],
+    links: content.links || [],
+    imgs: content.imgs || [],
+    lists: content.lists || [],
+    icons: content.icons || [],
+    videos: content.videos || [],
+    insets: content.insets || [],
+    buttons: content.buttons || [],
+    data: content.data || {},
+    cards: content.cards || [],
+    documents: content.documents || [],
+    forms: content.forms || [],
+    quotes: content.quotes || [],
+    headings: content.headings || [],
+    items: (content.items || []).map(guaranteeItemStructure),
+    sequence: content.sequence || [],
+    raw: content.raw,
+  }
+}
+
+/**
+ * Remove empty fields from content for clean output.
+ */
+function removeEmptyFields(obj) {
+  const result = {}
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === 'raw') continue // Always skip raw ProseMirror in clean output
+    if (value === null || value === undefined) continue
+    if (value === '') continue
+    if (Array.isArray(value) && value.length === 0) continue
+    if (typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0) continue
+
+    // Recursively clean items
+    if (key === 'items' && Array.isArray(value)) {
+      result[key] = value.map(item => removeEmptyFields(item))
+    } else {
+      result[key] = value
+    }
+  }
+  return result
+}
+
+/**
+ * Process a single markdown file and return its parsed shape.
+ */
+function processFile(fileContent, fileName, deps, options) {
+  const { raw, full, sequence } = options
+  const { markdownToProseMirror, parseContent } = deps
+
+  const { frontMatter, markdown } = extractFrontmatter(fileContent)
+  const { type, preset, reserved, params } = splitParams(frontMatter)
+
+  // Parse markdown to ProseMirror
+  const doc = markdownToProseMirror(markdown)
+
+  // Extract insets (mutates doc)
+  const insets = extractInsets(doc)
+
+  // Build result
+  const result = {}
+
+  if (type) result.type = type
+  if (preset) result.preset = preset
+
+  // Include non-empty reserved fields
+  for (const [key, value] of Object.entries(reserved)) {
+    if (value !== undefined && value !== null) result[key] = value
+  }
+
+  // Include params if any
+  if (Object.keys(params).length > 0) result.params = params
+
+  // Check if file is a child section
+  if (basename(fileName).startsWith('@')) {
+    result.child = true
+  }
+
+  if (raw) {
+    // Raw mode: return ProseMirror AST
+    result.prosemirror = doc
+    if (insets.length > 0) result.insets = insets
+    return result
+  }
+
+  // Parse to flat content shape
+  const parsed = parseContent(doc)
+
+  // Apply guarantees
+  let content = guaranteeContentStructure(parsed)
+
+  if (!full) {
+    content = removeEmptyFields(content)
+  } else {
+    // In full mode, still remove raw
+    delete content.raw
+  }
+
+  if (!sequence) {
+    delete content.sequence
+  }
+
+  result.content = content
+
+  if (insets.length > 0) result.insets = insets
+
+  return result
+}
+
+/**
+ * Natural sort comparator for filenames (handles numeric prefixes).
+ */
+function naturalSort(a, b) {
+  return a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' })
+}
+
+/**
+ * Main inspect entry point.
+ */
+export async function inspect(args) {
+  const flags = parseArgs(args)
+
+  if (flags.help || !flags.target) {
+    console.log(`
+Usage: uniweb inspect <path> [options]
+
+Inspect the parsed content shape of a markdown file or page folder.
+
+Arguments:
+  <path>        Path to a .md file or a page folder
+
+Options:
+  --raw         Show ProseMirror AST instead of flat content shape
+  --full        Include empty fields (matches runtime guarantees)
+  --sequence    Include sequence array (document-order elements)
+  -h, --help    Show this help
+`)
+    return
+  }
+
+  const target = resolve(process.cwd(), flags.target)
+  const deps = await loadDependencies()
+
+  let stat
+  try {
+    stat = statSync(target)
+  } catch {
+    console.error(`${colors.red}✗${colors.reset} Not found: ${flags.target}`)
+    process.exit(1)
+  }
+
+  const options = { raw: flags.raw, full: flags.full, sequence: flags.sequence }
+
+  if (stat.isFile()) {
+    if (extname(target) !== '.md') {
+      console.error(`${colors.red}✗${colors.reset} Expected a .md file: ${flags.target}`)
+      process.exit(1)
+    }
+    const content = readFileSync(target, 'utf8')
+    const result = processFile(content, basename(target), deps, options)
+    console.log(JSON.stringify(result, null, 2))
+  } else if (stat.isDirectory()) {
+    const files = readdirSync(target)
+      .filter(f => extname(f) === '.md' && !f.startsWith('_') && f !== 'README.md')
+      .sort(naturalSort)
+
+    if (files.length === 0) {
+      console.error(`${colors.yellow}No .md files found in: ${flags.target}${colors.reset}`)
+      return
+    }
+
+    const results = files.map(file => {
+      const content = readFileSync(resolve(target, file), 'utf8')
+      const result = processFile(content, file, deps, options)
+      result._file = file
+      return result
+    })
+
+    console.log(JSON.stringify(results, null, 2))
+  }
+}

package/src/index.js

@@ -21,6 +21,7 @@ import { build } from './commands/build.js'
 import { docs } from './commands/docs.js'
 import { doctor } from './commands/doctor.js'
 import { i18n } from './commands/i18n.js'
+import { inspect } from './commands/inspect.js'
 import { add } from './commands/add.js'
 import {
   resolveTemplate,
@@ -328,6 +329,12 @@ async function main() {
     return
   }
 
+  // Handle inspect command
+  if (command === 'inspect') {
+    await inspect(args.slice(1))
+    return
+  }
+
   // Handle add command
   if (command === 'add') {
     await add(args.slice(1))
@@ -568,6 +575,7 @@ ${colors.bright}Commands:${colors.reset}
   create [name]      Create a new project
   add <type> [name]  Add a foundation, site, or extension to a project
   build              Build the current project
+  inspect <path>     Inspect parsed content shape of a markdown file or folder
   docs               Generate component documentation
   doctor             Diagnose project configuration issues
   i18n <cmd>         Internationalization (extract, sync, status)

package/src/utils/scaffold.js

@@ -9,6 +9,7 @@ import fs from 'node:fs/promises'
 import { existsSync, readdirSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import yaml from 'js-yaml'
 import { copyTemplateDirectory, registerVersions } from '../templates/processor.js'
 import { getVersionsForTemplates } from '../versions.js'
 
@@ -103,13 +104,19 @@ export async function applyContent(contentDir, targetDir, context, options = {})
     '.gitignore',
   ])
 
-  await copyContentRecursive(contentDir, targetDir, context, STRUCTURAL_FILES, options)
+  // Config files that should be merged, not overwritten.
+  // Keys listed here are preserved from the scaffolded version.
+  const MERGE_FILES = {
+    'site.yml': ['name', 'foundation'],
+  }
+
+  await copyContentRecursive(contentDir, targetDir, context, STRUCTURAL_FILES, MERGE_FILES, options)
 }
 
 /**
  * Recursively copy content files, skipping structural files
  */
-async function copyContentRecursive(sourceDir, targetDir, context, structuralFiles, options) {
+async function copyContentRecursive(sourceDir, targetDir, context, structuralFiles, mergeFiles, options) {
   await fs.mkdir(targetDir, { recursive: true })
 
   const entries = readdirSync(sourceDir, { withFileTypes: true })
@@ -119,7 +126,7 @@ async function copyContentRecursive(sourceDir, targetDir, context, structuralFil
 
     if (entry.isDirectory()) {
       const targetSubDir = join(targetDir, entry.name)
-      await copyContentRecursive(sourcePath, targetSubDir, context, structuralFiles, options)
+      await copyContentRecursive(sourcePath, targetSubDir, context, structuralFiles, mergeFiles, options)
     } else {
       // Determine the output filename (strip .hbs extension)
       const outputName = entry.name.endsWith('.hbs')
@@ -131,13 +138,30 @@ async function copyContentRecursive(sourceDir, targetDir, context, structuralFil
 
       const targetPath = join(targetDir, outputName)
 
+      // Get new content (process .hbs or read as-is)
+      let newContent
       if (entry.name.endsWith('.hbs')) {
-        // Process through Handlebars
         const Handlebars = (await import('handlebars')).default
-        const content = await fs.readFile(sourcePath, 'utf-8')
-        const template = Handlebars.compile(content)
-        const result = template(context)
-        await fs.writeFile(targetPath, result)
+        const raw = await fs.readFile(sourcePath, 'utf-8')
+        const template = Handlebars.compile(raw)
+        newContent = template(context)
+      }
+
+      // Merge config files instead of overwriting
+      const preserveKeys = mergeFiles[outputName]
+      if (preserveKeys && existsSync(targetPath)) {
+        const existingContent = await fs.readFile(targetPath, 'utf-8')
+        const existing = yaml.load(existingContent) || {}
+        const incoming = yaml.load(newContent || await fs.readFile(sourcePath, 'utf-8')) || {}
+
+        // Template values as base, preserve specified keys from scaffolded version
+        const merged = { ...incoming }
+        for (const key of preserveKeys) {
+          if (existing[key] !== undefined) merged[key] = existing[key]
+        }
+        await fs.writeFile(targetPath, yaml.dump(merged, { lineWidth: -1 }))
+      } else if (newContent !== undefined) {
+        await fs.writeFile(targetPath, newContent)
       } else {
         // Copy as-is
         await fs.copyFile(sourcePath, targetPath)

package/templates/foundation/src/foundation.js.hbs

@@ -1,7 +1,29 @@
+// Foundation Configuration
+// Schema: schemas/foundation.schema.json
+//
+// ─── CSS Custom Properties ──────────────────────────────────────────────────────
+// Export `vars` to declare CSS custom properties that sites can override in theme.yml:
+//
+// export const vars = {
+//   'header-height': { default: '4rem', description: 'Fixed header height' },
+//   'max-content-width': { default: '80rem', description: 'Max content width' },
+// }
+//
+// Sites override in theme.yml:  vars: { header-height: 5rem }
+// Components use:               height: var(--header-height)
+
 {{#if isExtension}}
 export default {
   extension: true,
 }
 {{else}}
-export default {}
+export default {
+  // ─── Layout ─────────────────────────────────────────────────────────────────
+  // Create layouts in src/layouts/MyLayout/index.jsx (auto-discovered).
+  // defaultLayout: 'MyLayout',
+
+  // ─── Props ──────────────────────────────────────────────────────────────────
+  // Foundation-wide data accessible via website.foundationProps in components.
+  // props: {},
+}
 {{/if}}

package/templates/site/site.yml.hbs

@@ -1,3 +1,6 @@
+# Site Configuration
+# Full reference: uniweb docs site  |  Schema: schemas/site.schema.json
+
 name: {{projectName}}
 
 {{#if foundationRef}}
@@ -6,5 +9,51 @@ foundation: {{foundationRef}}
 {{/if}}
 index: home
 
+# ─── Page Ordering ─────────────────────────────────────────────────────────────
+# Control which pages appear in navigation and in what order.
+# pages: [home, about, ...]        # home first, about second, rest auto-discovered
+# pages: [home, ..., contact]      # home first, contact last, rest in middle
+# pages: [home, about]             # Strict: only these pages in nav (others still built)
+# Or just set the homepage and auto-discover the rest:
+# index: home
+
+# ─── Content Paths ─────────────────────────────────────────────────────────────
+# Mount external content directories into your site's page tree.
+# Paths resolve relative to this file.
+#
+# paths:
+#   pages/docs: ../../../docs       # Mount docs repo at /docs route
+#   pages/blog: ../../blog-content  # Mount blog content at /blog route
+#   layout: ./custom-layout         # Custom layout directory
+#   collections: ./data             # Collections directory
+
+# ─── Data Sources ─────────────────────────────────────────────────────────────
+# Define collections (local markdown folders) or fetch remote/local JSON data.
+# Pages and sections reference sources by name via `data: source-name`.
+#
+# collections:
+#   articles:
+#     path: collections/articles         # Folder of .md entity files
+#     sort: date desc                    # Sort by frontmatter field
+#
+# fetch:
+#   - url: https://api.example.com/team  # Remote JSON
+#     schema: team                       # Access as content.data.team
+#   - path: /data/config.json            # Local file from public/
+
+# ─── Extensions ────────────────────────────────────────────────────────────────
+# Load additional foundations (section types) via URL.
+# extensions:
+#   - https://cdn.example.com/effects/foundation.js
+
+# ─── Layout ────────────────────────────────────────────────────────────────────
+# Override the foundation's default layout per-site.
+# layout: DocsLayout
+# Or per-page in page.yml:  layout: { name: MarketingLayout, hide: [left] }
+
+# ─── Base Path ─────────────────────────────────────────────────────────────────
+# For subdirectory deployments (e.g., https://example.com/docs/).
+# base: /docs/
+
 build:
   prerender: true