uniweb 0.57.0 → 0.58.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.57.0",
+  "version": "0.58.1",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,17 +41,17 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
+    "@uniweb/core": "^0.29.5",
+    "@uniweb/runtime": "^0.26.6",
     "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/schemas": "^0.3.3",
-    "@uniweb/core": "^0.29.4",
     "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/runtime": "^0.26.5",
-    "@uniweb/kit": "^0.19.3"
+    "@uniweb/kit": "^0.19.3",
+    "@uniweb/schemas": "^0.3.3"
   },
   "peerDependencies": {
+    "@uniweb/build": "^0.54.1",
     "@uniweb/content-reader": "^1.2.5",
-    "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/build": "^0.53.0"
+    "@uniweb/semantic-parser": "^1.4.1"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -694,7 +694,7 @@ end the list with `...`.**
 
 **Configuration cascades: `page.yml` → `folder.yml` → `site.yml` → foundation defaults.** Each level inherits from the one above and overrides specific values, the way CSS specificity works. This is what makes bulk assignment natural — put `layout: marketing` in a `folder.yml` and every page in that folder inherits it, while one page can still override with its own `page.yml`. Reach for `folder.yml` before editing the same key into a dozen `page.yml` files.
 
-**Route mapping:** folder structure maps 1:1 to routes. Every folder keeps its natural route — `pages:` controls **order only**, not which child "becomes" the parent. The only exception is the site root, where `index:` (or first in `pages:`) sets `/`.
+**Route mapping:** folder structure maps 1:1 to routes. Every folder keeps its natural route — `pages:` controls **order only**, not which child "becomes" the parent. The only exception is the site root, where `index:` (or first in `pages:`) sets `/` — declared in `site.yml`, or in the pages directory's own `folder.yml` / `page.yml` (how a content repo carries its order), with `site.yml` winning.
 
 **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.
 

package/src/commands/add.js

@@ -355,6 +355,13 @@ async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
   // both. Format validation runs on the derived package name below, not
   // on the raw input — slashes in the input are intentional path syntax.
   const placement = resolvePlacement(rootDir, name, opts, FOUNDATION_KIND)
+  if (placement.outsideRoot) {
+    error(`--path must name a folder inside the workspace: ${placement.outsideRoot}`)
+    log('')
+    log(`The workspace root is ${colors.bright}${rootDir}${colors.reset}.`)
+    log(`A package outside it cannot be a workspace member.`)
+    process.exit(1)
+  }
   const { relativePath } = placement
   let { packageName } = placement
   const fullPath = join(rootDir, relativePath)
@@ -470,6 +477,13 @@ async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
 
   // Resolve placement first (path + package name); see notes in addFoundation.
   const placement = resolvePlacement(rootDir, name, opts, SITE_KIND)
+  if (placement.outsideRoot) {
+    error(`--path must name a folder inside the workspace: ${placement.outsideRoot}`)
+    log('')
+    log(`The workspace root is ${colors.bright}${rootDir}${colors.reset}.`)
+    log(`A package outside it cannot be a workspace member.`)
+    process.exit(1)
+  }
   const { relativePath } = placement
   let siteName = placement.packageName
   const fullPath = join(rootDir, relativePath)

package/src/commands/clone.js

@@ -271,6 +271,14 @@ export async function clone(args = [], deps = {}) {
       { path: pathFlag, project: projectFlag },
       SITE_KIND
     )
+    if (placement.outsideRoot) {
+      error(`--path must name a folder inside the workspace: ${placement.outsideRoot}`)
+      note(
+        `The workspace root is ${existingRoot}. A package outside it cannot be a ` +
+          `workspace member — the directory and the manifests would disagree.`
+      )
+      return { exitCode: 1 }
+    }
     siteDir = join(existingRoot, placement.relativePath)
     sitePkgName = placement.packageName
     workspaceName = sitePkgName

package/src/commands/pull.js

@@ -156,14 +156,39 @@ function shouldFetchAssets(args, siteDir) {
   return true
 }
 
-// Read a top-level `$uuid:` scalar from a YAML file, or null.
+// Read a top-level `$uuid:` scalar from a YAML file.
+//
+// ⛔ THREE STATES, AND COLLAPSING THEM TO `null` IS A LIE TO THE USER.
+// This returned `null` on any throw, so a site.yml that EXISTS and carries a
+// `$uuid:` line but does not PARSE was reported as "this project has no $uuid
+// yet. Run `uniweb push` first." — advice that is wrong, and actively harmful
+// on a cloned site, since `push` would send an empty tree at the uuid the file
+// already holds.
+//
+// It is also invisible: the user greps the file, sees `$uuid:`, and disbelieves
+// the CLI. The clone suite's own comment records an earlier round of exactly
+// this ("an unquoted `@…` scalar matched a regex here while the file did not
+// parse, and `pull` then found no `$uuid`") — that CAUSE was fixed by quoting
+// the ref; the SYMPTOM stayed reachable by any other parse error.
+// Re-surfaced 2026-09-18 by the backend lane, whose clone wrote a `$uuid:` and
+// whose pull then said there was none.
+//
+// ⇒ Name the state. A missing file and a `$uuid`-less file are "no uuid"; a
+// file that will not parse is an error with the parser's own message.
 function readYamlUuid(filePath) {
+  let text
   try {
-    const obj = yaml.load(readFileSync(filePath, 'utf8'))
-    return typeof obj?.$uuid === 'string' ? obj.$uuid : null
+    text = readFileSync(filePath, 'utf8')
   } catch {
-    return null
+    return { uuid: null } // no site.yml — genuinely nothing to pull
+  }
+  let obj
+  try {
+    obj = yaml.load(text)
+  } catch (err) {
+    return { uuid: null, unparsed: err.message.split('\n')[0] }
   }
+  return { uuid: typeof obj?.$uuid === 'string' ? obj.$uuid : null }
 }
 
 // Conditional-pull ETag cache (gitignored `.uniweb/pull-cache.json`): the last ETag
@@ -583,7 +608,20 @@ export async function pull(args = [], deps = {}) {
 
   // One identity per site: `site.yml::$uuid`. Both lanes (content + folder) are keyed
   // by it — the backend resolves the site's `@uniweb/folder` from this uuid.
-  const siteContentUuid = readYamlUuid(join(siteDir, 'site.yml'))
+  const siteYmlPath = join(siteDir, 'site.yml')
+  const identity = readYamlUuid(siteYmlPath)
+
+  // A file that will not parse is an error, not an absence — see readYamlUuid.
+  if (identity.unparsed) {
+    error(`site.yml did not parse: ${identity.unparsed}`)
+    note(siteYmlPath)
+    note(
+      'Nothing was read, so the $uuid in it (if any) was not seen. Fix the YAML and re-run.'
+    )
+    return { exitCode: 1 }
+  }
+
+  const siteContentUuid = identity.uuid
 
   if (!siteContentUuid) {
     info(

package/src/framework-index.json

@@ -1,16 +1,16 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-18T17:09:07.963Z",
+  "generatedAt": "2026-09-20T02:07:02.158Z",
   "packages": {
     "@uniweb/api": {
-      "version": "0.4.0",
+      "version": "0.4.1",
       "path": "framework/api",
       "deps": [
         "@uniweb/core"
       ]
     },
     "@uniweb/build": {
-      "version": "0.53.0",
+      "version": "0.54.1",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -35,7 +35,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.29.4",
+      "version": "0.29.5",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -83,7 +83,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.26.5",
+      "version": "0.26.6",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -126,7 +126,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.9.23",
+      "version": "0.9.25",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/utils/placement.js

@@ -1,3 +1,5 @@
+import { isAbsolute, relative, sep } from 'node:path'
+
 /**
  * Package placement resolution — shared by `add` and `clone`.
  *
@@ -7,6 +9,31 @@
  * (the same reason `utils/workspace.js` loads the classifier lazily).
  */
 
+// `--path` is documented as a folder INSIDE the workspace, and every consumer of
+// the result treats it that way: the caller does `join(rootDir, relativePath)`
+// while the workspace manifests get `relativePath` verbatim. An ABSOLUTE path
+// silently satisfies neither — `join('/ws', '/tmp/x')` is `/ws/tmp/x`, so the
+// directory is created in one place while `package.json::workspaces` and
+// `pnpm-workspace.yaml` record `/tmp/x`. The two disagree, and the manifests are
+// committed files carrying a path that exists on exactly one machine.
+//
+// Reported by the backend lane 2026-09-18 from a `clone --path <abs>`: the site
+// landed under `company-websites/tmp/claude-502/clonetest/` and both manifests
+// gained the absolute string.
+//
+// So: accept an absolute path when it names a folder inside the root (people type
+// one, and it is unambiguous), by rewriting it to the root-relative form every
+// consumer already expects. Refuse it when it escapes — a workspace package cannot
+// live outside its workspace, and guessing which half the user meant is how you get
+// the split above.
+function normalizeParent(given, rootDir) {
+  const trimmed = String(given).replace(/\/+$/, '')
+  if (!isAbsolute(trimmed)) return { relative: trimmed }
+  const rel = relative(rootDir || '', trimmed)
+  if (!rel || rel === '..' || rel.startsWith('../')) return { outsideRoot: true, given: trimmed }
+  return { relative: rel.split(sep).join('/') }
+}
+
 /** Foundation placement defaults (folder `src/`, package `src`). */
 export const FOUNDATION_KIND = {
   defaultDir: 'src',
@@ -59,17 +86,19 @@ export function resolvePlacement(rootDir, name, opts, kind) {
   //    name was given, or `<path>` itself if not (the path's last segment
   //    is then taken as the package name).
   if (opts.path) {
-    const parent = opts.path.replace(/\/+$/, '')
+    const parent = normalizeParent(opts.path, rootDir)
+    if (parent.outsideRoot) return { outsideRoot: parent.given, relativePath: null, packageName: null }
+    const dir = parent.relative
     if (name) {
       const last = name.split('/').filter(Boolean).pop()
       return {
-        relativePath: `${parent}/${name}`.replace(/\/+/g, '/'),
+        relativePath: `${dir}/${name}`.replace(/\/+/g, '/'),
         packageName: last
       }
     }
-    const lastSegment = parent.split('/').filter(Boolean).pop() || parent
+    const lastSegment = dir.split('/').filter(Boolean).pop() || dir
     return {
-      relativePath: parent,
+      relativePath: dir,
       packageName: lastSegment
     }
   }

package/src/utils/site-identity.js

@@ -28,7 +28,7 @@
  * and it has to move the readers and the writers together or it makes the split worse.
  */
 
-import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import yaml from 'js-yaml'
 import { DEFAULT_BACKEND_ORIGIN } from './config.js'
@@ -136,10 +136,25 @@ export async function recordSiteBackend(siteDir, origin, deps = {}) {
     // Lazy by necessity, not by taste — see the header.
     mod = await loadUwx()
   } catch {
-    // No `@uniweb/build` at all. It is an OPTIONAL peer, so this is a supported
-    // configuration and not worth a word — the scope simply goes unrecorded, which is
-    // the behaviour everyone had before this key existed.
-    return null
+    // ⛔ NO `@uniweb/build` — and this is the COMMON case on the path that needs it
+    // most, not the rare one this branch used to assume.
+    //
+    // `clone` calls us straight after scaffolding and BEFORE `pnpm install`, so the
+    // site has no `node_modules` yet; under `npx uniweb@latest` the CLI's own tree
+    // may not carry build either (it is an optional peer). The import therefore
+    // fails on a FRESH CLONE essentially always, and returning null wrote nothing.
+    //
+    // The cost is not cosmetic: the clone then holds a `$uuid` minted by the
+    // `--backend` origin it was given, with nothing recording that origin, so the
+    // scope guard infers the DEFAULT backend and stops the very next command with
+    // "this project's stored identity belongs to https://uniweb.app". The origin was
+    // on the command line the whole time.
+    // Measured by the backend lane 2026-09-18: `0.48.5` recorded `$backend`,
+    // `0.57.0` did not, and their clone was unusable until they added the line by hand.
+    //
+    // ⇒ Fall back to a dependency-free write. `js-yaml` is the CLI's own direct
+    // dependency, so this path needs nothing installed in the project.
+    return writeSiteBackendFallback(siteDir, norm)
   }
 
   // ⚠️ PRESENT BUT TOO OLD is a different problem, and it must not look like the one
@@ -167,6 +182,41 @@ export async function recordSiteBackend(siteDir, origin, deps = {}) {
   }
 }
 
+/**
+ * Write `$backend` into `site.yml` without `@uniweb/build` — the fallback for a
+ * project whose dependencies are not installed yet (see `recordSiteBackend`).
+ *
+ * ⭐ Verifies the RESULT rather than trusting the edit: the file must still parse and
+ * must read back the origin we meant to write. A write that corrupts `site.yml` would
+ * be far worse than an unrecorded scope — an unparseable `site.yml` is the failure this
+ * same channel spent an evening on.
+ *
+ * @returns {string|null} the recorded origin, or null when nothing was written
+ */
+function writeSiteBackendFallback(siteDir, norm) {
+  const file = join(siteDir, 'site.yml')
+  let text
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch {
+    return null // no site.yml — nothing to annotate, and we do not create one
+  }
+  try {
+    // Quote through js-yaml rather than by hand: an origin is plain today, but the
+    // value is not ours to assume. Replace an existing key, else prepend.
+    const scalar = yaml.dump(norm, { lineWidth: -1 }).trim()
+    const next = /^\$backend:/m.test(text)
+      ? text.replace(/^\$backend:.*$/m, `$backend: ${scalar}`)
+      : `$backend: ${scalar}\n` + text
+    const parsed = yaml.load(next)
+    if (!parsed || typeof parsed !== 'object' || parsed.$backend !== norm) return null
+    writeFileSync(file, next)
+    return norm
+  } catch {
+    return null
+  }
+}
+
 /**
  * Refuse to act on a site whose stored identity belongs to a different backend.
  *

package/templates/site/site.yml.hbs

@@ -31,6 +31,12 @@ index: home
 # (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.
+#
+# ! A `pages/<segment>:` sub-mount is BUILD-ONLY today. `uniweb export` and
+#   `uniweb deploy --host <adapter>` mount it normally, but `uniweb push` /
+#   `uniweb publish` do not read the key, so the mounted pages do not reach a
+#   backend (the CLI warns when it skips them). The whole-directory form
+#   `paths: { pages: <dir> }` IS carried by both. Static hosting: use either.
 
 # ─── Structured Content ───────────────────────────────────────────────────────
 # Three things, and they are separate on purpose: