uniweb 0.61.0 → 0.63.0

package/src/utils/args.js

@@ -21,25 +21,17 @@
  * @returns {string | null | undefined}
  */
 /**
- * The org a site is created under. `--org` is the documented spelling; `--as-org`
- * is a working alias.
+ * The workspace a site command names — `--org @acme` — and, on a site's first push or
+ * publish, the org it is created under.
  *
- * `--as-org` mirrors the wire (`?as_org=`) and names an *acting capacity* — the
- * request is made as a member of that org, membership-gated. That is accurate, and
- * it is also not the name anyone reaches for: asked in one day, the backend's docs
- * said `--as-unit` and a second reader said `--org`; nobody produced `--as-org`.
- * Since the flag's main job is answering *who owns this site*, `--org` is the name
- * that matches the question, and the alias costs one `||` (the same shape
- * `--backend` already uses).
- *
- * `||`, not `??`, on purpose: a valueless `--org` falls through to `--as-org`
- * rather than shadowing it.
+ * ⛔ `--as-org` is RETIRED (2026-09-23). It mirrored the wire's `?as_org=`, which the
+ * `x-uniweb-workspace` header replaced; `flag-guard.js` refuses it and names `--org`.
  *
  * @param {string[]} args
  * @returns {string|null|undefined}
  */
 export function readOrgFlag(args) {
-  return readFlagValue(args, '--org') || readFlagValue(args, '--as-org')
+  return readFlagValue(args, '--org')
 }
 
 /**
@@ -97,7 +89,7 @@ function editDistance(a, b) {
 
 /**
  * The closest known flag to `flag`, or null when nothing is close enough.
- * The threshold scales with length so `--org` → `--as-org` is offered while two
+ * The threshold scales with length so `--forcee` → `--force` is offered while two
  * unrelated short flags are not.
  * @param {string} flag
  * @param {string[]} known

package/src/utils/flag-guard.js

@@ -50,12 +50,11 @@ const VIA_DEPLOY = ['--target', '--host', '--no-save']
 /**
  * Per-verb flag sets. Derived by scanning each command for dash-literals AND the
  * helpers it calls — not from the help text, which has drifted from the parser in
- * both directions (`--as-org` was implemented and undocumented; `--yes` is
- * documented on `publish` and consumed two files away).
+ * both directions (`--yes` is documented on `publish` and consumed two files away).
  */
 const VERBS = {
   push: [
-    '--all', '--as-org', '--org', '--dry-run', '--force',
+    '--all', '--org', '--dry-run', '--force',
     '--foundation', '--output', '-o', '--personal',
     // read in utils/conformance.js and backend/site-sync.js respectively —
     // neither appears in push.js
@@ -69,7 +68,7 @@ const VERBS = {
     '--no-release', ...VIA_DEPLOY
   ],
   publish: [
-    '--as-org', '--org', '--dry-run', '--force', '--foundation',
+    '--org', '--dry-run', '--force', '--foundation',
     '--personal',
     // read in utils/conformance.js, backend/site-sync.js, and
     // backend/foundation-bring-along.js — none appear in publish.js
@@ -80,15 +79,15 @@ const VERBS = {
     '--no-assets',
     '--no-records', '--no-delete', '--no-prune',
     // via backend/site-sync.js (the owner resolver) and utils/conformance.js
-    '--yes', '--org', '--as-org', '--no-validate', ...VIA_DEPLOY
+    '--yes', '--org', '--no-validate', ...VIA_DEPLOY
   ],
   clone: [
     '--content-only', '--no-assets', '--no-records', '--path',
-    '--project', '--org', '--as-org'
+    '--project', '--org'
   ],
   register: [
     '--dry-run', '--json', '--output', '-o',
-    '--schema-only', '--scope', '--org', '--as-org'
+    '--schema-only', '--scope', '--org'
   ],
   /**
    * `forget` = remove one backend's records (`--backend <url>`), or everything a
@@ -99,7 +98,7 @@ const VERBS = {
   forget: ['--backend', '--all'],
   status: [
     '--json', '--remote', '--dry-run',
-    '--force', '--no-verify', '--no-validate', '--yes', '--org', '--as-org',
+    '--force', '--no-verify', '--no-validate', '--yes', '--org',
     // inert here, reachable through the bring-along module status imports for
     // `resolveLocalFoundation` — listed per the over-approximation note above
     '--no-release', ...VIA_DEPLOY
@@ -119,7 +118,7 @@ const VERBS = {
    */
   refresh: [
     '--no-backend', '--no-git',
-    '--as-org', '--org', '--dry-run', '--no-validate', '--yes', ...VIA_DEPLOY
+    '--org', '--dry-run', '--no-validate', '--yes', ...VIA_DEPLOY
   ]
 }
 
@@ -213,6 +212,15 @@ export function checkFlags(verb, args = []) {
       ].join('\n')
     }
   }
+  // ⭐ `--as-org` is RETIRED (2026-09-23) with the `?as_org=` it mirrored — the request
+  // names its workspace in a header now, and `--org` is the one spelling.
+  if (flag === '--as-org' && all.includes('--org')) {
+    return {
+      flag,
+      suggestion: '--org',
+      message: `\`--as-org\` is retired — use \`--org @org\` (e.g. \`uniweb ${verb} --org @acme\`).`
+    }
+  }
   const suggestion = didYouMean(flag, all)
   const lines = [`Unknown flag \`${flag}\` for \`uniweb ${verb}\`.`]
   if (suggestion) lines.push(`  Did you mean \`${suggestion}\`?`)

package/src/utils/foundation-name.js

@@ -0,0 +1,179 @@
+/**
+ * Giving a foundation its name — `name` in `main.js`'s default export.
+ *
+ * The rule itself (main.js `name`, else package.json `name`; `src` and `foundation`
+ * refused) is `@uniweb/build`'s `foundation-name.js`, shared by the build, `register`
+ * and `push`. This module only WRITES the name: the scaffold at `create` / `add`, and
+ * `register` when it asks for one.
+ *
+ * ⛔ NO `@uniweb/build` IMPORT, AND NO IMPORT OF main.js. `uniweb create` runs before
+ * any project exists: `@uniweb/build` is an optional peer that may not be installed,
+ * and main.js's own imports may not be either. Hence text scans rather than a load,
+ * and the one duplicated fact below, pinned to the build's list by
+ * `test/foundation-name.test.js`. What a foundation IS named is always read by the
+ * build (`readFoundationName`); these only decide where to write.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve, basename, dirname } from 'node:path'
+
+// The folders a foundation's code lives in — never a foundation's name
+// (`@uniweb/build`'s FORBIDDEN_FOUNDATION_NAMES; the test keeps them equal).
+export const SCAFFOLD_FOLDER_NAMES = new Set(['src', 'foundation'])
+
+// Written above the name wherever the CLI adds one — the scaffold's main.js
+// template says the same.
+const NAME_COMMENT = '// What this foundation registers as — @<org>/<name> — and what sites pin.'
+
+/**
+ * A name made from free text — a project's name, a folder's — in the form a
+ * foundation name takes: lowercase letters, digits and inner hyphens.
+ * `My Site` → `my-site`. Null when nothing usable is left, or when what is left
+ * names a folder rather than a foundation.
+ *
+ * @param {unknown} raw
+ * @returns {string|null}
+ */
+export function normalizeFoundationName(raw) {
+  const name = String(raw ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/^@[^/]*\//, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return name && !SCAFFOLD_FOLDER_NAMES.has(name) ? name : null
+}
+
+/**
+ * A name to offer a foundation that has none of its own: its folder's — or, for
+ * the `src/` and `foundation/` a scaffold makes, its project's folder. Null when
+ * neither makes one.
+ *
+ * @param {string} foundationDir
+ * @returns {string|null}
+ */
+export function suggestFoundationName(foundationDir) {
+  const dir = resolve(foundationDir)
+  return (
+    normalizeFoundationName(basename(dir)) ||
+    normalizeFoundationName(basename(dirname(dir)))
+  )
+}
+
+/**
+ * Whether `main.js`'s default export names the foundation — a `name` key at the
+ * export's own level, not one nested in `props` or `vars`.
+ *
+ * A scan, not a parse (see the module note): it skips strings and comments and
+ * counts brackets, which is all an object literal of declarations needs. A name
+ * that arrives by a spread is invisible to it — the build's read is the truth.
+ *
+ * @param {string} text - main.js source
+ * @returns {boolean}
+ */
+export function mainNamesFoundation(text) {
+  const opening = /export\s+default\s*\{/.exec(text)
+  if (!opening) return false
+  let depth = 1
+  let atKey = true // just after the opening brace, or a comma at the top level
+  for (let i = opening.index + opening[0].length; i < text.length && depth > 0; i++) {
+    const c = text[i]
+    if (c === '/' && text[i + 1] === '/') {
+      i = text.indexOf('\n', i)
+      if (i < 0) break
+    } else if (c === '/' && text[i + 1] === '*') {
+      i = text.indexOf('*/', i + 2) + 1
+      if (i <= 0) break
+    } else if (c === "'" || c === '"' || c === '`') {
+      let j = i + 1
+      while (j < text.length && text[j] !== c) j += text[j] === '\\' ? 2 : 1
+      if (depth === 1 && atKey && text.slice(i + 1, j) === 'name' && /^\s*:/.test(text.slice(j + 1))) {
+        return true
+      }
+      i = j
+      atKey = false
+    } else if ('{[('.includes(c)) {
+      depth++
+      atKey = false
+    } else if ('}])'.includes(c)) {
+      depth--
+    } else if (depth === 1 && c === ',') {
+      atKey = true
+    } else if (depth === 1 && atKey && /[A-Za-z_$]/.test(c)) {
+      const word = /^[A-Za-z_$][\w$]*/.exec(text.slice(i))[0]
+      // `name: 'x'`, or the shorthand `{ name }`
+      if (word === 'name' && /^\s*[:,}]/.test(text.slice(i + word.length))) return true
+      i += word.length - 1
+      atKey = false
+    } else if (!/\s/.test(c)) {
+      atKey = false
+    }
+  }
+  return false
+}
+
+/**
+ * Write `name` into a foundation's `main.js`.
+ *
+ * With `replace`, the one `name: '<replace>'` literal is rewritten — the case where
+ * main.js already names the foundation, with a name that cannot register. Without
+ * it, `name` becomes the default export's first key. A missing main.js is created.
+ *
+ * ⚠️ A text edit, not a parse: it handles `export default { … }` — every scaffold
+ * and every template — and says so otherwise rather than guessing.
+ *
+ * @param {string} mainFile
+ * @param {string} name - already a valid foundation name
+ * @param {{ replace?: string|null }} [opts]
+ * @returns {{ ok: true } | { ok: false, reason: string }}
+ */
+export function writeFoundationName(mainFile, name, { replace = null } = {}) {
+  const line = `${NAME_COMMENT}\n  name: '${name}',`
+  if (!existsSync(mainFile)) {
+    writeFileSync(mainFile, `export default {\n  ${line}\n}\n`)
+    return { ok: true }
+  }
+  const text = readFileSync(mainFile, 'utf8')
+
+  if (replace !== null) {
+    const literal = new RegExp(
+      `(\\bname\\s*:\\s*)(['"\`])${replace.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\2`,
+      'g'
+    )
+    const hits = text.match(literal) || []
+    if (hits.length !== 1) {
+      return {
+        ok: false,
+        reason: `main.js does not name the foundation "${replace}" in exactly one place`
+      }
+    }
+    writeFileSync(mainFile, text.replace(literal, `$1'${name}'`))
+    return { ok: true }
+  }
+
+  const opening = /export\s+default\s*\{/.exec(text)
+  if (!opening) {
+    return { ok: false, reason: 'main.js has no `export default { … }` to add a name to' }
+  }
+  // The name leads the export — on lines of its own, so a multi-line export keeps
+  // its first line and gains a blank one between.
+  const at = opening.index + opening[0].length
+  writeFileSync(mainFile, `${text.slice(0, at)}\n  ${line}\n${text.slice(at)}`)
+  return { ok: true }
+}
+
+/**
+ * Give a freshly scaffolded foundation its name, unless its main.js already has one.
+ *
+ * Called after template content is applied, because a template's own main.js
+ * replaces the scaffolded one — and with it the name the scaffold wrote.
+ *
+ * @param {string} foundationDir - the scaffolded package (flat layout: main.js at its root)
+ * @param {string|null} name
+ */
+export function ensureFoundationName(foundationDir, name) {
+  if (!name) return
+  const mainFile = join(foundationDir, 'main.js')
+  if (existsSync(mainFile) && mainNamesFoundation(readFileSync(mainFile, 'utf8'))) return
+  writeFoundationName(mainFile, name)
+}

package/src/utils/git.js

@@ -37,12 +37,15 @@ export function siteContentRoots(siteDir) {
   // root added below already covered it and the bare `'collections.yml'` entry
   // that used to sit in this list resolved to a path no site ever had. A
   // root-level file has no directory entry standing in for it.
+  //
+  // The records folder's `folder.yml` is the reverse case: it lives in the records
+  // directory, which is a root below, so it needs no entry. (It was `records.yml` at
+  // the site root until 2026-09-21, and was listed here then.)
   const roots = new Set([
     'site.yml',
     'theme.yml',
     'head.html',
     'queries.yml',
-    'records.yml',
     'locales'
   ])
   let paths = {}

package/src/utils/registry-orgs.js

@@ -61,8 +61,9 @@ export function bareHandle(scope) {
 
 /**
  * A publish scope in the one form the registry names things by — `@acme` — from any
- * spelling `--scope` or `package.json::uniweb.scope` may carry it in (`@acme`, `acme`,
- * `@acme/…`). Null when there is no handle in it.
+ * spelling `--scope` or a schemas-only package's `package.json::uniweb.scope` may carry
+ * it in (`@acme`, `acme`, `@acme/…`). Null when there is no handle in it. (A
+ * foundation's scope is part of its name, `@acme/marketing`, and needs no reading.)
  *
  * ⛔ Every name built from a scope goes through this. The `.uwx` assembly
  * (`@uniweb/build`'s `buildRegistryPackage`) has always accepted `acme` as well as

package/src/utils/scaffold.js

@@ -76,14 +76,16 @@ export async function getWorkspaceTemplateOutputs({ blank = false } = {}) {
 }
 
 /**
- * Scaffold a foundation from the foundation package template
+ * Scaffold a foundation from the foundation package template.
  *
- * @param {string} targetDir - Target directory for the foundation
+ * @param {string} targetDir
  * @param {Object} context - Template context
- * @param {string} context.name - Package name
+ * @param {string} context.name - Package name — workspace plumbing (`src`, `docs-src`)
+ * @param {string} [context.registryName] - The foundation's own name, written to
+ *   main.js's `name`: what it registers as (`@org/<name>`). Omitted when none can be
+ *   made, and `uniweb register` asks for one
  * @param {string} context.projectName - Workspace name
- * @param {boolean} [context.isExtension] - Whether this is an extension
- * @param {Object} [options] - Processing options
+ * @param {boolean} [context.isExtension]
  */
 export async function scaffoldFoundation(targetDir, context, options = {}) {
   registerVersions(getVersionsForTemplates())

package/src/utils/site-data-upload.js

@@ -51,6 +51,7 @@
  * demonstrated.**
  */
 
+import { WORKSPACE_HEADER } from '../backend/client.js'
 import { createHash } from 'node:crypto'
 import { humanBytes } from './bytes.js'
 import { fetchWithRetry, isTransientStatus } from './fetch-retry.js'
@@ -62,6 +63,9 @@ import { fetchWithRetry, isTransientStatus } from './fetch-retry.js'
  * @param {string} opts.apiBase - backend origin
  * @param {string} opts.token - bearer, used on the direct arm only
  * @param {string} opts.siteUuid - the site these files belong to (path segment)
+ * @param {string|null} [opts.workspace] - the workspace the requests name, `@handle`
+ *   (`x-uniweb-workspace`) — on the plan and on every DIRECT PUT, never on a presigned
+ *   one, which is self-authorizing and must carry nothing it was not signed with
  * @param {{ data: Record<string, unknown> }|null} opts.ball - source of the set:
  *   `{ "<relpath under dist/data>": <json> }`, media refs already rewritten
  * @param {(m: string) => void} [opts.onProgress]
@@ -72,9 +76,13 @@ export async function uploadSiteData({
   apiBase,
   token,
   siteUuid,
+  workspace = null,
   ball,
   onProgress = () => {}
 }) {
+  // A plan made with the header mints BARE PUT urls: the PUT names its workspace with
+  // the header like every other request (backend, 2026-09-23).
+  const workspaceHeader = workspace ? { [WORKSPACE_HEADER]: workspace } : {}
   // ⛔ An EMPTY set still posts a plan, and that is the whole point of this lane
   // being a manifest rather than a stream of files.
   //
@@ -131,7 +139,8 @@ export async function uploadSiteData({
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
-        Authorization: `Bearer ${token}`
+        Authorization: `Bearer ${token}`,
+        ...workspaceHeader
       },
       body: JSON.stringify({
         files: files.map(({ path, content_type, size, sha256 }) => ({
@@ -172,7 +181,9 @@ export async function uploadSiteData({
   // PUT is a bearer-authed backend route; a presigned URL is self-authorizing
   // and must NOT carry a foreign bearer, which can break signature validation.
   const authHeaders =
-    plan.mode === 'presigned' ? {} : { Authorization: `Bearer ${token}` }
+    plan.mode === 'presigned'
+      ? {}
+      : { Authorization: `Bearer ${token}`, ...workspaceHeader }
 
   const uploaded = []
   const failed = []

package/starter/foundation/main.js

@@ -6,7 +6,8 @@
  * - defaultLayout: Name of the default layout from src/layouts/ (optional)
  * - props: Foundation-wide props accessible via website.foundationProps
  *
- * Identity (name, version, description) comes from package.json.
+ * Name: `name` in the default export is what this foundation registers as
+ * (@org/<name>) — `uniweb create` adds it. The version comes from package.json.
  */
 
 // Create a layout at src/layouts/MyLayout/index.jsx

package/templates/foundation/main.js.hbs

@@ -14,10 +14,19 @@
 
 {{#if isExtension}}
 export default {
+{{#if registryName}}
+  name: '{{registryName}}',
+{{/if}}
   extension: true,
 }
 {{else}}
 export default {
+{{#if registryName}}
+  // ─── Name ───────────────────────────────────────────────────────────────────
+  // What this foundation registers as — @<org>/<name> — and what sites pin.
+  name: '{{registryName}}',
+
+{{/if}}
   // ─── Layout ─────────────────────────────────────────────────────────────────
   // Create layouts in layouts/MyLayout/index.jsx (auto-discovered).
   // defaultLayout: 'MyLayout',

package/templates/site/site.yml.hbs

@@ -46,8 +46,9 @@ index: home
 #                          records/article/        → @/article  (your foundation's)
 #                          records/std/person/     → @std/person
 #                        A file whose name starts with `_` is not a record.
-#   records.yml          OPTIONAL — sorts records into folders a query can slice
-#                        with `scope:`. Most sites have none:
+#   records/folder.yml   OPTIONAL — sorts records into folders a query can slice
+#                        with `scope:`. The one file in records/ that is not a
+#                        record. Most sites have none:
 #                            - folder: archive
 #                              records:
 #                                - article/2025-*.md