uniweb 0.25.4 → 0.25.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.25.4",
+  "version": "0.25.5",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -42,12 +42,12 @@
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
     "@uniweb/core": "^0.10.1",
-    "@uniweb/semantic-parser": "^1.2.3",
+    "@uniweb/kit": "^0.12.3",
     "@uniweb/runtime": "^0.12.2",
-    "@uniweb/kit": "^0.12.3"
+    "@uniweb/semantic-parser": "^1.2.3"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.24.4",
+    "@uniweb/build": "^0.24.5",
     "@uniweb/content-reader": "^1.2.3",
     "@uniweb/semantic-parser": "^1.2.3"
   },

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

@@ -1,10 +1,10 @@
 /**
- * Bring-the-foundation-along — the freshness loop `uniweb publish` runs before
- * it makes a site live (shipping-model.md §4).
+ * Bring-the-foundation-along — the freshness loop `uniweb publish` AND `uniweb
+ * push` run before handing a site to a backend (shipping-model.md §4).
  *
  * A publish must never ship a site pointing at stale or missing foundation code
  * (the footgun: a site goes live referencing a version the catalog doesn't
- * have). So when the site references a LOCAL foundation, publish fingerprints it
+ * have). So when the site references a LOCAL foundation, the verb fingerprints it
  * and reconciles with the catalog. Three cases (§4):
  *
  *   | version not yet registered    | release it, then publish        |
@@ -20,6 +20,16 @@
  * "Release" here is literally `uniweb register` run in the foundation directory
  * — same build-if-stale → schema submit → code upload → digest the standalone
  * verb does, so there is exactly one foundation-release path.
+ *
+ * ⭐ **`push` runs it too, and for a reason publish's framing does not cover.**
+ * [Diego, 2026-08-19] — *"A published site can only reference a registered
+ * foundation … In fact, not even a push can, because we can't preview the site in
+ * the frontend in that case."* A push is the collaboration verb: a teammate opens
+ * the site in the visual app straight after, and the app can only render it against
+ * foundation code the backend can serve. So an unregistered ref is not merely a
+ * publish-time problem — it is a broken preview, which is where a teammate actually
+ * meets it. `verb` names the caller in the messages so the fix the user is told to
+ * run is the command they ran.
  */
 
 import { readFileSync } from 'node:fs'
@@ -177,7 +187,8 @@ export async function bringFoundationAlong({
   say,
   confirm,
   cliBin,
-  dryRun = false
+  dryRun = false,
+  verb = 'publish'
 }) {
   const local = resolveLocalFoundation(siteDir, siteYml)
   if (!local) {
@@ -194,7 +205,8 @@ export async function bringFoundationAlong({
     say,
     confirm,
     cliBin,
-    dryRun
+    dryRun,
+    verb
   })
 }
 
@@ -216,7 +228,8 @@ async function bringLocalCodeAlong({
   say,
   confirm,
   cliBin,
-  dryRun = false
+  dryRun = false,
+  verb = 'publish'
 }) {
   const Kind = kind === 'extension' ? 'Extension ' : 'Foundation'
   const label =
@@ -243,7 +256,18 @@ async function bringLocalCodeAlong({
     say.dim(
       `${Kind}  : ${label} — local; would release if changed or not yet registered`
     )
-    return { released: false, proceed: true, ref: null }
+    // The ref still comes back where one can be formed: it is read from the
+    // foundation's own package.json, so it costs no network, and an offline preview
+    // that omitted it would emit a document the real run would not — the one thing
+    // `-o` exists to avoid.
+    //
+    // ⚠️ It is null for a foundation that has NEVER been registered and carries no
+    // scope (a freshly scaffolded `name: "src"`), because the scope is what
+    // `register` writes back (`writePkgScope`). So the preview shows the authored
+    // value there, and the first real push — which releases, and so acquires the
+    // scope — sends the pinned ref instead. That gap is unavoidable offline: before
+    // the first release there is no registered name to name.
+    return { released: false, proceed: true, ref: pinnedRef() }
   }
 
   // Ask the catalog what it has. Null → not registered (or the backend can't
@@ -294,7 +318,7 @@ async function bringLocalCodeAlong({
     )
     if (skipPrompts || isNonInteractive(args)) {
       say.dim(
-        'Proceeding without re-releasing — pass nothing to re-deliver, or bump the version to publish a change.'
+        'Proceeding without re-releasing — pass nothing to re-deliver, or bump the version to release a change.'
       )
       return { released: false, proceed: true, ref: pinnedRef() }
     }
@@ -318,19 +342,19 @@ async function bringLocalCodeAlong({
     `Your local ${label} differs from the registered version ${reg.latest_version}, but the version wasn't bumped.`
   )
   say.dim(
-    `A registered version is immutable. Bump the ${kind}'s version to release the change, then re-run \`uniweb publish\`.`
+    `A registered version is immutable. Bump the ${kind}'s version to release the change, then re-run \`uniweb ${verb}\`.`
   )
   if (skipPrompts || isNonInteractive(args)) {
     say.dim(`Proceeding with the already-registered ${reg.latest_version}.`)
     return { released: false, proceed: true, ref: pinnedRef() }
   }
   const proceed = await confirm(
-    `Publish with the already-registered ${reg.latest_version} anyway?`,
+    `Continue with the already-registered ${reg.latest_version} anyway?`,
     false
   )
   if (!proceed) {
     say.info(
-      `Aborted — bump the ${kind} version, then re-run \`uniweb publish\`.`
+      `Aborted — bump the ${kind} version, then re-run \`uniweb ${verb}\`.`
     )
     return { released: false, proceed: false, ref: null }
   }

package/src/commands/publish.js

@@ -46,7 +46,6 @@ import { existsSync, readFileSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { execSync } from 'node:child_process'
-import { createInterface } from 'node:readline/promises'
 import yaml from 'js-yaml'
 
 import {
@@ -66,7 +65,7 @@ import { resolveSiteDir, resolveSiteBackend } from './deploy.js'
 import { warnIfContentDoesNotConform } from '../utils/conformance.js'
 import { readFlagValue, readOrgFlag } from '../utils/args.js'
 import { checkFlags } from '../utils/flag-guard.js'
-import { isNonInteractive } from '../utils/interactive.js'
+import { isNonInteractive, confirm } from '../utils/interactive.js'
 import { headProvenance } from '../utils/git.js'
 import {
   makeModelResolver,
@@ -106,22 +105,6 @@ const say = {
   dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`)
 }
 
-// Minimal yes/no prompt. Returns `defaultYes` on an empty answer.
-async function confirm(question, defaultYes = false) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout })
-  try {
-    const a = (
-      await rl.question(`${question} ${defaultYes ? '[Y/n]' : '[y/N]'} `)
-    )
-      .trim()
-      .toLowerCase()
-    if (!a) return defaultYes
-    return a === 'y' || a === 'yes'
-  } finally {
-    rl.close()
-  }
-}
-
 // Origin-relative serve path → clickable absolute URL (self-serve default).
 function absolutizeServeUrl(origin, url) {
   if (!url || typeof url !== 'string') return null

package/src/commands/pull.js

@@ -692,10 +692,47 @@ export async function pull(args = [], deps = {}) {
         }
       }
 
+      // ⛔ Do NOT overwrite a workspace project's `site.yml::foundation`.
+      //
+      // Same principle as restoring authored asset paths above, and the same
+      // failure it prevents: a round trip must not mangle what the author wrote.
+      // `publish` stamps the RELEASED, version-pinned ref into `info.foundation`
+      // (delivery is version-pinned end to end), so projecting the stored value
+      // back turns `foundation: src` into `@org/x@1.2.3` — which the build then
+      // REFUSES to resolve, leaving the project unable to `build`, `dev` or
+      // `export`. It stays publishable throughout, so nothing surfaces it.
+      //
+      // ⚖️ Only suppressed when the AUTHORED value resolves to a local foundation.
+      // A project from `uniweb clone` has no local foundation on disk, and there
+      // the pinned ref is exactly what site.yml should say — so this is a
+      // question about which project shape we are writing into, not a blanket
+      // "never project it".
+      //
+      // Lazily imported: the resolver lives behind `@uniweb/build`'s root, which
+      // pulls the vite chain, and this file deliberately imports only the `uwx`
+      // leaf. Reused rather than reimplemented so "which foundation" cannot drift
+      // from what the build itself resolves.
+      let keepAuthoredFoundation = false
+      try {
+        const { resolveLocalFoundation } = await import(
+          '../backend/foundation-bring-along.js'
+        )
+        const authored = yaml.load(
+          readFileSync(join(siteDir, 'site.yml'), 'utf8')
+        )
+        keepAuthoredFoundation = Boolean(
+          resolveLocalFoundation(siteDir, authored)
+        )
+      } catch {
+        // No site.yml, unreadable, or nothing local — project the stored value,
+        // which is the pre-existing behaviour and right for a fresh clone.
+      }
+
       const report = siteContentDocumentToProject({
         document: siteDoc,
         siteRoot: siteDir,
-        prune
+        prune,
+        keepAuthoredFoundation
       })
       wrote.push(...report.pages, ...report.sections, ...report.layout)
       removed.push(

package/src/commands/push.js

@@ -60,8 +60,9 @@
  * the emit, and the `-o`/`--dry-run` preview.
  */
 
-import { writeFileSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import yaml from 'js-yaml'
 import { emitSyncPackages } from '@uniweb/build/uwx'
 import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
 import { updateAssetMap, ASSET_MAP_FILE } from '@uniweb/build/uwx'
@@ -71,6 +72,8 @@ import { warnIfContentDoesNotConform } from '../utils/conformance.js'
 import { reportSchemalessCollections } from '../utils/schemaless-report.js'
 import { readOrgFlag } from '../utils/args.js'
 import { checkFlags } from '../utils/flag-guard.js'
+import { confirm } from '../utils/interactive.js'
+import { bringFoundationAlong } from '../backend/foundation-bring-along.js'
 import {
   makeModelResolver,
   readSyncCache,
@@ -179,6 +182,61 @@ export async function push(args = [], deps = {}) {
   }
   const asOrg = org.asOrg
 
+  // Bring the foundation along — BEFORE any asset upload, because an upload is
+  // chargeable and a push that aborts after one has spent the user's money for
+  // nothing.
+  //
+  // ⭐ Why push and not just publish. [Diego, 2026-08-19] — *"A published site can
+  // only reference a registered foundation … In fact, not even a push can, because
+  // we can't preview the site in the frontend in that case."* Push is the
+  // collaboration verb: a teammate opens the site in the visual app right after,
+  // and the app can only render against foundation code the backend can serve. So
+  // storing an unregistered ref does not merely defer a problem to publish — it
+  // hands the teammate a site that cannot render, which is where they meet it.
+  //
+  // `fnd.ref` is the pinned `@scope/name@version`, stamped onto the wire below.
+  // That also makes push and publish agree about the document they emit; until now
+  // push sent the authored string and publish sent the pinned ref, so the two saw
+  // each other's pushes as changes.
+  const siteYml = (() => {
+    try {
+      return yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8')) || {}
+    } catch {
+      return {}
+    }
+  })()
+  const say = {
+    ok: success,
+    info,
+    warn,
+    err: error,
+    dim: note
+  }
+  let fnd = { ref: null }
+  try {
+    fnd = await bringFoundationAlong({
+      client,
+      siteDir,
+      siteYml,
+      args,
+      say,
+      confirm,
+      cliBin: process.argv[1],
+      // An offline emit reports what it WOULD do and touches no network; the ref
+      // still comes back (read from the foundation's package.json) so the preview
+      // matches what a real push sends — EXCEPT for a foundation never yet
+      // registered, which has no scope to form a ref from until the first release
+      // writes one. See the dry-run branch in foundation-bring-along.js.
+      dryRun: !!output || dryRun,
+      verb: 'push'
+    })
+  } catch (err) {
+    error(`Foundation release failed: ${err.message}`)
+    note('Fix the foundation, then re-run `uniweb push`.')
+    return { exitCode: 1 }
+  }
+  if (!fnd.proceed) return { exitCode: 1 }
+
   // Build BOTH directional packages (the producer side). Each carries its own
   // `index` — the per-entity source-file map for back-fill, correlated by submission
   // position. Non-local Models are fetched from the registry on demand. `priorHashes`
@@ -346,6 +404,12 @@ export async function push(args = [], deps = {}) {
       priorHashes,
       sendAll,
       itemUuids,
+      // The PINNED foundation ref from the bring-along above, stamped over the
+      // authored `site.yml` string. Delivery is version-pinned end to end, so an
+      // unpinned local name on the wire names code no host can serve. Absent when
+      // the site already references a registry ref or URL — then site.yml's own
+      // value rides verbatim.
+      ...(fnd.ref ? { injectInfo: { foundation: fnd.ref } } : {}),
       // Both grains are dropped together by --force: one flag, one meaning,
       // no partial-force mode.
       ...(force

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-19T03:59:24.190Z",
+  "generatedAt": "2026-08-19T04:22:45.477Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.24.4",
+      "version": "0.24.5",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",

package/src/utils/flag-guard.js

@@ -58,7 +58,12 @@ const VERBS = {
     '--foundation', '--output', '-o', '--personal', '--registry', '--token',
     // read in utils/conformance.js and backend/site-sync.js respectively —
     // neither appears in push.js
-    '--no-validate', '--yes', ...VIA_DEPLOY
+    '--no-validate', '--yes',
+    // via backend/foundation-bring-along.js, which push runs since 2026-08-19 —
+    // one of the three flags that skip its prompts. Found by
+    // flag-guard-coverage.test.js the moment push gained the import, which is
+    // exactly the hand-enumeration failure that test exists to catch.
+    '--no-verify', ...VIA_DEPLOY
   ],
   publish: [
     '--as-org', '--org', '--backend', '--dry-run', '--force', '--foundation',

package/src/utils/interactive.js

@@ -18,6 +18,33 @@ export function isNonInteractive(args) {
   return false
 }
 
+/**
+ * Minimal yes/no prompt. Returns `defaultYes` on an empty answer.
+ *
+ * Shared rather than per-command: every verb that can stop and ask needs one, and
+ * three hand-rolled copies would eventually disagree about what a bare Enter means
+ * — which is the answer the user gives most often and thinks about least.
+ *
+ * ⛔ Callers must decide NOT to ask before calling: this always reads stdin, and a
+ * prompt in a non-interactive run hangs a pipeline. Gate on `isNonInteractive(args)`
+ * (and on any --yes/--force style skip the verb defines).
+ */
+export async function confirm(question, defaultYes = false) {
+  const { createInterface } = await import('node:readline/promises')
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    const a = (
+      await rl.question(`${question} ${defaultYes ? '[Y/n]' : '[y/N]'} `)
+    )
+      .trim()
+      .toLowerCase()
+    if (!a) return defaultYes
+    return a === 'y' || a === 'yes'
+  } finally {
+    rl.close()
+  }
+}
+
 /**
  * Get the CLI invocation prefix to use in suggested commands.
  * Mirrors however the user actually ran the CLI.