uniweb 0.10.13 → 0.12.0

package/src/commands/publish.js

@@ -12,14 +12,15 @@
  */
 
 import { existsSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
+import { readFile, writeFile } 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 { getRegistryUrl } from '../utils/config.js'
-import { findWorkspaceRoot, findFoundations, findSites, classifyPackage, promptSelect } from '../utils/workspace.js'
+import { findWorkspaceRoot, findFoundations, findSites, promptSelect } from '../utils/workspace.js'
 import { isNonInteractive, getCliPrefix } from '../utils/interactive.js'
 
 // Colors for terminal output
@@ -62,7 +63,7 @@ async function resolveFoundationDir(args) {
   const prefix = getCliPrefix()
 
   // Check if current directory is a foundation
-  const type = await classifyPackage(cwd)
+  const type = classifyPackage(cwd)
   if (type === 'foundation') {
     return cwd
   }
@@ -128,6 +129,21 @@ function parseNamespace(args) {
   return args[idx + 1]
 }
 
+/**
+ * Parse --name <id> from args.
+ * The publish-time "id" — the bare-name segment in the registry name.
+ * Distinct from `package.json::name` (a workspace concern). Persisted
+ * to `package.json::uniweb.id` after the first successful publish so
+ * it doesn't need to be supplied again.
+ * @param {string[]} args
+ * @returns {string|null}
+ */
+function parseName(args) {
+  const idx = args.indexOf('--name')
+  if (idx === -1 || !args[idx + 1]) return null
+  return args[idx + 1]
+}
+
 /**
  * Parse --edit-access <policy> from args.
  * @param {string[]} args
@@ -150,16 +166,24 @@ function parseEditAccess(args) {
 export async function publish(args = []) {
   const isLocal = args.includes('--local')
   const isDryRun = args.includes('--dry-run')
+  // --propagate opts the new version into the registry's version-update
+  // walk: trusting sites whose policy permits the jump pick it up
+  // automatically via gated rollout. Without --propagate (default
+  // 'silent'), the artifact is stored but no site moves until republish
+  // or manual refresh.
+  const isPropagate = args.includes('--propagate')
   const registryUrl = parseRegistryUrl(args)
   const editAccess = parseEditAccess(args)
   const namespaceFlag = parseNamespace(args)
+  const nameFlag = parseName(args)
 
   // 1. Resolve foundation directory
   const foundationDir = await resolveFoundationDir(args)
 
-  // Verify it's actually a foundation (has src/foundation.js)
-  if (!existsSync(join(foundationDir, 'src', 'foundation.js'))) {
-    error('Not a foundation directory (no src/foundation.js)')
+  // Verify it's actually a foundation (canonical classifier checks
+  // package.json::main, then main.js, then legacy foundation.js).
+  if (classifyPackage(foundationDir) !== 'foundation') {
+    error(`Not a foundation directory: ${foundationDir}`)
     process.exit(1)
   }
 
@@ -201,45 +225,206 @@ export async function publish(args = []) {
     process.exit(1)
   }
 
-  // 3b. Resolve namespace (priority: --namespace flag > package.json uniweb.namespace > scoped name)
-  const pkg = JSON.parse(await readFile(join(foundationDir, 'package.json'), 'utf8'))
+  // 3b. Resolve scope and foundation id.
+  //
+  // The publish-time identity is two pieces: a SCOPE (org `@`, personal `~`,
+  // or empty → server-resolved personal) and an ID (the bare name segment).
+  // They live in different places and get different defaults.
+  //
+  // Scope priority:
+  //   1. --namespace <handle> CLI flag           → forces `@<handle>` org scope
+  //   2. Sigil in `package.json::name`:
+  //        - `@org/x`                            → `@org`
+  //        - `~user/x`                           → `~user` (personal alias)
+  //   3. `package.json::uniweb.namespace`        → legacy explicit org field
+  //   4. (none)                                  → empty scope; server attaches
+  //                                                 the publisher's personal
+  //                                                 scope at upload time
+  //
+  // ID priority (the bare name segment):
+  //   1. --name <id> CLI flag                    → override
+  //   2. Sigil-stripped `package.json::name`     → @org/<id> or ~user/<id>
+  //   3. `package.json::uniweb.id`               → persisted publish-id
+  //   4. Interactive prompt                      → and write back to
+  //                                                 `package.json::uniweb.id`
+  //                                                 so future publishes don't
+  //                                                 re-prompt.
+  //   5. Non-interactive without a usable id     → fail with guidance.
+  //
+  // Note: a bare `package.json::name` (e.g. the scaffold default `src`)
+  // is intentionally NOT used as a fallback id. The workspace name is for
+  // pnpm linking and the file: dependency in site/package.json — using it
+  // as the publish id would couple the registry identity to the workspace,
+  // exactly what `uniweb.id` exists to prevent. Users who want their
+  // workspace name to be the publish id pass `--name <pkg-name>` once;
+  // it persists.
+  //
+  // Why two storage locations for an ID? `package.json::name` is a
+  // workspace concern — pnpm uses it to link packages, sites reference
+  // it via `file:` deps and `site.yml::foundation`. Renaming it cascades
+  // through several files. `uniweb.id` is publish-only — changing it
+  // 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'))
   const uniwebNamespace = pkg.uniweb?.namespace
-  const scopedMatch = rawName.match(/^@([a-z0-9_-]+)\//)
-  const namespace = namespaceFlag || uniwebNamespace || scopedMatch?.[1]
+  const uniwebId = pkg.uniweb?.id
+  const orgScopeMatch = (pkg.name || '').match(/^@([a-z0-9_-]+)\/([a-z0-9_-]+)$/)
+  const personalScopeMatch = (pkg.name || '').match(/^~([a-z0-9_-]+)\/([a-z0-9_-]+)$/)
+
+  // Resolve the SCOPE.
+  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
+  }
+
+  // Resolve the ID.
+  const ID_RE = /^[a-z0-9_-]+$/
+  let foundationName = null
+  let writeBackId = false
+  if (nameFlag) {
+    foundationName = nameFlag
+    // Persist the flag's value when it differs from what's already in
+    // `uniweb.id`. This makes rename a one-shot:
+    //   $ uniweb publish --name new-name
+    // From here on, `uniweb publish` (no flag) keeps using `new-name`.
+    // No-op when --name matches the existing id.
+    if (nameFlag !== uniwebId) writeBackId = true
+  } else if (orgScopeMatch) {
+    foundationName = orgScopeMatch[2]
+  } else if (personalScopeMatch) {
+    foundationName = personalScopeMatch[2]
+  } else if (uniwebId) {
+    foundationName = uniwebId
+  }
+  if (!foundationName) {
+    // No id resolvable from any field. Prompt — or fail in non-interactive.
+    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)
+    }
+
+    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'
 
-  if (!namespace) {
-    error('Namespace is required for publishing.')
     console.log('')
-    console.log(`  ${colors.dim}Use one of:${colors.reset}`)
-    console.log(`    ${colors.cyan}uniweb publish --namespace <org-handle>${colors.reset}`)
-    console.log(`    ${colors.dim}Add ${colors.reset}"uniweb": { "namespace": "<org-handle>" }${colors.dim} to package.json${colors.reset}`)
-    console.log(`    ${colors.dim}Or use a scoped name: ${colors.reset}"name": "@org/foundation"${colors.dim} in package.json${colors.reset}`)
+    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
+    writeBackId = true
+  }
+
+  // Validate the resolved id (may have come from any source).
+  if (!ID_RE.test(foundationName)) {
+    error(`Invalid foundation name: "${foundationName}"`)
+    console.log(`  ${colors.dim}Names must be lowercase letters, digits, hyphens, or underscores.${colors.reset}`)
     process.exit(1)
   }
 
-  // Construct scoped name: @namespace/foundationName
-  const foundationName = scopedMatch ? rawName.slice(scopedMatch[0].length) : rawName
-  const name = `@${namespace}/${foundationName}`
+  // Persist the id so future publishes don't re-prompt.
+  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}`)
+  }
+
+  // The registry name. Three cases:
+  //
+  //   1. Explicit scope (`@org/x` or `~user/x`)         → `<sigil><name>/<base>`.
+  //   2. Empty-scope, --local                           → synthesize a
+  //        personal-scope form `~<loginName-or-sub-or-'me'>/<base>` so the
+  //        local index mirrors what production will write. This is the
+  //        local mock's stand-in for the server-side memberId resolution.
+  //   3. Empty-scope, remote                            → send the bare
+  //        name. The Worker attaches the personal scope server-side
+  //        (anchoring to the `sub` claim), and the publish response
+  //        carries the canonical URL back to the CLI for the receipt.
+  let name
+  if (scopeSigil) {
+    name = `${scopeSigil}${scopeName}/${foundationName}`
+  } else if (isLocal) {
+    const localAuth = await readAuth()
+    const personalSeed = localAuth?.loginName || localAuth?.sub || 'me'
+    name = `~${personalSeed}/${foundationName}`
+  } else {
+    name = foundationName
+  }
 
-  // 3c. Advisory namespace check (Worker enforces — this is for early UX feedback)
+  // 3c. Advisory scope authorization (Worker enforces — this is for early UX feedback)
   if (!isLocal) {
     const auth = await readAuth()
-    if (auth?.token) {
-      try {
-        const payload = JSON.parse(atob(auth.token.split('.')[1]))
-        if (payload.namespaces && !payload.namespaces.includes(namespace)) {
-          error(`You don't have publish access to namespace "${colors.bright}@${namespace}${colors.reset}"`)
-          if (payload.namespaces.length > 0) {
-            console.log(`  ${colors.dim}Your namespaces: ${payload.namespaces.map(n => '@' + n).join(', ')}${colors.reset}`)
-          } else {
-            console.log(`  ${colors.dim}You don't belong to any organizations. Ask an admin to add you.${colors.reset}`)
-          }
-          process.exit(1)
+    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}`)
         }
-      } catch {
-        // JWT decode failed — let the Worker validate
+        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}`)
+        process.exit(1)
       }
     }
+    // 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)
@@ -288,13 +473,15 @@ export async function publish(args = []) {
   const auth = isLocal ? null : await readAuth()
   const publishMetadata = {
     publishedBy: auth?.email || (isLocal ? 'local' : 'cli'),
+    classification: isPropagate ? 'propagate' : 'silent',
   }
   if (editAccess) {
     publishMetadata.editAccess = editAccess
   }
 
+  let publishResult
   try {
-    await registry.publish(name, version, distDir, publishMetadata)
+    publishResult = 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.`)
@@ -309,6 +496,24 @@ 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 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,
+    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('')
@@ -351,4 +556,20 @@ function bumpPatch(version) {
   return parts.join('.')
 }
 
+function readGitState(dir) {
+  try {
+    const sha = execSync('git rev-parse HEAD', {
+      cwd: dir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString().trim()
+    const status = execSync('git status --porcelain', {
+      cwd: dir,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString()
+    return { gitSha: sha || null, gitDirty: status.length > 0 }
+  } catch {
+    return { gitSha: null, gitDirty: false }
+  }
+}
+
 export default publish

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-04-27T20:54:30.546Z",
+  "generatedAt": "2026-04-29T13:02:15.924Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.11.9",
+      "version": "0.13.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -92,7 +92,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.2.9",
+      "version": "0.3.0",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/index.js

@@ -201,7 +201,7 @@ async function createFromPackageTemplates(projectDir, projectName, options = {})
   // 1. Scaffold workspace
   await scaffoldWorkspace(projectDir, {
     projectName,
-    workspaceGlobs: ['foundation', 'site'],
+    workspaceGlobs: ['site', 'src'],
     scripts: {
       dev: filterCmd(pm, 'site', 'dev'),
       build: 'uniweb build',
@@ -209,10 +209,13 @@ async function createFromPackageTemplates(projectDir, projectName, options = {})
     },
   }, { onProgress, onWarning })
 
-  // 2. Scaffold foundation
+  // 2. Scaffold foundation (folder: src/, package name: src)
+  // The folder name 'src' carries the meaning — a foundation is the site's
+  // source code. The package name 'src' keeps it unique within the
+  // workspace, since 'site' is taken by the site package.
   onProgress?.('Creating foundation...')
-  await scaffoldFoundation(join(projectDir, 'foundation'), {
-    name: 'foundation',
+  await scaffoldFoundation(join(projectDir, 'src'), {
+    name: 'src',
     projectName,
     isExtension: false,
   }, { onProgress, onWarning })
@@ -222,8 +225,9 @@ async function createFromPackageTemplates(projectDir, projectName, options = {})
   await scaffoldSite(join(projectDir, 'site'), {
     name: 'site',
     projectName,
-    foundationName: 'foundation',
-    foundationPath: 'file:../foundation',
+    foundationName: 'src',
+    foundationPath: 'file:../src',
+    foundationRef: 'src',
   }, { onProgress, onWarning })
 
   // 4. Apply starter content (unless creating a "none" project)
@@ -264,9 +268,12 @@ async function createFromContentTemplate(projectDir, projectName, metadata, temp
   const { onProgress, onWarning, pm = 'pnpm' } = options
 
   // Determine packages to create
+  // Default single-foundation single-site project uses package names
+  // 'src' (folder: src/) and 'site' (folder: site/). The folder
+  // convention is set in computePlacement() below.
   const packages = metadata.packages || [
-    { type: 'foundation', name: 'foundation' },
-    { type: 'site', name: 'site', foundation: 'foundation' },
+    { type: 'foundation', name: 'src' },
+    { type: 'site', name: 'site', foundation: 'src' },
   ]
 
   // Compute placement for each package
@@ -314,21 +321,25 @@ async function createFromContentTemplate(projectDir, projectName, metadata, temp
       }, { onProgress, onWarning })
     } else if (pkg.type === 'site') {
       // Find the foundation this site wires to
-      const foundationName = pkg.foundation || 'foundation'
+      const foundationName = pkg.foundation || 'src'
       const foundationPkg = placed.find(p =>
         (p.type === 'foundation') && (p.name === foundationName)
       )
       const foundationPath = foundationPkg
         ? computeFoundationFilePath(pkg.relativePath, foundationPkg.relativePath)
-        : 'file:../foundation'
+        : 'file:../src'
 
       onProgress?.(`Creating site: ${pkg.name}...`)
+      // Always write `foundation: <name>` to site.yml — the value is
+      // never the implicit default in the new layout (the build's
+      // `detectFoundationType` defaults to 'foundation' when absent,
+      // which doesn't match 'src').
       await scaffoldSite(fullPath, {
         name: pkg.name,
         projectName,
         foundationName,
         foundationPath,
-        foundationRef: foundationName !== 'foundation' ? foundationName : undefined,
+        foundationRef: foundationName,
       }, { onProgress, onWarning })
     }
 
@@ -355,7 +366,9 @@ async function createFromContentTemplate(projectDir, projectName, metadata, temp
  * Compute placement (relative paths) for packages
  *
  * Rules:
- * - 1 foundation named "foundation" → foundation/
+ * - 1 foundation → src/             (folder name is 'src' regardless of package name;
+ *                                    the package name is typically 'src' or
+ *                                    whatever the template declared)
  * - Multiple foundations → foundations/{name}/
  * - Extensions → extensions/{name}/
  * - 1 site named "site" → site/
@@ -369,8 +382,8 @@ function computePlacement(packages) {
   const placed = []
 
   for (const f of foundations) {
-    if (foundations.length === 1 && f.name === 'foundation') {
-      placed.push({ ...f, relativePath: 'foundation' })
+    if (foundations.length === 1) {
+      placed.push({ ...f, relativePath: 'src' })
     } else {
       placed.push({ ...f, relativePath: `foundations/${f.name}` })
     }

package/src/utils/auth.js

@@ -5,6 +5,22 @@
  * User-global (not workspace-local) — you publish as yourself, not as a project.
  *
  * Used by `login`, `publish`, and `deploy` commands.
+ *
+ * Stored shape (auth.json):
+ *   {
+ *     token: string,           // bearer JWT, sent in Authorization: Bearer <token>
+ *     email: string,           // signup_email; permanent, deliverable
+ *     loginName?: string,      // PHP session login_name; immutable per session model
+ *     sub?: string,            // memberId from JWT; permanent, numeric
+ *     namespaces?: string[],   // org handles the user can publish under
+ *     expiresAt?: string       // ISO timestamp; JWT exp claim
+ *   }
+ *
+ * The extra identity fields (loginName, sub, namespaces) are decoded from
+ * the JWT at write time and persisted alongside the token. They're cheap
+ * to derive (HS256 payload is base64url-encoded JSON), but persisting them
+ * means callers don't need to decode the JWT themselves to ask
+ * "who is the user?" — they just `readAuth()`.
  */
 
 import { existsSync } from 'node:fs'
@@ -29,28 +45,88 @@ export function getAuthPath() {
 }
 
 /**
- * Read stored credentials.
- * @returns {Promise<{ token: string, email: string, expiresAt?: string } | null>}
+ * Decode the payload of a JWT. Returns `null` for malformed tokens.
+ * No signature verification — that's the server's job; we just want to
+ * read the claims locally.
+ *
+ * @param {string} token
+ * @returns {Object|null}
+ */
+export function decodeJwtPayload(token) {
+  if (typeof token !== 'string') return null
+  const parts = token.split('.')
+  if (parts.length < 2) return null
+  try {
+    // base64url → base64
+    const b64 = parts[1].replace(/-/g, '+').replace(/_/g, '/')
+    return JSON.parse(Buffer.from(b64, 'base64').toString('utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Read stored credentials. If the persisted record predates the
+ * identity-fields plumbing (no loginName/sub/namespaces) but has a
+ * token, derive the missing fields from the JWT in memory so callers
+ * see a consistent shape regardless of write generation.
+ *
+ * @returns {Promise<{ token: string, email: string, loginName?: string, sub?: string, namespaces?: string[], expiresAt?: string } | null>}
  */
 export async function readAuth() {
   const authPath = getAuthPath()
   if (!existsSync(authPath)) return null
 
+  let auth
   try {
-    return JSON.parse(await readFile(authPath, 'utf8'))
+    auth = JSON.parse(await readFile(authPath, 'utf8'))
   } catch {
     return null
   }
+
+  // Backfill identity fields from the JWT for older auth.json files
+  // that were written before this plumbing existed. Read-only — the
+  // file isn't rewritten until the next login.
+  if (auth?.token && (auth.loginName === undefined || auth.sub === undefined || auth.namespaces === undefined)) {
+    const payload = decodeJwtPayload(auth.token)
+    if (payload) {
+      if (auth.loginName === undefined && typeof payload.loginName === 'string') {
+        auth.loginName = payload.loginName
+      }
+      if (auth.sub === undefined && typeof payload.sub === 'string') {
+        auth.sub = payload.sub
+      }
+      if (auth.namespaces === undefined && Array.isArray(payload.namespaces)) {
+        auth.namespaces = payload.namespaces
+      }
+    }
+  }
+
+  return auth
 }
 
 /**
- * Write credentials to storage.
- * @param {{ token: string, email: string, expiresAt?: string }} auth
+ * Write credentials to storage. Decodes the JWT and persists the
+ * identity claims (loginName, sub, namespaces) alongside the token,
+ * so future `readAuth()` calls don't have to decode it themselves.
+ *
+ * @param {{ token: string, email: string, expiresAt?: string }} auth - Caller passes the basics; identity fields are derived.
  */
 export async function writeAuth(auth) {
+  const record = { ...auth }
+
+  if (record.token) {
+    const payload = decodeJwtPayload(record.token)
+    if (payload) {
+      if (typeof payload.loginName === 'string') record.loginName = payload.loginName
+      if (typeof payload.sub === 'string') record.sub = payload.sub
+      if (Array.isArray(payload.namespaces)) record.namespaces = payload.namespaces
+    }
+  }
+
   const dir = getAuthDir()
   await mkdir(dir, { recursive: true })
-  await writeFile(join(dir, 'auth.json'), JSON.stringify(auth, null, 2))
+  await writeFile(join(dir, 'auth.json'), JSON.stringify(record, null, 2))
 }
 
 /**

package/src/utils/names.js

@@ -14,12 +14,19 @@ import { join } from 'node:path'
  * Names that must not be used as package names.
  * - JS module keywords: default, undefined, null, true, false
  * - Node/filesystem: node_modules, package
- * - Common directory names that would cause confusion: src, dist, build
+ * - Common build-output directories: dist, build (would shadow `dist/` /
+ *   `build/` references)
+ *
+ * Note: `src` is NOT reserved. A foundation in `src/` whose package name is
+ * also `src` is the default scaffold pattern — folder name and package name
+ * match. Multi-foundation co-located workspaces still use suffixes
+ * (`<project>-src`) because pnpm requires workspace-unique package names;
+ * that's a real constraint, not aesthetic.
  */
 const RESERVED_NAMES = new Set([
   'default', 'undefined', 'null', 'true', 'false',
   'node_modules', 'package',
-  'src', 'dist', 'build',
+  'dist', 'build',
 ])
 
 /**