@rsc-kit/core 0.30.14 → 0.30.16

package/dist/vite.js

@@ -24,7 +24,7 @@ import { loadEnv, parseAst } from "vite";
 import { stampDisplayNames } from "./stableNames.js";
 import { REPORT_FILE, buildReport } from "./buildReport.js";
 import { MANIFEST_PATH, manifestWarning, webManifest } from "./webManifest.js";
-import { ASSET_BASE, allAppAssets, appAssets, headTags, typeOf, } from "./appAssets.js";
+import { ASSET_BASE, allAppAssets, assetFile, appAssets, headTags, shareImageUrls, typeOf, } from "./appAssets.js";
 import { reactCacheImports } from "./reactCache.js";
 import { clientEntries, clientScanPlugin, engineClientEntries, } from "./clientEntries.js";
 import { serverImportsOfClientPackages } from "./clientImports.js";
@@ -33,6 +33,7 @@ import { ownHosts } from "./hostRouting.js";
 import { unrollBarrelImports } from "./barrelImports.js";
 import { hasUseSsr, serverRendererMessage, SERVER_RENDERER, ssrProxyModule, UseSsrError, withoutSsrDirective } from "./useSsr.js";
 import { httpHostCalls } from "./hostCalls.js";
+import { COMMANDS_MODULE_ID, commandFiles, commandsEntry, commandsEntrySource, commandsModule } from "./commandFiles.js";
 import { clientPackages, importsServerRenderer, packageDir as installedPackageDir, packageEntryInGraph, polyfillsToTrace, traceableByName } from "./clientPackages.js";
 // Resolved once per rscKit() call. One build runs in one process, so these are
 // module state rather than threaded through every helper.
@@ -47,6 +48,46 @@ let clientLibraryImports = [];
  * decisions buildApp makes about where stored pages can live.
  */
 let nitroPreset = null;
+/** `src/commands`, read once per build; null until asked. See buildCommands(). */
+let commandsFound = null;
+/**
+ * The presets whose output is a process that Node or Bun starts: where a
+ * command runs. Every other preset is a platform that starts the app itself -
+ * a function, a Worker - and a release step there is not the app's to run.
+ */
+const COMMAND_PRESETS = /^(?:bun|node|node[-_]server|node[-_]cluster)$/;
+/**
+ * The app's commands, for a build that has a process to run them in.
+ *
+ * Decided once, the first time the bundle asks, and every later step reads the
+ * same answer: the table in the bundle, `commands.mjs`, the compile entry and
+ * `.output/rsc-kit.json` cannot disagree about what is there.
+ *
+ * Not the dev server, which has no output to run one from - a command there is
+ * `bun src/commands/<name>.ts`. Not a Worker: its bundle targets workerd, where
+ * the packages a release step wants (a database driver, `node:child_process`)
+ * either resolve to a different build or not at all, so a command that ran there
+ * would run something other than what was written. And not a preset this has not
+ * been run on: it says so, rather than writing an entry for a layout it has not
+ * seen.
+ */
+function buildCommands() {
+    if (resolvedConfig?.command !== "build")
+        return [];
+    if (commandsFound)
+        return commandsFound;
+    const { commands, ignored } = commandFiles(sourceDir);
+    for (const { path, reason } of ignored)
+        log(`${relative(projectRoot, path)} is not a command: ${reason}.`);
+    if (commands.length && !(nitroPreset && COMMAND_PRESETS.test(nitroPreset))) {
+        const names = commands.map((c) => c.name).join(", ");
+        log(nitroPreset?.startsWith("cloudflare")
+            ? `src/commands is not built for a Worker (${names}): the bundle runs on workerd, which is not where a release step runs. Run the file itself, or wrangler.`
+            : `src/commands is built for the bun and node presets, and this build is ${nitroPreset ? `for ${nitroPreset}` : "not using a Nitro preset"} (${names}). Run the file itself from CI.`);
+        return (commandsFound = []);
+    }
+    return (commandsFound = commands);
+}
 /**
  * Modules a runtime provides and no bundle should try to carry.
  *
@@ -195,8 +236,7 @@ let foundAssets = {
     appleIcon: null,
     appleSplash: [],
     screenshots: [],
-    openGraph: null,
-    twitter: null,
+    shareImages: {},
 };
 /** Host functions to generate stubs for — see RscKitOptions.hostActions. */
 let hostActions;
@@ -1393,7 +1433,7 @@ function copyAppAssets(clientDir) {
     if (all.length === 0)
         return;
     for (const asset of all) {
-        const to = join(clientDir, asset.href.slice(1));
+        const to = join(clientDir, assetFile(asset.href.slice(1)));
         mkdirSync(dirname(to), { recursive: true });
         copyFileSync(join(sourceDir, "app", asset.file), to);
     }
@@ -2424,6 +2464,8 @@ const API_METHODS = [
 ];
 /** `orders.section.tsx` — a region of a page that can be refreshed by name. */
 const SECTION_FILE = /\.section\.(tsx|jsx|ts|js)$/;
+/** A share image file: the pages beneath its folder change what they say about themselves. */
+const SHARE_IMAGE_FILE = /^(?:opengraph|twitter)-image[-\w]*\.(?:png|svg|jpe?g|webp|gif|avif)$/i;
 /**
  * Whether a page or a section declares refreshOn. Read from the source, as
  * section names are, because the manifest is written before any bundle exists.
@@ -2489,6 +2531,20 @@ function registerOpenApiRoutes() {
     }
     apiRoutes.set(name, { name, absPath: OPENAPI_ROUTE_ID, methods: ["GET"], generated: { kind: "openapi", file: "" } });
 }
+/** The table behind `runCommand` in the server's entry: src/commands, or nothing where they are not built. */
+function commandsPlugin() {
+    return {
+        name: "rsc-kit:commands",
+        resolveId(id) {
+            if (id === COMMANDS_MODULE_ID)
+                return "\0" + id;
+        },
+        load(id) {
+            if (id === "\0" + COMMANDS_MODULE_ID)
+                return commandsModule(buildCommands());
+        },
+    };
+}
 /** The module behind the synthesised /openapi.json route. */
 function openApiPlugin() {
     return {
@@ -3069,7 +3125,7 @@ export function instrumentationImport(instrumentation) {
     return (`import { ${hooks.map((hook) => `${hook} as __instrumentation_${hook}`).join(", ")} } from ${from}\n` +
         `const __instrumentation: ${type} = { ${hooks.map((hook) => `${hook}: __instrumentation_${hook}`).join(", ")} }`);
 }
-function generateEntryRsc(fallbackOrigin = "") {
+function generateEntryRsc(fallbackOrigin = "", withCommands = false) {
     const instrumentation = instrumentationFile();
     // Every 404 page the app has, and the layouts each renders inside. Computed
     // here rather than looked up at runtime: not-found is not a route, so the
@@ -3146,6 +3202,7 @@ ${
 import { SegmentBoundary } from ${JSON.stringify(join(packageDir, "js/SegmentBoundary"))}
 import { LoadingBoundary } from ${JSON.stringify(join(packageDir, "js/LoadingBoundary"))}
 import { DocumentTitle } from ${JSON.stringify(join(packageDir, "js/DocumentTitle"))}
+import { depthOf, fileWins, folderOf, nearestShareImage } from ${JSON.stringify(join(packageDir, "shareImages"))}
 import { SlotBoundary } from ${JSON.stringify(join(packageDir, "js/SlotBoundary"))}
 import { RouteErrorBoundary } from ${JSON.stringify(join(packageDir, "js/RouteErrorBoundary"))}
 import __rsc_assets from 'virtual:vite-rsc/assets-manifest'
@@ -3199,6 +3256,9 @@ ${mapEntries.join("\n")}
 /** Head tags for the icons and share images found in app/. */
 const APP_HEAD: { tag: any; props: Record<string, string> }[] = ${JSON.stringify(headTags(foundAssets))}
 
+/** The share images found under app/, by the folder each is in - see shareImages.ts. */
+const SHARE_IMAGES: Record<string, { openGraph?: string; twitter?: string }> = ${JSON.stringify(shareImageUrls(foundAssets))}
+
 const WEB_MANIFEST: { href: string; themeColor?: string } | null = ${JSON.stringify(webManifestOptions
         ? {
             href: MANIFEST_PATH,
@@ -3598,7 +3658,9 @@ if (!isolateRuntime) {
   ;(globalThis as { __rscKitShutdown?: () => unknown }).__rscKitShutdown = () => __instrumentation.shutdown?.()
 }
 
-if (__instrumentation.register && !isolateRuntime) {
+// Started to run a command (src/commands), not to serve: register() waits for
+// the command that asks for it, rather than running at import.
+if (__instrumentation.register && !isolateRuntime && !(globalThis as Record<symbol, unknown>)[Symbol.for('rsc-kit.command')]) {
   instrumented().catch((error) => {
     console.error('[rsc-kit] instrumentation.ts register() failed:', error)
 
@@ -4199,13 +4261,35 @@ async function renderTree(
     }
 
     for (const [i, found] of APP_HEAD.entries()) {
-      const props = { ...found.props }
+      head.push(createElement(found.tag, { key: '__a' + i, ...found.props }))
+    }
 
-      if (props.content && /^(og:image|twitter:image)$/.test(props.property ?? props.name ?? '')) {
-        props.content = absolute(props.content)
-      }
+    // The share image files found in app/. The nearest to this page is its
+    // card - unless its metadata exports images from a segment nearer still,
+    // in which case the file is left out and the exported ones render, so a
+    // page that names its own image replaces the site's instead of following
+    // it. Scrapers read the first og:image they meet; a second after the
+    // site's would be a card that never changes.
+    const folder = folderOf(component)
+    const sources = md ? imageSources.get(md) : undefined
+    const shared = (kind: 'openGraph' | 'twitter') => {
+      const file = nearestShareImage(SHARE_IMAGES, folder, kind)
+      const source = sources?.[kind]
+
+      return fileWins(file, source?.exports ? source : null) ? file : null
+    }
+    const ogFile = shared('openGraph')
+    const twitterFile = shared('twitter')
+
+    if (ogFile) head.push(createElement('meta', { key: '__og', property: 'og:image', content: absolute(ogFile.href) }))
 
-      head.push(createElement(found.tag, { key: '__a' + i, ...props }))
+    if (twitterFile) {
+      head.push(createElement('meta', { key: '__tw', name: 'twitter:image', content: absolute(twitterFile.href) }))
+
+      // The card a twitter image implies, unless the page named its own.
+      if ((md?.twitter as { card?: unknown } | undefined)?.card == null) {
+        head.push(createElement('meta', { key: '__twc', name: 'twitter:card', content: 'summary_large_image' }))
+      }
     }
 
     if (md) {
@@ -4305,7 +4389,7 @@ async function renderTree(
         if (og.siteName != null) head.push(tag('og:site_name', og.siteName))
         if (og.type != null) head.push(tag('og:type', og.type))
         if (og.locale != null) head.push(tag('og:locale', og.locale))
-        if (og.images != null) images('og:image', og.images)
+        if (og.images != null && !ogFile) images('og:image', og.images)
       }
 
       if (md.twitter) {
@@ -4316,7 +4400,7 @@ async function renderTree(
         if (tw.description != null) head.push(tag('twitter:description', tw.description))
         if (tw.site != null) head.push(tag('twitter:site', tw.site))
         if (tw.creator != null) head.push(tag('twitter:creator', tw.creator))
-        if (tw.images != null) images('twitter:image', tw.images)
+        if (tw.images != null && !twitterFile) images('twitter:image', tw.images)
       }
 
       // icons is links, not meta. A string is one icon; an object names which
@@ -5209,6 +5293,17 @@ const METADATA_PROBE_GRACE_MS = 20
 
 const METADATA_POSTPONED = Symbol('metadata postponed')
 
+/**
+ * For each of openGraph and twitter, how deep the segment that supplied the
+ * merged object is, and whether it exports images - the other half of the
+ * comparison a share image file is held to. Beside the metadata rather than
+ * inside it, so the object a page's tags are rendered from stays only what
+ * the app wrote.
+ */
+type ImageSources = { openGraph?: { depth: number; exports: boolean }; twitter?: { depth: number; exports: boolean } }
+
+const imageSources = new WeakMap<object, ImageSources>()
+
 export async function resolveMetadata(
   component: string,
   props: Record<string, unknown> = {},
@@ -5273,18 +5368,27 @@ export async function resolveMetadata(
   // happened to declare one of its own.
   const merged: Record<string, unknown> = {}
   const other: Record<string, unknown> = {}
+  const sources: ImageSources = {}
 
-  const take = (from: Record<string, unknown>) => {
+  const take = (from: Record<string, unknown>, depth: number) => {
     for (const [k, v] of Object.entries(from)) {
       if (k === 'title') continue
       if (k === 'other') Object.assign(other, v as Record<string, unknown>)
       else merged[k] = v
+
+      // openGraph and twitter are replaced whole by a nearer segment's, so
+      // whichever segment took them last is the one whose images - or lack of
+      // them - the merged object carries. That segment's depth is what a file
+      // in app/ is weighed against; see shareImages.ts.
+      if (k === 'openGraph' || k === 'twitter') {
+        sources[k] = { depth, exports: typeof v === 'object' && v !== null && (v as { images?: unknown }).images != null }
+      }
     }
   }
 
-  for (const m of layoutMeta) take(m)
+  layoutMeta.forEach((m, i) => take(m, depthOf(folderOf(layouts[i].component))))
 
-  take(page)
+  take(page, depthOf(folderOf(component)))
 
   if (Object.keys(other).length > 0) merged.other = other
 
@@ -5309,7 +5413,11 @@ export async function resolveMetadata(
   }
   if (title != null) merged.title = title
 
-  return Object.keys(merged).length ? merged : null
+  if (Object.keys(merged).length === 0) return null
+
+  imageSources.set(merged, sources)
+
+  return merged
 }
 
 // Buffered render (worker: rsc / rscWithoutCallbacks — used at prerender time).
@@ -5939,7 +6047,11 @@ async function renderNotFound(request: Request): Promise<Response> {
         : ""}
   return new Response('Not found', { status: 404 })
 }
-`;
+${
+    // After everything the entry is for: running a command reads its
+    // register() and shutdown(). Only a build for an app that has commands; what
+    // is in the table is decided later, when the bundle is built.
+    withCommands ? commandsEntry(join(packageDir, "commands")) : ""}`;
 }
 function generateEntrySsr() {
     const devUrls = join(packageDir, "devUrls");
@@ -7168,6 +7280,20 @@ export function rscKit(options = {}) {
                 if (nitro.options.dev)
                     return;
                 nitroPreset = nitro.options.preset ?? null;
+                // The entry a command runs from, beside the server it does not start.
+                // Written once Nitro has assembled the output, because it names a
+                // file Nitro places: if that moves, the build says so rather than a
+                // release step finding out.
+                nitro.hooks.hook("compiled", async () => {
+                    if (buildCommands().length === 0)
+                        return;
+                    const serverDir = nitro.options.output.serverDir;
+                    if (!existsSync(join(serverDir, "_ssr", "rsc.mjs"))) {
+                        throw new Error(`[rsc-kit] src/commands runs from ${join(serverDir, "_ssr", "rsc.mjs")}, and Nitro did not write it there. ` +
+                            "Nitro's output layout changed; the commands entry needs to follow it.");
+                    }
+                    writeFileSync(join(serverDir, "commands.mjs"), commandsEntrySource());
+                });
                 // On Workers the stored pages ride the static assets, not the bundle.
                 // Copied once Nitro has listed its public files, so the copies are
                 // not in that list: a path in it is served as an asset before the
@@ -7280,6 +7406,7 @@ export function rscKit(options = {}) {
             // Both maps, not one: the config hook runs again when the config
             // changes under a dev server, and a route.ts or a synthesised
             // robots.txt left over from the previous run read as a duplicate.
+            commandsFound = null;
             components.clear();
             apiRoutes.clear();
             discover(appDir);
@@ -7362,7 +7489,7 @@ export function rscKit(options = {}) {
                     : env.command === "build"
                         ? (declaresBackend ? "" : false)
                         : (detected || (declaresBackend ? "" : false));
-            writeGenerated(join(genDir, "entry.rsc.tsx"), generateEntryRsc(fallbackOrigin));
+            writeGenerated(join(genDir, "entry.rsc.tsx"), generateEntryRsc(fallbackOrigin, env.command === "build" && existsSync(join(sourceDir, "commands"))));
             writeGenerated(join(genDir, "entry.ssr.tsx"), generateEntrySsr());
             writeGenerated(join(genDir, "entry.browser.tsx"), generateEntryBrowser());
             // Written beside the entries, for a host to read instead of walking the
@@ -7637,7 +7764,8 @@ export function rscKit(options = {}) {
                         res.end(webManifest(webManifestOptions));
                         return;
                     }
-                    const asset = allAppAssets(foundAssets).find((a) => a.href === url);
+                    // Either spelling of a bracket: the tag says %5B, a hand-typed url says [.
+                    const asset = allAppAssets(foundAssets).find((a) => assetFile(a.href) === assetFile(url));
                     const file = asset ? join(sourceDir, "app", asset.file) : null;
                     if (!asset || !file || !existsSync(file))
                         return next();
@@ -7724,6 +7852,7 @@ export function rscKit(options = {}) {
                     // published without any — generic-host.test.ts fails if it reappears.
                     return ((base !== stem && shapes.has(stem)) ||
                         SECTION_FILE.test(base) ||
+                        SHARE_IMAGE_FILE.test(base) ||
                         (routeConfig !== null && base === routeConfig.file));
                 };
                 const restart = (file) => {
@@ -7840,7 +7969,7 @@ export function rscKit(options = {}) {
                 // And the entry a binary is compiled from, so the pages above end up
                 // inside it rather than rendered live: bun build --compile
                 // .output/server/compile.mjs. The scaffold's script names it.
-                writeFileSync(join(dirname(staticDir), "compile.mjs"), compileEntrySource(NITRO_STATIC_DIR));
+                writeFileSync(join(dirname(staticDir), "compile.mjs"), compileEntrySource(NITRO_STATIC_DIR, { commands: buildCommands().length > 0 }));
             }
             // Manifest first. The service worker precaches whatever it finds in this
             // directory, so writing it afterwards leaves it out of the list — and an
@@ -7864,7 +7993,12 @@ export function rscKit(options = {}) {
             if (clientOut) {
                 writeFileSync(join(dirname(clientOut), "rsc-kit.json"), JSON.stringify(output === "export"
                     ? { version: PACKAGE_VERSION, output: "export", dir: relative(projectRoot, exportPath) }
-                    : { version: PACKAGE_VERSION, output: "server", ...compileStep(projectRoot) }, null, 2) + "\n");
+                    : {
+                        version: PACKAGE_VERSION,
+                        output: "server",
+                        ...compileStep(projectRoot),
+                        ...(buildCommands().length ? { commands: buildCommands().map((c) => c.name) } : {}),
+                    }, null, 2) + "\n");
             }
         },
         configResolved(config) {
@@ -7947,6 +8081,7 @@ export function rscKit(options = {}) {
         serverRendererInRsc(),
         metadataRoutesPlugin(),
         openApiPlugin(),
+        commandsPlugin(),
         extendableClientReferences(),
         stableComponentNames(),
         typecheckPlugin(),