uniweb 0.10.13 → 0.12.0

package/src/commands/deploy.js

@@ -42,6 +42,8 @@ import { resolve, join, basename, relative, sep } from 'node:path'
 import { execSync } from 'node:child_process'
 import yaml from 'js-yaml'
 
+import { detectFoundationType } from '@uniweb/build'
+
 import { ensureAuth } from '../utils/auth.js'
 import { getBackendUrl, getRegistryUrl } from '../utils/config.js'
 import {
@@ -55,6 +57,70 @@ import { isNonInteractive, getCliPrefix } from '../utils/interactive.js'
 const REVIEW_TIMEOUT_MS = 15 * 60 * 1000 // 15 min — matches PHP session TTL
 const ASSET_UPLOAD_CONCURRENCY = 6
 const ASSET_UPLOAD_RETRIES = 2
+
+const FOUNDATION_POLICIES = new Set(['exact', 'auto-patch', 'auto-minor'])
+
+/**
+ * Parse the `foundation:` field from site.yml into a normalized shape.
+ *
+ * Accepts:
+ *   - string: '@uniweb/votiverse@0.1.1'
+ *   - object: { ref: '@uniweb/votiverse@0.1.1', policy?: ..., pinned?: true }
+ *
+ * Returns one of:
+ *   - { error: 'description of what's wrong' }
+ *   - { normalized, policy?, pinned }   where `normalized` is whichever
+ *     shape we received (string or { ref, policy?, pinned? }) — the Worker
+ *     accepts both. `policy`/`pinned` are also returned individually so
+ *     the CLI can print friendly diagnostics.
+ *
+ * Validation rules (mirrors publish.js::parseFoundationConfig):
+ *   - `policy` must be one of 'exact', 'auto-patch', 'auto-minor'
+ *   - `pinned: true` + `policy: not-exact` is rejected as conflicting
+ */
+function parseSiteFoundation(input) {
+  if (typeof input === 'string') {
+    return { normalized: input, policy: null, pinned: false }
+  }
+  if (!input || typeof input !== 'object') {
+    return { error: 'foundation must be a string or object' }
+  }
+
+  // Object form must carry `ref`; everything else is metadata.
+  if (!input.ref || typeof input.ref !== 'string') {
+    return { error: 'foundation.ref is required when using object form' }
+  }
+  if (!/^@[a-z0-9_-]+\/[a-z0-9_-]+@.+$/.test(input.ref)) {
+    return {
+      error: `foundation.ref does not match @namespace/name@version: '${input.ref}'`,
+    }
+  }
+
+  let policy = null
+  if (input.policy != null) {
+    if (!FOUNDATION_POLICIES.has(input.policy)) {
+      return {
+        error: `foundation.policy must be one of 'exact', 'auto-patch', 'auto-minor' (got '${input.policy}')`,
+      }
+    }
+    policy = input.policy
+  }
+  const pinned = input.pinned === true
+
+  if (pinned && policy && policy !== 'exact') {
+    return {
+      error: `foundation: 'pinned: true' conflicts with policy '${policy}'. ` +
+        `Use either 'pinned: true' or 'policy: \"exact\"' (they're equivalent), or drop one.`,
+    }
+  }
+
+  return {
+    normalized: { ref: input.ref, ...(policy ? { policy } : {}), ...(pinned ? { pinned: true } : {}) },
+    policy: pinned ? 'exact' : policy,
+    pinned,
+  }
+}
+
 // Vite content-addresses these formats. Same filename → same content, so we
 // can skip upload without checking size. Unhashed formats fall through to
 // size-compare diffing.
@@ -98,6 +164,100 @@ const say = {
   dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`),
 }
 
+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 }
+  }
+}
+
+function composeFoundationUrl(ref, registryBase) {
+  if (typeof ref !== 'string') return null
+  if (ref.startsWith('https://') || ref.startsWith('http://')) return ref
+  const m = ref.match(/^(@[^/]+\/[^@]+|[^@]+)@(.+)$/)
+  if (!m || !registryBase) return null
+  const [, name, version] = m
+  return `${registryBase.replace(/\/$/, '')}/${name}/${version}/`
+}
+
+/**
+ * Inspect a workspace-local foundation's `dist/publish.json` (Phase 1 receipt)
+ * and decide whether it's stale relative to the current source tree.
+ *
+ * Returns `{ stale, reason, receipt }`. The caller decides whether to
+ * auto-publish (Phase 2 default) or fail (`--no-auto-publish`).
+ */
+async function inspectLocalFoundationReceipt(localPath, { dirtyAsStale }) {
+  const receiptPath = join(localPath, 'dist', 'publish.json')
+  let receipt = null
+  try {
+    receipt = JSON.parse(await readFile(receiptPath, 'utf8'))
+  } catch {
+    return { stale: true, reason: 'no dist/publish.json (foundation has not been published from this checkout)' }
+  }
+
+  const { gitSha, gitDirty } = readGitState(localPath)
+  if (!gitSha) {
+    return { stale: true, reason: 'foundation directory is not in a git repo or has no commits', receipt }
+  }
+  if (receipt.publishedFromGitSha && receipt.publishedFromGitSha !== gitSha) {
+    return {
+      stale: true,
+      reason: `foundation has new commits since last publish (${receipt.publishedFromGitSha.slice(0, 7)} → ${gitSha.slice(0, 7)})`,
+      receipt,
+    }
+  }
+  if (gitDirty && dirtyAsStale) {
+    return { stale: true, reason: 'foundation working tree is dirty', receipt }
+  }
+  return { stale: false, receipt }
+}
+
+/**
+ * Read a workspace-local foundation's identity (scoped name + version) from
+ * its `dist/meta/schema.json` + `package.json`, mirroring `publish.js`'s
+ * namespace resolution. Returns the registry ref (`@ns/name@ver`), or null
+ * if any of the inputs are missing.
+ */
+async function deriveLocalFoundationRef(localPath) {
+  let pkg
+  try {
+    pkg = JSON.parse(await readFile(join(localPath, 'package.json'), 'utf8'))
+  } catch {
+    return null
+  }
+
+  let rawName, version
+  try {
+    const schema = JSON.parse(await readFile(join(localPath, 'dist', 'meta', 'schema.json'), 'utf8'))
+    rawName = schema._self?.name
+    version = schema._self?.version
+  } catch {
+    // Fallback to package.json when the build hasn't run yet.
+  }
+  rawName = rawName || pkg.name
+  version = version || pkg.version
+  if (!rawName || !version) return null
+
+  const uniwebNamespace = pkg.uniweb?.namespace
+  const pkgScopeMatch = (pkg.name || '').match(/^@([a-z0-9_-]+)\//)
+  const selfScopeMatch = rawName.match(/^@([a-z0-9_-]+)\//)
+  const namespace = uniwebNamespace || pkgScopeMatch?.[1] || selfScopeMatch?.[1]
+  if (!namespace) return null
+
+  const bareName = selfScopeMatch ? rawName.slice(selfScopeMatch[0].length) : rawName
+  return `@${namespace}/${bareName}@${version}`
+}
+
 // ─── Main ───────────────────────────────────────────────────
 
 export async function deploy(args = []) {
@@ -111,6 +271,11 @@ export async function deploy(args = []) {
   // to DB, so any change the user makes there ends up in site.yml after
   // the loopback finalize roundtrip.
   const forceReview = args.includes('--review')
+  // Phase 2 (deploy-ux-v4): when `foundation:` in site.yml points at a
+  // workspace-local file: ref, deploy auto-publishes the foundation when
+  // its `dist/publish.json` receipt is missing/stale. These flags opt out.
+  const autoPublishFoundation = !args.includes('--no-auto-publish')
+  const treatDirtyAsStale = !args.includes('--no-dirty-as-stale')
 
   const siteDir = await resolveSiteDir(args)
   const backendUrl = getBackendUrl()
@@ -120,13 +285,79 @@ export async function deploy(args = []) {
   // site.id / site.handle from prior deploys.
   const siteYmlPath = join(siteDir, 'site.yml')
   const siteYml = await readSiteYml(siteYmlPath)
-  const foundation = siteYml.foundation
-  if (!foundation) {
+  if (!siteYml.foundation) {
     say.err('site.yml is missing `foundation`.')
     say.dim('Add a line like:  foundation: \'@uniweb/docs-foundation@0.1.20\'')
     process.exit(1)
   }
 
+  // Foundation may be string or object form (see site.yml docs).
+  const fnd = parseSiteFoundation(siteYml.foundation)
+  if (fnd.error) {
+    say.err(`site.yml: ${fnd.error}`)
+    process.exit(1)
+  }
+  // `foundation` is the on-the-wire shape we forward to PHP authorize +
+  // Worker publish. PHP only inspects the namespace via the ref string;
+  // it doesn't care about policy/pinned, so the object form passes through.
+  // The Worker (publish.js::parseFoundationConfig) handles both shapes.
+  let foundation = fnd.normalized
+  if (fnd.policy && fnd.policy !== 'auto-patch') {
+    say.dim(`Foundation policy: ${fnd.policy}${fnd.pinned ? ' (pinned)' : ''}`)
+  } else if (fnd.pinned) {
+    say.dim('Foundation policy: exact (pinned)')
+  }
+
+  // Phase 2: resolve workspace-local `file:` foundation refs.
+  //
+  // The object form of `foundation:` already requires a registry ref
+  // (`@ns/name@ver`) per parseSiteFoundation, so only the string form can
+  // resolve to a local path. Pass-through cases (registry ref, full URL,
+  // npm package) all leave `foundation` untouched. The resolved registry
+  // ref is also passed to the site build via UNIWEB_FOUNDATION_REF so the
+  // build runs in runtime mode against the just-published artifact instead
+  // of bundling the local foundation source. site.yml on disk is never
+  // modified.
+  let foundationBuildOverride = null
+  if (typeof foundation === 'string') {
+    const detected = detectFoundationType(foundation, siteDir)
+    if (detected.type === 'local') {
+      const localPath = detected.path
+      const relPath = relative(siteDir, localPath) || localPath
+
+      const inspection = await inspectLocalFoundationReceipt(localPath, {
+        dirtyAsStale: treatDirtyAsStale,
+      })
+
+      if (inspection.stale && !autoPublishFoundation) {
+        say.err(`Local foundation at ${relPath} is stale: ${inspection.reason}.`)
+        say.dim(`Run \`${getCliPrefix()} publish\` from ${relPath}, or drop --no-auto-publish to let deploy publish it for you.`)
+        process.exit(1)
+      }
+      if (inspection.stale) {
+        say.info(`Foundation at ${relPath} is stale (${inspection.reason}). Auto-publishing…`)
+        console.log('')
+        try {
+          execSync('npx uniweb publish', { cwd: localPath, stdio: 'inherit' })
+        } catch {
+          say.err(`Auto-publish of foundation at ${relPath} failed. See output above.`)
+          process.exit(1)
+        }
+        console.log('')
+      }
+
+      const resolved = await deriveLocalFoundationRef(localPath)
+      if (!resolved) {
+        say.err(`Could not derive a registry ref for foundation at ${relPath}.`)
+        say.dim(`Make sure its package.json has a name + version and a namespace (uniweb.namespace, scoped name, or run \`uniweb publish --namespace <handle>\` once).`)
+        process.exit(1)
+      }
+      say.dim(`Foundation: ${foundation} → ${resolved} (resolved from ${relPath})`)
+      foundation = resolved
+      foundationBuildOverride = resolved
+    }
+  }
+
   // Runtime defaults to "latest" resolved at authorize time.
   let runtimeVersion = siteYml.runtime
   if (!runtimeVersion) {
@@ -160,9 +391,18 @@ export async function deploy(args = []) {
     // link-mode URLs, which auto-enters runtime mode. Prerender also
     // auto-skips for link-mode foundations (HTML is rendered on the
     // serving edge, not here).
+    //
+    // For workspace-local foundations (Phase 2 resolution above),
+    // UNIWEB_FOUNDATION_REF tells defineSiteConfig to use the resolved
+    // registry ref instead of site.yml's literal value, so the build
+    // produces a runtime-mode bundle pointing at the just-published
+    // foundation rather than embedding the local source.
     execSync('npx uniweb build', {
       cwd: siteDir,
       stdio: 'inherit',
+      env: foundationBuildOverride
+        ? { ...process.env, UNIWEB_FOUNDATION_REF: foundationBuildOverride }
+        : process.env,
     })
     console.log('')
   } else if (!existsSync(contentPath)) {
@@ -202,7 +442,7 @@ export async function deploy(args = []) {
     say.info('Dry run — showing what would be deployed:')
     say.dim(`Site dir       : ${siteDir}`)
     say.dim(`site.id        : ${siteYml.site?.id || '(none — would use create flow)'}`)
-    say.dim(`Foundation     : ${foundation}`)
+    say.dim(`Foundation     : ${typeof foundation === 'string' ? foundation : foundation.ref}`)
     say.dim(`Runtime        : ${runtimeVersion}`)
     say.dim(`Languages      : ${languages.join(', ')}`)
     say.dim(`Default locale : ${defaultLanguage}`)
@@ -397,6 +637,25 @@ export async function deploy(args = []) {
   }
   await callPublish({ url: publishUrl, token: publishToken, body: publishPayload })
 
+  // Local event memory — used by future re-deploys (e.g., to skip
+  // redundant work when nothing has changed). Lives under dist/ which is
+  // gitignored; the platform never reads it.
+  const foundationRef = typeof foundation === 'string' ? foundation : foundation?.ref
+  const { gitSha, gitDirty } = readGitState(siteDir)
+  const deployReceipt = {
+    schemaVersion: 1,
+    deployedFromGitSha: gitSha,
+    deployedFromGitDirty: gitDirty,
+    deployedAt: new Date().toISOString(),
+    url: handleResolved ? `https://${handleResolved}.uniweb.website/` : null,
+    foundation: {
+      ref: foundationRef,
+      url: composeFoundationUrl(foundationRef, getRegistryUrl()),
+    },
+    locales: languages,
+  }
+  await writeFile(join(distDir, 'deploy.json'), JSON.stringify(deployReceipt, null, 2) + '\n')
+
   // Write site.id / site.handle / features back to site.yml so the file
   // stays in sync with the live billing state. site.id and site.handle
   // are written on first deploy and any time the server-side handle drifts.

package/src/commands/docs.js

@@ -23,7 +23,7 @@
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { resolve, join, dirname } from 'node:path'
-import { generateDocs } from '@uniweb/build'
+import { generateDocs, resolveFoundationSrcPath, classifyPackage } from '@uniweb/build'
 import {
   isWorkspaceRoot,
   findFoundations,
@@ -160,7 +160,7 @@ ${colors.dim}Schema: https://raw.githubusercontent.com/uniweb/cli/main/schemas/p
 const META_REFERENCE = `
 ${colors.cyan}${colors.bright}Component meta.js Reference${colors.reset}
 
-Component metadata in foundation/src/components/[Name]/meta.js
+Component metadata in <foundation>/components/[Name]/meta.js (or sections/[Name]/meta.js)
 
 ${colors.bright}Identity:${colors.reset}
   ${colors.cyan}title${colors.reset}             Display name in editor
@@ -314,16 +314,15 @@ ${colors.dim}Notes:${colors.reset}
  * Detect if current directory is a foundation
  */
 function isFoundation(dir) {
-  const srcDir = join(dir, 'src')
-  const componentsDir = join(srcDir, 'components')
-  return existsSync(componentsDir)
+  return classifyPackage(dir) === 'foundation'
 }
 
 /**
  * Detect if current directory is a site
  */
 function isSite(dir) {
-  return existsSync(join(dir, 'site.yml')) || existsSync(join(dir, 'site.yaml'))
+  // Use the canonical classifier; also accept legacy `site.yaml`.
+  return classifyPackage(dir) === 'site' || existsSync(join(dir, 'site.yaml'))
 }
 
 /**

package/src/commands/doctor.js

@@ -5,6 +5,7 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { join, resolve, basename, dirname, relative } from 'node:path'
 import yaml from 'js-yaml'
+import { resolveFoundationSrcPath, classifyPackage, isExtensionPackage as buildIsExtensionPackage } from '@uniweb/build'
 import { getCliVersion } from '../versions.js'
 import { readAgentsVersion } from '../utils/agents-stamp.js'
 
@@ -29,36 +30,37 @@ const log = console.log
  * Check if a directory is a site
  */
 function isSite(dir) {
-  return existsSync(join(dir, 'site.yml')) || existsSync(join(dir, 'site.yaml'))
+  // Use the canonical classifier; also accept legacy `site.yaml`
+  // (the classifier only recognizes `.yml` and `.document.yml`).
+  return classifyPackage(dir) === 'site' || existsSync(join(dir, 'site.yaml'))
 }
 
 /**
  * Check if a directory is a foundation
  */
 function isFoundation(dir) {
-  // Primary: has foundation.js config
-  if (existsSync(join(dir, 'src', 'foundation.js'))) return true
-  // Fallback: has src/sections/
-  if (existsSync(join(dir, 'src', 'sections'))) return true
-  // Legacy fallback: has src/components/
-  if (existsSync(join(dir, 'src', 'components'))) return true
-  return false
+  return classifyPackage(dir) === 'foundation'
 }
 
 /**
- * Load foundation.js config from a directory
- * Returns the default export, or null if not found/loadable
+ * Load the foundation's authored declarations file (main.js or legacy
+ * foundation.js) and return a minimal summary used by the doctor.
+ * Returns null if no declarations file is found.
  */
 function loadFoundationJs(dir) {
-  const filePath = join(dir, 'src', 'foundation.js')
-  if (!existsSync(filePath)) return null
-  try {
-    const content = readFileSync(filePath, 'utf8')
-    // Simple extraction: check for extension: true
-    return { extension: /extension\s*:\s*true/.test(content) }
-  } catch {
-    return null
+  const srcDir = resolveFoundationSrcPath(dir)
+  for (const name of ['main.js', 'foundation.js']) {
+    const filePath = join(srcDir, name)
+    if (existsSync(filePath)) {
+      try {
+        const content = readFileSync(filePath, 'utf8')
+        return { extension: /extension\s*:\s*true/.test(content) }
+      } catch {
+        return null
+      }
+    }
   }
+  return null
 }
 
 /**
@@ -78,10 +80,7 @@ function loadSchemaJson(dir) {
  * Check if a foundation is an extension (via schema.json or foundation.js)
  */
 function isExtensionPackage(dir) {
-  const schema = loadSchemaJson(dir)
-  if (schema?._self?.role === 'extension') return true
-  const config = loadFoundationJs(dir)
-  return config?.extension === true
+  return buildIsExtensionPackage(dir)
 }
 
 /**