uniweb 0.12.3 → 0.12.5

package/src/commands/publish.js

@@ -12,16 +12,17 @@
  */
 
 import { existsSync } from 'node:fs'
-import { readFile, writeFile } from 'node:fs/promises'
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
 import { resolve, join } from 'node:path'
 import { execSync } from 'node:child_process'
 
 import { resolveFoundationSrcPath, classifyPackage } from '@uniweb/build'
 import { createLocalRegistry, RemoteRegistry } from '../utils/registry.js'
-import { ensureAuth, readAuth } from '../utils/auth.js'
+import { ensureAuth, readAuth, decodeJwtPayload } from '../utils/auth.js'
 import { getRegistryUrl } 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 = {
@@ -187,13 +188,129 @@ export async function publish(args = []) {
     process.exit(1)
   }
 
-  // 2. Auto-build if dist/ is missing
+  // 2. Auto-build if dist/ is missing OR stale.
+  //
+  //    "Stale" means the schema fingerprint baked into
+  //    `dist/meta/schema.json::_self.version` doesn't match the user's
+  //    current `package.json::version`. That happens when the user bumps
+  //    the version and runs `uniweb publish` without rebuilding — the
+  //    artifact in dist/ encodes the OLD version, but the publish
+  //    intends the NEW one. Without rebuilding we'd ship inconsistent
+  //    bytes (schema says one version, registry record says another).
   const distDir = join(foundationDir, 'dist')
   const foundationJs = join(distDir, 'foundation.js')
   const schemaJson = join(distDir, 'meta', 'schema.json')
 
-  if (!existsSync(foundationJs) || !existsSync(schemaJson)) {
-    console.log(`${colors.yellow}⚠${colors.reset} No build found. Building foundation...`)
+  // Pre-read package.json so we can compare its version against the
+  // schema before deciding whether to rebuild.
+  const pkgPath = join(foundationDir, 'package.json')
+  let earlyPkg
+  try {
+    earlyPkg = JSON.parse(await readFile(pkgPath, 'utf8'))
+  } catch (err) {
+    error(`Failed to read package.json: ${err.message}`)
+    process.exit(1)
+  }
+
+  let needsBuild = !existsSync(foundationJs) || !existsSync(schemaJson)
+  let buildReason = needsBuild ? 'no dist/ found' : null
+
+  if (!needsBuild) {
+    try {
+      const peekSchema = JSON.parse(await readFile(schemaJson, 'utf8'))
+      if (peekSchema?._self?.version && earlyPkg.version && peekSchema._self.version !== earlyPkg.version) {
+        needsBuild = true
+        buildReason = `package.json::version (${earlyPkg.version}) differs from dist/meta/schema.json::_self.version (${peekSchema._self.version})`
+      }
+    } catch {
+      // Malformed schema → treat as stale.
+      needsBuild = true
+      buildReason = 'dist/meta/schema.json could not be parsed'
+    }
+  }
+
+  // 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.
+  //
+  //     Two outcomes short-circuit the build:
+  //
+  //       a. The registry already has `<canonicalName>@<version>`
+  //          published from the CURRENT git sha (per-foundation last
+  //          commit). The artifact upstream is correct; refresh the
+  //          local receipt and exit. (Same outcome as the post-build
+  //          duplicate check, just earlier — saves a build.)
+  //
+  //       b. The registry has the version published from a DIFFERENT
+  //          sha. The user has unpublished changes against an already-
+  //          published version → "bump the version" error before any
+  //          build work. Was the eval skill's pp-03 row.
+  //
+  //     If the pre-flight can't determine the canonical name from
+  //     pkg.json + flags + auth alone (e.g., needs a TTY prompt for
+  //     the foundation id), it falls through silently to the existing
+  //     post-build path. No-build-saved is still the existing behavior.
+  if (!isLocal) {
+    const preflightName = quickResolveCanonicalName(earlyPkg, { namespaceFlag, nameFlag })
+    const preflightVersion = earlyPkg.version
+    if (preflightName && preflightVersion) {
+      try {
+        const auth = await readAuth()
+        if (auth?.token) {
+          const claims = decodeJwtPayload(auth.token)
+          const memberUuid = claims?.memberUuid
+          // Empty-scope publishes are server-rewritten to ~<memberUuid>/<id>.
+          // Mirror that here so getVersionEntry queries the canonical key.
+          const lookupName = preflightName.startsWith('@') || preflightName.startsWith('~')
+            ? preflightName
+            : memberUuid ? `~${memberUuid}/${preflightName}` : null
+          if (lookupName) {
+            const registryUrlPre = registryUrl || getRegistryUrl()
+            const registryPre = new RemoteRegistry(registryUrlPre, auth.token)
+            const existing = await registryPre.getVersionEntry(lookupName, preflightVersion)
+            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
+                }
+              }
+              // 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.
+              console.log('')
+              error(`${colors.bright}${lookupName}@${preflightVersion}${colors.reset} is already published.`)
+              console.log('')
+              console.log(`  Bump the version in package.json to publish an update:`)
+              console.log(`    ${colors.dim}"version": "${bumpPatch(preflightVersion)}"${colors.reset}`)
+              process.exit(1)
+            }
+          }
+        }
+      } catch {
+        // Network down, malformed auth, etc. — fall through to the
+        // existing post-build flow. No-build-saved is still the same
+        // behavior the user got before this pre-flight existed.
+      }
+    }
+  }
+
+  if (needsBuild) {
+    console.log(`${colors.yellow}⚠${colors.reset} ${buildReason}. Building foundation...`)
     console.log('')
     execSync('npx uniweb build --target foundation', {
       cwd: foundationDir,
@@ -207,7 +324,13 @@ export async function publish(args = []) {
     }
   }
 
-  // 3. Read name and version from meta/schema.json
+  // 3. Read name + version from the (now-fresh) schema + package.json.
+  //
+  //    `_self.name` is the build-RESOLVED form — applies `uniweb.id`,
+  //    scope resolution, etc., that are easier to read off the build
+  //    output than to redo here. `version` is sourced from package.json
+  //    directly; the version-skew check above already ensured the
+  //    schema and package.json agree.
   let schema
   try {
     schema = JSON.parse(await readFile(schemaJson, 'utf8'))
@@ -217,11 +340,12 @@ export async function publish(args = []) {
   }
 
   const rawName = schema._self?.name
-  const version = schema._self?.version
+  const version = earlyPkg.version
 
   if (!rawName || !version) {
-    error('dist/meta/schema.json missing _self.name or _self.version')
-    console.log(`${colors.dim}  Ensure your package.json has "name" and "version" fields.${colors.reset}`)
+    error('Foundation missing name or version')
+    console.log(`${colors.dim}  Ensure your package.json has "name" and "version" fields,${colors.reset}`)
+    console.log(`${colors.dim}  and that the build has produced dist/meta/schema.json with _self.name.${colors.reset}`)
     process.exit(1)
   }
 
@@ -266,8 +390,9 @@ export async function publish(args = []) {
   // affects only the registry identity, never the workspace. Most users
   // benefit from leaving `package.json::name` as the scaffold default
   // (`src`) and putting the published-as id in `uniweb.id`.
-  const pkgPath = join(foundationDir, 'package.json')
-  const pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
+  // pkgPath was declared earlier (during the rebuild-stale-dist check).
+  // Reuse the already-loaded `earlyPkg` rather than re-reading from disk.
+  const pkg = earlyPkg
   const uniwebNamespace = pkg.uniweb?.namespace
   const uniwebId = pkg.uniweb?.id
   const orgScopeMatch = (pkg.name || '').match(/^@([a-z0-9_-]+)\/([a-z0-9_-]+)$/)
@@ -310,53 +435,106 @@ export async function publish(args = []) {
     foundationName = uniwebId
   }
   if (!foundationName) {
-    // No id resolvable from any field. Prompt — or fail in non-interactive.
+    // No id resolvable from any field. Build a set of suggestions
+    // contextual to this workspace, then either prompt (TTY) or print
+    // them as guidance (CI). The bare `pkg.name` is intentionally NOT
+    // a suggestion when it equals the scaffold default `src` — picking
+    // that name would couple the registry id to a generic placeholder
+    // that future renames couldn't undo.
+    const workspaceRoot = findWorkspaceRoot(foundationDir) || foundationDir
+    const suggestions = await buildIdSuggestions({ foundationDir, workspaceRoot, pkg })
+
     if (isNonInteractive(process.argv)) {
-      error('Foundation id is required for publishing.')
-      console.log('')
-      console.log(`  ${colors.dim}Use one of:${colors.reset}`)
-      console.log(`    ${colors.cyan}uniweb publish --name <id>${colors.reset}`)
-      console.log(`    ${colors.dim}Add ${colors.reset}"uniweb": { "id": "<your-id>" }${colors.dim} to package.json${colors.reset}`)
-      console.log(`    ${colors.dim}Or use a scoped name in package.json: ${colors.reset}"name": "@org/<id>"${colors.reset}`)
-      process.exit(1)
-    }
+      // CI: when there's a high-confidence signal — the workspace
+      // package.json's name (the user typed it via `uniweb create
+      // <name>`) — auto-derive and persist. This unblocks first-deploy
+      // CI flows (pp-01 etc.) where stopping to ask isn't an option.
+      // Other suggestion sources (sibling-site name, M-code) are NOT
+      // auto-picked because they're ambiguous in multi-package
+      // workspaces; they remain available via the error message
+      // when no high-confidence signal exists.
+      const autoId = await pickAutoDerivedId({ workspaceRoot, foundationDir })
+      if (autoId) {
+        info(`Auto-deriving ${colors.bright}uniweb.id: "${autoId}"${colors.reset} ${colors.dim}(matches workspace name; persisted to package.json)${colors.reset}`)
+        foundationName = autoId
+        writeBackId = true
+      } else {
+        error('Foundation id is required for publishing.')
+        console.log('')
+        if (suggestions.length > 0) {
+          console.log(`  ${colors.bright}Suggestions for your workspace:${colors.reset}`)
+          for (const { id, why } of suggestions) {
+            console.log(`    ${colors.cyan}${id}${colors.reset}  ${colors.dim}${why}${colors.reset}`)
+          }
+          console.log('')
+        }
+        console.log(`  ${colors.dim}Use one of:${colors.reset}`)
+        const example = suggestions[0]?.id || '<id>'
+        console.log(`    ${colors.cyan}uniweb publish --name ${example}${colors.reset}`)
+        console.log(`    ${colors.dim}Add ${colors.reset}"uniweb": { "id": "<your-id>" }${colors.dim} to package.json${colors.reset}`)
+        console.log(`    ${colors.dim}Or use a scoped name in package.json: ${colors.reset}"name": "@org/<id>"${colors.reset}`)
+        process.exit(1)
+      }
+    } else {
 
     const prompts = (await import('prompts')).default
-    // Default suggestion: derive from the workspace folder or pkg.name.
-    // Strip the suffix `-src` so a foundation in `marketing-src/` defaults
-    // to `marketing` as its publish id.
-    const workspaceRoot = findWorkspaceRoot(foundationDir) || foundationDir
-    const folderName = workspaceRoot === foundationDir
-      ? null
-      : foundationDir.replace(workspaceRoot + '/', '').split('/')[0]
-    const suggestion =
-      (typeof pkg.name === 'string' && ID_RE.test(pkg.name) ? pkg.name : null) ||
-      (folderName ? folderName.replace(/-src$/, '') : null) ||
-      'foundation'
-
     console.log('')
     console.log(`${colors.dim}This is the first publish of this foundation. Pick a name${colors.reset}`)
     console.log(`${colors.dim}for the registry — what your foundation will be known as.${colors.reset}`)
-    const response = await prompts({
-      type: 'text',
-      name: 'id',
-      message: 'Foundation name',
-      initial: suggestion,
-      validate: (v) => {
-        if (!v) return 'Required'
-        if (!ID_RE.test(v)) return 'Lowercase letters, digits, hyphens, underscores only'
-        return true
-      },
-    }, {
-      onCancel: () => {
-        console.log('')
-        console.log('Publish cancelled.')
-        process.exit(0)
-      },
-    })
-    if (!response.id) process.exit(0)
-    foundationName = response.id
+    console.log('')
+
+    let chosen
+    if (suggestions.length > 0) {
+      // Surface contextual suggestions first (sibling site, workspace name,
+      // M-code series). Always include "Type a different name…" so the
+      // user is never trapped in a list.
+      const choices = [
+        ...suggestions.map(s => ({ title: s.id, description: s.why, value: s.id })),
+        { title: 'Type a different name…', value: '__custom__' },
+      ]
+      const pickResp = await prompts({
+        type: 'select',
+        name: 'pick',
+        message: 'Foundation name',
+        choices,
+        initial: 0,
+      }, {
+        onCancel: () => { console.log(''); console.log('Publish cancelled.'); process.exit(0) },
+      })
+      if (!pickResp.pick) process.exit(0)
+      chosen = pickResp.pick
+    } else {
+      chosen = '__custom__'
+    }
+
+    if (chosen === '__custom__') {
+      const folderName = workspaceRoot === foundationDir
+        ? null
+        : foundationDir.replace(workspaceRoot + '/', '').split('/')[0]
+      const suggestion =
+        suggestions[0]?.id ||
+        (folderName ? folderName.replace(/-src$/, '') : null) ||
+        ''
+      const textResp = await prompts({
+        type: 'text',
+        name: 'id',
+        message: 'Foundation name',
+        initial: suggestion,
+        validate: (v) => {
+          if (!v) return 'Required'
+          if (!ID_RE.test(v)) return 'Lowercase letters, digits, hyphens, underscores only'
+          return true
+        },
+      }, {
+        onCancel: () => { console.log(''); console.log('Publish cancelled.'); process.exit(0) },
+      })
+      if (!textResp.id) process.exit(0)
+      chosen = textResp.id
+    }
+
+    foundationName = chosen
     writeBackId = true
+    }
   }
 
   // Validate the resolved id (may have come from any source).
@@ -443,8 +621,70 @@ export async function publish(args = []) {
 
   const registryLabel = isLocal ? 'local registry' : `registry`
 
-  // 5. Check for duplicates
-  if (await registry.exists(name, version)) {
+  // Git state — read up-front so it can both gate the duplicate check
+  // (fresh-checkout no-op vs. true conflict) and ride along in the
+  // publish payload.
+  const { gitSha, gitDirty } = readGitState(foundationDir)
+
+  // Compute the canonical name the server stores under. Empty-scope
+  // (bare-name) publishes go to the registry as `<name>` but are
+  // server-side rewritten to `~<memberUuid>/<name>`. The duplicate
+  // check below queries the registry's index, which uses the canonical
+  // form as the key — so we have to mirror the rewrite locally.
+  // Org / personal-scope publishes skip this (their `name` is already
+  // canonical).
+  let lookupName = name
+  if (!scopeSigil && !isLocal) {
+    try {
+      const localAuth = await readAuth()
+      const claims = decodeJwtPayload(localAuth?.token)
+      if (claims?.memberUuid) {
+        lookupName = `~${claims.memberUuid}/${foundationName}`
+      }
+    } catch {
+      // No usable auth — fall back to the bare name. The publish call
+      // itself will fail later with an auth error if a token is needed.
+    }
+  }
+
+  // 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).
+  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
+      }
+    }
     console.log('')
     error(`${colors.bright}${name}@${version}${colors.reset} is already published.`)
     console.log('')
@@ -474,6 +714,11 @@ 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.
+    ...(gitSha ? { publishedFromGitSha: gitSha } : {}),
+    ...(typeof gitDirty === 'boolean' ? { publishedFromGitDirty: gitDirty } : {}),
   }
   if (editAccess) {
     publishMetadata.editAccess = editAccess
@@ -499,19 +744,13 @@ export async function publish(args = []) {
   // 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 receiptUrl = publishResult?.url
-    || (isLocal
-      ? `file://${registry.getPackagePath(name, version)}/`
-      : `${registry.apiUrl}/${name}/${version}/`)
-  const { gitSha, gitDirty } = readGitState(foundationDir)
-  const receipt = {
-    schemaVersion: 1,
-    publishedFromGitSha: gitSha,
-    publishedFromGitDirty: gitDirty,
-    url: receiptUrl,
+  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()
@@ -549,6 +788,65 @@ export async function publish(args = []) {
  * @param {string} version - e.g. "1.0.0"
  * @returns {string} - e.g. "1.0.1"
  */
+/**
+ * Quickly compute the canonical foundation name from `package.json` +
+ * CLI flags alone, without prompting and without reading the build's
+ * `dist/meta/schema.json`. Used by the pre-flight registry check so we
+ * can short-circuit the build when the registry already has this
+ * version published.
+ *
+ * Returns null when resolution would need a prompt or auto-derive
+ * (caller falls through to the existing post-build resolution path,
+ * which handles those cases). The returned string is one of:
+ *   - `@<scope>/<id>`  (org scope, full canonical form)
+ *   - `~<handle>/<id>` (personal alias scope)
+ *   - `<id>`            (bare; caller may prepend `~<memberUuid>/`
+ *                       from the JWT for the actual lookup)
+ *
+ * The full resolution at line 313+ is the canonical implementation;
+ * this helper is a strict subset that mirrors the high-confidence
+ * paths only. If they diverge, the helper is the one that should
+ * stay conservative (return null on uncertainty).
+ */
+function quickResolveCanonicalName(pkg, { namespaceFlag, nameFlag } = {}) {
+  if (!pkg) return null
+  const orgScopeMatch = (pkg.name || '').match(/^@([a-z0-9_-]+)\/([a-z0-9_-]+)$/)
+  const personalScopeMatch = (pkg.name || '').match(/^~([a-z0-9_-]+)\/([a-z0-9_-]+)$/)
+  const uniwebNamespace = pkg.uniweb?.namespace
+  const uniwebId = pkg.uniweb?.id
+
+  // Scope precedence mirrors the full resolution.
+  let scopeSigil = null
+  let scopeName = null
+  if (namespaceFlag) {
+    scopeSigil = '@'
+    scopeName = namespaceFlag
+  } else if (orgScopeMatch) {
+    scopeSigil = '@'
+    scopeName = orgScopeMatch[1]
+  } else if (personalScopeMatch) {
+    scopeSigil = '~'
+    scopeName = personalScopeMatch[1]
+  } else if (uniwebNamespace) {
+    scopeSigil = '@'
+    scopeName = uniwebNamespace
+  }
+
+  // Id precedence mirrors the full resolution but stops at "no-prompt"
+  // sources. Auto-derive and TTY prompts both happen post-build so the
+  // user sees suggestions in context; the pre-flight only fires when
+  // the id is already determined.
+  let id = null
+  if (nameFlag) id = nameFlag
+  else if (orgScopeMatch) id = orgScopeMatch[2]
+  else if (personalScopeMatch) id = personalScopeMatch[2]
+  else if (uniwebId) id = uniwebId
+  else return null
+
+  if (scopeSigil) return `${scopeSigil}${scopeName}/${id}`
+  return id
+}
+
 function bumpPatch(version) {
   const parts = version.split('.')
   if (parts.length !== 3) return version
@@ -556,13 +854,163 @@ function bumpPatch(version) {
   return parts.join('.')
 }
 
+/**
+ * High-confidence auto-derive for non-interactive (CI) first publishes.
+ *
+ * Diego's principle: never silently take a generic scaffold default like
+ * `src` or `site` as the registry id (those are placeholders, not user
+ * intent). But when the user has typed a real name elsewhere — most
+ * unambiguously the workspace package.json's `name` (set by
+ * `uniweb create <name>`) — picking that in CI is the obvious right
+ * answer and stopping to ask just breaks the CI run.
+ *
+ * Auto-derive set is intentionally NARROW:
+ *   1. Workspace package.json::name, when it's a clean id and not a
+ *      generic placeholder.
+ *
+ * Other suggestion sources from `buildIdSuggestions` (sibling-site
+ * name, M-code series) are NOT auto-picked: they're ambiguous in
+ * multi-package or multi-foundation workspaces. They remain visible
+ * in the CI error message when no high-confidence signal exists, so
+ * the user can pick one explicitly via `--name <id>`.
+ *
+ * Returns the id string, or null when no high-confidence signal is
+ * available (caller falls through to the existing error-with-
+ * suggestions guidance).
+ */
+async function pickAutoDerivedId({ workspaceRoot, foundationDir }) {
+  const ID_RE = /^[a-z0-9_-]+$/
+  const PLACEHOLDERS = new Set(['src', 'site', 'foundation', 'workspace', 'project'])
+  const isHighConfidence = s => typeof s === 'string' && ID_RE.test(s) && !PLACEHOLDERS.has(s)
+
+  if (!workspaceRoot || workspaceRoot === foundationDir) return null
+  try {
+    const wsPkg = JSON.parse(await readFile(join(workspaceRoot, 'package.json'), 'utf8'))
+    const wsName = typeof wsPkg.name === 'string'
+      ? wsPkg.name.toLowerCase().replace(/[^a-z0-9_-]/g, '-').replace(/^-+|-+$/g, '')
+      : null
+    if (isHighConfidence(wsName)) return wsName
+  } catch { /* no workspace package.json — skip */ }
+  return null
+}
+
+/**
+ * Build a list of contextual `uniweb.id` suggestions for first-time publishes.
+ *
+ * The CLI never auto-picks an id (Diego's principle: a bare folder name like
+ * "src" is wrong, and silently committing to it would couple the registry
+ * id to scaffold noise the user can't easily undo). Instead, suggest names
+ * derived from signals the workspace already exposes:
+ *
+ *   - **Sibling site name.** When exactly one site exists in the workspace,
+ *     the user's mental model is "this foundation is FOR that site" — so
+ *     the site's name (or "<site>-foundation" if it would collide with the
+ *     site's own package name) is a natural pick.
+ *   - **Workspace name.** A workspace package.json often carries a name
+ *     more meaningful than the foundation folder ("acme-marketing" vs "src").
+ *   - **Folder name minus `-src`.** Foundations placed under
+ *     `<name>-src/` strongly suggest `<name>` as the publish id (this
+ *     is the existing default; preserved here for back-compat).
+ *   - **Code-based fallback (M1, M2, …).** When the workspace already has
+ *     other foundations (i.e., the user manages a category of similar
+ *     foundations across sites/projects), suggest the next code in series.
+ *
+ * Returns deduplicated `{ id, why }` entries — `why` is shown next to the
+ * id in both the CI guidance message and the TTY select prompt so the
+ * user can tell at a glance which signal each suggestion comes from.
+ *
+ * The bare scaffold default `pkg.name === 'src'` is excluded by design.
+ * Likewise any non-conforming shape (uppercase, dots, etc.) is filtered
+ * out so users only ever see valid candidates.
+ */
+async function buildIdSuggestions({ foundationDir, workspaceRoot, pkg }) {
+  const ID_RE = /^[a-z0-9_-]+$/
+  const sanitize = s => (typeof s === 'string' ? s.toLowerCase().replace(/[^a-z0-9_-]/g, '-').replace(/^-+|-+$/g, '') : null)
+  const isValid = s => typeof s === 'string' && ID_RE.test(s) && s !== 'src' && s !== 'site'
+
+  const seen = new Set()
+  const out = []
+  const push = (id, why) => {
+    if (!isValid(id) || seen.has(id)) return
+    seen.add(id)
+    out.push({ id, why })
+  }
+
+  // 1. Sibling-site suggestion. Only fires when there's exactly one site
+  //    in the workspace, because that's the unambiguous "for X" case.
+  try {
+    const sites = await findSites(workspaceRoot)
+    if (sites.length === 1) {
+      const sitePath = sites[0]
+      try {
+        const sitePkg = JSON.parse(await readFile(join(workspaceRoot, sitePath, 'package.json'), 'utf8'))
+        const siteName = sanitize(sitePkg.name)
+        if (siteName) {
+          push(siteName, `matches your site "${siteName}"`)
+          push(`${siteName}-foundation`, `derived from your site "${siteName}"`)
+        }
+      } catch { /* missing or malformed site package.json — skip */ }
+    }
+  } catch { /* findSites can fail in odd workspaces; non-fatal */ }
+
+  // 2. Workspace name suggestion. The workspace package.json's name is
+  //    the user's chosen project identity; if it's a clean id, suggest it.
+  try {
+    if (workspaceRoot && workspaceRoot !== foundationDir) {
+      const wsPkg = JSON.parse(await readFile(join(workspaceRoot, 'package.json'), 'utf8'))
+      const wsName = sanitize(wsPkg.name)
+      if (wsName) push(wsName, `matches your workspace "${wsName}"`)
+    }
+  } catch { /* no workspace package.json — skip */ }
+
+  // 3. Folder name minus `-src`. The pre-existing default lives on as a
+  //    suggestion now rather than the auto-pick.
+  if (workspaceRoot && foundationDir !== workspaceRoot) {
+    const folderName = foundationDir.replace(workspaceRoot + '/', '').split('/')[0]
+    const stripped = sanitize(folderName?.replace(/-src$/, ''))
+    if (stripped) push(stripped, `derived from the folder "${folderName}"`)
+  }
+
+  // 4. Code-based fallback. Only suggested when the workspace already has
+  //    multiple foundations — the case Diego flagged (publishers managing
+  //    a category like M1, M2, M3 across sites/projects).
+  try {
+    const foundations = await findFoundations(workspaceRoot)
+    if (foundations.length >= 2) {
+      // Find the next M-number not already used by a sibling foundation's id.
+      const usedCodes = new Set()
+      for (const fp of foundations) {
+        try {
+          const fp_pkg = JSON.parse(await readFile(join(workspaceRoot, fp, 'package.json'), 'utf8'))
+          const id = fp_pkg.uniweb?.id
+          const m = typeof id === 'string' && id.match(/^m(\d+)$/i)
+          if (m) usedCodes.add(parseInt(m[1], 10))
+        } catch { /* skip */ }
+      }
+      let n = 1
+      while (usedCodes.has(n)) n++
+      push(`m${n}`, `next in your "M-code" series`)
+    }
+  } catch { /* findFoundations failed — skip */ }
+
+  return out
+}
+
+/**
+ * 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.
+ */
 function readGitState(dir) {
   try {
-    const sha = execSync('git rev-parse HEAD', {
+    const sha = execSync('git log -1 --format=%H -- .', {
       cwd: dir,
       stdio: ['ignore', 'pipe', 'ignore'],
     }).toString().trim()
-    const status = execSync('git status --porcelain', {
+    const status = execSync('git status --porcelain -- .', {
       cwd: dir,
       stdio: ['ignore', 'pipe', 'ignore'],
     }).toString()