uniweb 1.31.6 → 1.31.8

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uniweb",
3
- "version": "1.31.6",
3
+ "version": "1.31.8",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -42,14 +42,14 @@
42
42
  "prompts": "^2.4.2",
43
43
  "tar": "^7.5.21",
44
44
  "@uniweb/content-writer": "~1.3.1",
45
- "@uniweb/schemas": "~1.7.1",
46
45
  "@uniweb/core": "~1.6.11",
46
+ "@uniweb/schemas": "~1.7.1",
47
47
  "@uniweb/semantic-parser": "~1.13.2"
48
48
  },
49
49
  "peerDependencies": {
50
- "@uniweb/semantic-parser": "~1.13.2",
50
+ "@uniweb/build": "~1.20.8",
51
51
  "@uniweb/content-reader": "~1.5.9",
52
- "@uniweb/build": "~1.20.6"
52
+ "@uniweb/semantic-parser": "~1.13.2"
53
53
  },
54
54
  "peerDependenciesMeta": {
55
55
  "@uniweb/build": {
@@ -136,7 +136,7 @@ data: {
136
136
 
137
137
  `single`/`whole` are refused over a schema whose root is a list (`@std/nav`, `@std/form`). A `whole` key its source cannot answer whole is `null`. An optional `schemas.config.js` routes a scope to a directory: `export default { '@acme': '../shared/acme-schemas' }` — a routed scope wins, has no package fallback, and `@/`/`@uniweb` are never routable. Worked examples: `development/schemas-in-practice.md`.
138
138
 
139
- **Any foundation can use a data schema another defines, by its full name** — `data: { members: '@acme/member' }`, `schema: '@acme/member'` in `queries.yml`. No backend is involved, and nothing to configure: a local build, `uniweb dev` included, reads the type from the package of the workspace that defines it (a foundation whose name gives the `@acme` scope, with the type in its own `schemas/`), or from a library the foundation bundles whose package.json gives that scope (`uniweb guide foundation` § Libraries). Two packages defining it stop the build, naming both. A type no such package defines comes from `schemas.config.js` (`'@acme/member': '../elsewhere/member.yml'`, or the scope's directory), which wins over both, or an installed `@acme/schemas` package. A scope is a namespace that keeps names from colliding, not a limit on who uses a type. So a type another foundation defines is named, never copied: a copy of its file is a second definition of the same type, which `doctor` points out where the two foundations' names give one scope (`type-defined-twice`). Registering, which only a site with a backend does, names such a type and sends no definition of it. A push also needs one of the site's foundations to declare the type, as a section type's data key or a schema of its own: the backend refuses a query whose type none of them declares, since nothing there would render it. A site can hold another site's records of a type too: `paths: { 'records/acme/member': '../../hub/site/records/acme/member' }` in its `site.yml` reads them as its own, a push adds them by reference rather than as copies once their own site has pushed them, and a pull leaves those files alone. A site's records of it sit in `records/acme/member/`; in `records/member/` they'd be the foundation's own `@/member`.
139
+ **Any foundation can use a data schema another defines, by its full name** — `data: { members: '@acme/member' }`, `schema: '@acme/member'` in `queries.yml`. No backend is involved, and nothing to configure: a local build, `uniweb dev` included, reads the type from the package of the workspace that defines it (a foundation whose name gives the `@acme` scope, with the type in its own `schemas/`), or from a library the foundation bundles whose package.json gives that scope (`uniweb guide foundation` § Libraries). Two packages defining it stop the build, naming both. A type no such package defines comes from `schemas.config.js` (`'@acme/member': '../elsewhere/member.yml'`, or the scope's directory), which wins over both, or an installed `@acme/schemas` package. A scope is a namespace that keeps names from colliding, not a limit on who uses a type. So a type another foundation defines is named, never copied: a copy of its file is a second definition of the same type, which `doctor` points out where the two foundations' names give one scope (`type-defined-twice`). Registering, which only a site with a backend does, names such a type and sends no definition of it; a type a library defines is registered from the library, first (`uniweb guide foundation` § Libraries). A push also needs one of the site's foundations to declare the type, as a section type's data key or a schema of its own: the backend refuses a query whose type none of them declares, since nothing there would render it. A site can hold another site's records of a type too: `paths: { 'records/acme/member': '../../hub/site/records/acme/member' }` in its `site.yml` reads them as its own, a push adds them by reference rather than as copies once their own site has pushed them, and a pull leaves those files alone. A site's records of it sit in `records/acme/member/`; in `records/member/` they'd be the foundation's own `@/member`.
140
140
 
141
141
  ```jsx
142
142
  function Article({ content, block }) { // data: { article: { schema: '@std/article', single: true } }
@@ -165,15 +165,17 @@ export default function Pricing({ content, params }) {
165
165
 
166
166
  A section type is a front desk; a **library** is the back office several foundations share: workers, hooks, logic and data types, with no section type of its own. Each foundation keeps its own section types, layouts and look, and calls on the same library. Take the first of these that holds what differs between two sites: the site's `theme.yml` (colors, fonts), foundation vars (radius, shadow, density), a param and the workers it picks, and only then a second foundation sharing a library with the first. A foundation is the vocabulary a kind of site is made with, so a second one is for another vocabulary, never for a smaller bundle.
167
167
 
168
- `uniweb add library libraries/ui --foundation classic,modern` makes it and wires each foundation: `"ui": "file:../../libraries/ui"` in its dependencies, and `@import "ui/styles.css";` in its `styles.css`. The library's own stylesheet holds `@source "./**/*.{js,jsx}";`, as kit's does, so Tailwind reads its classes wherever it is installed; without the import they are in no CSS at all, and the build says which line to add. Run it again with another `--foundation` to wire one more. A library is any local package a foundation depends on: one made by hand, cloned or kept as a git submodule inside the workspace works the same, and `uniweb add library <its folder>` wires it.
168
+ `uniweb add library libraries/ui --foundation classic,modern` makes it and wires each foundation: `"ui": "file:../../libraries/ui"` in its dependencies, and `@import "ui/styles.css";` in its `styles.css`. The library's own stylesheet holds `@source "./**/*.{js,jsx}";`, as kit's does, so Tailwind reads its classes wherever it is installed; without the import they are in no CSS at all, and the build says which line to add. Run it again with another `--foundation` to wire one more. A library is any local package a foundation depends on: one made by hand, cloned, kept as a git submodule, or in a folder beside the workspace works the same, and `uniweb add library <its folder>` wires it.
169
169
 
170
170
  - Export workers from its `index.js` and import them as from any package: `import { PlanCard } from 'ui'`.
171
171
  - A worker takes ordinary props and reads every design decision from foundation vars and theme tokens (`var(--card-radius)`, `bg-card`), never a fixed radius or color. That is what lets one worker look classic in one foundation and modern in another.
172
172
  - Import `@uniweb/core` by its bare name only, as kit does: a subpath bundles a second core.
173
- - A section type the library holds stays each foundation's to offer: a directory in the foundation's `sections/` whose `index.jsx` is `export { default } from 'ui/sections/Banner/index.jsx'`, with a `meta.js` that re-exports the library's the same way. Share one only when both vocabularies offer that type with the same content and params; otherwise each foundation writes its own over the same workers.
174
- - Data types: `uniweb add library libraries/data --schemas --scope @acme` gives it a `schemas/` folder and its scope (`"uniweb": { "scope": "@acme" }` in its package.json). Foundations name its types in full (`data: { plans: '@acme/plan' }`), with nothing to configure (`uniweb guide data`).
175
- - Each foundation bundles the library, so a build after a change in the library rebuilds every foundation that uses it. A registered foundation version keeps the library as it was built, as it keeps kit: a fix reaches a hosted site when that site's foundation releases again, which `uniweb publish` from the site does.
176
- - Keep a library inside the workspace. Outside it, under npm a build cannot resolve what the library's own code imports (kit); under pnpm a `file:` library is a copy that misses new files until a reinstall, and a `link:` one has the site load a copy of the foundation.
173
+ - A section type the library holds stays each foundation's to offer: a directory in the foundation's `sections/` whose `index.jsx` is `export { default } from 'ui/sections/Banner/index.jsx'`, with a `meta.js` that re-exports the library's the same way, when both offer it alike. When only the component is the same, the foundation keeps its own `meta.js` and re-exports `index.jsx` alone. When the components differ, the type stays the foundation's whole, even with the same `meta.js`: a shared `meta.js` over two components shows each foundation's params in the other's editor.
174
+ - Moving copies in: a file moves only with every file it imports by path (`./`, `#components/`), the same in each foundation holding it; a component that imports its foundation's own `Button` stays until `Button` moves. In the library it keeps its path, and foundations import it by name and path (`ui/components/Button.jsx`); give the library the foundations' `imports` map when the moved files use `#components/`. Build the workspace before and after and `diff -r -x '*.map'` each `dist/` (a sourcemap names source paths, which the move changes): the same files mean nothing a visitor sees or a publish sends changed. Steps: [Libraries](https://uniweb.io/docs/development/libraries.md) § *Moving copies into a library*.
175
+ - Split shared code by the foundations that use it, a library per group (one all of them use, one for each pair that shares more): a foundation's `@import "ui/styles.css"` has Tailwind read every file of the library, so one library for everything puts other foundations' classes in each one's CSS. A library that uses another lists it in its own dependencies (`"ui": "file:../ui"`).
176
+ - Data types: `uniweb add library libraries/data --schemas --scope @acme` gives it a `schemas/` folder and its scope (`"uniweb": { "scope": "@acme" }` in its package.json). Foundations name its types in full (`data: { plans: '@acme/plan' }`), with nothing to configure (`uniweb guide data`). On a synced site, `register` in a foundation registers the types it names from the library first, since a foundation is taken only once they are; `push` and `publish` release the foundation through `register`, so they do too, and a change to a type releases each foundation that names it on its site's next push. `uniweb register` in the library registers them alone.
177
+ - Each foundation bundles the library, so a build after a change in the library rebuilds every foundation that uses it, and `uniweb status` run in the library names those foundations and their sites. A registered foundation version keeps the library as it was built, as it keeps kit: a fix reaches a hosted site when that site's foundation releases again, which `uniweb publish` from the site does.
178
+ - A library beside the workspace (`uniweb add library ../acme-shared`, another repository's folder) is listed in the workspace by that path (`- '../acme-shared'` in `pnpm-workspace.yaml`), so npm and pnpm link it and `uniweb update` moves its ranges; under npm the build resolves its imports (React, kit, its own dependencies) as the foundation's. Depend on it with `file:`. One wired but not listed is a copy under pnpm, which the build warns about, naming the line to add.
177
179
 
178
180
  ### The Front Desk pattern
179
181
 
@@ -37,8 +37,11 @@
37
37
  * posture as `uniweb status` on a 404).
38
38
  *
39
39
  * "Release" here is literally `uniweb register` run in the foundation directory
40
- * — same build-if-stale → schema submit → code upload → digest the standalone
41
- * verb does, so there is exactly one foundation-release path.
40
+ * — same build-if-stale → the types its libraries define → schema submit → code
41
+ * upload → digest the standalone verb does, so there is exactly one
42
+ * foundation-release path. A library's types reach the registry this way: a change
43
+ * to one changes the foundation's built schema, which the digest folds in, so the
44
+ * foundation is released, and its register sends them first.
42
45
  *
43
46
  * ⭐ **`push` runs it too, and for a reason publish's framing does not cover.**
44
47
  * [Diego, 2026-08-19] — *"A published site can only reference a registered
@@ -0,0 +1,108 @@
1
+ /**
2
+ * ⭐ THE TYPES A FOUNDATION NAMES THAT A LIBRARY DEFINES ARE REGISTERED WITH IT. A foundation is
3
+ * released only once the data types it names are registered: the registry refuses one that names a
4
+ * Model it doesn't hold. A type a library defines is read by the foundation's build from that
5
+ * library's `schemas/` (`workspaceTypeFiles`), so `register` in the foundation registers it from
6
+ * there first, and `push` and `publish`, which release a site's foundation with `register`, do too
7
+ * *[Diego, 2026-11-10: "yes, push and publish should register a library's types automatically"]*.
8
+ *
9
+ * A library here is what the build read the type from, in the build's order: a type
10
+ * `schemas.config.js` routes is read from where the route says, so it is no library's; otherwise the
11
+ * one schemas package (`isSchemasPackage`, not a foundation) that gives the type's scope and holds
12
+ * it, bundled by the foundation, a package of its workspace, or one inside the foundation's own
13
+ * folder. A type another FOUNDATION defines is registered when that foundation is, and a refused
14
+ * release names it (`unregistered-types.js`).
15
+ *
16
+ * ⚖️ Each library sends the types the foundation names from it, the ones its types reference among
17
+ * them, and nothing else: its other files may be another package's to register, or a copy of one the
18
+ * foundation defines. A changed definition replaces the registered one, which every site naming the
19
+ * type then reads, and the registry judges the change: one records of the type can't take it refuses
20
+ * (`destructive_republish`), and the release stops there. Libraries go in the order their types
21
+ * reference each other, a referenced one first, since the registry refuses a reference to a Model it
22
+ * doesn't hold yet.
23
+ */
24
+
25
+ import { existsSync, realpathSync } from 'node:fs'
26
+ import { dirname, join, resolve } from 'node:path'
27
+ import { collectNestedRefs } from '@uniweb/schemas/format'
28
+
29
+ const real = (path) => {
30
+ try {
31
+ return realpathSync(path)
32
+ } catch {
33
+ return resolve(path)
34
+ }
35
+ }
36
+
37
+ /** The package `file` is in: the nearest folder above it with a package.json. */
38
+ function packageDirOf(file) {
39
+ for (let at = dirname(resolve(file)); ; at = dirname(at)) {
40
+ if (existsSync(join(at, 'package.json'))) return at
41
+ if (dirname(at) === at) return null
42
+ }
43
+ }
44
+
45
+ /** Libraries in an order where one whose types another's reference comes before it; else as found. */
46
+ function referencedFirst(libraries, schemas) {
47
+ const holder = new Map()
48
+ for (const lib of libraries) for (const ref of lib.refs) holder.set(ref, lib)
49
+ const before = new Map(libraries.map((lib) => [lib, new Set()]))
50
+ for (const lib of libraries) {
51
+ for (const ref of lib.refs) {
52
+ for (const target of collectNestedRefs(schemas[ref] || {})) {
53
+ const other = holder.get(target)
54
+ if (other && other !== lib) before.get(lib).add(other)
55
+ }
56
+ }
57
+ }
58
+ const out = []
59
+ const placed = new Set()
60
+ const place = (lib, path = new Set()) => {
61
+ if (placed.has(lib) || path.has(lib)) return
62
+ path.add(lib)
63
+ for (const other of before.get(lib)) place(other, path)
64
+ placed.add(lib)
65
+ out.push(lib)
66
+ }
67
+ for (const lib of libraries) place(lib)
68
+ return out
69
+ }
70
+
71
+ /**
72
+ * The libraries that define types the foundation names, each once, with the types it names from
73
+ * each, in the order they register in. A type its own `schemas/` defines (`@/x`), one nothing local
74
+ * defines, one two packages define (which the build refused) and one `schemas.config.js` routes are
75
+ * left out.
76
+ *
77
+ * @param {object} o
78
+ * @param {Record<string, object>} o.schemas - the foundation's built `dataSchemas`: every type it
79
+ * names, with its definition
80
+ * @param {string} o.foundationDir
81
+ * @returns {Promise<Array<{ dir: string, scope: string, refs: string[] }>>}
82
+ * @throws {Error} `code: 'BUILD_TOO_OLD'` when the installed `@uniweb/build` can't tell
83
+ */
84
+ export async function typesFromLibraries({ schemas, foundationDir }) {
85
+ const build = await import('@uniweb/build')
86
+ const { workspaceTypeFiles, packageTypeScope, classifyPackage, isSchemasPackage, routedSchema, resolveFoundationSrcPath } = build
87
+ if ([workspaceTypeFiles, packageTypeScope, routedSchema].some((fn) => typeof fn !== 'function')) {
88
+ throw Object.assign(new Error('the installed @uniweb/build cannot tell which library defines a type'), { code: 'BUILD_TOO_OLD' })
89
+ }
90
+ const srcDir = resolveFoundationSrcPath(foundationDir)
91
+ const own = real(foundationDir)
92
+ const byDir = new Map()
93
+ for (const ref of Object.keys(schemas || {})) {
94
+ // `@uniweb` is reserved, and nothing registers under it.
95
+ if (!/^@[^/]+\/./.test(ref) || ref.startsWith('@uniweb/')) continue
96
+ if (await routedSchema(ref, srcDir).catch(() => false)) continue
97
+ const files = await workspaceTypeFiles(ref, foundationDir).catch(() => [])
98
+ if (files.length !== 1) continue
99
+ const dir = packageDirOf(files[0])
100
+ if (!dir || real(dir) === own) continue
101
+ if (classifyPackage(dir) === 'foundation' || !isSchemasPackage(dir)) continue
102
+ const scope = await packageTypeScope(dir, 'schemas')
103
+ if (!scope) continue
104
+ if (!byDir.has(dir)) byDir.set(dir, { dir, scope, refs: [] })
105
+ byDir.get(dir).refs.push(ref)
106
+ }
107
+ return referencedFirst([...byDir.values()], schemas || {})
108
+ }
@@ -0,0 +1,53 @@
1
+ /**
2
+ * ⭐ THE TYPES A FOUNDATION NAMES THAT ANOTHER LOCAL PACKAGE DEFINES, AND THE REGISTRY DOESN'T HOLD.
3
+ * A foundation is released only once the data types it names are registered: the registry refuses
4
+ * one that depends on a Model it doesn't have. Measured 2026-11-10 on a local backend: a site's push
5
+ * released its foundation, which names `@acme/libplan` from a library it bundles, and the registry
6
+ * answered 400, "no such data-schema is registered on this deployment and this package does not
7
+ * publish one"; after `uniweb register` in the library, the push went through.
8
+ *
9
+ * A library's types `register` now sends before the foundation (`library-types.js`), so what this
10
+ * names after a refusal is a type ANOTHER FOUNDATION of the workspace defines: that foundation
11
+ * registers it, with `uniweb register` there.
12
+ */
13
+
14
+ import { existsSync } from 'node:fs'
15
+ import { dirname, join, resolve } from 'node:path'
16
+
17
+
18
+ /** The package `file` is in: the nearest folder above it with a package.json. */
19
+ function packageDirOf(file) {
20
+ for (let at = dirname(resolve(file)); ; at = dirname(at)) {
21
+ if (existsSync(join(at, 'package.json'))) return at
22
+ if (dirname(at) === at) return null
23
+ }
24
+ }
25
+
26
+ /**
27
+ * Each type `named` that the foundation does not define, that one other local package does, and that
28
+ * the registry answers it does not hold (`readDataSchema` → null). A type the registry could not be
29
+ * asked about is left out: this explains a refusal, and says nothing it could not check.
30
+ *
31
+ * @param {object} o
32
+ * @param {string[]} o.named - every type the foundation names (its schema's `dataSchemas`)
33
+ * @param {string[]} o.defined - the ones it defines, which its register sends
34
+ * @param {string} o.foundationDir
35
+ * @param {{ readDataSchema(name: string): Promise<object|null> }} o.client
36
+ * @returns {Promise<Array<{ ref: string, dir: string }>>} each type and the folder of the package that defines it
37
+ */
38
+ export async function unregisteredLocalTypes({ named, defined, foundationDir, client }) {
39
+ const { workspaceTypeFiles } = await import('@uniweb/build')
40
+ if (typeof workspaceTypeFiles !== 'function') return []
41
+ const out = []
42
+ for (const ref of named) {
43
+ if (defined.includes(ref) || /^@(?:std|uniweb)\//.test(ref)) continue
44
+ const files = await workspaceTypeFiles(ref, foundationDir).catch(() => [])
45
+ if (files.length !== 1) continue
46
+ const dir = packageDirOf(files[0])
47
+ // The foundation's own package, not one inside its folder (`library-types.js` reads them the same way).
48
+ if (!dir || resolve(dir) === resolve(foundationDir)) continue
49
+ const held = await client.readDataSchema(ref).catch(() => undefined)
50
+ if (held === null) out.push({ ref, dir })
51
+ }
52
+ return out
53
+ }
@@ -14,16 +14,24 @@
14
14
  * package already, made by hand, cloned or kept as a git submodule, this wires it without making
15
15
  * anything.
16
16
  *
17
+ * ⭐ A library may be outside the workspace's folder: a folder beside it, another repository say.
18
+ * It is listed in the workspace by its path all the same (`../acme-shared`), so the package manager
19
+ * links it rather than copying it, pnpm installs its dependencies in its folder, and `uniweb update`
20
+ * moves its ranges with the rest; the build resolves what it imports as its foundations do
21
+ * (`@uniweb/build`'s `foundation/library-imports.js`). ⛔ Until 2026-11-10 an outside folder was
22
+ * refused, and for a few hours that day it was wired unlisted, which pnpm installs as a copy that a
23
+ * change to the folder doesn't reach. Never the workspace's own folder, or one that holds it.
24
+ *
17
25
  * `--schemas` gives it a `schemas/` folder, whose files are data types its foundations name in full
18
26
  * (`@acme/plan`), under the scope in its `package.json` (`uniweb.scope`): `--scope`, or the one the
19
27
  * foundations it is wired into share.
20
28
  */
21
29
 
22
- import { existsSync, readFileSync } from 'node:fs'
30
+ import { existsSync, readFileSync, realpathSync } from 'node:fs'
23
31
  import { mkdir, readFile, writeFile } from 'node:fs/promises'
24
- import { join, relative, sep } from 'node:path'
32
+ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
25
33
  import prompts from 'prompts'
26
- import { checkRegistrationScope, classifyPackage, readFoundationName, resolveFoundationSrcPath, splitFoundationName } from '@uniweb/build'
34
+ import { checkRegistrationScope, classifyPackage, libraryLine as buildLibraryLine, readFoundationName, resolveFoundationSrcPath, splitFoundationName } from '@uniweb/build'
27
35
  import { resolvePlacement, LIBRARY_KIND } from '../utils/placement.js'
28
36
  import { registerWorkspacePackage } from '../utils/config.js'
29
37
  import { discoverFoundations } from '../utils/discover.js'
@@ -81,16 +89,35 @@ export function libraryManifest({ name, projectName, scope = null, versions = ge
81
89
  }
82
90
  }
83
91
 
84
- const INDEX = (name) => `// What this library shares with the foundations that depend on it. Export each component, hook
92
+ /** `path` with links followed, as far as it exists: a folder still to be made keeps its own name. */
93
+ function realOrNearest(path) {
94
+ const rest = []
95
+ for (let at = path; ; at = dirname(at)) {
96
+ try {
97
+ return join(realpathSync(at), ...rest.reverse())
98
+ } catch {
99
+ if (dirname(at) === at) return path
100
+ rest.push(basename(at))
101
+ }
102
+ }
103
+ }
104
+
105
+ // The two example lines are aligned on the longer, which the library's name decides.
106
+ const INDEX = (name) => {
107
+ const here = `export { default as PlanCard } from './components/PlanCard.jsx'`
108
+ const there = `import { PlanCard } from '${name}'`
109
+ const width = Math.max(here.length, there.length) + 3
110
+ return `// What this library shares with the foundations that depend on it. Export each component, hook
85
111
  // or helper here, and a foundation imports it by the library's name:
86
112
  //
87
- // export { default as PlanCard } from './components/PlanCard.jsx' (here)
88
- // import { PlanCard } from '${name}' (in a foundation)
113
+ // ${here.padEnd(width)}(here)
114
+ // ${there.padEnd(width)}(in a foundation)
89
115
  //
90
116
  // A component here takes ordinary props, and reads its look from the foundation's vars and the
91
117
  // theme's tokens (var(--card-radius), bg-card), so each foundation that uses it keeps its own.
92
118
  export {}
93
119
  `
120
+ }
94
121
 
95
122
  // The form kit's own stylesheet uses, which holds wherever a package manager puts the package.
96
123
  const STYLES = `/* Tailwind reads this library's files wherever it is installed: each foundation that uses it imports this stylesheet. */
@@ -115,18 +142,10 @@ const USES_TAILWIND = /@import\s+["']tailwindcss/
115
142
  * @returns {string}
116
143
  */
117
144
  export function libraryLine({ libraryDir, libraryName, stylesDir }) {
118
- let pkg = null
119
- try {
120
- pkg = JSON.parse(readFileSync(join(libraryDir, 'package.json'), 'utf8'))
121
- } catch {
122
- // no manifest to refuse the import
123
- }
124
- const exp = pkg?.exports
125
- // ⛔ An `exports` map without the stylesheet refuses the import, in Tailwind and in Node alike.
126
- const importable = !exp || typeof exp !== 'object' || Object.keys(exp).some((k) => k === './styles.css' || k === './*')
127
- if (existsSync(join(libraryDir, 'styles.css')) && importable) return `@import "${libraryName}/styles.css";`
128
- const rel = posix(relative(stylesDir, libraryDir))
129
- return `@source "${rel.startsWith('.') ? rel : `./${rel}`}";`
145
+ // ⭐ The build's one rule, which its stylesheet check names too: the library's stylesheet when it
146
+ // reads the library's files and the library exports it, else a `@source`. ⛔ Until 2026-11-10 this
147
+ // kept its own, which imported a stylesheet that read nothing and a string `exports` refused.
148
+ return buildLibraryLine({ name: libraryName, dir: libraryDir }, stylesDir)
130
149
  }
131
150
 
132
151
  /**
@@ -288,31 +307,50 @@ export async function addLibrary(rootDir, projectName, opts, pm = 'pnpm') {
288
307
  }
289
308
 
290
309
  const placement = resolvePlacement(rootDir, name, opts, LIBRARY_KIND)
291
- if (placement.outsideRoot) {
310
+ // Outside the workspace's folder: made or wired there, and said by its path from the root.
311
+ const outside = !!placement.outsideRoot
312
+ // Its real path, so the `file:` path written from each foundation's real folder is the short one
313
+ // (on macOS `/tmp` and `/var` are links into `/private`).
314
+ const libraryDir = realOrNearest(outside ? resolve(rootDir, placement.outsideRoot) : join(rootDir, placement.relativePath))
315
+ const relativePath = outside ? relative(rootDir, libraryDir).split(sep).join('/') : placement.relativePath
316
+ // ⛔ The workspace itself, or a folder holding it, is no library of it: `add library .` from a
317
+ // package's folder named the root, which then read as a library of everything.
318
+ const fromLibrary = relative(libraryDir, rootDir)
319
+ if (fromLibrary === '' || (!fromLibrary.startsWith('..') && !isAbsolute(fromLibrary))) {
292
320
  fail(
293
- `A library's folder must be inside the workspace: ${placement.outsideRoot}`,
294
- '',
295
- `A library from another repository goes inside the workspace, as a git submodule or a clone,`,
296
- `and \`${prefix} add library <its folder>\` lists it in the workspace and wires it.`
321
+ `A library's folder is a package of the workspace, never the workspace's own folder or one that holds it: ${relativePath || '.'}/`,
322
+ `Name the library's folder, from the workspace's root:`,
323
+ ` ${prefix} add library libraries/<name>`
297
324
  )
298
325
  }
299
- const { relativePath } = placement
300
- const libraryDir = join(rootDir, relativePath)
301
326
 
302
- let libraryName = placement.packageName
327
+ let libraryName = outside ? basename(libraryDir) : placement.packageName
303
328
  let created = false
304
329
  let scope = null
330
+ let ownScope = null
305
331
  if (existsSync(libraryDir)) {
306
332
  const kind = classifyPackage(libraryDir)
307
333
  if (kind) fail(`${relativePath}/ is a ${kind}, not a library.`)
308
334
  if (!existsSync(join(libraryDir, 'package.json'))) {
309
335
  fail(`${relativePath}/ exists and holds no package.json, so it is no package to wire.`, `Pick another folder, or give it a package.json.`)
310
336
  }
337
+ let manifest
311
338
  try {
312
- libraryName = JSON.parse(readFileSync(join(libraryDir, 'package.json'), 'utf8')).name || libraryName
339
+ manifest = JSON.parse(readFileSync(join(libraryDir, 'package.json'), 'utf8'))
313
340
  } catch {
314
341
  fail(`${relativePath}/package.json does not parse.`)
315
342
  }
343
+ libraryName = manifest.name || libraryName
344
+ ownScope = manifest.uniweb?.scope || null
345
+ // A package already there keeps its name, which another package of the workspace may have:
346
+ // listed, the workspace would hold two packages of one name, which npm refuses.
347
+ const taken = workspacePackageNames(rootDir).get(libraryName)
348
+ if (taken && resolve(rootDir, taken) !== libraryDir) {
349
+ fail(
350
+ `${relativePath}/ holds the package ${colors.bright}${libraryName}${colors.reset}, and a package of that name is in this workspace already, at ${taken}/.`,
351
+ `A foundation imports a library by its name: rename one of them in its package.json, then run this again.`
352
+ )
353
+ }
316
354
  } else {
317
355
  const valid = validatePackageName(libraryName)
318
356
  if (valid !== true) fail(valid)
@@ -329,7 +367,8 @@ export async function addLibrary(rootDir, projectName, opts, pm = 'pnpm') {
329
367
  const { wire, note } = await foundationsToWire(rootDir, opts.foundation, relativePath)
330
368
 
331
369
  if (opts.schemas || opts.scope) {
332
- scope = opts.scope ? `@${String(opts.scope).trim().replace(/^@/, '').replace(/\/.*$/, '')}` : await sharedScope(rootDir, wire)
370
+ // The scope given, else the one the library has already, else the one its foundations share.
371
+ scope = opts.scope ? `@${String(opts.scope).trim().replace(/^@/, '').replace(/\/.*$/, '')}` : ownScope || (await sharedScope(rootDir, wire))
333
372
  if (!scope || scope === '@') {
334
373
  fail(
335
374
  `A library's data types are named in full, under its scope (${colors.bright}@acme/plan${colors.reset}), and none is known yet.`,
@@ -362,7 +401,8 @@ export async function addLibrary(rootDir, projectName, opts, pm = 'pnpm') {
362
401
  await writeFile(join(libraryDir, 'schemas', 'README.md'), SCHEMAS_README(scope))
363
402
  }
364
403
 
365
- // Listed by its path, unless a pattern the workspace lists covers it already.
404
+ // Listed by its path, unless a pattern the workspace lists covers it already: one outside the
405
+ // workspace's folder too, so the package manager links it.
366
406
  await registerWorkspacePackage(rootDir, relativePath)
367
407
 
368
408
  const wired = []
@@ -389,6 +429,12 @@ export async function addLibrary(rootDir, projectName, opts, pm = 'pnpm') {
389
429
  info(` Export its components from ${relativePath}/index.js, and import them in a foundation: import { PlanCard } from '${libraryName}'`)
390
430
  if (scope) info(` Its data types go in ${relativePath}/schemas/, named ${scope}/<file name>.`)
391
431
  }
432
+ if (outside) {
433
+ log(
434
+ ` ${colors.dim}${relativePath}/ is outside the workspace's folder, and listed in the workspace by that path, so the package manager links it;` +
435
+ ` builds resolve what it imports as its foundations do.${colors.reset}`
436
+ )
437
+ }
392
438
  log('')
393
439
  log(`Next: ${colors.cyan}${installCmd(pm)}${colors.reset}`)
394
440
  }
@@ -963,8 +963,28 @@ export async function checkUnreadFolders({ foundationName, srcDir, issues }) {
963
963
  * Loaded here for the same reason.
964
964
  */
965
965
  export async function checkUnreadLibraries({ foundationName, srcDir, foundationDir, issues }) {
966
- const { unreadLibraries } = await import('@uniweb/build')
967
- const unread = unreadLibraries?.(join(srcDir, 'styles.css'), foundationDir) || []
966
+ const { unreadLibraries, copiedLibraries, copiedLibrariesWarning } = await import('@uniweb/build')
967
+ // ⛔ A check that throws stops nothing: until 2026-11-10 an unreadable folder in a library ended
968
+ // doctor here, every later check skipped.
969
+ let unread = []
970
+ try {
971
+ unread = unreadLibraries?.(join(srcDir, 'styles.css'), foundationDir) || []
972
+ } catch {
973
+ unread = []
974
+ }
975
+ // A library the package manager installed as a copy, which a change to its folder doesn't reach.
976
+ let copied = []
977
+ try {
978
+ copied = copiedLibraries?.(foundationDir) || []
979
+ } catch {
980
+ copied = []
981
+ }
982
+ if (copied.length) {
983
+ const id = 'copied-library'
984
+ const named = copied.map(({ name }) => name).join(', ')
985
+ issues.push({ id, type: 'warn', foundation: foundationName, message: `${foundationName} bundles ${named}, installed as a copy` })
986
+ warn(`[${id}] ${copiedLibrariesWarning(copied, findWorkspaceRoot(foundationDir) || undefined).replace(/^\[uniweb\] /, '')}`)
987
+ }
968
988
  if (unread.length === 0) return
969
989
  const id = 'unread-library'
970
990
  const named = unread.map(({ name }) => name).join(', ')
@@ -562,7 +562,7 @@ export async function publish(args = []) {
562
562
  }
563
563
  // A scope you are not a member of is said as that, with the ways on (`explainReleaseFailure`).
564
564
  say.err(err.notMember ? err.message : `Foundation release failed: ${err.message}`)
565
- for (const line of err.notMember ? err.ways : ['Fix the foundation, then re-run `uniweb publish`.']) say.dim(line)
565
+ for (const line of err.notMember ? err.ways : ['Nothing was sent. Settle what the release said above, then re-run `uniweb publish`.']) say.dim(line)
566
566
  return { exitCode: 1 }
567
567
  }
568
568
 
@@ -340,7 +340,7 @@ export async function push(args = [], deps = {}) {
340
340
  }
341
341
  // A scope you are not a member of is said as that, with the ways on (`explainReleaseFailure`).
342
342
  error(err.notMember ? err.message : `Foundation release failed: ${err.message}`)
343
- for (const line of err.notMember ? err.ways : ['Fix the foundation, then re-run `uniweb push`.']) note(line)
343
+ for (const line of err.notMember ? err.ways : ['Nothing was sent. Settle what the release said above, then re-run `uniweb push`.']) note(line)
344
344
  return { exitCode: 1 }
345
345
  }
346
346
  if (!fnd.proceed) return { exitCode: 1 }
@@ -12,10 +12,16 @@
12
12
  * — `register` builds it first. Preview paths (`--dry-run`, `-o`) never write to
13
13
  * `dist/`; they require a pre-built foundation.
14
14
  *
15
- * Run from a foundation, or from a schemas-only package — a package that exports
16
- * schemas (e.g. `@uniweb/schemas`, any `@org/schemas`) or a bare `schemas/*.yml`
17
- * folder. The schemas-only package is auto-detected and submits its data schemas
18
- * standalone (foundation-less); same flags, `--scope` names them.
15
+ * Run from a foundation, or from a schemas-only package — a package holding a
16
+ * `schemas/*.yml` folder (a library's), or one that exports schemas (e.g.
17
+ * `@uniweb/schemas`, any `@org/schemas`). The schemas-only package is auto-detected
18
+ * and submits its data schemas standalone (foundation-less); same flags, `--scope`
19
+ * names them.
20
+ *
21
+ * A foundation's register first registers the types it names that a library
22
+ * defines, from the library (`backend/library-types.js`): the registry takes a
23
+ * foundation only once the types it names are registered. So `push` and `publish`,
24
+ * which release a site's foundation with this command, register them too.
19
25
  *
20
26
  * Usage:
21
27
  * uniweb register Build the .uwx, submit it, then deliver
@@ -93,6 +99,8 @@ import { BackendClient } from '../backend/client.js'
93
99
  import { resolveWorkspace, scopeOfWorkspace, topOfChildHandle, SOURCE_LABEL } from '../backend/workspace.js'
94
100
  import { writeJsonPreservingStyleAsync } from '../utils/json-file.js'
95
101
  import { newerInput } from '../utils/foundation-freshness.js'
102
+ import { unregisteredLocalTypes } from '../backend/unregistered-types.js'
103
+ import { typesFromLibraries } from '../backend/library-types.js'
96
104
  import {
97
105
  findWorkspaceRoot,
98
106
  findFoundations,
@@ -159,7 +167,10 @@ function readPkgScope(foundationDir) {
159
167
  const pkg = JSON.parse(
160
168
  readFileSync(join(foundationDir, 'package.json'), 'utf8')
161
169
  )
162
- return pkg?.uniweb?.scope || null
170
+ // ⭐ Else the `@org` of a package named `@org/schemas`, as `packageTypeScope` and the build read
171
+ // it. ⛔ Until 2026-11-10 such a package with no `uniweb.scope` registered under the login's.
172
+ const named = /^@([^/]+)\/schemas$/.exec(typeof pkg?.name === 'string' ? pkg.name : '')
173
+ return pkg?.uniweb?.scope || (named ? `@${named[1]}` : null)
163
174
  } catch {
164
175
  return null
165
176
  }
@@ -188,6 +199,182 @@ function readPkgName(dir) {
188
199
  }
189
200
  }
190
201
 
202
+ // Whether the account is a member of `scope`: true, false, or null when that can't be told. Read to
203
+ // explain a refusal, never to gate one; a 401 is the credential itself, so it asks nothing.
204
+ async function memberOfScope(res, scope, client) {
205
+ return res.status === 401 ? null : belongsToScope(scope, await client.fetchOrgs().catch(() => null))
206
+ }
207
+
208
+ /**
209
+ * Say why the registry refused a submission: a foundation's, a schemas package's, or a library's
210
+ * registered before its foundation.
211
+ *
212
+ * ⭐ NOT A MEMBER OF THE SCOPE IS SAID AS THAT *[Diego, 2026-10-06]*. The registry decides who may
213
+ * release into a scope — its account, or an org's members — and when the orgs read says you are
214
+ * neither, that is the refusal to name. ⛔ Until then a 403 here printed "log in again", the wrong
215
+ * advice for a scope that is not yours.
216
+ *
217
+ * @param {object} o
218
+ * @param {Response} o.res
219
+ * @param {object|null} o.parsedBody
220
+ * @param {string} o.rawBody
221
+ * @param {string} o.scope
222
+ * @param {boolean|null} o.member - `memberOfScope`
223
+ * @param {string} o.what - what was refused, for the not-a-member sentence
224
+ */
225
+ function sayRefused({ res, parsedBody, rawBody, scope, member, what }) {
226
+ if (member === false) {
227
+ error(`You can't release ${what}: you're not a member of ${scope}.`)
228
+ log(
229
+ ` ${colors.dim}A member of ${scope} can release it. (The registry answered HTTP ${res.status}.)${colors.reset}`
230
+ )
231
+ } else {
232
+ error(
233
+ `Registry rejected the submission: HTTP ${res.status} ${res.statusText}`
234
+ )
235
+ }
236
+ if (member !== false && (res.status === 401 || res.status === 403)) {
237
+ log(
238
+ ` ${colors.dim}The registry didn't accept your credentials — it may use different ones than \`uniweb login\`.${colors.reset}`
239
+ )
240
+ log(
241
+ ` ${colors.dim}Log in again (uniweb login --server <url>), or check UNIWEB_TOKEN — an existing one may be wrong or expired.${colors.reset}`
242
+ )
243
+ }
244
+ // ⭐ **Surface `detail` as a sentence, not as a JSON dump.** The registry
245
+ // answers with problem+json (RFC 9457), and its `detail` is written for a
246
+ // human — it carries the actual next step, which for a rejected
247
+ // re-register is "bump the version". Printing the whole body dimmed put
248
+ // that sentence inside a blob, at the end of a 500-char truncation, in the
249
+ // one moment the reader most needs it.
250
+ //
251
+ // ⚖️ Keyed on the SHAPE, not on any particular code: a new refusal the CLI
252
+ // has never seen explains itself the day the backend ships it, with no
253
+ // release here. That is the property worth having — this branch exists
254
+ // because a 422 the CLI did not know about arrived exactly that way.
255
+ if (parsedBody?.detail) {
256
+ log(` ${parsedBody.detail}`)
257
+ const code = parsedBody.code ?? parsedBody.reason
258
+ if (code) {
259
+ log(` ${colors.dim}(${code})${colors.reset}`)
260
+ }
261
+ } else if (rawBody) {
262
+ log(` ${colors.dim}${rawBody.slice(0, 500)}${colors.reset}`)
263
+ }
264
+ }
265
+
266
+ /**
267
+ * Register the data schemas a library defines, before the foundation that names them
268
+ * (`backend/library-types.js`): the library's package whole, as `uniweb register` there sends it.
269
+ *
270
+ * ⚖️ A library of a scope the account isn't a member of can't be registered from here, and needn't
271
+ * be once its types are: the foundation is released against them as the registry holds them, which
272
+ * only that scope's members change. A library made by another org, kept in this workspace, is used
273
+ * so.
274
+ *
275
+ * @param {{ dir: string, scope: string, refs: string[] }} lib - its folder, scope, and the types the
276
+ * foundation names from it
277
+ * @param {object} o
278
+ * @param {BackendClient} o.client
279
+ * @param {object} o.exporter - the `.uwx` envelope's exporter
280
+ * @param {string} o.at - its folder as the person sees it
281
+ * @returns {Promise<{ names: string[], body: object|null }|null>} the names sent and the registry's
282
+ * answer; null when the release stops, which is said already
283
+ */
284
+ async function registerLibraryTypes(lib, { client, exporter, at }) {
285
+ let doc
286
+ try {
287
+ // The types the foundation names from it, and no other of its files: those may be another
288
+ // package's to register, or a copy of one the foundation defines (`library-types.js`).
289
+ const wanted = new Set(lib.refs.map((ref) => `@/${ref.slice(lib.scope.length + 1)}`))
290
+ const all = await collectStandaloneSchemas(lib.dir)
291
+ doc = buildSchemaOnlyPackage({
292
+ schemas: Object.fromEntries(Object.entries(all).filter(([key]) => wanted.has(key))),
293
+ scope: lib.scope,
294
+ exporter
295
+ })
296
+ } catch (err) {
297
+ error(`Could not read the data schemas in ${at}: ${err.message}`)
298
+ return null
299
+ }
300
+ const names = doc.entities.map((e) => e.name)
301
+ info(`Registering the data schemas in ${at} (${names.join(', ')}) …`)
302
+ let res
303
+ try {
304
+ res = await client.register(JSON.stringify(doc, null, 2))
305
+ } catch (err) {
306
+ error(`Could not reach the registry at ${client.origin}: ${err.message}`)
307
+ return null
308
+ }
309
+ const rawBody = await res.text().catch(() => '')
310
+ let body = null
311
+ try {
312
+ body = rawBody ? JSON.parse(rawBody) : null
313
+ } catch {
314
+ body = null
315
+ }
316
+ if (res.ok) {
317
+ const answers = Array.isArray(body?.data_schemas) ? body.data_schemas : []
318
+ if (answers.length === names.length && answers.every((a) => a?.unchanged === true)) {
319
+ log(` ${colors.dim}Unchanged: the registry holds them as they are.${colors.reset}`)
320
+ } else {
321
+ success(`Registered ${names.length} data schema(s) under ${lib.scope}, from ${at}`)
322
+ }
323
+ return { names, body }
324
+ }
325
+ const member = await memberOfScope(res, lib.scope, client)
326
+ // ⚖️ Released against what the registry holds only when the refusal is the scope's alone: no
327
+ // typed reason, which a change records can't take carries (`destructive_republish`), and an orgs
328
+ // read that says so. ⛔ Until 2026-11-10 any refusal to a non-member went on this way.
329
+ if (member === false && !(body?.code || body?.reason)) {
330
+ const held = await Promise.all(
331
+ lib.refs.map((ref) => client.readDataSchema(ref).catch(() => undefined))
332
+ )
333
+ if (held.every(Boolean)) {
334
+ const one = lib.refs.length === 1
335
+ info(
336
+ `${lib.refs.join(', ')} ${one ? 'is' : 'are'} registered under ${lib.scope}, whose members change ${one ? 'it' : 'them'}: the foundation is released against ${one ? 'it' : 'them'} as registered.`
337
+ )
338
+ return { names: [], body: null }
339
+ }
340
+ }
341
+ sayRefused({
342
+ res,
343
+ parsedBody: body,
344
+ rawBody,
345
+ scope: lib.scope,
346
+ member,
347
+ what: `data schemas under ${lib.scope}`
348
+ })
349
+ log(
350
+ ` ${colors.dim}The foundation was not submitted: the registry takes a foundation only once the types it names are registered.${colors.reset}`
351
+ )
352
+ return null
353
+ }
354
+
355
+ /**
356
+ * After a refusal, each type the foundation names that another local package defines and the
357
+ * registry doesn't hold, with the command that registers it there (`unregistered-types.js`).
358
+ */
359
+ async function sayWhatToRegisterFirst({ schema, defined, targetDir, client }) {
360
+ const missing = await unregisteredLocalTypes({
361
+ named: Object.keys(schema?.dataSchemas || {}),
362
+ defined,
363
+ foundationDir: targetDir,
364
+ client
365
+ }).catch(() => [])
366
+ if (!missing.length) return
367
+ // ⚖️ From the workspace root: `push` and `publish` run this in the foundation's folder, which is
368
+ // not where their person is.
369
+ const root = findWorkspaceRoot(targetDir) || targetDir
370
+ log('')
371
+ for (const { ref, dir } of missing) {
372
+ const at = relative(root, dir) || '.'
373
+ log(` ${ref} is defined in ${at}/, which has not registered it. Register it there first, from the workspace root:`)
374
+ log(` ${colors.blue}cd ${at} && npx uniweb register${colors.reset}`)
375
+ }
376
+ }
377
+
191
378
  /**
192
379
  * Resolve which foundation to register: the cwd if it's a foundation, else the
193
380
  * single foundation in the workspace, else prompt (or error in non-interactive).
@@ -560,8 +747,8 @@ export function foundationNeedsBuild(targetDir) {
560
747
  return {
561
748
  needs: true,
562
749
  reason: newer.library
563
- ? `a file of ${newer.library}, a library it bundles, is newer than dist/entry.js`
564
- : 'a source file is newer than dist/entry.js'
750
+ ? `${newer.library}, a library it bundles, changed since dist/entry.js was built`
751
+ : 'a source changed since dist/entry.js was built'
565
752
  }
566
753
  } catch {
567
754
  // Can't compare — leave the other signals to decide rather than forcing a
@@ -731,6 +918,26 @@ async function runRegister(args = []) {
731
918
  }
732
919
  }
733
920
 
921
+ // ⭐ The types it names that a library defines: registered from the library before the
922
+ // foundation, which the registry refuses while a type it names is missing (`library-types.js`).
923
+ let fromLibraries = []
924
+ if (!standalone) {
925
+ try {
926
+ fromLibraries = await typesFromLibraries({ schemas: schema?.dataSchemas || {}, foundationDir: targetDir })
927
+ } catch (err) {
928
+ // ⛔ Said, never silent: a build too old to tell which library defines a type registers none,
929
+ // and the registry then refuses the foundation for it.
930
+ if (err?.code === 'BUILD_TOO_OLD') {
931
+ log(
932
+ ` ${colors.yellow}⚠${colors.reset} This uniweb registers the types a library defines before the foundation, and the installed @uniweb/build is too old to tell which: ${colors.blue}npx uniweb@latest update --yes${colors.reset}`
933
+ )
934
+ }
935
+ }
936
+ }
937
+ // Where each is, said from the workspace root, which is where its person is.
938
+ const workspaceRoot = standalone ? null : findWorkspaceRoot(targetDir) || targetDir
939
+ const shownAt = (dir) => `${relative(workspaceRoot, dir) || '.'}/`
940
+
734
941
  // A schemas-only package with no scope, on a real submit → the workspace you work in,
735
942
  // else derived from your orgs (`deriveScopeFromLogin`), and persisted to package.json.
736
943
  // (A foundation's was settled before its build — `settleFoundationScope`.)
@@ -805,6 +1012,11 @@ async function runRegister(args = []) {
805
1012
  log(
806
1013
  ` ${colors.dim}data schemas ${standalone ? 'registered' : 'defined'}: ${defined.length ? defined.join(', ') : '(none)'}${colors.reset}`
807
1014
  )
1015
+ for (const lib of fromLibraries) {
1016
+ log(
1017
+ ` ${colors.dim}data schemas from ${shownAt(lib.dir)}: ${lib.refs.join(', ')} — ${isPreview ? 'would be registered' : 'registered'} from there first${colors.reset}`
1018
+ )
1019
+ }
808
1020
  if (scope)
809
1021
  log(` ${colors.dim}scope: ${scope} (${scopeSource})${colors.reset}`)
810
1022
  if (digest) log(` ${colors.dim}digest: ${digest}${colors.reset}`)
@@ -848,6 +1060,17 @@ async function runRegister(args = []) {
848
1060
  )
849
1061
  return { exitCode: 2 }
850
1062
  }
1063
+ // The libraries' types first: the registry checks a foundation's types when it takes it.
1064
+ const fromLibrariesSent = []
1065
+ for (const lib of fromLibraries) {
1066
+ const sent = await registerLibraryTypes(lib, { client, exporter, at: shownAt(lib.dir) })
1067
+ if (!sent) {
1068
+ await sayWhatToRegisterFirst({ schema, defined, targetDir, client })
1069
+ return { exitCode: 1 }
1070
+ }
1071
+ fromLibrariesSent.push(sent)
1072
+ }
1073
+
851
1074
  // Submit — the client carries the bearer (UNIWEB_TOKEN › stored
852
1075
  // session › login), resolved lazily on this first authed call.
853
1076
  info(`Submitting to ${colors.dim}${client.origin}${colors.reset} …`)
@@ -892,54 +1115,20 @@ async function runRegister(args = []) {
892
1115
  `${colors.dim}Schema for this version is already registered — resuming code delivery.${colors.reset}`
893
1116
  )
894
1117
  } else {
895
- // ⭐ NOT A MEMBER OF THE SCOPE IS SAID AS THAT *[Diego, 2026-10-06]*. The registry
896
- // decides who may release into a scope — its account, or an org's members — and
897
- // when the orgs read says you are neither, that is the refusal to name. ⛔ Until then
898
- // a 403 here printed "log in again", the wrong advice for a scope that is not yours.
899
- // Read to explain a refusal, never to gate one; a 401 is the credential itself.
900
- const member =
901
- res.status === 401 ? null : belongsToScope(scope, await client.fetchOrgs().catch(() => null))
902
- if (member === false) {
903
- const what = standalone
1118
+ const member = await memberOfScope(res, scope, client)
1119
+ sayRefused({
1120
+ res,
1121
+ parsedBody,
1122
+ rawBody,
1123
+ scope,
1124
+ member,
1125
+ what: standalone
904
1126
  ? `data schemas under ${scope}`
905
1127
  : doc.entities.find((e) => e.model === '@uniweb/foundation-schema')?.info?.name || `a foundation under ${scope}`
906
- error(`You can't release ${what}: you're not a member of ${scope}.`)
907
- log(
908
- ` ${colors.dim}A member of ${scope} can release it. (The registry answered HTTP ${res.status}.)${colors.reset}`
909
- )
910
- } else {
911
- error(
912
- `Registry rejected the submission: HTTP ${res.status} ${res.statusText}`
913
- )
914
- }
915
- if (member !== false && (res.status === 401 || res.status === 403)) {
916
- log(
917
- ` ${colors.dim}The registry didn't accept your credentials — it may use different ones than \`uniweb login\`.${colors.reset}`
918
- )
919
- log(
920
- ` ${colors.dim}Log in again (uniweb login --server <url>), or check UNIWEB_TOKEN — an existing one may be wrong or expired.${colors.reset}`
921
- )
922
- }
923
- // ⭐ **Surface `detail` as a sentence, not as a JSON dump.** The registry
924
- // answers with problem+json (RFC 9457), and its `detail` is written for a
925
- // human — it carries the actual next step, which for a rejected
926
- // re-register is "bump the version". Printing the whole body dimmed put
927
- // that sentence inside a blob, at the end of a 500-char truncation, in the
928
- // one moment the reader most needs it.
929
- //
930
- // ⚖️ Keyed on the SHAPE, not on any particular code: a new refusal the CLI
931
- // has never seen explains itself the day the backend ships it, with no
932
- // release here. That is the property worth having — this branch exists
933
- // because a 422 the CLI did not know about arrived exactly that way.
934
- if (parsedBody?.detail) {
935
- log(` ${parsedBody.detail}`)
936
- const code = parsedBody.code ?? parsedBody.reason
937
- if (code) {
938
- log(` ${colors.dim}(${code})${colors.reset}`)
939
- }
940
- } else if (rawBody) {
941
- log(` ${colors.dim}${rawBody.slice(0, 500)}${colors.reset}`)
942
- }
1128
+ })
1129
+ // ⭐ A type it names that another foundation here defines, and the registry doesn't hold:
1130
+ // that foundation registers it first (`unregistered-types.js`). A library's were sent above.
1131
+ if (!standalone && member !== false) await sayWhatToRegisterFirst({ schema, defined, targetDir, client })
943
1132
  return { exitCode: 1 }
944
1133
  }
945
1134
  }
@@ -1078,7 +1267,12 @@ async function runRegister(args = []) {
1078
1267
  parsedBody.data_schemas.forEach(addMint)
1079
1268
  if (parsedBody.foundation_schema) addMint(parsedBody.foundation_schema)
1080
1269
  }
1270
+ for (const sent of fromLibrariesSent) {
1271
+ if (Array.isArray(sent.body?.data_schemas)) sent.body.data_schemas.forEach(addMint)
1272
+ }
1081
1273
  const names = [
1274
+ // A library's types, registered first (and none for one registered by its own scope's members).
1275
+ ...fromLibrariesSent.flatMap((sent) => sent.names),
1082
1276
  ...doc.entities
1083
1277
  .filter((e) => e.model === '@uniweb/data-schema')
1084
1278
  .map((e) => e.name),
@@ -43,7 +43,7 @@
43
43
  */
44
44
 
45
45
  import { execFileSync } from 'node:child_process'
46
- import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
46
+ import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
47
47
  import { basename, dirname, join, posix, relative, resolve, sep } from 'node:path'
48
48
  import yaml from 'js-yaml'
49
49
 
@@ -1169,6 +1169,92 @@ function workspaceLine(ws) {
1169
1169
  return `${parts.slice(0, -1).join(', ')} and ${parts.at(-1)} in this workspace${from}.`
1170
1170
  }
1171
1171
 
1172
+ /**
1173
+ * ⭐ THE LIBRARY `cwd` IS IN, when it is one: a package of the workspace that is neither a site nor a
1174
+ * foundation, and that a foundation or an extension of the workspace bundles (`librariesOf`, the one
1175
+ * rule). With the foundations that bundle it and the sites each serves, which is what a change in it
1176
+ * reaches. Null for anything else, which `status` answers as before.
1177
+ */
1178
+ async function libraryAround(cwd) {
1179
+ const root = findWorkspaceRoot(cwd)
1180
+ if (!root) return null
1181
+ let dir = resolve(cwd)
1182
+ while (!existsSync(join(dir, 'package.json')) && dir !== root && dirname(dir) !== dir) dir = dirname(dir)
1183
+ if (dir === resolve(root) || !existsSync(join(dir, 'package.json'))) return null
1184
+ if (await classifyPackage(dir)) return null
1185
+ const { librariesOf } = await import('@uniweb/build')
1186
+ let real = dir
1187
+ try {
1188
+ real = realpathSync(dir)
1189
+ } catch {
1190
+ // as it is
1191
+ }
1192
+ const ws = await workspaceFacts(root)
1193
+ const bundling = [
1194
+ ...ws.foundations.map((f) => ({ ...f, extension: false })),
1195
+ ...ws.extensions.map((f) => ({ ...f, extension: true }))
1196
+ ].filter((f) => librariesOf(resolve(root, f.path)).some((lib) => lib.dir === real))
1197
+ if (!bundling.length) return null
1198
+ let name = basename(dir)
1199
+ try {
1200
+ name = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).name || name
1201
+ } catch {
1202
+ // named for its folder
1203
+ }
1204
+ const foundations = []
1205
+ for (const f of bundling) {
1206
+ const abs = resolve(root, f.path)
1207
+ const sites = []
1208
+ for (const site of ws.sites) {
1209
+ const siteDir = resolve(root, site.path)
1210
+ const yml = readSiteYml(siteDir)
1211
+ if (f.extension) {
1212
+ const exts = await extensionsOf(siteDir, yml, root)
1213
+ if (exts.some((e) => e.kind === 'local' && resolve(root, e.path) === abs)) sites.push(site.path)
1214
+ } else {
1215
+ const fnd = await foundationOf(siteDir, yml, root)
1216
+ if (fnd.kind === 'local' && fnd.abs === abs) sites.push(site.path)
1217
+ }
1218
+ }
1219
+ foundations.push({ name: f.name, path: f.path, extension: f.extension, sites })
1220
+ }
1221
+ return { root, path: relative(root, dir) || '.', name, foundations }
1222
+ }
1223
+
1224
+ /** `status` in a library: what bundles it, and so what a change in it reaches. */
1225
+ function libraryOverview(lib, { json }) {
1226
+ const { path, name, foundations } = lib
1227
+ const kinds = foundations.some((f) => f.extension) ? 'foundations and extensions' : 'foundations'
1228
+ const summary = `${name} — a library in ${path}/, bundled by ${count(foundations.length, foundations.some((f) => f.extension) ? 'package' : 'foundation')}`
1229
+ const sites = [...new Set(foundations.flatMap((f) => f.sites))]
1230
+ const reach =
1231
+ 'A change here reaches each of those sites when its foundation next builds, and a hosted site when its foundation releases again (`uniweb publish` from the site).'
1232
+ if (json) {
1233
+ console.log(
1234
+ JSON.stringify({
1235
+ schema: STATUS_SCHEMA,
1236
+ uniweb: getCliVersion(),
1237
+ scope: 'library',
1238
+ summary,
1239
+ library: { name, path },
1240
+ foundations,
1241
+ sites,
1242
+ checks: [],
1243
+ next: []
1244
+ })
1245
+ )
1246
+ return { exitCode: 0 }
1247
+ }
1248
+ const out = ['', `${c.bold}${summary}${c.reset}`, '']
1249
+ for (const f of foundations) {
1250
+ const what = `${f.extension ? 'extension' : 'foundation'} ${f.name} (${f.path}/)`
1251
+ out.push(` ${what} — ${f.sites.length ? `${f.sites.length === 1 ? 'site' : 'sites'} ${f.sites.join(', ')}` : 'no site in this workspace'}`)
1252
+ }
1253
+ out.push('', sites.length ? reach : `No site in this workspace uses those ${kinds} yet.`, '')
1254
+ console.log(out.join('\n'))
1255
+ return { exitCode: 0 }
1256
+ }
1257
+
1172
1258
  /**
1173
1259
  * A site's foundation, as the build finds it — the one resolver (`detectFoundationType`), so
1174
1260
  * what status names is what the build would build. A catalog ref, which a build refuses, is
@@ -1265,11 +1351,18 @@ async function projectChecks(siteDir, siteYml) {
1265
1351
  : `Extension \`${e.value}\` names ${e.name ? `\`${e.name}\`, which no folder here holds` : 'nothing this site can find'}.`
1266
1352
  )
1267
1353
  if (extensions.some((e) => e.kind === 'unresolved')) state = 'attention'
1354
+ // And the libraries it bundles (`librariesOf`): a change in one reaches this site too.
1355
+ let libraries = []
1356
+ if (fnd.kind === 'local') {
1357
+ const { librariesOf } = await import('@uniweb/build')
1358
+ libraries = librariesOf(fnd.abs).map((lib) => ({ name: lib.name, path: relative(root, lib.dir) || '.' }))
1359
+ }
1360
+ const libraryLines = libraries.map((lib) => `Library ${lib.name}, in ${lib.path}/ — the foundation bundles it, so a change there reaches this site too.`)
1268
1361
  checks.push({
1269
1362
  id: 'project.foundation',
1270
1363
  state,
1271
1364
  summary,
1272
- lines: extensionLines,
1365
+ lines: [...extensionLines, ...libraryLines],
1273
1366
  detail: {
1274
1367
  kind: fnd.kind,
1275
1368
  name: fnd.name ?? null,
@@ -1277,7 +1370,8 @@ async function projectChecks(siteDir, siteYml) {
1277
1370
  url: fnd.url ?? null,
1278
1371
  editable: fnd.kind === 'local',
1279
1372
  sharedWith,
1280
- extensions: extensions.map(({ value, kind, name, path }) => ({ value, kind, name: name ?? null, path: path ?? null }))
1373
+ extensions: extensions.map(({ value, kind, name, path }) => ({ value, kind, name: name ?? null, path: path ?? null })),
1374
+ libraries
1281
1375
  }
1282
1376
  })
1283
1377
 
@@ -1772,13 +1866,24 @@ export async function status(args = []) {
1772
1866
  const json = args.includes('--json')
1773
1867
  const offline = args.includes('--offline')
1774
1868
 
1869
+ // In a library, what bundles it: its foundations and their sites.
1870
+ const library = await libraryAround(process.cwd())
1871
+ if (library) return libraryOverview(library, { json })
1872
+
1775
1873
  const found = await findSite(process.cwd())
1776
1874
  if (!found.siteDir) {
1777
1875
  // ⭐ A WORKSPACE OF SEVERAL SITES IS ANSWERED, not refused: what each one is, from its
1778
1876
  // files, and the way to one site's checks.
1779
1877
  if (found.several?.length) return workspaceOverview(found.root, { json })
1780
1878
  if (json) console.log(JSON.stringify({ schema: STATUS_SCHEMA, scope: null, error: 'no-site' }))
1781
- else console.error(`${c.red}✗${c.reset} No Uniweb site here. Run status from a site, or a project with one site.`)
1879
+ else if (!findWorkspaceRoot(process.cwd()) && existsSync(join(process.cwd(), 'package.json'))) {
1880
+ // A package in no workspace's folder: a library beside the workspace, say, whose workspace
1881
+ // can't be found from here, since it is listed there and points nowhere back.
1882
+ console.error(`${c.red}✗${c.reset} No Uniweb site here, and no workspace above this folder.`)
1883
+ console.error(
1884
+ ` For a library beside a workspace, run status in that workspace: a site's status names the libraries its foundation bundles.`
1885
+ )
1886
+ } else console.error(`${c.red}✗${c.reset} No Uniweb site here. Run status from a site, or a project with one site.`)
1782
1887
  return { exitCode: 2 }
1783
1888
  }
1784
1889
  const siteDir = found.siteDir
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-11-10T05:06:45.377Z",
3
+ "generatedAt": "2026-11-10T17:25:48.202Z",
4
4
  "packages": {
5
5
  "@uniweb/api": {
6
6
  "version": "1.7.0"
7
7
  },
8
8
  "@uniweb/build": {
9
- "version": "1.20.6"
9
+ "version": "1.20.8"
10
10
  },
11
11
  "@uniweb/content-reader": {
12
12
  "version": "1.5.9"
package/src/index.js CHANGED
@@ -73,6 +73,8 @@ import {
73
73
  } from './utils/interactive.js'
74
74
  import { findWorkspaceRoot } from './utils/workspace.js'
75
75
  import { exitWhenDrained } from './utils/exit.js'
76
+ import { staleFrameworkExport, installedVersion } from './utils/stale-export.js'
77
+ import { getVersion } from './versions.js'
76
78
  import { outliveTheReader } from './utils/closed-reader.js'
77
79
  import { isGitRepo } from './utils/git.js'
78
80
 
@@ -256,6 +258,25 @@ async function importProjectCommand(modulePath) {
256
258
  try {
257
259
  return await import(modulePath)
258
260
  } catch (err) {
261
+ // A @uniweb/* package older than this CLI: an export it needs is not there (`stale-export.js`).
262
+ const stale = staleFrameworkExport(err)
263
+ if (stale) {
264
+ const have = installedVersion(stale.pkg)
265
+ // ⚖️ Older or newer than the one this CLI goes with: said as it is. ⛔ Until 2026-11-10 it
266
+ // always said "needs a newer", and a project ahead of the CLI was told its package was old.
267
+ const wanted = getVersion(stale.pkg)
268
+ const floor = /(\d+)\.(\d+)\.(\d+)/.exec(wanted || '')?.slice(1).map(Number)
269
+ const at = /(\d+)\.(\d+)\.(\d+)/.exec(have || '')?.slice(1).map(Number)
270
+ const older = floor && at ? at[0] - floor[0] || at[1] - floor[1] || at[2] - floor[2] : -1
271
+ error(
272
+ older < 0
273
+ ? `This uniweb (${getCliVersion()}) needs a newer ${stale.pkg} than the one installed${have ? ` (${have})` : ''}, which has no \`${stale.name}\`.`
274
+ : `This uniweb (${getCliVersion()}) goes with ${stale.pkg} ${wanted}, and the one installed (${have}) has no \`${stale.name}\`.`
275
+ )
276
+ log(`Bring the project's framework packages to the versions this CLI goes with:`)
277
+ log(` ${colors.cyan}npx uniweb@latest update --yes${colors.reset}`)
278
+ await exitWhenDrained(1)
279
+ }
259
280
  if (
260
281
  err.code !== 'ERR_MODULE_NOT_FOUND' ||
261
282
  !err.message?.includes('@uniweb/')
@@ -1435,10 +1456,15 @@ async function main() {
1435
1456
  const recPm = isPnpmAvailable() ? 'pnpm' : pm
1436
1457
 
1437
1458
  if (isBlank) {
1459
+ // ⛔ The install comes first. `add` loads @uniweb/build, which reaches a blank workspace only
1460
+ // with its own install: it is an optional peer of the CLI, so `npx uniweb` and a bare global
1461
+ // install hold none. Until 2026-11-10 these steps put `add project` first, and it stopped with
1462
+ // "Cannot load @uniweb/build, which this command needs" (measured on 1.30.0, 1.31.5, 1.31.6).
1438
1463
  log(`Next steps:\n`)
1439
1464
  if (!inPlace) log(` ${colors.cyan}cd ${projectName}${colors.reset}`)
1465
+ log(` ${colors.cyan}${installCmd(recPm)}${colors.reset} ${colors.dim}# the build tools \`add\` needs${colors.reset}`)
1440
1466
  log(` ${colors.cyan}${prefix} add project${colors.reset}`)
1441
- log(` ${colors.cyan}${installCmd(recPm)}${colors.reset}`)
1467
+ log(` ${colors.cyan}${installCmd(recPm)}${colors.reset} ${colors.dim}# links what you added${colors.reset}`)
1442
1468
  log(
1443
1469
  ` ${colors.cyan}${runCmd(recPm, 'dev')}${colors.reset} ${colors.dim}# start the dev server${colors.reset}`
1444
1470
  )
@@ -1810,6 +1836,7 @@ ${colors.bright}Examples:${colors.reset}
1810
1836
  uniweb add library libraries/ui --foundation a,b # Create ./libraries/ui/, shared by a and b
1811
1837
  uniweb add library libraries/ui --foundation c # Wire one more foundation to it
1812
1838
  uniweb add library shared --schemas --scope @acme # With data types named @acme/<file>
1839
+ uniweb add library ../acme-shared --foundation a # A library beside the workspace, another repo's
1813
1840
  uniweb add section Hero # Create Hero section type
1814
1841
  uniweb add section Hero --foundation ui # Target specific foundation
1815
1842
  uniweb add section Hero --starter # Starter content for an existing Hero
@@ -14,11 +14,16 @@ import { spawn } from 'node:child_process'
14
14
  import { fstatSync } from 'node:fs'
15
15
  import { whenDrained } from './exit.js'
16
16
 
17
+ // What a write says when its reader has gone: EPIPE from a pipe, and from a socket also ENOTCONN or
18
+ // ECONNRESET. ⛔ Until 2026-11-10 only EPIPE was taken for it, and a reader leaving a socket at the
19
+ // wrong moment ended `create` with "Error: write ENOTCONN" (the closed-reader test, once in six runs).
20
+ const READER_GONE = new Set(['EPIPE', 'ENOTCONN', 'ECONNRESET'])
21
+
17
22
  /** For the CLI's own process, once, before it prints. Any other write error stays an error. */
18
23
  export function outliveTheReader() {
19
24
  for (const stream of [process.stdout, process.stderr]) {
20
25
  stream.on('error', (err) => {
21
- if (err.code !== 'EPIPE') throw err
26
+ if (!READER_GONE.has(err.code)) throw err
22
27
  })
23
28
  }
24
29
  }
@@ -4,14 +4,19 @@
4
4
  * they use it (`ensureFoundationFresh`), and `register` before it uploads it
5
5
  * (`foundationNeedsBuild`). A build reads:
6
6
  * - the foundation's source root, the folder `package.json::main` names (`resolveFoundationSrcPath`:
7
- * the package itself when flat, `src/` when nested), and the files at its root that shape the
8
- * build (`package.json`, `vite.config.js`, a legacy `foundation.js` or `meta.js`);
7
+ * the package itself when flat, `src/` when nested), and what at its root shapes the build
8
+ * (`package.json`, a `vite.config.*`, a legacy `foundation.js` or `meta.js`, and `public/`,
9
+ * which Vite copies into `dist/`);
9
10
  * - every library it bundles: any local package it depends on (`librariesOf`, `@uniweb/build`),
10
11
  * wherever it is linked from.
11
12
  * Dot-folders, `node_modules`, and what a foundation's build writes into one (`dist/`, the
12
13
  * generated entry) are never sources. A library that is not a foundation keeps its `dist/`, which
13
14
  * may be what the foundation imports.
14
15
  *
16
+ * A folder counts as well as its files: adding, removing or renaming a file changes its folder's
17
+ * time and no file's, so a deleted section type or a renamed component makes the build stale too.
18
+ * ⛔ Until 2026-11-10 only files counted, and a build kept a section type whose file was gone.
19
+ *
15
20
  * Ties count as fresh: a build writes its output after it reads its input, so equal times mean a
16
21
  * build in the same millisecond, and on a fresh clone, where whole trees share a time, a tie
17
22
  * counted stale would rebuild every foundation once for nothing.
@@ -27,17 +32,23 @@ import { existsSync, readdirSync, statSync } from 'node:fs'
27
32
  import { join } from 'node:path'
28
33
  import { classifyPackage, librariesOf, resolveFoundationSrcPath } from '@uniweb/build'
29
34
 
30
- // The files at a foundation's root that shape its build, when its sources are in `src/`.
31
- const ROOT_FILES = ['package.json', 'vite.config.js', 'foundation.js', 'meta.js']
35
+ // What at a foundation's root shapes its build, when its sources are in `src/`.
36
+ const ROOT_FILES = ['package.json', 'vite.config.js', 'vite.config.mjs', 'vite.config.cjs', 'vite.config.ts', 'vite.config.mts', 'foundation.js', 'meta.js']
37
+ const ROOT_FOLDERS = ['public']
32
38
 
33
39
  // What a foundation's build writes into the foundation.
34
40
  const BUILD_OUTPUT = new Set(['dist', '_entry.generated.js'])
35
41
 
36
- /** The first file under `dir` newer than `builtAt`, or null. */
42
+ /** The first file or folder under `dir`, `dir` itself included, newer than `builtAt`, or null. */
37
43
  function newerUnder(dir, builtAt, { skipOutput }) {
38
44
  const stack = [dir]
39
45
  while (stack.length) {
40
46
  const at = stack.pop()
47
+ try {
48
+ if (statSync(at).mtimeMs > builtAt) return at
49
+ } catch {
50
+ continue
51
+ }
41
52
  let entries
42
53
  try {
43
54
  entries = readdirSync(at, { withFileTypes: true })
@@ -79,8 +90,16 @@ export function newerInput(foundationDir, builtAt) {
79
90
  // unreadable: not newer
80
91
  }
81
92
  }
82
- const own = newerUnder(resolveFoundationSrcPath(foundationDir), builtAt, { skipOutput: true })
93
+ const srcDir = resolveFoundationSrcPath(foundationDir)
94
+ const own = newerUnder(srcDir, builtAt, { skipOutput: true })
83
95
  if (own) return { file: own, library: null }
96
+ if (srcDir !== foundationDir) {
97
+ for (const f of ROOT_FOLDERS) {
98
+ const p = join(foundationDir, f)
99
+ const file = existsSync(p) ? newerUnder(p, builtAt, { skipOutput: false }) : null
100
+ if (file) return { file, library: null }
101
+ }
102
+ }
84
103
  for (const { name, dir } of librariesOf(foundationDir)) {
85
104
  const file = newerUnder(dir, builtAt, { skipOutput: classifyPackage(dir) === 'foundation' })
86
105
  if (file) return { file, library: name }
@@ -42,7 +42,8 @@ function normalizeParent(given, rootDir) {
42
42
  */
43
43
  function insideRoot(rootDir, path) {
44
44
  if (!rootDir) return { relativePath: path }
45
- const trimmed = String(path).replace(/\/+$/, '')
45
+ // Trailing slashes off, but never the whole of `/`, which would be read as no path at all.
46
+ const trimmed = String(path).replace(/(.)\/+$/, '$1')
46
47
  const rel = relative(rootDir, resolve(rootDir, trimmed))
47
48
  if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return { outsideRoot: trimmed, relativePath: null, packageName: null }
48
49
  return { relativePath: rel.split(sep).join('/') }
@@ -131,7 +132,9 @@ export function resolvePlacement(rootDir, name, opts, kind) {
131
132
  // is then taken as the package name).
132
133
  if (opts.path) {
133
134
  const parent = normalizeParent(opts.path, rootDir)
134
- if (parent.outsideRoot) return { outsideRoot: parent.given, relativePath: null, packageName: null }
135
+ // ⛔ With the name: `--path /abs/libs ui` is `/abs/libs/ui`, as it is inside the root. Until
136
+ // 2026-11-10 the name was dropped here, and `add library` wired `/abs/libs` itself.
137
+ if (parent.outsideRoot) return { outsideRoot: name ? `${parent.given}/${name}`.replace(/\/+/g, '/') : parent.given, relativePath: null, packageName: null }
135
138
  const dir = parent.relative
136
139
  if (name) {
137
140
  const last = name.split('/').filter(Boolean).pop()
@@ -143,6 +143,9 @@ export async function fetchOrgs({ apiBase, token, fetchImpl = globalThis.fetch }
143
143
  `Could not list your orgs: HTTP ${res.status} ${res.statusText}`
144
144
  )
145
145
  const data = await res.json().catch(() => null)
146
+ // ⛔ An answer that isn't the orgs read is unknown, never "a member of nothing": until 2026-11-10 a
147
+ // body that didn't parse read as no orgs, and a member's refusal as a non-member's.
148
+ if (!data || typeof data !== 'object') throw new Error('Could not list your orgs: the answer was not readable')
146
149
  return {
147
150
  account_handle: data?.account_handle ?? null,
148
151
  orgs: Array.isArray(data?.orgs) ? data.orgs : [],
@@ -0,0 +1,33 @@
1
+ /**
2
+ * ⭐ A @uniweb/* package older than this CLI: an export the CLI imports is not there. It happens
3
+ * when a project's CLI moves without its framework packages, and Node then says only which name is
4
+ * missing. ⛔ Measured 2026-11-10: uniweb 1.31.6 over @uniweb/build 1.20.5 stopped every build with
5
+ * "The requested module '@uniweb/build' does not provide an export named 'librariesOf'".
6
+ */
7
+
8
+ import { existsSync, readFileSync } from 'node:fs'
9
+ import { dirname, join } from 'node:path'
10
+ import { fileURLToPath } from 'node:url'
11
+
12
+ /**
13
+ * The framework package and the export it lacks, when `err` is that failure; else null.
14
+ *
15
+ * @param {unknown} err - what an `import()` of a command threw
16
+ * @returns {{ pkg: string, name: string }|null}
17
+ */
18
+ export function staleFrameworkExport(err) {
19
+ if (!(err instanceof SyntaxError)) return null
20
+ const m = /module '(@uniweb\/[^'/]+)[^']*' does not provide an export named '([^']+)'/.exec(err.message || '')
21
+ return m ? { pkg: m[1], name: m[2] } : null
22
+ }
23
+
24
+ /** The installed version of `pkg`, as this module resolves it, or null. */
25
+ export function installedVersion(pkg) {
26
+ try {
27
+ let dir = dirname(fileURLToPath(import.meta.resolve(pkg)))
28
+ while (!existsSync(join(dir, 'package.json')) && dirname(dir) !== dir) dir = dirname(dir)
29
+ return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version ?? null
30
+ } catch {
31
+ return null
32
+ }
33
+ }
@@ -30,8 +30,9 @@ Edit a page or a section type and the page updates as you save. With npm, use `n
30
30
  This workspace started empty. Add a foundation and a site, then run them:
31
31
 
32
32
  ```bash
33
+ pnpm install # the build tools `uniweb add` needs
33
34
  npx uniweb add project <name> # a foundation in <name>/src, a site in <name>/site
34
- pnpm install
35
+ pnpm install # links what you added
35
36
  pnpm uniweb dev # prints the address it serves the site at
36
37
  ```
37
38
  {{/if}}