uniweb 0.17.0 → 0.18.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -43,12 +43,12 @@
     "tar": "^7.0.0",
     "@uniweb/kit": "^0.11.3",
     "@uniweb/core": "^0.8.5",
-    "@uniweb/runtime": "^0.11.6"
+    "@uniweb/runtime": "^0.11.7"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.18.5",
+    "@uniweb/content-reader": "^1.2.2",
     "@uniweb/semantic-parser": "^1.2.2",
-    "@uniweb/content-reader": "^1.2.2"
+    "@uniweb/build": "^0.18.5"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -1906,6 +1906,7 @@ uniweb add ci --target foundation # Publish a foundation for free at permanent v
                                   # (GitHub Pages → foundations/<name>/<version>/entry.js)
 
 uniweb push / pull / clone / status   # Git-style content sync with the Uniweb backend
+uniweb push --org @acme               # First push/publish of a site: who owns it (see below)
 uniweb register [--scope @org]        # Register a foundation + its data schemas to the registry
 uniweb login / logout                 # Start or clear the backend session the verbs above reuse
 uniweb org list / create <handle>     # Publish orgs you belong to — the @org in a scoped ref
@@ -1947,6 +1948,26 @@ Foundations have their own free path too: `uniweb add ci --target foundation` pu
 
 **Content authors work visually in the Uniweb App.** They compose the same extended markdown and set the same component params you defined, through a visual editor — never touching code, git, or the CLI. They see exactly the section types your foundation offers and exactly the knobs each one exposes, because **every `meta.js` is registered as the foundation's schema** when you publish. Your `meta.js` is the app's UI (see *meta.js* in Part 4).
 
+> ⚠️ **The FIRST push or publish of a site asks who owns it — and refuses if it cannot ask.**
+> That create decides which organization owns the site (and whose storage its assets are billed
+> to), it is the only moment the choice is made, and there is no CLI command to change it
+> afterwards. At a terminal you get a picker. **Without a terminal — CI, a script, or you, an
+> agent — the command exits non-zero instead of choosing**, and `--yes` refuses too, because
+> guessing an owner is not an answer. Name it and it never asks again:
+>
+> ```bash
+> uniweb publish --org @acme     # an organization
+> uniweb publish --personal      # your personal account, deliberately
+> ```
+>
+> The answer is recorded in `site.yml::$org` and committed, so it is a one-time choice per site,
+> not per machine. **Ask the human which one to use** rather than picking for them — a site in
+> the wrong org cannot be moved from here. Sites that already exist are unaffected: their
+> ownership is settled, so nothing is asked.
+>
+> Relatedly: these commands now **reject flags they do not recognize** instead of ignoring them.
+> If you get `Unknown flag`, read the suggestion — it is usually a near miss.
+
 **Sync is developer-only and one-sided by design.** `uniweb push` and `uniweb pull` are your commands, not theirs:
 
 - **The app is the live source of truth for content** — where authors work and where your push lands live.

package/src/backend/site-sync.js

@@ -101,6 +101,15 @@ export function extractFinalized(payload) {
       // resubmit returns the value we already hold, and anything else is theirs
       // to report, not ours to derive.
       version: typeof d?.version === 'string' ? d.version : null,
+      // Per-item post-write tokens, `{ recordUuid: <opaque> }` (backend `d7e46335`).
+      // Same map shape and same key name the PULL manifest entry stamps, deliberately
+      // — one kind of value, cached from whichever lane last handed it over, echoed
+      // as `item_base_versions`. Absent on an older backend ⇒ null ⇒ the cached
+      // tokens are left alone and gating degrades to the entity grain.
+      itemVersions:
+        d?.item_versions && typeof d.item_versions === 'object'
+          ? d.item_versions
+          : null,
       document: d?.document ?? null
     }))
     .filter((e) => Number.isInteger(e.index) && e.uuid)
@@ -1060,9 +1069,37 @@ export async function pushSyncPackages({
   // otherwise the next attempt would re-send lane 1 with a base the backend has
   // already moved past, and refuse a push the user just made.
   const newVersions = {}
+  // Per-item tokens from the SAME response. Keyed by record `$uuid` and flat
+  // across entities (the cache is a single map), unlike `newVersions`, which is
+  // keyed by entity uuid.
+  //
+  // ⛔ Both grains must be re-armed from the push, for one reason: a push writes,
+  // so every token this clone holds for a record it just changed is now stale. Read
+  // on pull only, push 2 classifies that record `pkg != base, host != base` and the
+  // backend refuses it — a conflict naming records nobody else touched, on a second
+  // push with no edit in between. And it is unrecoverable locally, because the
+  // tokens are opaque by contract: a pull would be the only other source, and a
+  // pull rewrites the working tree. That is precisely the `--force` habit the gate
+  // exists to prevent. Returning the entity `version` on push was added to fix this
+  // exact shape one grain up (see delivery-lane.md "Both feed directions are
+  // load-bearing"); the item grain had the same hole until backend `d7e46335`
+  // started echoing `item_versions` here.
+  const newItemVersions = {}
   const harvest = (finalized) => {
-    for (const f of finalized || [])
+    for (const f of finalized || []) {
       if (f.uuid && f.version) newVersions[f.uuid] = f.version
+      // Unconditionally, and NOT gated on `changed` — same rule as the entity
+      // token: the backend pins "zero-write ⇒ version unmoved", so a no-op
+      // resubmit hands back the value we already hold. An older backend omits the
+      // field entirely, which leaves the cached tokens alone and degrades to the
+      // entity grain, exactly as before.
+      if (f.itemVersions) Object.assign(newItemVersions, f.itemVersions)
+    }
+  }
+  // Both grains land together, at every point the old code banked the entity one.
+  const mergeHarvested = () => {
+    mergeBaseVersions(siteDir, newVersions)
+    mergeItemBaseVersions(siteDir, newItemVersions)
   }
   // The backend's post-write copy of the site-content document, kept for the
   // remote-side unit base (see writeUnitBases).
@@ -1085,7 +1122,7 @@ export async function pushSyncPackages({
         { boundUuid: siteContentUuid }
       )
       if (!finalized) {
-        mergeBaseVersions(siteDir, newVersions)
+        mergeHarvested()
         return { exitCode: 1, finalizedTotal, wrote }
       }
       harvest(finalized)
@@ -1147,7 +1184,7 @@ export async function pushSyncPackages({
       { boundUuid: boundSiteUuid }
     )
     if (!finalized) {
-      mergeBaseVersions(siteDir, newVersions)
+      mergeHarvested()
       return { exitCode: 1, finalizedTotal, wrote }
     }
     harvest(finalized)
@@ -1164,7 +1201,7 @@ export async function pushSyncPackages({
   // Entities absent from finalized[] (skipped, or not editable) keep their cached
   // value — absence is not invalidation.
   writeSyncCache(siteDir, hashes)
-  mergeBaseVersions(siteDir, newVersions)
+  mergeHarvested()
   // Re-base the page attribution: our emitted document and the backend's post-write
   // copy of it are the two sides' new agreed state. Only when the site-content lane
   // actually shipped — a push that skipped it left that state where it was.

package/src/commands/pull.js

@@ -76,13 +76,13 @@ import {
   computeUnitHashes,
   collectUnitUuids
 } from '@uniweb/build/uwx'
-import { makeModelResolver } from './push.js'
 import {
   readWritten,
   recordWritten,
   isPullOutput
 } from '../utils/pull-written.js'
 import {
+  makeModelResolver,
   mergeBaseVersions,
   mergeItemBaseVersions,
   writeUnitBases,

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-12T22:56:55.282Z",
+  "generatedAt": "2026-08-12T23:11:50.036Z",
   "packages": {
     "@uniweb/build": {
       "version": "0.18.5",
@@ -73,7 +73,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.11.6",
+      "version": "0.11.7",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",

package/src/utils/flag-guard.js

@@ -30,37 +30,81 @@ import { findUnknownFlags, didYouMean } from './args.js'
 /** Accepted by every command, wherever they are actually consumed. */
 const GLOBAL = ['--non-interactive', '--help', '-h']
 
+/**
+ * Login-method flags. Any verb that can hit an unauthenticated backend may fall
+ * into `ensureRegistryAuth`, which hands `args` to the login picker — so these are
+ * genuinely reachable from all of them, not just from `uniweb login`.
+ */
+const AUTH = ['--browser', '--password', '--token-paste']
+
+/**
+ * Flags a verb inherits by importing `commands/deploy.js` for `resolveSiteDir` /
+ * `resolveSiteBackend`. Inert on these verbs, and listed rather than filtered:
+ * accepting a flag that does nothing is exactly the pre-guard behaviour, while
+ * rejecting one that works is a broken command. The guard's job is catching
+ * `--backed`, not policing inert-but-valid spellings.
+ */
+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).
  */
-export const VERB_FLAGS = {
+const VERBS = {
   push: [
     '--all', '--as-org', '--org', '--backend', '--dry-run', '--force',
     '--foundation', '--output', '-o', '--personal', '--registry', '--token',
-    '--no-validate'
+    // read in utils/conformance.js and backend/site-sync.js respectively —
+    // neither appears in push.js
+    '--no-validate', '--yes', ...VIA_DEPLOY
   ],
   publish: [
     '--as-org', '--org', '--backend', '--dry-run', '--force', '--foundation',
-    '--no-save', '--personal', '--registry', '--token', '--no-validate', '--yes'
+    '--personal', '--registry', '--token',
+    // read in utils/conformance.js, backend/site-sync.js, and
+    // backend/foundation-bring-along.js — none appear in publish.js
+    '--no-validate', '--yes', '--no-verify', ...VIA_DEPLOY
   ],
   pull: [
     '--backend', '--content-only', '--dry-run', '--force', '--merge',
-    '--no-collections', '--no-delete', '--no-prune', '--registry', '--token'
+    '--no-collections', '--no-delete', '--no-prune', '--registry', '--token',
+    // via backend/site-sync.js (the owner resolver) and utils/conformance.js
+    '--yes', '--org', '--as-org', '--no-validate', ...VIA_DEPLOY
   ],
   clone: [
     '--backend', '--content-only', '--no-collections', '--path', '--project',
-    '--registry', '--token'
+    '--registry', '--token', '--org', '--as-org'
   ],
   register: [
     '--backend', '--dry-run', '--json', '--output', '-o', '--registry',
-    '--schema-only', '--scope', '--token'
+    '--schema-only', '--scope', '--token', '--org', '--as-org'
   ],
-  status: ['--backend', '--json', '--registry', '--remote', '--token']
+  status: [
+    '--backend', '--json', '--registry', '--remote', '--token', '--dry-run',
+    '--force', '--no-verify', '--no-validate', '--yes', '--org', '--as-org',
+    ...VIA_DEPLOY
+  ]
 }
 
+/**
+ * The accepted set per verb: its own flags, plus the login-method flags every
+ * backend verb can reach, plus the globals.
+ *
+ * Derived from each verb's IMPORT GRAPH, not from its own source and not from the
+ * help text — `test/flag-guard-coverage.test.js` walks that graph and fails if a
+ * verb can honour a flag this list omits. Deliberately an over-approximation: a
+ * flag accepted here but inert costs nothing (it was ignored before the guard
+ * existed), while one rejected here breaks a working command.
+ */
+export const VERB_FLAGS = Object.fromEntries(
+  Object.entries(VERBS).map(([verb, flags]) => [
+    verb,
+    [...new Set([...flags, ...AUTH])]
+  ])
+)
+
 /**
  * Check `args` against the verb's accepted set. Returns null when everything is
  * recognized, or a ready-to-print message naming the first offender (plus a