uniweb 0.12.7 → 0.12.8

package/src/commands/export.js

@@ -0,0 +1,85 @@
+/**
+ * Export Command
+ *
+ * Produces a self-contained, vite-built site artifact in `dist/` for
+ * hosting on a third-party CDN (Netlify, Vercel, GitHub Pages, S3 +
+ * CloudFront, etc.). Does NOT upload anywhere — that's `uniweb deploy`.
+ *
+ * The `dist/` output bundles the runtime + foundation + content into
+ * concatenated packaging, with a vite-built `index.html` + `entry.js` +
+ * `assets/`. The user copies it to whatever host they like.
+ *
+ * Internally this is `uniweb build --bundle` plus user guidance for the
+ * upload step. The `--link` / `--bundle` flag pair is internal-only
+ * vocabulary now (Phase 2 of the CLI ergonomics overhaul); users see
+ * `uniweb deploy` (uniweb-edge) and `uniweb export` (third-party host).
+ *
+ * Usage:
+ *   uniweb export                          Produce dist/ for static hosting
+ *   uniweb export --no-prerender           Skip per-page prerendered HTML
+ */
+
+import { execSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { resolveSiteDir } from './deploy.js'
+
+const c = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+}
+const say = {
+  ok: (m) => console.log(`${c.green}✓${c.reset} ${m}`),
+  info: (m) => console.log(`${c.cyan}→${c.reset} ${m}`),
+  err: (m) => console.error(`${c.red}✗${c.reset} ${m}`),
+  dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`),
+}
+
+export async function exportSite(args = []) {
+  const siteDir = await resolveSiteDir(args, 'export')
+
+  // Pass through --no-prerender; everything else gets ignored. `uniweb
+  // export` is intentionally low-flag: the user picks the destination
+  // host themselves outside the CLI, so there's nothing to configure
+  // beyond what `uniweb build --bundle` already exposes.
+  const noPrerender = args.includes('--no-prerender')
+  const buildArgs = ['build', '--bundle']
+  if (noPrerender) buildArgs.push('--no-prerender')
+
+  say.info('Exporting site (vite build → dist/)…')
+  console.log('')
+
+  // Spawn the SAME CLI binary (process.argv[1]) — same reason as deploy.js:
+  // npx walks node_modules and could resolve to a different version.
+  try {
+    execSync(`node ${JSON.stringify(process.argv[1])} ${buildArgs.join(' ')}`, {
+      cwd: siteDir,
+      stdio: 'inherit',
+    })
+  } catch {
+    say.err('Build failed. See output above.')
+    process.exit(1)
+  }
+
+  const distDir = join(siteDir, 'dist')
+  if (!existsSync(distDir)) {
+    say.err('Build did not produce dist/.')
+    process.exit(1)
+  }
+
+  console.log('')
+  say.ok('Export complete.')
+  console.log('')
+  console.log(`  ${c.dim}Artifact:${c.reset} ${c.cyan}${distDir}${c.reset}`)
+  console.log('')
+  console.log(`  ${c.dim}Upload the contents of ${c.reset}${c.cyan}dist/${c.reset}${c.dim} to your static host. Examples:${c.reset}`)
+  console.log(`    ${c.dim}Netlify:${c.reset} ${c.cyan}netlify deploy --prod --dir=dist${c.reset}`)
+  console.log(`    ${c.dim}Vercel:${c.reset}  ${c.cyan}vercel --prod${c.reset}`)
+  console.log(`    ${c.dim}S3:${c.reset}      ${c.cyan}aws s3 sync dist/ s3://your-bucket/${c.reset}`)
+  console.log('')
+  console.log(`  ${c.dim}For Uniweb-hosted sites instead, use ${c.reset}${c.cyan}uniweb deploy${c.reset}${c.dim}.${c.reset}`)
+}

package/src/commands/publish.js

@@ -1,14 +1,36 @@
 /**
  * Publish Command
  *
- * Publishes a foundation to the Uniweb Registry.
+ * Publishes a foundation to the Uniweb Registry as a CATALOG product —
+ * a deliberate, named, versioned artifact that other developers may
+ * consume across many sites.
+ *
+ * For SITE-BOUND foundations (one foundation, one site), use
+ * `uniweb deploy` instead. The deploy command auto-publishes a
+ * workspace-local foundation as part of the deploy under a registry
+ * slot scoped to the site, with no naming ceremony. That's the right
+ * flow for the "this foundation only powers this one site" case.
+ *
+ * Phase 3 of the CLI ergonomics overhaul reshaped this command around
+ * the catalog/site-bound distinction:
+ *
+ *   - Bare `uniweb publish` (no explicit name) is no longer accepted.
+ *     The user must provide a deliberate name via --name, --namespace,
+ *     a sigil-scoped package.json::name, or package.json::uniweb.id.
+ *   - Catalog confirmation is required: interactive runs prompt; CI
+ *     runs need --catalog to skip the prompt.
+ *   - Both gates are skipped for --local (local mock, no public
+ *     consequences).
  *
  * Usage:
- *   uniweb publish                          # Publish to remote registry
- *   uniweb publish --local                  # Publish to local registry (.unicloud/)
- *   uniweb publish --registry <url>         # Publish to a specific registry URL
+ *   uniweb publish @org/my-foundation       # Catalog publish (interactive prompt confirms)
+ *   uniweb publish --name my-foundation     # Same; flag form
+ *   uniweb publish @org/x --catalog         # Skip the catalog confirmation prompt
+ *   uniweb publish --local                  # Local registry (.unicloud/) — no gates
+ *   uniweb publish --registry <url>         # Specific registry URL
  *   uniweb publish --edit-access open       # Anyone can edit in Studio (default: restricted)
- *   uniweb publish --dry-run                # Show what would be published
+ *   uniweb publish --dry-run                # Show what would be published; no writes
+ *   uniweb publish --propagate              # Walk trusting sites' policy waves
  */
 
 import { existsSync } from 'node:fs'
@@ -18,11 +40,10 @@ import { execSync } from 'node:child_process'
 
 import { resolveFoundationSrcPath, classifyPackage } from '@uniweb/build'
 import { createLocalRegistry, RemoteRegistry } from '../utils/registry.js'
-import { ensureAuth, readAuth, decodeJwtPayload } from '../utils/auth.js'
-import { getRegistryUrl } from '../utils/config.js'
+import { ensureAuth, readAuth, writeAuth, decodeJwtPayload } from '../utils/auth.js'
+import { getRegistryUrl, getBackendUrl } from '../utils/config.js'
 import { findWorkspaceRoot, findFoundations, findSites, promptSelect } from '../utils/workspace.js'
 import { isNonInteractive, getCliPrefix } from '../utils/interactive.js'
-import { composeReceipt, deriveReceiptUrl, receiptFromRegistryEntry } from '../utils/receipt.js'
 
 // Colors for terminal output
 const colors = {
@@ -173,6 +194,12 @@ export async function publish(args = []) {
   // 'silent'), the artifact is stored but no site moves until republish
   // or manual refresh.
   const isPropagate = args.includes('--propagate')
+  // --catalog confirms the user understands they're publishing to the
+  // public catalog. Phase 3 of the CLI ergonomics overhaul: in
+  // interactive mode, missing --catalog triggers a confirmation prompt;
+  // in non-interactive mode, it's required (otherwise fatal). Skipped
+  // entirely for --local (local mock) and --dry-run (no writes).
+  const isCatalog = args.includes('--catalog')
   const registryUrl = parseRegistryUrl(args)
   const editAccess = parseEditAccess(args)
   const namespaceFlag = parseNamespace(args)
@@ -212,6 +239,102 @@ export async function publish(args = []) {
     process.exit(1)
   }
 
+  // 1b. Phase 4e: catalog-publish gate.
+  //
+  //     `uniweb publish` is for cataloging a foundation as a product —
+  //     deliberate `@org/{name}` name, version-pinnable, discoverable.
+  //     Site-bound foundations go through `uniweb deploy` instead, which
+  //     uploads them to `sites/{siteId}/_src/...` automatically.
+  //
+  //     The gate rejects two shapes:
+  //       (a) No explicit name at all — running `uniweb publish` from a
+  //           fresh scaffold would otherwise register `src` (or whatever
+  //           the workspace name is) as a catalog entry.
+  //       (b) `~user/...` or personal-UUID scopes — Phase 4e retired the
+  //           personal scope; site-bound foundations use deploy, catalog
+  //           uses `@org/`. There is no "personal catalog" any more.
+  //
+  //     `--local` skips the gate (local mock registry, no public consequences).
+  const hasExplicitName = !!(
+    nameFlag ||
+    namespaceFlag ||
+    /^[@~]/.test(earlyPkg.name || '') ||
+    earlyPkg.uniweb?.id ||
+    earlyPkg.uniweb?.namespace
+  )
+  if (!hasExplicitName && !isLocal) {
+    error('uniweb publish needs a deliberate foundation name.')
+    console.log('')
+    console.log(`  ${colors.bright}If this foundation only powers one site, use ${colors.cyan}uniweb deploy${colors.reset}${colors.bright} instead.${colors.reset}`)
+    console.log(`  ${colors.dim}Deploy uploads your foundation alongside the site's assets — no name ceremony.${colors.reset}`)
+    console.log('')
+    console.log(`  ${colors.bright}If you're cataloging this foundation as a product, name it explicitly:${colors.reset}`)
+    console.log(`    ${colors.cyan}uniweb publish @your-org/foundation-name${colors.reset}`)
+    console.log('')
+    console.log(`  ${colors.dim}For local development, ${colors.reset}${colors.cyan}--local${colors.reset}${colors.dim} skips this gate.${colors.reset}`)
+    process.exit(1)
+  }
+
+  // 1b'. Phase 4e: reject `~`-scoped names. Site-bound foundations don't
+  //      go through publish at all.
+  if (!isLocal) {
+    const candidateName = nameFlag || earlyPkg.name || earlyPkg.uniweb?.id || ''
+    const candidateNamespace = namespaceFlag || earlyPkg.uniweb?.namespace || ''
+    if (candidateName.startsWith('~') || candidateNamespace.startsWith('~')) {
+      error('uniweb publish is for cataloged foundations only.')
+      console.log('')
+      console.log(`  ${colors.dim}The personal-UUID scope (${colors.reset}~uuid/name${colors.dim}) is no longer accepted.${colors.reset}`)
+      console.log(`  ${colors.dim}Site-bound foundations are uploaded automatically by ${colors.reset}${colors.cyan}uniweb deploy${colors.reset}${colors.dim} — they live with site assets, not in the catalog.${colors.reset}`)
+      console.log('')
+      console.log(`  ${colors.bright}For a catalog product, use an org scope:${colors.reset}`)
+      console.log(`    ${colors.cyan}uniweb publish @your-org/foundation-name${colors.reset}`)
+      console.log('')
+      console.log(`  ${colors.dim}No org yet? The CLI will offer to claim one for you the first time you publish to a handle you don't own.${colors.reset}`)
+      process.exit(1)
+    }
+  }
+
+  // 1c. Phase 3 catalog confirmation gate.
+  //
+  //     Cataloging a foundation has consequences (visible in the catalog,
+  //     other developers may pin to versions, propagation system tracks
+  //     it). Require explicit confirmation:
+  //       - Interactive: prompt unless --catalog passed.
+  //       - Non-interactive: fatal unless --catalog passed.
+  //       - Skipped for --local and --dry-run (no public consequences).
+  if (hasExplicitName && !isLocal && !isDryRun && !isCatalog) {
+    if (isNonInteractive(process.argv)) {
+      error('uniweb publish to the catalog needs --catalog confirmation.')
+      console.log('')
+      console.log(`  ${colors.dim}Catalog publishes are public — other developers can pin to your versions.${colors.reset}`)
+      console.log(`  ${colors.dim}Pass ${colors.reset}${colors.cyan}--catalog${colors.reset}${colors.dim} to confirm:${colors.reset}`)
+      console.log(`    ${colors.cyan}uniweb publish ${colors.reset}${colors.dim}<args>${colors.reset} ${colors.cyan}--catalog${colors.reset}`)
+      console.log('')
+      console.log(`  ${colors.dim}For site-bound foundations, use ${colors.reset}${colors.cyan}uniweb deploy${colors.reset}${colors.dim} instead.${colors.reset}`)
+      process.exit(1)
+    }
+
+    const prompts = (await import('prompts')).default
+    console.log('')
+    console.log(`${colors.dim}You're publishing this foundation to the public catalog.${colors.reset}`)
+    console.log(`${colors.dim}Other developers will be able to find it and pin to its versions.${colors.reset}`)
+    console.log(`${colors.dim}For site-bound foundations, ${colors.reset}${colors.cyan}uniweb deploy${colors.reset}${colors.dim} is the right command.${colors.reset}`)
+    console.log('')
+    const confirm = await prompts({
+      type: 'confirm',
+      name: 'go',
+      message: 'Continue with catalog publish?',
+      initial: false,
+    }, {
+      onCancel: () => { console.log(''); console.log('Publish cancelled.'); process.exit(0) },
+    })
+    if (!confirm.go) {
+      console.log('')
+      console.log(`${colors.dim}Cancelled. Use ${colors.reset}${colors.cyan}uniweb deploy${colors.reset}${colors.dim} for site-bound foundations.${colors.reset}`)
+      process.exit(0)
+    }
+  }
+
   let needsBuild = !existsSync(foundationJs) || !existsSync(schemaJson)
   let buildReason = needsBuild ? 'no dist/ found' : null
 
@@ -229,6 +352,25 @@ export async function publish(args = []) {
     }
   }
 
+  // --dry-run gate. Must come BEFORE the pre-flight registry check (which
+  // may persist `uniweb.id` to package.json on the matching-sha path) and
+  // BEFORE the build (which writes to dist/). Earlier the dry-run check
+  // sat after both, which violated the zero-writes contract.
+  if (isDryRun) {
+    const previewName = quickResolveCanonicalName(earlyPkg, { namespaceFlag, nameFlag })
+      || earlyPkg.name
+      || '(unresolved)'
+    const target = isLocal ? 'local registry' : `remote registry (${registryUrl || getRegistryUrl()})`
+    console.log('')
+    info(`Would publish ${colors.bright}${previewName}@${earlyPkg.version}${colors.reset} to ${target}`)
+    if (needsBuild) {
+      console.log(`  ${colors.dim}Would build first: ${buildReason}${colors.reset}`)
+    } else {
+      console.log(`  ${colors.dim}Source: ${distDir}${colors.reset}`)
+    }
+    return
+  }
+
   // 2b. Pre-flight registry check — runs BEFORE the build so we don't
   //     burn vite cycles on a foundation we already know we can't (or
   //     don't need to) publish.
@@ -271,27 +413,13 @@ export async function publish(args = []) {
             if (existing) {
               const { gitSha } = readGitState(foundationDir)
               if (gitSha && existing.publishedFromGitSha === gitSha) {
-                // Match → refresh receipt, exit clean. NO BUILD.
-                const refreshed = receiptFromRegistryEntry({
-                  existingEntry: existing,
-                  registry: registryPre,
-                  name: lookupName,
-                  version: preflightVersion,
-                  isLocal: false,
-                  isPropagateDefault: isPropagate,
-                })
-                if (refreshed) {
-                  await mkdir(distDir, { recursive: true })
-                  await writeFile(join(distDir, 'publish.json'), JSON.stringify(refreshed, null, 2) + '\n')
-                  console.log('')
-                  success(`${colors.bright}${lookupName}@${preflightVersion}${colors.reset} already published from ${gitSha.slice(0, 7)} — receipt refreshed.`)
-                  return
-                }
+                // Already published from this exact source — nothing to do.
+                console.log('')
+                success(`${colors.bright}${lookupName}@${preflightVersion}${colors.reset} already published from ${gitSha.slice(0, 7)}.`)
+                return
               }
               // Sha mismatch (or no provenance recorded for the existing
-              // entry, which shouldn't happen for new publishes after
-              // the receipt-as-cache work shipped). Clean error before
-              // any build work.
+              // entry). Clean error before any build work.
               console.log('')
               error(`Foundation source has changed since the last publish, but ${colors.bright}${lookupName}@${preflightVersion}${colors.reset} is already published.`)
               console.log('')
@@ -574,35 +702,88 @@ export async function publish(args = []) {
     name = foundationName
   }
 
-  // 3c. Advisory scope authorization (Worker enforces — this is for early UX feedback)
-  if (!isLocal) {
+  // 3c. Phase 4f: org-claim flow.
+  //
+  //     `uniweb publish @handle/foo` against a handle the user doesn't own
+  //     yet drops into the org-claim flow instead of failing. Three cases:
+  //       (a) JWT has no `namespaces` claim at all → token predates org
+  //           support; tell the user to `uniweb login` again.
+  //       (b) Handle is already in `namespaces` → proceed.
+  //       (c) Handle is NOT in `namespaces` → call POST /api/orgs/{handle}.
+  //           Confirm-and-claim if available; hard-fail if taken; refresh
+  //           the cached token on success and proceed with publish.
+  //
+  //     Skipped for `--local` (no auth, no org system).
+  const claimOrgFlag = args.includes('--claim-org')
+  if (!isLocal && scopeSigil === '@') {
     const auth = await readAuth()
-    if (scopeSigil === '@') {
-      // Org scope: must be in the user's namespaces[] claim.
-      const namespaces = auth?.namespaces
-      if (Array.isArray(namespaces) && !namespaces.includes(scopeName)) {
-        error(`You don't have publish access to namespace "${colors.bright}@${scopeName}${colors.reset}"`)
-        if (namespaces.length > 0) {
-          console.log(`  ${colors.dim}Your organizations: ${namespaces.map(n => '@' + n).join(', ')}${colors.reset}`)
-          console.log(`  ${colors.dim}Or remove the scope from package.json::name to publish under your personal scope.${colors.reset}`)
-        } else {
-          console.log(`  ${colors.dim}You don't belong to any organizations.${colors.reset}`)
-          console.log(`  ${colors.dim}Use a bare name in package.json (e.g. "src") to publish under your personal scope.${colors.reset}`)
-        }
+    if (!Array.isArray(auth?.namespaces)) {
+      // Old token, predates org support.
+      error('Your authentication token doesn\'t carry organization claims.')
+      console.log('')
+      console.log(`  ${colors.dim}Run ${colors.reset}${colors.cyan}uniweb login${colors.reset}${colors.dim} to refresh your session, then retry.${colors.reset}`)
+      process.exit(1)
+    }
+    if (!auth.namespaces.includes(scopeName)) {
+      // Need to claim. Confirm interactively unless --claim-org was passed.
+      if (isNonInteractive(process.argv) && !claimOrgFlag) {
+        error(`You don't own ${colors.bright}@${scopeName}${colors.reset} yet.`)
+        console.log('')
+        console.log(`  ${colors.dim}In CI, pass ${colors.reset}${colors.cyan}--claim-org${colors.reset}${colors.dim} to claim available handles automatically.${colors.reset}`)
+        console.log(`  ${colors.dim}Interactive mode prompts for confirmation.${colors.reset}`)
         process.exit(1)
       }
-    } else if (scopeSigil === '~') {
-      // Personal alias scope: must match the user's loginName claim
-      // (until handle-aliasing ships, this is loginName-only).
-      if (auth?.loginName && auth.loginName !== scopeName) {
-        error(`Personal scope "${colors.bright}~${scopeName}${colors.reset}" doesn't match your account`)
-        console.log(`  ${colors.dim}Your personal scope: ~${auth.loginName}${colors.reset}`)
-        console.log(`  ${colors.dim}Or remove the scope from package.json::name to publish under your personal scope.${colors.reset}`)
+
+      if (!claimOrgFlag) {
+        const prompts = (await import('prompts')).default
+        console.log('')
+        console.log(`${colors.dim}You don't own ${colors.reset}${colors.bright}@${scopeName}${colors.reset}${colors.dim} yet.${colors.reset}`)
+        console.log(`${colors.dim}Org handles are global and permanent — only the claiming account can publish under them.${colors.reset}`)
+        console.log('')
+        const confirm = await prompts({
+          type: 'confirm',
+          name: 'go',
+          message: `Claim @${scopeName} for your account?`,
+          initial: false,
+        }, {
+          onCancel: () => { console.log(''); console.log('Publish cancelled.'); process.exit(0) },
+        })
+        if (!confirm.go) {
+          console.log('')
+          console.log(`${colors.dim}Cancelled. Publish under a handle you already own, or pick a different one.${colors.reset}`)
+          process.exit(0)
+        }
+      }
+
+      // Org claim hits the PHP backend (auth/identity is PHP's domain),
+      // not the worker. In local dev unicloud serves both on one port, so
+      // tests work; in production these are different hosts.
+      const claimed = await claimOrgHandle({
+        handle: scopeName,
+        token: auth.token,
+        backendUrl: getBackendUrl(),
+      })
+      if (claimed.taken) {
+        error(`@${scopeName} is already claimed by another account.`)
+        console.log('')
+        console.log(`  ${colors.dim}Pick a different handle. Org names are global and exclusive.${colors.reset}`)
         process.exit(1)
       }
+      // Swap the cached token for the refreshed one (now carries the new
+      // namespace claim). Subsequent publish calls in this run see it via
+      // a fresh `readAuth()` and the worker accepts the upload.
+      await writeAuth({
+        token: claimed.token,
+        email: auth.email,
+        expiresAt: auth.expiresAt,
+      })
+      if (claimed.created) {
+        success(`Claimed ${colors.bright}@${scopeName}${colors.reset} for your account.`)
+      } else {
+        info(`Refreshed your token; ${colors.bright}@${scopeName}${colors.reset} is yours.`)
+      }
+      console.log('')
     }
-    // Empty-scope: no client-side check. The server resolves to the
-    // memberId from the JWT (sub claim) and writes ownership accordingly.
   }
 
   // 4. Create registry (local or remote)
@@ -649,41 +830,28 @@ export async function publish(args = []) {
 
   // 5. Check for duplicates. If the registry already has this exact
   //    version recorded as published from the current commit, treat it
-  //    as a fresh-checkout no-op: refresh the local receipt and exit
-  //    successfully. The artifact upstream is already correct; there's
-  //    nothing to upload. See `kb/framework/build/workspace-ergonomics.md`
-  //    (receipt-as-cache).
+  //    as a fresh-checkout no-op — the artifact upstream is already
+  //    correct; there's nothing to upload.
   const existingEntry = await registry.getVersionEntry(lookupName, version)
   if (existingEntry) {
     if (gitSha && existingEntry.publishedFromGitSha === gitSha) {
-      const refreshedReceipt = receiptFromRegistryEntry({
-        existingEntry,
-        registry,
-        name: lookupName,
-        version,
-        isLocal,
-        isPropagateDefault: isPropagate,
-      })
-      if (refreshedReceipt) {
-        // Persist uniweb.id BEFORE the early return when an auto-derive
-        // or prompt-resolved id was set in this run. Without this, the
-        // next run wouldn't know the id and would have to re-derive
-        // from scratch — which means the pre-flight registry check at
-        // the top of publish() can't fire either (it relies on a
-        // resolvable id from pkg.json alone). Persisting here closes
-        // that loop so future deploys hit the pre-flight bail and skip
-        // the build entirely.
-        if (writeBackId) {
-          pkg.uniweb = pkg.uniweb || {}
-          pkg.uniweb.id = foundationName
-          await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
-          info(`Wrote ${colors.cyan}uniweb.id: "${foundationName}"${colors.reset} to ${colors.dim}package.json${colors.reset}`)
-        }
-        await writeFile(join(distDir, 'publish.json'), JSON.stringify(refreshedReceipt, null, 2) + '\n')
-        console.log('')
-        success(`${colors.bright}${lookupName}@${version}${colors.reset} already published from ${gitSha.slice(0, 7)} — receipt refreshed.`)
-        return
+      // Persist uniweb.id BEFORE the early return when an auto-derive
+      // or prompt-resolved id was set in this run. Without this, the
+      // next run wouldn't know the id and would have to re-derive
+      // from scratch — which means the pre-flight registry check at
+      // the top of publish() can't fire either (it relies on a
+      // resolvable id from pkg.json alone). Persisting here closes
+      // that loop so future deploys hit the pre-flight bail and skip
+      // the build entirely.
+      if (writeBackId) {
+        pkg.uniweb = pkg.uniweb || {}
+        pkg.uniweb.id = foundationName
+        await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+        info(`Wrote ${colors.cyan}uniweb.id: "${foundationName}"${colors.reset} to ${colors.dim}package.json${colors.reset}`)
       }
+      console.log('')
+      success(`${colors.bright}${lookupName}@${version}${colors.reset} already published from ${gitSha.slice(0, 7)}.`)
+      return
     }
     console.log('')
     error(`Foundation source has changed since the last publish, but ${colors.bright}${name}@${version}${colors.reset} is already published.`)
@@ -693,20 +861,7 @@ export async function publish(args = []) {
     process.exit(1)
   }
 
-  // 6. Dry-run check
-  if (isDryRun) {
-    console.log('')
-    info(`Would publish ${colors.bright}${name}@${version}${colors.reset} to ${registryLabel}`)
-    console.log(`  ${colors.dim}Source: ${distDir}${colors.reset}`)
-    if (isLocal) {
-      console.log(`  ${colors.dim}Target: ${registry.getPackagePath(name, version)}${colors.reset}`)
-    } else {
-      console.log(`  ${colors.dim}Target: ${registry.apiUrl}${colors.reset}`)
-    }
-    return
-  }
-
-  // 7. Publish
+  // 6. Publish
   info(`Publishing ${colors.bright}${name}@${version}${colors.reset} to ${registryLabel}...`)
 
   // Resolve the publisher's identity
@@ -714,9 +869,8 @@ export async function publish(args = []) {
   const publishMetadata = {
     publishedBy: auth?.email || (isLocal ? 'local' : 'cli'),
     classification: isPropagate ? 'propagate' : 'silent',
-    // Git provenance lets the registry serve as a recovery source for
-    // the local `dist/publish.json` cache on fresh checkouts, without
-    // requiring the cache itself to survive across machines.
+    // Git provenance lets `uniweb deploy` decide whether a workspace-local
+    // foundation needs republishing — see deploy.js's staleness check.
     ...(gitSha ? { publishedFromGitSha: gitSha } : {}),
     ...(typeof gitDirty === 'boolean' ? { publishedFromGitDirty: gitDirty } : {}),
   }
@@ -724,9 +878,8 @@ export async function publish(args = []) {
     publishMetadata.editAccess = editAccess
   }
 
-  let publishResult
   try {
-    publishResult = await registry.publish(name, version, distDir, publishMetadata)
+    await registry.publish(name, version, distDir, publishMetadata)
   } catch (err) {
     if (err.code === 'CONFLICT') {
       error(`${colors.bright}${name}@${version}${colors.reset} already exists on the registry.`)
@@ -741,18 +894,6 @@ export async function publish(args = []) {
     throw err
   }
 
-  // Local event memory — read by `uniweb deploy` to decide whether a
-  // workspace-local foundation needs republishing. Lives under dist/ which
-  // is gitignored; not part of the upload.
-  const receipt = composeReceipt({
-    gitSha,
-    gitDirty,
-    url: deriveReceiptUrl({ publishResult, registry, name, version, isLocal }),
-    publishedAt: new Date().toISOString(),
-    classification: isPropagate ? 'propagate' : 'silent',
-  })
-  await writeFile(join(distDir, 'publish.json'), JSON.stringify(receipt, null, 2) + '\n')
-
   const prefix = getCliPrefix()
   const isExtension = schema._self?.role === 'extension'
   console.log('')
@@ -999,10 +1140,9 @@ async function buildIdSuggestions({ foundationDir, workspaceRoot, pkg }) {
 /**
  * Per-directory git state. Mirrors `deploy.js::readGitState` exactly —
  * scopes the sha + dirty check to `dir` rather than reading the whole
- * repo's HEAD. Receipts compare against this; if publish records the
- * repo HEAD but deploy compares against the foundation's last commit,
- * the receipt-as-cache no-op-refresh path drifts. Both sides must read
- * the same shape.
+ * repo's HEAD. Publish records this in registry metadata; deploy
+ * compares against it for staleness. Both sides must read the same
+ * shape or the staleness check drifts.
  */
 function readGitState(dir) {
   try {
@@ -1020,4 +1160,36 @@ function readGitState(dir) {
   }
 }
 
+/**
+ * POST /api/orgs/{handle} — claim an `@handle` for the calling user.
+ *
+ * Returns one of:
+ *   { created: true,  token: '<refreshed JWT>' }   — handle was free
+ *   { created: false, token: '<refreshed JWT>' }   — user already owned it
+ *   { taken:  true }                               — claimed by someone else
+ *
+ * Other failures throw.
+ */
+async function claimOrgHandle({ handle, token, backendUrl }) {
+  const url = `${backendUrl.replace(/\/$/, '')}/api/orgs/${encodeURIComponent(handle)}`
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`,
+    },
+  })
+  if (res.status === 409) return { taken: true }
+  if (!res.ok) {
+    let detail = `HTTP ${res.status}`
+    try {
+      const j = await res.json()
+      detail = j.error || detail
+    } catch { /* non-JSON body */ }
+    throw new Error(`Org claim failed: ${detail}`)
+  }
+  const body = await res.json()
+  return { created: !!body.created, token: body.token }
+}
+
 export default publish

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-04-30T18:07:13.397Z",
+  "generatedAt": "2026-05-01T02:07:21.541Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.13.4",
+      "version": "0.13.5",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -92,7 +92,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.4.3",
+      "version": "0.4.4",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",