npm - uniweb - Versions diffs - 0.13.1 → 0.13.3 - Mend

uniweb 0.13.1 → 0.13.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/package.json +5 -5
package/partials/agents.md +6 -1
package/src/backend/site-sync.js +4 -2
package/src/commands/dev.js +40 -0
package/src/commands/doctor.js +22 -5
package/src/commands/update.js +46 -0
package/src/framework-index.json +5 -5
package/src/utils/install-integrity.js +206 -0
package/templates/site/site.yml.hbs +5 -0
package/templates/site/vite.config.js +4 -0

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,14 +41,14 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/runtime": "0.8.33",
     "@uniweb/core": "0.7.27",
-    "@uniweb/kit": "0.9.34"
+    "@uniweb/kit": "0.9.35",
+    "@uniweb/runtime": "0.8.34"
   },
   "peerDependencies": {
+    "@uniweb/build": "0.15.3",
     "@uniweb/content-reader": "1.1.15",
-    "@uniweb/semantic-parser": "1.1.18",
-    "@uniweb/build": "0.15.1"
+    "@uniweb/semantic-parser": "1.1.18"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md CHANGED Viewed

@@ -312,6 +312,8 @@ Description paragraph.
 Heading levels set *structure* (pretitle, title, subtitle), not font size — the component controls visual sizing.
+**A section with no `type:` renders through the foundation's default section type — a component named `Section`, unless the foundation's `main.js` sets `defaultSection` to something else.** This is what lets a folder of plain markdown with no frontmatter at all become pages: mounted documentation, an imported wiki, anything written before it met this framework. If such content renders blank, the foundation has no `Section` — that, not the markdown, is what to fix.
 **Markdown order ≠ rendering order.** The parser extracts content into a flat structure; the component decides how to arrange it visually. Write markdown in semantic order, not visual order — start with the heading, then add icons, images, and text in any order.
 **Placing content *before* the first heading changes the parse:** headings after body content become items, not the section title. This is by design — it's how repeating content groups are created.
@@ -605,6 +607,8 @@ pages: [home, about, ...]   # Order pages (... = rest, first = homepage); withou
 **Content-less containers:** folders with `page.yml` but no markdown are structural groups (`hasContent: false`). Visiting one auto-redirects to the first descendant with content — this is what supports courses → modules → lessons at any depth.
+**A local folder for a mounted route should use `folder.yml`, not `page.yml`.** The filename is how you say what the folder holds — `page.yml` for a page built from sections, `folder.yml` for a folder of pages — and for a mount that answer also decides how the mounted tree is read. A `page.yml` stub over a mounted folder of pages says "sections", and top-level markdown in the mounted repo collapses into one page instead of becoming pages of its own. Keep `layout:`, `title:` and SEO in that stub; the mounted repo's own `folder.yml` supplies its ordering and title where the stub is silent.
 **SEO & social cards:** set site-wide defaults in `site.yml`; any page overrides per-field in `page.yml` (page wins, site fills gaps). These render into every page's static `<head>` — Open Graph, Twitter Card, canonical, robots — so shares and crawlers see them without running JS. The social `image` is the field most worth setting once at site level.
 ```yaml
@@ -808,11 +812,12 @@ Names only — for signatures and props, read the package: it's on disk at `node
 **Media:** `Visual` (first non-empty: inset/video/image), `Image`, `Media`, `Icon`, `Asset`
 **Navigation:** `Link`, `useActiveRoute()`, `useWebsite()`, `useRouting()`
 **Header/layout:** `useScrolled(threshold)`, `useMobileMenu()`, `useAppearance()`
+**Documentation shells:** `useHeadings()` (the page's headings + the one being read, derived from content so it prerenders), `website.getBranchHierarchy({ route, for })` (the page tree for one branch). Kit ships no ready-made layout — a layout is your foundation's design; write it in `src/layouts/` and use these for the behaviour.
 **Layout helpers:** `useGridLayout(columns, { gap })`, `useAccordion({ multiple, defaultOpen })`, `useTheme(name)`
 **Theming data:** `useThemeData()`, `useColorContext(block)`
 **Data fetching:** `useFetched`, `useCacheEntry`, `useEntityDetail`
 **Utilities:** `cn()`, `SafeHtml`, `SocialIcon`, `filterSocialLinks(links)`, `getSocialPlatform(url)`, `getLocaleLabel(locale)`
-**Other styled:** `SidebarLayout`, `Code`, `Alert`, `Table`, `Details`, `Divider`, `Disclaimer`
+**Other styled:** `Code`, `Alert`, `Table`, `Details`, `Divider`, `Disclaimer`
 Four things you won't discover by reading exports:

package/src/backend/site-sync.js CHANGED Viewed

@@ -110,8 +110,10 @@ export function writeSyncCache(siteDir, hashes) {
  * Offline-probe how many of a site's entities differ from the last successful push.
  * Runs the SAME emit + send-only-changed diff `uniweb push` runs, but with an
  * OFFLINE Model resolver — no auth, no submit, no backend round-trip. Used by
- * `uniweb status` and the `uniweb publish` pre-flight. Throws if the producer
- * can't build the sync packages (e.g. an unresolved data Model); callers report it.
+ * `uniweb status` only. (It was also `uniweb publish`'s pre-flight back when publish
+ * went live WITHOUT pushing and so had to warn about unpushed content; publish now
+ * always pushes, which makes the warning moot.) Throws if the producer can't build
+ * the sync packages (e.g. an unresolved data Model); callers report it.
  *
  * @param {string} siteDir
  * @returns {Promise<{ changed: number, unchanged: number, warnings: string[] }>}

package/src/commands/dev.js CHANGED Viewed

@@ -40,6 +40,8 @@ import { readWorkspaceConfig } from '../utils/config.js'
 import { discoverSites } from '../utils/discover.js'
 import { findWorkspaceRoot } from '../utils/workspace.js'
 import { readFlagValue } from '../utils/args.js'
+import { checkSiteInstall, readDeclaredFoundation } from '../utils/install-integrity.js'
+import { discoverFoundations } from '../utils/discover.js'
 const RED = '\x1b[31m'
 const YELLOW = '\x1b[33m'
@@ -95,6 +97,13 @@ export async function dev(args = []) {
     console.error('')
   }
+  // A `file:` foundation dependency can be satisfied by a link or by a copy,
+  // and a copy is a snapshot: the dev server serves it while builds read the
+  // workspace source, so the two disagree and only the browser shows it. The
+  // check is a few stats and package.json reads, so it runs every time rather
+  // than waiting for someone to suspect it.
+  await warnOnStaleInstall(rootDir, site)
   const pm = detectPackageManager()
   const command = filterCmd(pm, site.name, 'dev')
   const [bin, ...rest] = command.split(' ')
@@ -110,3 +119,34 @@ export async function dev(args = []) {
     process.exit(1)
   })
 }
+/**
+ * Say so if the site is about to be served from an install that no longer
+ * matches the workspace. Warns rather than exits — the server may still be
+ * useful, and the author is the one who knows whether it is.
+ */
+async function warnOnStaleInstall(rootDir, site) {
+  try {
+    const sitePath = join(rootDir, site.path)
+    const foundationName = readDeclaredFoundation(sitePath)
+    if (!foundationName) return
+    const foundations = await discoverFoundations(rootDir)
+    const foundation = foundations
+      .map(f => ({ ...f, path: join(rootDir, f.path) }))
+      .find(f => f.name === foundationName)
+    if (!foundation) return
+    const findings = checkSiteInstall({ name: site.name, path: sitePath }, foundation, rootDir)
+    if (!findings.length) return
+    console.error(`${YELLOW}⚠${RESET} Dev will not build against your workspace foundation:`)
+    for (const finding of findings) {
+      console.error(`  ${finding.message}`)
+    }
+    console.error(`  ${findings[0].remedy}. \`uniweb doctor\` explains in full.`)
+    console.error('')
+  } catch {
+    // A diagnostic must never be the reason dev fails to start.
+  }
+}

package/src/commands/doctor.js CHANGED Viewed

@@ -13,6 +13,7 @@ import { readAgentsVersion } from '../utils/agents-stamp.js'
 import { writeJsonPreservingStyle } from '../utils/json-file.js'
 import { surveyWorkspaceDeps } from '../utils/dep-survey.js'
 import { discoverFoundations, discoverSites } from '../utils/discover.js'
+import { checkSiteInstall } from '../utils/install-integrity.js'
 import { findWorkspaceRoot } from '../utils/workspace.js'
 /**
@@ -409,8 +410,24 @@ export async function doctor(args = []) {
       success(`Dependency: ${depValue} (npm package)`)
     }
+    // Is what is installed what is declared? A `file:` dependency can be
+    // satisfied by a link or by a copy, and only the link stays true. The copy
+    // is invisible to a build — which reads the workspace source directly — so
+    // it surfaces as a dev server serving stale code, or nothing at all.
+    for (const finding of checkSiteInstall(
+      { name: siteName, path: sitePath },
+      matchingFoundation,
+      workspaceDir
+    )) {
+      issues.push({ id: finding.id, type: finding.severity, site: siteName, message: finding.message })
+      error(`[${finding.id}] ${finding.message}`)
+      log(`${colors.dim}${finding.detail}${colors.reset}`)
+      log('')
+      log(`  ${colors.dim}To fix: ${finding.remedy}${colors.reset}`)
+    }
     // Check if foundation is built
-    const foundationDist = join(matchingFoundation.path, 'dist', 'foundation.js')
+    const foundationDist = join(matchingFoundation.path, 'dist', 'entry.js')
     if (!existsSync(foundationDist)) {
       issues.push({
         type: 'warn',
@@ -420,7 +437,7 @@ export async function doctor(args = []) {
       warn(`Foundation not built yet`)
       log(`  ${colors.dim}Run: uniweb build${colors.reset}`)
     } else {
-      success(`Foundation built: dist/foundation.js exists`)
+      success(`Foundation built: dist/entry.js exists`)
     }
   }
@@ -463,7 +480,7 @@ export async function doctor(args = []) {
     }
     // Check if built
-    const extensionDist = join(ext.path, 'dist', 'foundation.js')
+    const extensionDist = join(ext.path, 'dist', 'entry.js')
     if (!existsSync(extensionDist)) {
       issues.push({
         type: 'warn',
@@ -472,7 +489,7 @@ export async function doctor(args = []) {
       warn(`Extension not built yet`)
       log(`  ${colors.dim}Run: uniweb build${colors.reset}`)
     } else {
-      success(`Extension built: dist/foundation.js exists`)
+      success(`Extension built: dist/entry.js exists`)
     }
   }
@@ -513,7 +530,7 @@ export async function doctor(args = []) {
       // Check if a matching extension exists and is built
       const matchingExt = extensions.find(e => e.folderName === extName || e.name === extName)
-      if (matchingExt && !existsSync(join(matchingExt.path, 'dist', 'foundation.js'))) {
+      if (matchingExt && !existsSync(join(matchingExt.path, 'dist', 'entry.js'))) {
         issues.push({
           type: 'warn',
           site: site.name,

package/src/commands/update.js CHANGED Viewed

@@ -49,6 +49,7 @@ import { isNonInteractive } from '../utils/interactive.js'
 import { detectWorkspacePm, installCmd, detectGlobalCliPm, globalCliUpdateCmd } from '../utils/pm.js'
 import { writeJsonPreservingStyle } from '../utils/json-file.js'
 import { surveyWorkspaceDeps, compareSemver } from '../utils/dep-survey.js'
+import { checkWorkspaceInstall, readDeclaredFoundation } from '../utils/install-integrity.js'
 const colors = {
   reset: '\x1b[0m',
@@ -422,12 +423,57 @@ export async function update(args = []) {
     })
   }
+  // ── Verify the install actually took ─────────────────────────────
+  // An install that was interrupted, or that satisfied a `file:` foundation
+  // with a copy instead of a link, leaves a tree that no longer matches what
+  // was just written. Builds keep working — they read the workspace source —
+  // so the mismatch only shows up later, as a dev server serving stale code,
+  // by which point this command is nobody's first suspect. It is the most
+  // likely command to produce that state, so it is the right one to check.
+  if (!dryRun && installRan) {
+    await reportInstallIntegrity(workspaceDir)
+  }
   // ── Closing summary ──────────────────────────────────────────────
   if (!dryRun && (depsEdited || agentsResult === 'created' || agentsResult === 'updated')) {
     printSummary({ editedPaths, depsEdited, installRan, installPm, agentsResult, cliVersion })
   }
 }
+/**
+ * Report any drift between the workspace and the tree that was just installed.
+ */
+async function reportInstallIntegrity(workspaceDir) {
+  try {
+    // Imported here, not at the top: discover.js reaches @uniweb/build, an
+    // optional peer that must stay off the CLI's startup path so `npx uniweb
+    // create` works in an empty directory. update.js is loaded at startup.
+    const { discoverSites, discoverFoundations } = await import('../utils/discover.js')
+    const sites = (await discoverSites(workspaceDir)).map((s) => ({
+      name: s.name,
+      path: join(workspaceDir, s.path),
+      foundation: readDeclaredFoundation(join(workspaceDir, s.path)),
+    }))
+    const foundations = (await discoverFoundations(workspaceDir)).map((f) => ({
+      name: f.name,
+      path: join(workspaceDir, f.path),
+    }))
+    const findings = checkWorkspaceInstall(sites, foundations, workspaceDir)
+    if (!findings.length) return
+    log('')
+    warn('The install finished, but dev will not resolve what is declared:')
+    for (const finding of findings) {
+      log(`  ${finding.message}`)
+    }
+    log(`  ${colors.dim}${findings[0].remedy}. \`uniweb doctor\` explains in full.${colors.reset}`)
+  } catch {
+    // A post-flight check must never turn a successful update into a failure.
+  }
+}
 /**
  * Step 2 — regenerate AGENTS.md from the CLI's bundled partial, stamped
  * with the CLI version. Guarded: won't run if the deps were edited but

package/src/framework-index.json CHANGED Viewed

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-25T13:16:31.947Z",
+  "generatedAt": "2026-07-25T16:40:40.342Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.15.1",
+      "version": "0.15.3",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -43,7 +43,7 @@
       "deps": []
     },
     "@uniweb/kit": {
-      "version": "0.9.34",
+      "version": "0.9.35",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -61,7 +61,7 @@
       "deps": []
     },
     "@uniweb/runtime": {
-      "version": "0.8.33",
+      "version": "0.8.34",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -99,7 +99,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.5.0",
+      "version": "0.5.2",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/utils/install-integrity.js ADDED Viewed

@@ -0,0 +1,206 @@
+/**
+ * Local development: is the bundler reading the foundation source you are editing?
+ *
+ * SCOPE — this is a check about CLI scaffolding, and only about one modality.
+ * A site's `package.json`, its `file:` dependency on the foundation, and its
+ * `node_modules` are not part of the site as an artifact; they are the project
+ * shape the CLI hangs tooling on (see the three-ingredient model,
+ * kb/framework/architecture/site-foundation-runtime-model.md, Part 1). Treating
+ * that scaffolding as part of the site is where most of the confusion in this
+ * area comes from, so: nothing here says anything about what a foundation *is*,
+ * how it is distributed, or how it reaches a host.
+ *
+ * The one modality it covers is bundled dev mode against a workspace-local
+ * foundation — `uniweb dev` with `foundation:` naming a sibling package. There,
+ * the site imports `#foundation`, which `build/src/site/config.js` aliases to
+ * the foundation's PACKAGE NAME, so Vite resolves it through node_modules. A
+ * linked site (registry ref or URL) never takes that path, and neither does the
+ * desktop app, unipress, or the edge — they load a built `dist/entry.js`, or
+ * read a content folder directly. The check stays silent for all of them
+ * because there is no node_modules entry to look at.
+ *
+ * What goes wrong in that one modality: a `file:` dependency can be satisfied
+ * by a link to the workspace source or by a materialized copy, and a copy is a
+ * snapshot carrying its own nested node_modules — so it keeps resolving
+ * whatever `@uniweb/*` versions were current when it was taken.
+ *
+ * It hides well. `uniweb build` resolves the foundation by PATH and reads the
+ * workspace source, so the build is green and the tests pass while the dev
+ * server serves code from weeks ago. Cheap enough (a few lstats and JSON reads)
+ * to run on every `uniweb dev` rather than waiting for someone to suspect it.
+ *
+ * Reports; never prints. Callers present findings in their own voice.
+ */
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import yaml from 'js-yaml'
+import { stripVersionRange } from './dep-survey.js'
+/**
+ * The foundation a site declares, or null. Small enough to live beside the one
+ * check that needs it rather than becoming another shared module.
+ *
+ * @param {string} sitePath
+ * @returns {string|null}
+ */
+export function readDeclaredFoundation(sitePath) {
+  for (const name of ['site.yml', 'site.yaml']) {
+    const path = join(sitePath, name)
+    if (!existsSync(path)) continue
+    try {
+      return yaml.load(readFileSync(path, 'utf8'))?.foundation ?? null
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    return null
+  }
+}
+/**
+ * Where a package name resolves from a starting directory, walking up through
+ * node_modules the way Node does. Returns the directory, or null.
+ */
+function resolvePackageDir(fromDir, packageName) {
+  let dir = resolve(fromDir)
+  while (true) {
+    const candidate = join(dir, 'node_modules', packageName)
+    if (existsSync(join(candidate, 'package.json'))) return candidate
+    const parent = resolve(dir, '..')
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+/**
+ * Check one site against the foundation it declares.
+ *
+ * @param {Object} site - { name, path }
+ * @param {Object} foundation - { name, path } — the workspace source
+ * @param {string} workspaceDir - For readable paths in findings
+ * @returns {Array<Object>} findings, each { id, severity, site, message, detail, remedy }
+ */
+export function checkSiteInstall(site, foundation, workspaceDir) {
+  const findings = []
+  const rel = (p) => relative(workspaceDir, p) || '.'
+  const linkPath = join(site.path, 'node_modules', foundation.name)
+  // Nothing installed at all — not this check's business to complain about,
+  // and every other check will already be shouting.
+  if (!existsSync(linkPath)) {
+    return findings
+  }
+  // A symlink points at one source of truth; a real directory is a snapshot.
+  const stat = lstatSync(linkPath)
+  const isLink = stat.isSymbolicLink()
+  if (!isLink) {
+    findings.push({
+      id: 'dev-foundation-source-stale',
+      severity: 'error',
+      site: site.name,
+      message: `In dev, this site builds against a copy of "${foundation.name}", not your workspace source.`,
+      detail:
+        `  ${rel(linkPath)} is a directory rather than a link, so it is a snapshot of\n` +
+        `  ${rel(foundation.path)} taken when it was installed. Edits you make will not\n` +
+        `  reach the dev server. \`uniweb build\` resolves the foundation by path and reads\n` +
+        `  your source, so builds stay correct — which is why this is easy to miss.`,
+      remedy: 'Reinstall so it links to the workspace source (e.g. pnpm install)',
+    })
+  } else {
+    // Linked, but possibly at the wrong source.
+    const target = realpathSync(linkPath)
+    const expected = realpathSync(foundation.path)
+    if (target !== expected) {
+      findings.push({
+        id: 'dev-foundation-source-elsewhere',
+        severity: 'error',
+        site: site.name,
+        message: `In dev, this site resolves "${foundation.name}" somewhere other than your workspace source.`,
+        detail: `  resolves to: ${rel(target)}\n  workspace source: ${rel(expected)}`,
+        remedy: 'Reinstall, and check the site\'s package.json file: reference',
+      })
+    }
+  }
+  // What the site actually reaches, versus what the foundation asks for. These
+  // agree through a link and drift through a copy — the drift is what runs.
+  const foundationPkg = readJson(join(foundation.path, 'package.json'))
+  const declared = { ...foundationPkg?.dependencies, ...foundationPkg?.peerDependencies }
+  for (const [name, spec] of Object.entries(declared)) {
+    if (!name.startsWith('@uniweb/')) continue
+    // A range says "anything compatible" — only an exact pin is a promise.
+    if (stripVersionRange(spec) !== spec) continue
+    const reachedDir = resolvePackageDir(linkPath, name)
+    if (!reachedDir) continue
+    const reached = readJson(join(reachedDir, 'package.json'))?.version
+    if (reached && reached !== spec) {
+      findings.push({
+        id: 'dev-foundation-dep-skew',
+        severity: 'error',
+        site: site.name,
+        message: `In dev, "${foundation.name}" compiles against ${name} ${reached}, but declares ${spec}.`,
+        detail:
+          `  declared in ${rel(join(foundation.path, 'package.json'))}: ${spec}\n` +
+          `  resolved from ${rel(linkPath)}: ${reached}\n` +
+          `  ${name} is bundled into the foundation, so the dev server runs the version it\n` +
+          `  reaches here. A build reads the workspace tree and may compile a different one.`,
+        remedy: 'Reinstall so the resolved tree matches what is declared',
+      })
+    }
+  }
+  return findings
+}
+/**
+ * Check every site in the workspace.
+ *
+ * @param {Array<Object>} sites - [{ name, path, foundation }]
+ * @param {Array<Object>} foundations - [{ name, path }]
+ * @param {string} workspaceDir
+ * @returns {Array<Object>} findings
+ */
+export function checkWorkspaceInstall(sites, foundations, workspaceDir) {
+  const findings = []
+  for (const site of sites) {
+    const foundation = foundations.find((f) => f.name === site.foundation)
+    // An unresolvable foundation name is a different check's finding.
+    if (!foundation) continue
+    findings.push(...checkSiteInstall(site, foundation, workspaceDir))
+  }
+  return findings
+}
+/**
+ * One-line summary for callers that only want to know whether to speak up.
+ * @param {Array<Object>} findings
+ * @returns {string|null}
+ */
+export function summarizeInstallFindings(findings) {
+  if (!findings.length) return null
+  const sites = [...new Set(findings.map((f) => f.site))]
+  const what = findings.some((f) => f.id === 'foundation-dep-skew')
+    ? 'the installed packages do not match what is declared'
+    : 'the foundation is not linked to its workspace source'
+  return `Install is out of date in ${sites.join(', ')} — ${what}. Run your package manager's install, or \`uniweb doctor\` for detail.`
+}

package/templates/site/site.yml.hbs CHANGED Viewed

@@ -26,6 +26,11 @@ index: home
 #   pages/blog: ../../blog-content  # Mount blog content at /blog route
 #   layout: ./custom-layout         # Custom layout directory
 #   collections: ./data             # Collections directory
+#
+# To give a mounted route a layout or a title, add a local folder for it
+# (pages/docs/) holding a folder.yml — folder.yml, not page.yml, because the
+# mounted directory is a folder of pages. Whatever that stub leaves unset comes
+# from the mounted directory's own folder.yml, so it need only say what differs.
 # ─── Data Sources ─────────────────────────────────────────────────────────────
 # Define collections (local markdown folders) or fetch remote/local JSON data.

package/templates/site/vite.config.js CHANGED Viewed

@@ -1,3 +1,7 @@
 import { defineSiteConfig } from '@uniweb/build/site'
+// Options passed here REPLACE the framework's, key by key — except
+// optimizeDeps.include / .exclude, which are added to rather than replaced.
+// So `build: { sourcemap: true }` overrides the framework's whole build block;
+// check what you are replacing before you pass one.
 export default defineSiteConfig()