uniweb 0.3.3 → 0.3.5

package/README.md

@@ -106,7 +106,16 @@ role: Lead Architect
 ```
 ````
 
-Components receive validated, localized data. Natural content stays in markdown; structured data goes in tagged blocks (YAML or JSON).
+Access the parsed data via `content.data`:
+
+```jsx
+function TeamCard({ content }) {
+  const member = content.data['team-member']
+  return <div>{member.name} — {member.role}</div>
+}
+```
+
+Natural content stays in markdown; structured data goes in tagged blocks (YAML or JSON).
 
 ### Components as React
 
@@ -648,6 +657,76 @@ Yes. Content is pre-embedded in the initial HTML—no fetch waterfalls, no layou
 
 Pages can define data sources that auto-generate subroutes. A `/blog` page can have an index and a `[slug]` template that renders each post.
 
+## Common Gotchas
+
+### Homepage Configuration
+
+Set your homepage with `index:` in `site.yml`:
+
+```yaml
+# site.yml
+index: home  # The page folder that becomes /
+```
+
+The `index:` option tells the build which page folder becomes the root route (`/`). The page still exists in `pages/home/`, but visitors access it at `/`.
+
+Don't confuse this with `pages:` (which explicitly lists pages and hides any not listed).
+
+### Content Shapes
+
+Lists and items in markdown become **objects**, not strings. A bullet list:
+
+```markdown
+- First item
+- Second item
+```
+
+Becomes:
+
+```js
+content.items = [
+  { title: "First item", paragraphs: [], links: [], imgs: [] },
+  { title: "Second item", paragraphs: [], links: [], imgs: [] }
+]
+```
+
+Each item has the same structure as a content block. See [Content Structure](./docs/content-structure.md) for the full shape.
+
+### Tagged Data Blocks
+
+Tagged code blocks like:
+
+````markdown
+```yaml:team-member
+name: Sarah Chen
+role: Lead Architect
+```
+````
+
+Are accessible via `content.data`:
+
+```jsx
+function TeamMember({ content }) {
+  const member = content.data['team-member']
+  return <div>{member.name} - {member.role}</div>
+}
+```
+
+The tag name (after the colon) becomes the key in `content.data`.
+
+### Root vs Package Commands
+
+In a Uniweb workspace, commands run differently at different levels:
+
+| Location | Command | What it does |
+|----------|---------|--------------|
+| Project root | `pnpm build` | Builds all packages (foundation + site) |
+| Project root | `pnpm dev` | Starts dev server for site |
+| `foundation/` | `uniweb build` | Builds just the foundation |
+| `site/` | `uniweb build` | Builds just the site |
+
+For day-to-day development, run `pnpm dev` from the project root. The workspace scripts handle the rest.
+
 ## Related Packages
 
 - [`@uniweb/build`](https://github.com/uniweb/build) — Foundation build tooling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -37,8 +37,8 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/build": "0.2.1",
-    "@uniweb/core": "0.2.1",
+    "@uniweb/build": "0.2.2",
+    "@uniweb/core": "0.2.2",
     "@uniweb/kit": "0.2.1",
     "@uniweb/runtime": "0.3.0"
   }

package/src/commands/build.js

@@ -311,12 +311,39 @@ async function generateLocalizedHtml(projectDir, i18nConfig) {
 /**
  * Resolve foundation directory based on site config and project structure
  *
- * For single projects: ../foundation
- * For multi projects: ../../foundations/{name}
+ * Priority:
+ * 1. Read site's package.json to find foundation dependency path (most reliable)
+ * 2. Check foundations/{name} for multi-site projects
+ * 3. Check ../foundation for single-site projects
+ * 4. Check ../{name} as fallback
  */
 function resolveFoundationDir(projectDir, siteConfig) {
   const foundationName = siteConfig?.foundation
 
+  // First, try to resolve from site's package.json dependencies
+  // This is the most reliable method as it matches how Vite resolves imports
+  if (foundationName) {
+    const pkgPath = join(projectDir, 'package.json')
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+        const depValue = deps[foundationName]
+
+        // Check for file: protocol (local dependency)
+        if (depValue && depValue.startsWith('file:')) {
+          const relativePath = depValue.slice(5) // Remove 'file:' prefix
+          const resolvedPath = join(projectDir, relativePath)
+          if (existsSync(resolvedPath)) {
+            return resolvedPath
+          }
+        }
+      } catch {
+        // Ignore JSON parse errors, fall through to other methods
+      }
+    }
+  }
+
   // Check if we're in a multi-site structure (site is under sites/)
   const parentDir = join(projectDir, '..')
   const grandParentDir = join(projectDir, '..', '..')
@@ -416,6 +443,20 @@ async function buildSite(projectDir, options = {}) {
       }
     } catch (err) {
       error(`Pre-rendering failed: ${err.message}`)
+
+      // Provide helpful guidance for common errors
+      if (err.message.includes('Foundation not found')) {
+        log('')
+        log(`${colors.yellow}This usually means:${colors.reset}`)
+        log(`  1. The foundation hasn't been built yet (run foundation build first)`)
+        log(`  2. The foundation name in site.yml doesn't match your setup`)
+        log('')
+        log(`${colors.dim}Check that:${colors.reset}`)
+        log(`  • site.yml 'foundation:' matches the package name in your foundation's package.json`)
+        log(`  • site's package.json has a dependency pointing to the correct foundation path`)
+        log(`  • The foundation's dist/foundation.js exists (build the foundation first)`)
+      }
+
       if (process.env.DEBUG) {
         console.error(err.stack)
       }

package/src/commands/doctor.js

@@ -0,0 +1,331 @@
+/**
+ * uniweb doctor - Diagnose project configuration issues
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join, resolve, basename, dirname, relative } from 'node:path'
+import yaml from 'js-yaml'
+
+// ANSI colors
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[36m'
+}
+
+const success = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`)
+const warn = (msg) => console.log(`${colors.yellow}⚠${colors.reset} ${msg}`)
+const error = (msg) => console.log(`${colors.red}✗${colors.reset} ${msg}`)
+const info = (msg) => console.log(`${colors.blue}→${colors.reset} ${msg}`)
+const log = console.log
+
+/**
+ * Check if a directory is a site
+ */
+function isSite(dir) {
+  return existsSync(join(dir, 'site.yml')) || existsSync(join(dir, 'site.yaml'))
+}
+
+/**
+ * Check if a directory is a foundation
+ */
+function isFoundation(dir) {
+  return existsSync(join(dir, 'src', 'components'))
+}
+
+/**
+ * Load package.json from a directory
+ */
+function loadPackageJson(dir) {
+  const pkgPath = join(dir, 'package.json')
+  if (!existsSync(pkgPath)) return null
+  try {
+    return JSON.parse(readFileSync(pkgPath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Load site.yml from a directory
+ */
+function loadSiteYml(dir) {
+  const ymlPath = join(dir, 'site.yml')
+  const yamlPath = join(dir, 'site.yaml')
+  const configPath = existsSync(ymlPath) ? ymlPath : existsSync(yamlPath) ? yamlPath : null
+  if (!configPath) return null
+  try {
+    return yaml.load(readFileSync(configPath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Main doctor command
+ */
+export async function doctor(args = []) {
+  log('')
+  log(`${colors.blue}${colors.bright}Uniweb Doctor${colors.reset}`)
+  log(`${colors.dim}Checking project configuration...${colors.reset}`)
+
+  const projectDir = resolve(process.cwd())
+
+  // Detect project type and find workspace root
+  let workspaceDir = projectDir
+
+  if (isSite(projectDir)) {
+    workspaceDir = dirname(projectDir)
+    if (basename(workspaceDir) === 'sites') {
+      workspaceDir = dirname(workspaceDir)
+    }
+  } else if (isFoundation(projectDir)) {
+    workspaceDir = dirname(projectDir)
+    if (basename(workspaceDir) === 'foundations') {
+      workspaceDir = dirname(workspaceDir)
+    }
+  }
+
+  // Check workspace structure
+  const hasWorkspaceConfig = existsSync(join(workspaceDir, 'pnpm-workspace.yaml')) ||
+                             existsSync(join(workspaceDir, 'package.json'))
+
+  if (!hasWorkspaceConfig) {
+    error('Not in a Uniweb workspace')
+    log(`${colors.dim}Run this command from your project root or a site/foundation directory.${colors.reset}`)
+    process.exit(1)
+  }
+
+  log('')
+  info(`Workspace: ${workspaceDir}`)
+
+  // Find all foundations
+  const foundations = []
+
+  // Check single-foundation layout
+  const foundationDir = join(workspaceDir, 'foundation')
+  if (isFoundation(foundationDir)) {
+    const pkg = loadPackageJson(foundationDir)
+    foundations.push({
+      path: foundationDir,
+      name: pkg?.name || 'foundation',
+      folderName: 'foundation'
+    })
+  }
+
+  // Check multi-foundation layout
+  const foundationsDir = join(workspaceDir, 'foundations')
+  if (existsSync(foundationsDir)) {
+    try {
+      const entries = readdirSync(foundationsDir, { withFileTypes: true })
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const foundationPath = join(foundationsDir, entry.name)
+          if (isFoundation(foundationPath)) {
+            const pkg = loadPackageJson(foundationPath)
+            foundations.push({
+              path: foundationPath,
+              name: pkg?.name || entry.name,
+              folderName: entry.name
+            })
+          }
+        }
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  if (foundations.length === 0) {
+    warn('No foundations found')
+  } else {
+    success(`Found ${foundations.length} foundation(s):`)
+    for (const f of foundations) {
+      const nameMismatch = f.name !== f.folderName ? ` ${colors.dim}(folder: ${f.folderName}/)${colors.reset}` : ''
+      log(`    • ${f.name}${nameMismatch}`)
+    }
+  }
+
+  // Find all sites
+  const sites = []
+
+  // Check single-site layout
+  const siteDir = join(workspaceDir, 'site')
+  if (isSite(siteDir)) {
+    sites.push({ path: siteDir, name: 'site' })
+  }
+
+  // Check multi-site layout
+  const sitesDir = join(workspaceDir, 'sites')
+  if (existsSync(sitesDir)) {
+    try {
+      const entries = readdirSync(sitesDir, { withFileTypes: true })
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const sitePath = join(sitesDir, entry.name)
+          if (isSite(sitePath)) {
+            sites.push({ path: sitePath, name: entry.name })
+          }
+        }
+      }
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  if (sites.length === 0) {
+    warn('No sites found')
+  } else {
+    log('')
+    success(`Found ${sites.length} site(s):`)
+    for (const s of sites) {
+      log(`    • ${s.name}`)
+    }
+  }
+
+  // Check each site
+  const issues = []
+
+  for (const site of sites) {
+    const siteName = site.name
+    const sitePath = site.path
+    const siteYml = loadSiteYml(sitePath)
+    const sitePkg = loadPackageJson(sitePath)
+
+    log('')
+    info(`Checking site: ${siteName}`)
+
+    if (!siteYml) {
+      issues.push({ type: 'error', site: siteName, message: 'Missing site.yml' })
+      error('Missing site.yml')
+      continue
+    }
+
+    if (!sitePkg) {
+      issues.push({ type: 'error', site: siteName, message: 'Missing package.json' })
+      error('Missing package.json')
+      continue
+    }
+
+    const foundationName = siteYml.foundation
+    if (!foundationName) {
+      warn('No foundation specified in site.yml (using runtime loading?)')
+      continue
+    }
+
+    // Check if foundation name matches a known foundation
+    const matchingFoundation = foundations.find(f => f.name === foundationName)
+
+    if (!matchingFoundation) {
+      // Check if it might match a folder name instead
+      const folderMatch = foundations.find(f => f.folderName === foundationName)
+      if (folderMatch) {
+        issues.push({
+          type: 'error',
+          site: siteName,
+          message: `Foundation mismatch: site.yml uses folder name "${foundationName}" instead of package name "${folderMatch.name}"`
+        })
+        error(`Foundation mismatch:`)
+        log(`    site.yml says: ${colors.yellow}foundation: ${foundationName}${colors.reset}`)
+        log(`    This matches the folder name, but the package name is: ${colors.green}${folderMatch.name}${colors.reset}`)
+        log('')
+        log(`  ${colors.dim}To fix, update site.yml:${colors.reset}`)
+        log(`    foundation: ${folderMatch.name}`)
+        continue
+      }
+
+      issues.push({
+        type: 'error',
+        site: siteName,
+        message: `Foundation "${foundationName}" not found`
+      })
+      error(`Foundation "${foundationName}" not found`)
+      log('')
+      log(`  ${colors.dim}Available foundations:${colors.reset}`)
+      for (const f of foundations) {
+        log(`    • ${f.name} (${f.folderName}/)`)
+      }
+      continue
+    }
+
+    success(`Foundation reference: ${foundationName}`)
+
+    // Check package.json dependency
+    const deps = { ...sitePkg.dependencies, ...sitePkg.devDependencies }
+    const depValue = deps[foundationName]
+
+    if (!depValue) {
+      issues.push({
+        type: 'error',
+        site: siteName,
+        message: `Missing dependency "${foundationName}" in package.json`
+      })
+      error(`Missing dependency "${foundationName}" in package.json`)
+      log('')
+      log(`  ${colors.dim}Add to site's package.json dependencies:${colors.reset}`)
+      log(`    "${foundationName}": "file:${relative(sitePath, matchingFoundation.path)}"`)
+      continue
+    }
+
+    if (depValue.startsWith('file:')) {
+      const depPath = join(sitePath, depValue.slice(5))
+      if (!existsSync(depPath)) {
+        issues.push({
+          type: 'error',
+          site: siteName,
+          message: `Dependency path doesn't exist: ${depValue}`
+        })
+        error(`Dependency path doesn't exist: ${depValue}`)
+        log('')
+        log(`  ${colors.dim}Update site's package.json:${colors.reset}`)
+        log(`    "${foundationName}": "file:${relative(sitePath, matchingFoundation.path)}"`)
+        continue
+      }
+      success(`Dependency path: ${depValue}`)
+    } else {
+      success(`Dependency: ${depValue} (npm package)`)
+    }
+
+    // Check if foundation is built
+    const foundationDist = join(matchingFoundation.path, 'dist', 'foundation.js')
+    if (!existsSync(foundationDist)) {
+      issues.push({
+        type: 'warn',
+        site: siteName,
+        message: `Foundation not built: ${matchingFoundation.name}`
+      })
+      warn(`Foundation not built yet`)
+      log(`  ${colors.dim}Run: pnpm --filter ${matchingFoundation.name} build${colors.reset}`)
+    } else {
+      success(`Foundation built: dist/foundation.js exists`)
+    }
+  }
+
+  // Summary
+  log('')
+  log('─'.repeat(50))
+
+  const errors = issues.filter(i => i.type === 'error')
+  const warnings = issues.filter(i => i.type === 'warn')
+
+  if (errors.length === 0 && warnings.length === 0) {
+    log('')
+    log(`${colors.green}${colors.bright}All checks passed!${colors.reset}`)
+    log('')
+  } else {
+    log('')
+    if (errors.length > 0) {
+      log(`${colors.red}${errors.length} error(s)${colors.reset}`)
+    }
+    if (warnings.length > 0) {
+      log(`${colors.yellow}${warnings.length} warning(s)${colors.reset}`)
+    }
+    log('')
+  }
+
+  return { issues, errors: errors.length, warnings: warnings.length }
+}

package/src/index.js

@@ -18,6 +18,7 @@ import { fileURLToPath } from 'node:url'
 import prompts from 'prompts'
 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 { getVersionsForTemplates, getVersion } from './versions.js'
 import {
@@ -161,6 +162,12 @@ async function main() {
     return
   }
 
+  // Handle doctor command
+  if (command === 'doctor') {
+    await doctor(args.slice(1))
+    return
+  }
+
   // Handle create command
   if (command !== 'create') {
     error(`Unknown command: ${command}`)
@@ -321,6 +328,7 @@ ${colors.bright}Commands:${colors.reset}
   create [name]      Create a new project
   build              Build the current project
   docs               Generate component documentation
+  doctor             Diagnose project configuration issues
   i18n <cmd>         Internationalization (extract, sync, status)
 
 ${colors.bright}Create Options:${colors.reset}

package/templates/multi/sites/main/site.yml.hbs

@@ -2,6 +2,9 @@ name: {{projectName}}
 description: Main site for {{projectName}}
 foundation: default
 
+# Homepage - specifies which page folder becomes the root route (/)
+index: home
+
 theme:
   primary: '#3b82f6'
 

package/templates/single/site/site.yml.hbs

@@ -1,5 +1,8 @@
 name: {{projectName}}
 
+# Homepage - specifies which page folder becomes the root route (/)
+index: home
+
 theme:
   primary: '#3b82f6'