@uniweb/build 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -58,9 +58,9 @@
     "@uniweb/theming": "0.1.3"
   },
   "optionalDependencies": {
-    "@uniweb/content-reader": "1.1.9",
+    "@uniweb/runtime": "0.8.9",
     "@uniweb/schemas": "0.2.1",
-    "@uniweb/runtime": "0.8.9"
+    "@uniweb/content-reader": "1.1.9"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",

package/src/dev/plugin.js

@@ -25,6 +25,7 @@ import { watch } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { build } from 'vite'
+import { resolveFoundationSrcPath } from '../utils/foundation-source-root.js'
 
 /**
  * Create the foundation dev plugin
@@ -168,7 +169,7 @@ export function foundationDevPlugin(options = {}) {
 
       // Watch foundation source for changes
       if (shouldWatch) {
-        const srcPath = join(resolvedFoundationPath, 'src')
+        const srcPath = resolveFoundationSrcPath(resolvedFoundationPath)
 
         // Debounce rebuilds
         let rebuildTimeout = null

package/src/docs.js

@@ -9,6 +9,7 @@ import { readFile, writeFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join, isAbsolute } from 'node:path'
 import { buildSchema } from './schema.js'
+import { resolveFoundationSrcPath } from './utils/foundation-source-root.js'
 
 /**
  * Generate markdown documentation for a single component
@@ -174,7 +175,7 @@ export async function generateDocs(foundationDir, options = {}) {
     schema = JSON.parse(schemaContent)
   } else {
     // Build schema from source
-    const srcDir = join(foundationDir, 'src')
+    const srcDir = resolveFoundationSrcPath(foundationDir)
     if (!existsSync(srcDir)) {
       throw new Error(`Source directory not found: ${srcDir}`)
     }

package/src/foundation/config.js

@@ -25,6 +25,7 @@
 
 import { resolve } from 'node:path'
 import { foundationPlugin } from '../vite-foundation-plugin.js'
+import { resolveFoundationSrcDir } from '../utils/foundation-source-root.js'
 
 /**
  * Default externals for foundations
@@ -61,8 +62,16 @@ const DEFAULT_EXTERNALS = [
  * @returns {Promise<Object>} Vite configuration
  */
 export async function defineFoundationConfig(options = {}) {
+  // Determine foundation root (where vite.config.js is)
+  const foundationRoot = process.cwd()
+
+  // Source directory derived from package.json::main. `'src'` for legacy
+  // nested layouts, `'.'` for flat layouts. The default `entry` follows.
+  const srcDir = resolveFoundationSrcDir(foundationRoot)
+  const defaultEntry = srcDir === '.' ? '_entry.generated.js' : `${srcDir}/_entry.generated.js`
+
   const {
-    entry = 'src/_entry.generated.js',
+    entry = defaultEntry,
     fileName = 'foundation',
     sections: sectionPaths,
     externals: additionalExternals = [],
@@ -74,9 +83,6 @@ export async function defineFoundationConfig(options = {}) {
     ...restOptions
   } = options
 
-  // Determine foundation root (where vite.config.js is)
-  const foundationRoot = process.cwd()
-
   // Build externals list
   const externals = includeDefaultExternals
     ? [...DEFAULT_EXTERNALS, ...additionalExternals]
@@ -109,7 +115,7 @@ export async function defineFoundationConfig(options = {}) {
   // Build the plugins array
   // foundationPlugin handles entry generation and schema building
   const plugins = [
-    foundationPlugin({ srcDir: 'src', sections: sectionPaths }),
+    foundationPlugin({ srcDir, sections: sectionPaths }),
     tailwind && tailwindcss(),
     react(),
     svgr(),

package/src/generate-entry.js

@@ -75,17 +75,23 @@ async function detectHostShareableImports(srcDir) {
 /**
  * Detect foundation config file (for props, vars, etc.)
  *
- * Looks for: foundation.js or foundation.jsx
+ * Looks for (in priority order): main.js, main.jsx, foundation.js, foundation.jsx
+ *
+ * The canonical name is `main.js` (the foundation package's main authored
+ * module). `foundation.js` is the legacy name and remains supported so
+ * existing foundations build without a rename.
  *
  * The file should export:
  * - props (optional) - Foundation-wide props
  * - vars (optional) - CSS custom properties (also read by schema builder)
  * - defaultLayout (optional) - Default layout name
  *
- * Note: Layout components are now discovered from src/layouts/
+ * Note: Layout components are now discovered from layouts/ at the source root.
  */
 function detectFoundationExports(srcDir) {
   const candidates = [
+    { path: 'main.js', ext: 'js' },
+    { path: 'main.jsx', ext: 'jsx' },
     { path: 'foundation.js', ext: 'js' },
     { path: 'foundation.jsx', ext: 'jsx' },
   ]
@@ -374,8 +380,9 @@ export function shouldRegenerateForFile(file, srcDir) {
     return 'meta.js changed'
   }
 
-  // foundation.js / foundation.jsx at root — affects capabilities import
-  if (/^foundation\.(js|jsx)$/.test(rel)) {
+  // main.js / main.jsx / foundation.js / foundation.jsx at root —
+  // the authored declarations file affects the capabilities import.
+  if (/^(main|foundation)\.(js|jsx)$/.test(rel)) {
     return 'foundation config changed'
   }
 

package/src/index.js

@@ -48,7 +48,13 @@ export {
 export { defineFoundationConfig } from './foundation/config.js'
 
 // Site config
-export { defineSiteConfig } from './site/config.js'
+export { defineSiteConfig, detectFoundationType } from './site/config.js'
+
+// Foundation source root resolution (reads package.json::main)
+export { resolveFoundationSrcDir, resolveFoundationSrcPath } from './utils/foundation-source-root.js'
+
+// Package classification (foundation vs site)
+export { classifyPackage, isExtensionPackage } from './utils/classify-package.js'
 
 // Default export is the combined Vite plugin
 export { default } from './vite-foundation-plugin.js'

package/src/schema.js

@@ -19,8 +19,10 @@ import { inferTitle } from './utils/infer-title.js'
 // Component meta file name
 const META_FILE_NAME = 'meta.js'
 
-// Foundation config file name
-const FOUNDATION_FILE_NAME = 'foundation.js'
+// Foundation authored-declarations file name. `main.js` is the canonical
+// new name; `foundation.js` is the legacy name kept for backward compat.
+// Whichever exists at the source root is loaded.
+const FOUNDATION_FILE_NAMES = ['main.js', 'foundation.js']
 
 // Default paths to scan for section types (relative to srcDir)
 const DEFAULT_SECTION_PATHS = ['sections']
@@ -62,18 +64,26 @@ export async function loadComponentMeta(componentDir) {
 }
 
 /**
- * Load package.json from foundation root
- * Extracts identity fields: name, version, description
+ * Load package.json from a foundation's root.
+ * Extracts identity fields: name, version, description.
  *
- * @param {string} srcDir - Source directory (e.g., 'src')
+ * The foundation's `package.json` lives at the *foundation root*, not at
+ * the source root. For the legacy nested layout (`main: "./src/_entry.generated.js"`),
+ * foundation root is `dirname(srcDir)`. For the flat layout
+ * (`main: "./_entry.generated.js"`), `srcDir` IS the foundation root —
+ * so we check srcDir first, then fall back to its parent.
+ *
+ * @param {string} srcDir - Foundation source directory
  * @returns {Object} Identity fields from package.json
  */
 export async function loadPackageJson(srcDir) {
-  // package.json is in the foundation root (parent of srcDir)
-  const foundationRoot = dirname(srcDir)
-  const packagePath = join(foundationRoot, 'package.json')
+  const candidates = [
+    join(srcDir, 'package.json'),          // flat layout: srcDir IS the foundation root
+    join(dirname(srcDir), 'package.json'), // legacy nested layout
+  ]
+  const packagePath = candidates.find(p => existsSync(p))
 
-  if (!existsSync(packagePath)) {
+  if (!packagePath) {
     return {}
   }
 
@@ -94,22 +104,28 @@ export async function loadPackageJson(srcDir) {
 }
 
 /**
- * Load foundation-level config file (foundation.js)
+ * Load foundation-level config file (main.js, fallback foundation.js)
  *
  * Contains foundation-wide configuration:
  * - vars: CSS custom properties sites can override
- * - Layout: Custom layout component
+ * - defaultLayout: Default layout name
+ * - props: Foundation-wide props
  * - Future: providers, middleware, etc.
  */
 export async function loadFoundationConfig(srcDir) {
-  const filePath = join(srcDir, FOUNDATION_FILE_NAME)
-  if (!existsSync(filePath)) {
-    return {}
+  let filePath = null
+  for (const name of FOUNDATION_FILE_NAMES) {
+    const candidate = join(srcDir, name)
+    if (existsSync(candidate)) {
+      filePath = candidate
+      break
+    }
   }
+  if (!filePath) return {}
+
   try {
     const module = await import(pathToFileURL(filePath).href)
     // Support both default export and named exports
-    // Note: Layout/layouts no longer read from foundation.js — layouts come from src/layouts/ discovery
     return {
       ...module.default,
       vars: module.vars || module.default?.vars,

package/src/site/config.js

@@ -25,6 +25,7 @@ import { resolve, dirname, join } from 'node:path'
 import yaml from 'js-yaml'
 import { generateEntryPoint, shouldRegenerateForFile } from '../generate-entry.js'
 import { importMapPlugin } from '../import-map-plugin.js'
+import { resolveFoundationSrcPath } from '../utils/foundation-source-root.js'
 
 /**
  * Normalize a base path for Vite compatibility
@@ -60,7 +61,7 @@ function normalizeBasePath(raw) {
  * @param {string|Object} foundation - Foundation config from site.yml
  * @returns {{ type: 'local'|'npm'|'url', name?: string, url?: string, cssUrl?: string, path?: string }}
  */
-function detectFoundationType(foundation, siteRoot) {
+export function detectFoundationType(foundation, siteRoot) {
   // Object form with explicit URL
   if (foundation && typeof foundation === 'object') {
     if (foundation.url) {
@@ -228,6 +229,16 @@ export async function defineSiteConfig(options = {}) {
   // Read site.yml
   const siteConfig = readSiteConfig(siteRoot)
 
+  // Allow callers to override `foundation:` without modifying site.yml on
+  // disk. Used by `uniweb deploy` to substitute a workspace-local file: ref
+  // with the resolved registry ref (`@ns/name@ver`) for the duration of the
+  // deploy build, so the site builds in runtime/link mode against the just-
+  // published artifact instead of bundling the local source.
+  const foundationOverride = process.env.UNIWEB_FOUNDATION_REF
+  if (foundationOverride) {
+    siteConfig.foundation = foundationOverride
+  }
+
   // Determine base path for deployment (priority: option > env > site.yml)
   // Normalize: ensure leading slash, collapse repeated slashes, add trailing slash for Vite
   const rawBase = baseOption || process.env.UNIWEB_BASE || siteConfig.base
@@ -283,7 +294,7 @@ export async function defineSiteConfig(options = {}) {
   const ensureFoundationEntryPlugin = !isRuntimeMode && foundationInfo.type === 'local' ? {
     name: 'uniweb:ensure-foundation-entry',
     async config() {
-      const srcDir = join(foundationInfo.path, 'src')
+      const srcDir = resolveFoundationSrcPath(foundationInfo.path)
       const entryPath = join(srcDir, '_entry.generated.js')
 
       // Always regenerate on dev start to ensure it's current
@@ -300,7 +311,7 @@ export async function defineSiteConfig(options = {}) {
 
     configureServer(server) {
       // Watch foundation src for structural changes that affect the entry
-      const srcDir = join(foundationInfo.path, 'src')
+      const srcDir = resolveFoundationSrcPath(foundationInfo.path)
       const entryPath = join(srcDir, '_entry.generated.js')
 
       server.watcher.add(srcDir)

package/src/utils/classify-package.js

@@ -0,0 +1,102 @@
+/**
+ * Classify a Uniweb package as `'foundation'`, `'site'`, or `null`.
+ *
+ * One sync classifier shared by the build, the CLI, and any tooling that
+ * needs to ask "what kind of Uniweb package is this directory?". Replaces
+ * four duplicated implementations across the CLI that used different
+ * signals and could disagree at the edges.
+ *
+ * Signals are checked strict-first, lenient-fallback:
+ *
+ *   1. `package.json::main` matches `_entry.generated.js`  → foundation
+ *      (mandatory by build contract; uniquely identifies a Uniweb foundation;
+ *      set at scaffold time, before any install or build)
+ *   2. `site.yml` or `document.yml` at the package root    → site
+ *   3. Authored declarations file (`main.js`, fallback `foundation.js`) at
+ *      the resolved source root                            → foundation
+ *      (covers unscaffolded directories without `package.json` yet)
+ *   4. `pages/` at the package root                        → site
+ *   5. otherwise                                           → null
+ *
+ * Sync because the I/O is microsecond-scale and consumers were already
+ * blocking on the async version. Sync also lets workspace-scan helpers
+ * (findFoundations, findSites) be plain `.filter()` calls.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolveFoundationSrcPath } from './foundation-source-root.js'
+
+/**
+ * @param {string} packagePath - Absolute path to the package directory.
+ * @returns {'foundation'|'site'|null}
+ */
+export function classifyPackage(packagePath) {
+  // 1. Strongest foundation marker: package.json::main points at the
+  //    build-generated entry. Only Uniweb foundations have this shape.
+  const pkgPath = join(packagePath, 'package.json')
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+      if (typeof pkg.main === 'string' && /_entry\.generated\.js$/.test(pkg.main)) {
+        return 'foundation'
+      }
+    } catch {
+      // Malformed package.json — fall through to file-based signals.
+    }
+  }
+
+  // 2. Strongest site marker: configuration file at root.
+  if (existsSync(join(packagePath, 'site.yml')) ||
+      existsSync(join(packagePath, 'document.yml'))) {
+    return 'site'
+  }
+
+  // 3. Foundation fallback for unscaffolded directories: authored
+  //    declarations file at the resolved source root. Accept both the
+  //    new name (main.js) and the legacy name (foundation.js).
+  const srcDir = resolveFoundationSrcPath(packagePath)
+  if (existsSync(join(srcDir, 'main.js'))) return 'foundation'
+  if (existsSync(join(srcDir, 'foundation.js'))) return 'foundation'
+
+  // 4. Site fallback: pages/ at root.
+  if (existsSync(join(packagePath, 'pages'))) return 'site'
+
+  return null
+}
+
+/**
+ * Check whether a foundation package declares `extension: true` in its
+ * authored declarations file. Uses a regex on the source rather than
+ * importing the module — keeps the classifier sync and side-effect-free,
+ * and works before any install.
+ *
+ * @param {string} packagePath - Absolute path to the package directory.
+ * @returns {boolean}
+ */
+export function isExtensionPackage(packagePath) {
+  const srcDir = resolveFoundationSrcPath(packagePath)
+  // Prefer the schema's recorded role if the build has run.
+  const schemaPath = join(packagePath, 'dist', 'meta', 'schema.json')
+  if (existsSync(schemaPath)) {
+    try {
+      const schema = JSON.parse(readFileSync(schemaPath, 'utf8'))
+      if (schema?._self?.role === 'extension') return true
+    } catch {
+      // Fall through to source-based check.
+    }
+  }
+  // Source-based fallback. Accept both filenames.
+  for (const name of ['main.js', 'foundation.js']) {
+    const filePath = join(srcDir, name)
+    if (existsSync(filePath)) {
+      try {
+        const content = readFileSync(filePath, 'utf8')
+        return /extension\s*:\s*true/.test(content)
+      } catch {
+        return false
+      }
+    }
+  }
+  return false
+}

package/src/utils/foundation-source-root.js

@@ -0,0 +1,65 @@
+/**
+ * Resolve a foundation package's source root by reading its `package.json::main`.
+ *
+ * Two layouts are supported:
+ *
+ *   - Nested (legacy): `main: "./src/_entry.generated.js"` → source root is `<foundationDir>/src/`
+ *   - Flat: `main: "./_entry.generated.js"` → source root is `<foundationDir>/`
+ *
+ * The build derives every other path (sections, components, layouts, foundation.js,
+ * styles.css, the generated entry) from this single value. There is no filesystem
+ * probing — `main` is the source of truth for where the package's code lives,
+ * which is also exactly what npm-style consumers use.
+ *
+ * Existing foundations in the wild keep `main: "./src/_entry.generated.js"` and
+ * resolve to the same nested layout they always had. New scaffolds (per the
+ * first-run-ux plan, Thread D) ship with the flat layout and `main: "./_entry.generated.js"`.
+ */
+
+import { readFileSync, existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+/**
+ * Resolve a foundation's source directory (relative to the foundation root).
+ *
+ * @param {string} foundationDir - Absolute path to the foundation package root.
+ * @returns {string} Source directory, relative to `foundationDir` (e.g. `'src'` or `'.'`).
+ */
+export function resolveFoundationSrcDir(foundationDir) {
+  const pkgPath = join(foundationDir, 'package.json')
+  if (!existsSync(pkgPath)) {
+    // No package.json — fall back to legacy nested layout. Don't throw; the
+    // caller (e.g. the docs builder) may be inspecting a partial directory
+    // and existsSync checks downstream will surface the real error.
+    return 'src'
+  }
+
+  let pkg
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+  } catch {
+    return 'src'
+  }
+
+  const main = pkg.main
+  if (typeof main !== 'string' || !main) {
+    return 'src'
+  }
+
+  // dirname('./src/_entry.generated.js') → './src'    → 'src'
+  // dirname('./_entry.generated.js')      → '.'        → '.'
+  // dirname('src/_entry.generated.js')    → 'src'      → 'src'
+  const dir = dirname(main).replace(/^\.\//, '')
+  return dir || '.'
+}
+
+/**
+ * Resolve a foundation's absolute source directory.
+ *
+ * @param {string} foundationDir - Absolute path to the foundation package root.
+ * @returns {string} Absolute path to the source directory.
+ */
+export function resolveFoundationSrcPath(foundationDir) {
+  const srcDir = resolveFoundationSrcDir(foundationDir)
+  return srcDir === '.' ? foundationDir : resolve(foundationDir, srcDir)
+}

package/src/vite-foundation-plugin.js

@@ -134,8 +134,10 @@ async function emitRuntimePin(outDir, projectRoot) {
   if (!runtimeVersion) return
 
   // Read foundation's own package.json for an optional runtimePolicy
-  // field. Default policy (auto-patch) lives at the registry layer; we
-  // only record the foundation's override if explicitly set.
+  // field. Default policy (auto-minor) is applied platform-side when
+  // the field is omitted; we only record the foundation's override
+  // here if explicitly set. See framework/docs/reference/foundation-config.md
+  // for the full set of `uniweb.*` fields foundations can declare.
   let policy = null
   try {
     const foundationPkgPath = join(projectRoot, 'package.json')