uniweb 1.0.2 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
     "url": "https://github.com/uniweb/cli/issues"
   },
   "engines": {
-    "node": ">=20.19"
+    "node": ">=22.12"
   },
   "dependencies": {
     "handlebars": "^4.7.8",
@@ -42,12 +42,12 @@
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
     "@uniweb/content-writer": "~1.0.1",
-    "@uniweb/core": "~1.0.1",
+    "@uniweb/core": "~1.1.0",
     "@uniweb/semantic-parser": "~1.5.1",
     "@uniweb/schemas": "~1.0.1"
   },
   "peerDependencies": {
-    "@uniweb/build": "~1.0.1",
+    "@uniweb/build": "~1.1.1",
     "@uniweb/semantic-parser": "~1.5.1",
     "@uniweb/content-reader": "~1.2.8"
   },

package/partials/agents.md

@@ -194,6 +194,7 @@ The rest of this guide explains how Uniweb works. This part is what to do *first
 | `src`, `site` | **single** (the default) | foundation in `src/`, site in `site/` |
 | `foundations/*`, `sites/*` | **segregated** | several sites may share one foundation — a foundation edit hits all of them |
 | `*/src`, `*/site` | **co-located projects** | one self-contained pair per project: `docs/src` + `docs/site` |
+| `*/src`, `*/sites/*` | **projects with several sites** | each project's foundation with its sites: `memberships/src` + `memberships/sites/fitness`, `memberships/sites/society` — a foundation edit hits every site in its project |
 | a package whose `main.js` says `extension: true` — `effects`, `extensions/*` (alongside any of the above) | extensions present | extra section types, runtime-loaded — see step 2 |
 
 Those names are convention; the globs are the truth. Full guide with the wiring for each: `development/project-structures.md`.
@@ -2801,7 +2802,7 @@ npx uniweb@latest update             # apply: align @uniweb/* deps AND refresh A
 
 **`npx uniweb@latest update` is the command for bringing a project up to date.** It aligns the project's `@uniweb/*` dependencies *and* this AGENTS.md to the version matrix of the CLI that runs it. Deps and documentation move together — that's the whole point of the verb.
 
-**What the version numbers mean.** A patch brings fixes and features; a minor version is where Uniweb puts breaking changes — `update` lists each package that crosses one, so read those before shipping — and a major is kept for something really big. Dependencies are written as tilde ranges (`~1.0.1`), so `pnpm install` and `pnpm update` never cross a minor on their own. The move from 0.x to 1.0.1 asks nothing of a project that was on the latest 0.x versions — 1.0.1 carried every package's 0.x line over — though `update` marks each package `major · BREAKING`.
+**What the version numbers mean.** A patch brings fixes and features; a minor version is where Uniweb puts breaking changes — `update` lists each package that crosses one, so build and check the project before shipping — and a major is kept for something really big. Dependencies are written as tilde ranges (`~1.0.1`), so `pnpm install` and `pnpm update` never cross a minor on their own. The move from 0.x to 1.0.1 asks nothing of a project that was on the latest 0.x versions — 1.0.1 carried every package's 0.x line over — though `update` marks each package `major · BREAKING`.
 
 > ### ⛔ WRITE `@latest`. A BARE `uniweb update` IS USUALLY A NO-OP, AND IT SAYS SO CONVINCINGLY
 >

package/src/backend/foundation-bring-along.js

@@ -59,7 +59,8 @@ import {
   detectFoundationType,
   isExtensionUrl,
   readFoundationName,
-  checkFoundationName
+  checkFoundationName,
+  findSiteExtension
 } from '@uniweb/build'
 import { computeFoundationDigest } from '../utils/code-upload.js'
 import { isNonInteractive } from '../utils/interactive.js'
@@ -127,15 +128,24 @@ export function resolveLocalExtensions(siteDir, siteYml) {
           ? entry
           : null
     if (!decl || isExtensionUrl(decl)) continue
-    let info
+    // Resolved as the primary foundation is — and, where that finds nothing, where
+    // extensions live: the rule the build follows for a site-relative extension
+    // (`findSiteExtension`), which looks in `extensions/<name>/` and in the folders
+    // above the site. It takes a plain name only, so a catalog ref stays not local.
+    // ⛔ Until 2026-10-13 only the first: a site naming the `extensions` template's
+    // own `extensions/effects` — as publish's refusal of `/effects/entry.js`
+    // advises — released nothing and sent an unpinned ref the host cannot serve.
+    let dir = null
     try {
-      info = detectFoundationType(decl, siteDir)
+      const info = detectFoundationType(decl, siteDir)
+      if (info?.type === 'local' && info.path) dir = info.path
     } catch {
-      // Unresolved — the site build surfaces the canonical error; nothing local.
-      continue
+      // Not a foundation's shape — tried as an extension below.
     }
-    if (!info || info.type !== 'local' || !info.path) continue
-    out.push({ decl, dir: info.path, version: readPkgField(info.path, 'version') })
+    dir ??= findSiteExtension(decl, siteDir)
+    // Still nothing: the site build surfaces the canonical error; nothing local.
+    if (!dir) continue
+    out.push({ decl, dir, version: readPkgField(dir, 'version') })
   }
   return out
 }

package/src/commands/add.js

@@ -11,12 +11,16 @@
  *   uniweb add section <name> [--foundation <name>]
  */
 
-import { existsSync } from 'node:fs'
+import { existsSync, realpathSync } from 'node:fs'
 import { readFile, writeFile, mkdir } from 'node:fs/promises'
 import { join, relative, basename } from 'node:path'
 import prompts from 'prompts'
 import yaml from 'js-yaml'
-import { resolveFoundationSrcPath, readFoundationName } from '@uniweb/build'
+import {
+  resolveFoundationSrcPath,
+  readFoundationName,
+  findSiteExtension
+} from '@uniweb/build'
 import {
   scaffoldFoundation,
   scaffoldSite,
@@ -26,15 +30,12 @@ import {
 } from '../utils/scaffold.js'
 import {
   resolvePlacement,
+  projectConflictLines,
   SITE_KIND,
   FOUNDATION_KIND,
   EXTENSION_KIND
 } from '../utils/placement.js'
-import {
-  readWorkspaceConfig,
-  addWorkspaceGlob,
-  updateRootScripts
-} from '../utils/config.js'
+import { registerWorkspacePackage, updateRootScripts } from '../utils/config.js'
 import { discoverFoundations, discoverSites } from '../utils/discover.js'
 import { generateStarter, reportStarter, declarationFor } from './starter.js'
 import {
@@ -360,6 +361,7 @@ 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)
+  refuseProjectConflict(placement, 'foundation', name, opts)
   if (placement.outsideRoot) {
     error(`--path must name a folder inside the workspace: ${placement.outsideRoot}`)
     log('')
@@ -470,10 +472,10 @@ async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
     ensureFoundationName(fullPath, registryName)
   }
 
-  // Register the package in pnpm-workspace.yaml — by exact path, not by glob.
-  // No glob inference: if the user wants `foundations/*` they can edit the
-  // workspace file themselves. This matches the "no assumptions" rule.
-  await addWorkspaceGlob(rootDir, relativePath)
+  // Register the package by its exact path — unless a pattern the workspace lists
+  // already covers it (`foundations/*`, `*/src`), which leaves the file as it is.
+  // No glob inference: a pattern is the user's to write.
+  await registerWorkspacePackage(rootDir, relativePath)
 
   // Update root scripts
   const sites = await discoverSites(rootDir)
@@ -486,6 +488,18 @@ async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
   log(`Next: ${colors.cyan}${installCmd(pm)}${colors.reset}`)
 }
 
+/**
+ * Stop when `--project` came with a name or a `--path` — it names the folder itself,
+ * so the two disagree. Refused, never ignored (`projectConflictLines`).
+ */
+function refuseProjectConflict(placement, kind, name, opts) {
+  if (!placement.projectConflict) return
+  const [first, ...rest] = projectConflictLines(kind, name, opts, `${getCliPrefix()} add ${kind}`)
+  error(first)
+  for (const line of rest) log(line)
+  process.exit(1)
+}
+
 /**
  * Add a site to the workspace
  */
@@ -495,6 +509,7 @@ 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)
+  refuseProjectConflict(placement, 'site', name, opts)
   if (placement.outsideRoot) {
     error(`--path must name a folder inside the workspace: ${placement.outsideRoot}`)
     log('')
@@ -608,8 +623,8 @@ async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
     await applyFromTemplate(opts.from, 'site', fullPath, projectName)
   }
 
-  // Register the package by exact path. No glob inference.
-  await addWorkspaceGlob(rootDir, relativePath)
+  // Register the package by exact path, unless a listed pattern covers it already.
+  await registerWorkspacePackage(rootDir, relativePath)
 
   // Update root scripts (discover sites after registration — includes the new one)
   const sites = await discoverSites(rootDir)
@@ -678,6 +693,7 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
   // you name is the folder created — `effects` → effects/, `extensions/effects` →
   // extensions/effects/ — and `--path` is the folder it goes in.
   const placement = resolvePlacement(rootDir, name, opts, EXTENSION_KIND)
+  refuseProjectConflict(placement, 'extension', name, opts)
   if (placement.outsideRoot) {
     error(`--path must name a folder inside the workspace: ${placement.outsideRoot}`)
     log('')
@@ -739,7 +755,7 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
   }
 
   // Register the folder it is in, as add foundation does
-  await addWorkspaceGlob(rootDir, relativePath)
+  await registerWorkspacePackage(rootDir, relativePath)
 
   // Wire extension to site:
   //   - --site <name>: explicit, wire it.
@@ -750,60 +766,57 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
   //     warning so the user/agent knows wiring is pending, and exit 0
   //     (the extension itself is fine).
   //   - no sites: print a note and exit 0.
+  // ⭐ And only when that site can load it (extensionUnreachable): an entry the
+  // build cannot serve would build with a warning and 404 at runtime.
   let wiredSite = null
   let unwiredReason = null
-  // A site loads a workspace extension from `/<name>/entry.js`, which the build
-  // finds in `<name>/` or `extensions/<name>/` (wireExtensionToSite). An entry
-  // pointing anywhere else would build with a warning and 404 at runtime, so
-  // none is written.
-  const reachable = relativePath === name || relativePath === `extensions/${name}`
-  if (!reachable) {
-    unwiredReason =
-      `A site loads a workspace extension from /${name}/entry.js, which the build finds in ` +
-      `${name}/ or extensions/${name}/ — not ${relativePath}/. Move the folder to one of those, ` +
-      `or list a URL where the built extension is served under <site>/site.yml::extensions:.`
-  } else if (opts.site) {
-    wiredSite = await wireExtensionToSite(rootDir, opts.site, relativePath)
-  } else {
-    const sites = await discoverSites(rootDir)
-    if (sites.length === 1) {
-      wiredSite = await wireExtensionToSite(rootDir, sites[0].name, relativePath)
-    } else if (sites.length > 1) {
-      if (isNonInteractive(process.argv)) {
-        unwiredReason = `Multiple sites in workspace; extension not wired. Re-run with --site <name>, or edit <site>/site.yml::extensions: manually.`
-      } else {
-        const sortedSites = [...sites].sort((a, b) =>
-          a.name.localeCompare(b.name)
-        )
-        const response = await prompts(
-          {
-            type: 'select',
-            name: 'site',
-            message: 'Which site is this extension for?',
-            choices: sortedSites.map((s) => ({
-              title: s.name,
-              description: s.path,
-              value: s.name
-            }))
-          },
-          {
-            onCancel: () => {
-              log('\nCancelled.')
-              process.exit(0)
-            }
+  let target = null
+  const sites = await discoverSites(rootDir)
+  if (opts.site) {
+    target = sites.find((s) => s.name === opts.site) || null
+    if (!target) {
+      unwiredReason = `Could not find site '${opts.site}' to wire this extension to. Available: ${sites.map((s) => s.name).join(', ') || 'none'}.`
+    }
+  } else if (sites.length === 1) {
+    target = sites[0]
+  } else if (sites.length > 1) {
+    if (isNonInteractive(process.argv)) {
+      unwiredReason = `Multiple sites in workspace; extension not wired. Re-run with --site <name>, or edit <site>/site.yml::extensions: manually.`
+    } else {
+      const sortedSites = [...sites].sort((a, b) =>
+        a.name.localeCompare(b.name)
+      )
+      const response = await prompts(
+        {
+          type: 'select',
+          name: 'site',
+          message: 'Which site is this extension for?',
+          choices: sortedSites.map((s) => ({
+            title: s.name,
+            description: s.path,
+            value: s.name
+          }))
+        },
+        {
+          onCancel: () => {
+            log('\nCancelled.')
+            process.exit(0)
           }
-        )
-        if (response.site) {
-          wiredSite = await wireExtensionToSite(rootDir, response.site, relativePath)
         }
-      }
-    } else {
-      unwiredReason = `No site in this workspace yet. Wire this extension into a site's site.yml::extensions: once you create one.`
+      )
+      target = sites.find((s) => s.name === response.site) || null
+    }
+  } else {
+    unwiredReason = `No site in this workspace yet. Wire this extension into a site's site.yml::extensions: once you create one.`
+  }
+  if (target) {
+    unwiredReason = extensionUnreachable(rootDir, target, name, fullPath)
+    if (!unwiredReason) {
+      wiredSite = await wireExtensionToSite(rootDir, target.name, relativePath)
     }
   }
 
-  // Update root scripts
-  const sites = await discoverSites(rootDir)
+  // Update root scripts (an extension adds no site, so the list read above stands)
   await updateRootScripts(rootDir, sites, pm)
 
   let msg = `Created extension '${name}' at ${relativePath}/`
@@ -932,9 +945,10 @@ async function addProject(rootDir, projectName, opts, pm = 'pnpm') {
     )
   }
 
-  // Update workspace globs for co-located layout
-  await addWorkspaceGlob(rootDir, '*/src')
-  await addWorkspaceGlob(rootDir, '*/site')
+  // The co-located patterns — each added only if what it lists is not covered yet
+  // (a workspace listing `*/src` and `*/sites/*` keeps its file as it is for `src/`).
+  await registerWorkspacePackage(rootDir, `${name}/src`, { entry: '*/src' })
+  await registerWorkspacePackage(rootDir, `${name}/site`, { entry: '*/site' })
 
   // Update root scripts
   const sites = await discoverSites(rootDir)
@@ -1124,6 +1138,41 @@ async function applyFromTemplate(
   }
 }
 
+/**
+ * Why `site` cannot load the extension just made at `extensionDir` — or null when
+ * it can. A site loads `/<name>/entry.js` from the folder `@uniweb/build` finds for
+ * `<name>` (`findSiteExtension`): `<name>/` or `extensions/<name>/`, in the folder
+ * the site is in or one above it, up to the workspace root. The build, prerender
+ * and the dev server follow that rule, so `add` asks it rather than restating it.
+ *
+ * ⛔ Until 2026-10-13 this was a copy of the rule, judged from the workspace root
+ * while the build looked only in the folder the site is in — so a site at
+ * `sites/main` was wired to `extensions/effects`, and its build could not find it.
+ *
+ * @param {string} rootDir
+ * @param {{ name: string, path: string }} site - `path` relative to `rootDir`
+ * @param {string} name - the extension's folder name: its URL's first segment
+ * @param {string} extensionDir - absolute
+ * @returns {string|null}
+ */
+function extensionUnreachable(rootDir, site, name, extensionDir) {
+  const found = findSiteExtension(name, join(rootDir, site.path))
+  if (found && realpathSync(found) === realpathSync(extensionDir)) return null
+  const here = relative(rootDir, extensionDir)
+  if (found) {
+    return (
+      `Site '${site.name}' would load the nearer extension named '${name}', at ` +
+      `${relative(rootDir, found)}/ — not ${here}/. Rename one of them.`
+    )
+  }
+  return (
+    `A site loads a workspace extension from /${name}/entry.js, which the build finds in ` +
+    `${name}/ or extensions/${name}/ in the folder the site is in or a folder above it, up to ` +
+    `the workspace root. For ${site.path}/ that is not ${here}/: move the folder there, or list a ` +
+    `URL where the built extension is served under ${site.path}/site.yml::extensions:.`
+  )
+}
+
 /**
  * Wire an extension URL to a site's site.yml
  */
@@ -1147,10 +1196,11 @@ async function wireExtensionToSite(rootDir, siteName, extensionFolder) {
     const config = yaml.load(content) || {}
 
     // ⭐ The site loads it from its own origin at `/<name>/entry.js`, `<name>`
-    // being the extension's folder: the build finds that extension's build in
-    // `<name>/` or `extensions/<name>/`, copies it into the site's output there,
-    // and prerender imports it from the same place (`@uniweb/build`,
-    // resolveExtensionDist) — the form the `extensions` template declares.
+    // being the extension's folder: the build finds that extension by name
+    // (`@uniweb/build`, findSiteExtension — the caller has checked it finds THIS
+    // one), copies its build into the site's output there, and prerender and the
+    // dev server load it from the same place — the form the `extensions`
+    // template declares.
     // ⛔ Until 2026-10-08 this wrote `/<folder>/dist/entry.js`, which that lookup
     // reads as an extension named after the folder's FIRST segment —
     // `/extensions/effects/dist/entry.js` as one named `extensions` — so the
@@ -1589,7 +1639,7 @@ async function addCi(rootDir, opts, pm = 'pnpm') {
   }
 
   // Read node version from root package.json engines.node if pinned;
-  // otherwise default to 20 (matches the workspace template's >=20.19).
+  // otherwise default to 22, the framework's own floor (>=22.12).
   const rootPkg = JSON.parse(
     await readFile(join(rootDir, 'package.json'), 'utf-8').catch(() => '{}')
   )