@ultimat3/cli 27.8.1 → 27.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "27.8.1",
+  "version": "27.10.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -39,33 +39,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "27.8.1",
-    "@ultimat3/admin": "27.8.1",
-    "@ultimat3/ai": "27.8.1",
-    "@ultimat3/auth": "27.8.1",
-    "@ultimat3/cache": "27.8.1",
-    "@ultimat3/core": "27.8.1",
-    "@ultimat3/db": "27.8.1",
-    "@ultimat3/entity": "27.8.1",
-    "@ultimat3/flags": "27.8.1",
-    "@ultimat3/http": "27.8.1",
-    "@ultimat3/i18n": "27.8.1",
-    "@ultimat3/jobs": "27.8.1",
-    "@ultimat3/mail": "27.8.1",
-    "@ultimat3/manifest": "27.8.1",
-    "@ultimat3/mcp": "27.8.1",
-    "@ultimat3/money": "27.8.1",
-    "@ultimat3/notify": "27.8.1",
-    "@ultimat3/policy": "27.8.1",
-    "@ultimat3/pwa": "27.8.1",
-    "@ultimat3/query": "27.8.1",
-    "@ultimat3/realtime": "27.8.1",
-    "@ultimat3/render": "27.8.1",
-    "@ultimat3/schema": "27.8.1",
-    "@ultimat3/seo": "27.8.1",
-    "@ultimat3/storage": "27.8.1",
-    "@ultimat3/testing": "27.8.1",
-    "@ultimat3/time": "27.8.1",
+    "@ultimat3/action": "27.10.0",
+    "@ultimat3/admin": "27.10.0",
+    "@ultimat3/ai": "27.10.0",
+    "@ultimat3/auth": "27.10.0",
+    "@ultimat3/cache": "27.10.0",
+    "@ultimat3/core": "27.10.0",
+    "@ultimat3/db": "27.10.0",
+    "@ultimat3/entity": "27.10.0",
+    "@ultimat3/flags": "27.10.0",
+    "@ultimat3/http": "27.10.0",
+    "@ultimat3/i18n": "27.10.0",
+    "@ultimat3/jobs": "27.10.0",
+    "@ultimat3/mail": "27.10.0",
+    "@ultimat3/manifest": "27.10.0",
+    "@ultimat3/mcp": "27.10.0",
+    "@ultimat3/money": "27.10.0",
+    "@ultimat3/notify": "27.10.0",
+    "@ultimat3/policy": "27.10.0",
+    "@ultimat3/pwa": "27.10.0",
+    "@ultimat3/query": "27.10.0",
+    "@ultimat3/realtime": "27.10.0",
+    "@ultimat3/render": "27.10.0",
+    "@ultimat3/schema": "27.10.0",
+    "@ultimat3/seo": "27.10.0",
+    "@ultimat3/storage": "27.10.0",
+    "@ultimat3/testing": "27.10.0",
+    "@ultimat3/time": "27.10.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/cmd-generate.ts

@@ -19,6 +19,7 @@ import { followUpEdits } from './generate-follow-ups';
 import type { Generator } from './generate-kinds';
 import { readFeature, readKind, readName, readPermission, readSurface } from './generate-kinds';
 import { refusePluralTable } from './generate-plural';
+import { followReexports } from './generate-reexports';
 import { refuseShadowedTypes, refuseShadowedValues } from './generate-shadow';
 import { declaresOnlyOtherEntities } from './generate-sibling';
 import { containedPath, planWrites, writeFiles } from './generate-write';
@@ -90,6 +91,12 @@ export const generateCommand: CliCommand = {
     // A named slice that is not there is refused, never invented (X_FEATURE_UNKNOWN).
     assertFeatureExists(root, kind, featureFlag, slice);
     const sliceErrors = await readSliceErrors(root, kind, slice);
+    // And its `policy.ts`, for the same two kinds and the same reason: the action imports from it.
+    const slicePolicy = await followReexports(
+      root,
+      slice,
+      await readSliceErrors(root, kind, slice, 'policy.ts'),
+    );
     // Same reason again: whether `job`/`task` may assume the tenant-scoped shape is a fact about
     // THIS feature's own `entity.ts`/`repo.ts`, not a default the template gets to assume.
     const sliceEntity = await readSliceFile(root, kind, slice, 'entity.ts');
@@ -105,6 +112,7 @@ export const generateCommand: CliCommand = {
         name: planned,
         ...(featureFlag === undefined ? {} : { feature: featureFlag }),
         ...(sliceErrors === undefined ? {} : { sliceErrors }),
+        ...(slicePolicy === undefined ? {} : { slicePolicy }),
         ...(sliceEntity === undefined ? {} : { sliceEntity }),
         ...(sliceRepo === undefined ? {} : { sliceRepo }),
         ...(at === undefined ? {} : { at }),
@@ -321,9 +329,10 @@ async function readSliceErrors(
   root: string,
   kind: Generator,
   slice: string,
+  name: 'errors.ts' | 'policy.ts' = 'errors.ts',
 ): Promise<string | undefined> {
   if (kind !== 'action' && kind !== 'mutator') return undefined;
-  const file = containedPath(root, `${slice}/errors.ts`);
+  const file = containedPath(root, `${slice}/${name}`);
   return existsSync(file) ? await Bun.file(file).text() : undefined;
 }
 

package/src/error-codes.ts

@@ -233,6 +233,7 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_ISLAND_MODULE_DUPLICATED',
   'X_BACKFILL_SLICE_ENTITY',
   'X_LAYOUT_SIBLING_MODULE',
+  'X_SLICE_POLICY_INCOMPLETE',
 ] as const;
 
 /**
@@ -422,6 +423,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_ISLAND_MODULE_DUPLICATED: 'An island chunk bundles one module more than once',
   X_BACKFILL_SLICE_ENTITY: 'the slice holds no entity a generated backfill can sweep',
   X_LAYOUT_SIBLING_MODULE: 'a primitive module beside its directory',
+  X_SLICE_POLICY_INCOMPLETE: 'a generator needs an export the slice policy.ts does not declare',
 };
 
 // One unconditional call, so a second package claiming one of the CLI's codes throws

package/src/generate-files.ts

@@ -70,6 +70,8 @@ export interface GenerateOptions {
   readonly sliceEntity?: string;
   /** The same kinds: the slice's `repo.ts` as it stands on disk, absent alongside `sliceEntity`. */
   readonly sliceRepo?: string;
+  /** `action` and `mutator`: the slice's `policy.ts` as it stands on disk, absent when it has none. */
+  readonly slicePolicy?: string;
   /**
    * The app's own db package, `@<app>/db` — what every generated `repo.ts` imports the typed handle
    * from. Supplied by `run` (`resolveDbModule`) for `catalogModule`'s reason: the name lives in a
@@ -152,6 +154,7 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
         actionFiles(options.name, {
           ...target,
           ...(options.sliceErrors === undefined ? {} : { sliceErrors: options.sliceErrors }),
+          ...(options.slicePolicy === undefined ? {} : { slicePolicy: options.slicePolicy }),
           ...(options.sliceEntity === undefined ? {} : { sliceEntity: options.sliceEntity }),
           ...(options.sliceRepo === undefined ? {} : { sliceRepo: options.sliceRepo }),
         }),
@@ -162,6 +165,7 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
           ...target,
           mutator: true,
           ...(options.sliceErrors === undefined ? {} : { sliceErrors: options.sliceErrors }),
+          ...(options.slicePolicy === undefined ? {} : { slicePolicy: options.slicePolicy }),
           ...(options.sliceEntity === undefined ? {} : { sliceEntity: options.sliceEntity }),
           ...(options.sliceRepo === undefined ? {} : { sliceRepo: options.sliceRepo }),
         }),

package/src/generate-reexports.ts

@@ -0,0 +1,40 @@
+// Single responsibility: reading a slice module's relative `export * from './x'` targets off the
+// app's disk, one level deep, so a barrel is judged by what it really exports.
+
+// why: Bun has no synchronous "is this a FILE": a directory passes `existsSync`, and reading one
+// as a file is an uncoded EISDIR.
+import { statSync } from 'node:fs';
+import { containedPath } from './generate-write';
+import { inlineReexports } from './templates/slice-foundation';
+
+/**
+ * A slice module with its relative `export * from './x'` lines read in, one level deep — so a
+ * `policy.ts` that is a barrel is judged by what it really exports (`inlineReexports`).
+ */
+export async function followReexports(
+  root: string,
+  slice: string,
+  source: string | undefined,
+): Promise<string | undefined> {
+  if (source === undefined) return undefined;
+  const found = new Map<string, string>();
+  for (const match of source.matchAll(/\bexport\s*\*\s*from\s*['"](\.[^'"]+)['"]/g)) {
+    const specifier = match[1] ?? '';
+    for (const candidate of [`${specifier}.ts`, `${specifier}/index.ts`, specifier]) {
+      const file = containedPath(root, `${slice}/${candidate}`);
+      // A FILE, or it is not followed: `./rules` naming a directory with no `index.ts` is left as
+      // the `export *` it was, which is "cannot tell".
+      if (found.has(specifier) || !isFile(file)) continue;
+      found.set(specifier, await Bun.file(file).text());
+    }
+  }
+  return inlineReexports(source, (specifier) => found.get(specifier));
+}
+
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}

package/src/generate-slice-policy.ts

@@ -0,0 +1,29 @@
+// Single responsibility: the refusal `x g action` / `x g mutator` raise when the slice they were
+// pointed at has a hand-written `policy.ts` without the exports the generated file imports.
+// Declared outside `templates/` (source the CLI emits) and beside nothing else, as
+// `generate-feature.ts`'s `FeatureUnknownError` is: `errors.ts` sits at its line ceiling.
+
+import { UltimateError } from '@ultimat3/core';
+
+/** Thrown while the files are PLANNED, so nothing is on disk when it is. */
+export class SlicePolicyIncompleteError extends UltimateError {
+  constructor(input: {
+    readonly policy: string;
+    readonly feature: string;
+    readonly missing: readonly string[];
+    readonly kind: 'action' | 'mutator';
+  }) {
+    super({
+      code: 'X_SLICE_POLICY_INCOMPLETE',
+      cause: `${input.policy} does not export ${input.missing.join(' or ')}, which the ${input.kind} x g ${input.kind} writes imports from it — the file is hand-written, a generator never edits it, and nothing was written`,
+      // The fix IS the edit: `x g policy --dry-run` prints a write plan, never the source to copy.
+      fix: `${input.missing.map((name) => exportLine(name, input.feature)).join(' ')}   # add to ${input.policy} (tag from @ultimat3/cache, can from @ultimat3/policy; the permission must be one its definePermissions() declares), then run x g ${input.kind} again`,
+    });
+  }
+}
+
+/** The export line a scaffolded `policy.ts` carries for `name`. */
+const exportLine = (name: string, feature: string): string =>
+  name.endsWith('Tag')
+    ? `export const ${name} = tag('${feature}');`
+    : `export const ${name} = can('${feature}:write');`;

package/src/index.ts

@@ -157,8 +157,9 @@ export {
 export { quoteArg } from './shell-quote';
 export type { SiteSettings } from './site-config';
 export { loadSiteSettings, publicOrigin } from './site-config';
-export type { SiteSeo, SiteSeoOptions } from './site-seo';
+export type { SiteSeo, SiteSeoOptions, SiteSeoSitemap } from './site-seo';
 export { ROBOTS_PATH, SITEMAP_PATH, siteSeo } from './site-seo';
+export { writeSiteSeo } from './site-seo-write';
 export { eachSourceFile, isGenerated, isTest, SOURCE_GLOBS } from './source-files';
 export type { SkippedRoute, StaticReport } from './static-report';
 export { parseStaticReport } from './static-report';

package/src/mcp-errors.ts

@@ -304,6 +304,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x errors explain X_BACKFILL_SLICE_ENTITY --json   # the refusal itself names the x g job line for this slice',
   X_LAYOUT_SIBLING_MODULE:
     'x verify --only boundaries --json   # then move each declaration in X.ts to X/<name>.ts, one primitive per file',
+  X_SLICE_POLICY_INCOMPLETE:
+    'x policy list --json   # names the slice policy module; add the export lines the thrown fix spells out to it, then run the generator again',
 };
 
 const isCliCode = (code: string): code is CliErrorCode =>

package/src/seo-meta.ts

@@ -5,6 +5,8 @@
 // this is the only tier that can see both: `@ultimat3/seo` is tier 1 and may not import the route
 // registry, which is tier 4.
 
+import { ctxOf, runWithContext } from '@ultimat3/core';
+import { localizedPath } from '@ultimat3/i18n';
 import { metaContextFor, type RouteEntry, routeDataFor, routeEntries } from '@ultimat3/render';
 import type { RouteRecord } from '@ultimat3/seo';
 import { loadApp } from './app-load';
@@ -66,11 +68,19 @@ export async function scanSiteMeta(root: string): Promise<SiteMetaScan> {
 /**
  * The same scan over the registry as it stands, without loading anything.
  *
+ * `locale` runs every `meta` inside that locale's context; omitted, in none (the gate's read).
+ *
  * Split from `scanSiteMeta` so the resolution rules are testable against routes registered by hand:
  * the half worth pinning is which routes are reachable and what happens when one throws, and
  * neither of those is a fact about globbing a directory.
  */
-export async function readSiteMeta(): Promise<SiteMetaScan> {
+export async function readSiteMeta(locale?: string): Promise<SiteMetaScan> {
+  // In a locale: each `meta` runs as that locale's document would — `ctx.locale`, `t` and the URL
+  // are its own — which is what lets a page that is `noindex` in one language say so.
+  const scoped = <T>(run: () => Promise<T>): Promise<T> =>
+    locale === undefined ? run() : runWithContext(ctxOf({ role: 'web', locale }), run);
+  const pathOf = (path: string): string =>
+    locale === undefined ? path : localizedPath(path, locale);
   const records: RouteRecord[] = [];
   const unresolved: UnresolvedRoute[] = [];
   const findings: Finding[] = [];
@@ -82,10 +92,10 @@ export async function readSiteMeta(): Promise<SiteMetaScan> {
       unresolved.push({ path: entry.path, file: entry.file, reason });
       continue;
     }
-    const ctx = { url: `${PROBE_ORIGIN}${entry.path}`, params: {} };
+    const ctx = { url: `${PROBE_ORIGIN}${pathOf(entry.path)}`, params: {} };
     try {
-      const meta = await entry.config.meta(
-        metaContextFor(ctx, await routeDataFor(entry.config, ctx)),
+      const meta = await scoped(async () =>
+        entry.config.meta(metaContextFor(ctx, await routeDataFor(entry.config, ctx))),
       );
       records.push({
         path: entry.path,

package/src/site-config.ts

@@ -11,14 +11,14 @@ export interface SiteSettings {
   readonly origin: string | null;
   /** `seo.robots.disallow` — the paths a production `robots.txt` keeps crawlers out of. */
   readonly disallow: readonly string[];
-  /** `seo.sitemap` — public `app/` pages to list, and where `<lastmod>` comes from. */
+  /** `seo.sitemap` — public `app/` pages to list, where `<lastmod>` comes from, sections, page size. */
   readonly sitemap: SeoSitemapConfig;
 }
 
 export const NO_SITE_SETTINGS: SiteSettings = {
   origin: null,
   disallow: [],
-  sitemap: { extra: [], lastmod: 'none' },
+  sitemap: { extra: [], lastmod: 'none', sections: [], pageSize: 50_000 },
 };
 
 const trimSlash = (origin: string): string => origin.replace(/\/+$/, '');

package/src/site-seo-write.ts

@@ -0,0 +1,16 @@
+// Single responsibility: `siteSeo()`'s answer as files in a static export — `/sitemap.xml`, every
+// part an index names, and `robots.txt` — so a CDN serves the bytes a running web role answers.
+
+// why: Bun exposes no path-join primitive, and every file path is relative to the output root.
+import { join } from 'node:path';
+import { ROBOTS_PATH, type SiteSeo } from './site-seo';
+
+/**
+ * Writes every file of `seo` under `out` and answers their site-relative paths, the sitemap files
+ * first. `Bun.write` creates `sitemaps/` on the way, so an index and its parts land together.
+ */
+export async function writeSiteSeo(out: string, seo: SiteSeo): Promise<readonly string[]> {
+  for (const file of seo.sitemaps) await Bun.write(join(out, file.path), file.xml);
+  await Bun.write(join(out, ROBOTS_PATH), seo.robots);
+  return [...seo.sitemaps.map((file) => file.path), ROBOTS_PATH];
+}

package/src/site-seo.ts

@@ -8,8 +8,8 @@ import { localizedPath, unlocalizedPath } from '@ultimat3/i18n';
 import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
 import type { RouteEntry } from '@ultimat3/render';
 import { routeEntries } from '@ultimat3/render';
-import { enumeratePrerender, fillPath } from '@ultimat3/render/server';
-import type { RouteRecord, SitemapFile } from '@ultimat3/seo';
+import { enumeratePrerenderEntries, fillPath } from '@ultimat3/render/server';
+import type { RouteRecord, SitemapFile, SitemapPage } from '@ultimat3/seo';
 import { buildRobots, buildSitemap, isDynamic } from '@ultimat3/seo';
 import { readSiteMeta } from './seo-meta';
 import { lastmodOf } from './sitemap-lastmod';
@@ -25,7 +25,8 @@ export interface SiteSeoOptions {
   /**
    * The concrete pages a build EMITTED for a dynamic route. The static export passes its report's,
    * so the sitemap cannot name a page the artifact lacks; absent, `prerender()` is asked — which is
-   * the same list, enumerated by the same function the prerenderer calls.
+   * the same list, enumerated by the same function the prerenderer calls. Given, `prerender()` is
+   * still asked what each page says of ITSELF (`lastmod`, `locales`); the list stays this one.
    */
   readonly pagesFor?: ((routePath: string) => readonly string[]) | undefined;
   /**
@@ -35,14 +36,22 @@ export interface SiteSeoOptions {
   readonly disallow?: readonly string[] | undefined;
   /**
    * `seo.sitemap` from `app.config.ts` (`loadSiteSettings`): the public `app/` pages to list beside
-   * the `site/` ones, and where each `<lastmod>` comes from. Omitted: `site/` pages, no `<lastmod>`.
+   * the `site/` ones, where each `<lastmod>` comes from, and the sections and page size of an
+   * index. Omitted: `site/` pages, no `<lastmod>`, one urlset.
    */
-  readonly sitemap?: SeoSitemapConfig | undefined;
+  readonly sitemap?: SiteSeoSitemap | undefined;
   /** The app root the route files are relative to — read for `lastmod: 'git' | 'mtime'`. */
   readonly root?: string | undefined;
 }
 
-const NO_SITEMAP_SETTINGS: SeoSitemapConfig = { extra: [], lastmod: 'none' };
+/**
+ * `seo.sitemap` as `siteSeo` takes it: `sections` and `pageSize` optional, so a caller that wrote
+ * `{ extra, lastmod }` before either existed still compiles and still gets the one urlset.
+ */
+export type SiteSeoSitemap = Pick<SeoSitemapConfig, 'extra' | 'lastmod'> &
+  Partial<Pick<SeoSitemapConfig, 'sections' | 'pageSize'>>;
+
+const NO_SITEMAP_SETTINGS: SiteSeoSitemap = { extra: [], lastmod: 'none' };
 
 /** A `seo.sitemap.extra` path that names no public page outside `site/`. */
 export class SitemapExtraInvalidError extends UltimateError {
@@ -67,42 +76,87 @@ const isPublicSite = (entry: RouteEntry): boolean =>
   entry.surface === 'site' && entry.config.policy === undefined;
 
 /**
- * A dynamic route's pages, UNPREFIXED and once each. A static export's report lists every locale's
- * copy (`/blog/a` and `/en/blog/a`), and the sitemap localizes each page itself — reading the
- * prefixed copies back as pages of their own listed `/en/en/blog/a`.
+ * A route's pages, UNPREFIXED and once each, with what `prerender()` said of each one. A
+ * static export's report lists every locale's copy (`/blog/a` and `/en/blog/a`), and the sitemap
+ * localizes each page itself — reading the prefixed copies back as pages of their own listed
+ * `/en/en/blog/a`.
  */
-const pagesOf = async (entry: RouteEntry, options: SiteSeoOptions): Promise<readonly string[]> => {
-  if (options.pagesFor !== undefined) {
-    return [...new Set(options.pagesFor(entry.path).map((path) => unlocalizedPath(path)))];
-  }
-  const params = await enumeratePrerender(entry);
-  return params.map((set) => fillPath(entry.pattern.source, set));
+const pagesOf = async (
+  entry: RouteEntry,
+  options: SiteSeoOptions,
+): Promise<readonly SitemapPage[]> => {
+  const said = (await enumeratePrerenderEntries(entry)).map(
+    (page): SitemapPage => ({
+      path: fillPath(entry.pattern.source, page.params),
+      ...(page.lastmod === undefined ? {} : { lastmod: page.lastmod }),
+      ...(page.locales === undefined ? {} : { locales: page.locales }),
+    }),
+  );
+  // Only a DYNAMIC route's list is the report's: a page with no params is listed whether or not
+  // this build emitted it (an `isr` one is rendered by the server), exactly as before.
+  if (options.pagesFor === undefined || !isDynamic(entry.path)) return said;
+  const byPath = new Map(said.map((page) => [page.path, page]));
+  const emitted = new Set(options.pagesFor(entry.path).map((path) => unlocalizedPath(path)));
+  return [...emitted].map((path) => byPath.get(path) ?? { path });
 };
 
+/**
+ * What a page's own `meta` says about being indexed, per locale: the record's `meta` when every
+ * locale agrees, its `locales` when only some may be indexed. `robots: { index: false }` in ONE
+ * locale used to leave that copy listed and every other copy's hreflang pointing at it — the read
+ * was made once, in no locale at all.
+ */
+async function indexability(
+  locales: readonly string[],
+): Promise<(path: string) => Pick<RouteRecord, 'meta' | 'locales'>> {
+  if (locales.length < 2) {
+    const metaByPath = new Map((await readSiteMeta()).records.map((r) => [r.path, r.meta]));
+    return (path) => {
+      const meta = metaByPath.get(path);
+      return meta === undefined ? {} : { meta };
+    };
+  }
+  const scans = new Map<string, Map<string, RouteRecord['meta']>>();
+  // One locale at a time: each scan runs every route's `meta` inside that locale's context.
+  for (const locale of locales) {
+    scans.set(locale, new Map((await readSiteMeta(locale)).records.map((r) => [r.path, r.meta])));
+  }
+  return (path) => {
+    const listed = locales.filter(
+      (locale) => scans.get(locale)?.get(path)?.robots?.index !== false,
+    );
+    if (listed.length === locales.length) return {};
+    // No locale may be indexed: the `noindex` itself is what keeps the route out.
+    if (listed.length === 0) return { meta: { robots: { index: false } } };
+    return { locales: listed };
+  };
+}
+
 /**
  * The public `site/` routes as `@ultimat3/seo` reads them. `meta` is carried where it resolves
  * without a request (`readSiteMeta`), which is what lets a page's own `robots: { index: false }`
  * keep it out of the sitemap — a page that asks crawlers to stay away must not be listed for them.
+ * A route with params or a `load` resolves no `meta` here: its pages say it per entry (`locales`).
  */
 async function publicSiteRoutes(
   options: SiteSeoOptions,
   stamp: Stamp,
+  locales: readonly string[],
 ): Promise<readonly RouteRecord[]> {
-  const metaByPath = new Map((await readSiteMeta()).records.map((r) => [r.path, r.meta]));
+  const indexed = await indexability(locales);
   return routeEntries()
     .filter(isPublicSite)
-    .map((entry) => {
-      const meta = metaByPath.get(entry.path);
-      return {
-        path: entry.path,
-        file: entry.file,
-        surface: 'site' as const,
-        render: entry.config.render,
-        ...(meta === undefined ? {} : { meta }),
-        ...(isDynamic(entry.path) ? { prerender: () => pagesOf(entry, options) } : {}),
-        ...stamp(entry.file),
-      };
-    });
+    .map((entry) => ({
+      path: entry.path,
+      file: entry.file,
+      surface: 'site' as const,
+      render: entry.config.render,
+      ...indexed(entry.path),
+      ...(isDynamic(entry.path) || entry.config.prerender !== undefined
+        ? { prerender: () => pagesOf(entry, options) }
+        : {}),
+      ...stamp(entry.file),
+    }));
 }
 
 type Stamp = (file: string) => { readonly lastmod?: string };
@@ -158,11 +212,15 @@ export async function siteSeo(options: SiteSeoOptions): Promise<SiteSeo> {
     return lastmod === undefined ? {} : { lastmod };
   };
   const routes = [
-    ...(await publicSiteRoutes(options, stamp)),
+    ...(await publicSiteRoutes(options, stamp, locales)),
     ...extraRoutes(settings.extra, stamp),
   ];
   const sitemap = await buildSitemap(routes, {
     baseUrl: options.baseUrl,
+    // A URL `robots.txt` keeps crawlers out of is not handed to them here: one config, two files.
+    ...(options.disallow === undefined ? {} : { disallow: options.disallow }),
+    ...(settings.sections === undefined ? {} : { sections: settings.sections }),
+    ...(settings.pageSize === undefined ? {} : { maxUrls: settings.pageSize }),
     ...(locales.length < 2
       ? {}
       : {
@@ -172,8 +230,8 @@ export async function siteSeo(options: SiteSeoOptions): Promise<SiteSeo> {
             localizedPath(path, locale, defaultLocale),
         }),
   });
-  // Past 50,000 URLs `files` are `/sitemaps/<n>.xml` and the index is `/sitemap.xml`; below it,
-  // `files` is that one file and there is no index.
+  // With sections, or past a protocol cap, `files` are `/sitemaps/*.xml` and the index is
+  // `/sitemap.xml`; otherwise `files` is that one file and there is no index.
   const sitemaps = sitemap.index === undefined ? sitemap.files : [sitemap.index, ...sitemap.files];
   const robots = buildRobots({
     baseUrl: options.baseUrl,

package/src/templates/action.ts

@@ -2,12 +2,19 @@
 // pins both. One declaration projects to an HTTP route, an OpenAPI operation, a typed client, a
 // job handle, an MCP tool and these tests; the generator writes the declaration and the tests.
 
+import { SlicePolicyIncompleteError } from '../generate-slice-policy';
 import type { FeatureTarget } from './entity';
 import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
 import { PLACEHOLDER_DB_MODULE } from './scaffold-db-client';
-import { sliceExports, sliceFoundation, sliceTakesScaffoldRow } from './slice-foundation';
+import {
+  exportsUnknown,
+  grantOf,
+  sliceExports,
+  sliceFoundation,
+  sliceTakesScaffoldRow,
+} from './slice-foundation';
 import { wrapImport } from './wrap';
 
 /**
@@ -177,6 +184,12 @@ interface HandlerShape {
   /** The slice still takes the row `x g entity` scaffolds, so the test may store one. */
   readonly storesRow: boolean;
   readonly dbModule: string;
+  /**
+   * The permission the writer is granted — `<feature>:write` for the policy this generator wrote,
+   * the one literal `can('<perm>')` of a handwritten one, or `undefined` when that policy's grant
+   * cannot be read, and then no assertion depends on it.
+   */
+  readonly grant: string | undefined;
 }
 
 /**
@@ -204,6 +217,12 @@ unitTest('the local twin invents no row the store never held', () => {
 
 /** The authoritative half's cases, refusal first, in the shape the slice earns. */
 const handlerTests = (feature: NameSet, shape: HandlerShape): string => {
+  if (shape.grant === undefined) {
+    return `
+// No handler assertion: ../policy.ts is hand-written and its grant is not one literal can('…'),
+// so which actor reaches the handler is the author's to state — add that test here.
+`;
+  }
   const answer = shape.isMutator ? "{ id, title: 'a title' }" : '{ id }';
   if (!shape.lookup) {
     return `
@@ -253,7 +272,8 @@ unitTest('the handler answers the row it found', async () => {
  * it would be a guess about someone else's table.
  */
 const actionUnitTest = (name: NameSet, feature: NameSet, shape: HandlerShape): string => {
-  const stores = shape.lookup && shape.storesRow;
+  const known = shape.grant !== undefined;
+  const stores = known && shape.lookup && shape.storesRow;
   const testing = [
     ...(stores ? ['afterEach'] : []),
     'expect',
@@ -264,7 +284,7 @@ const actionUnitTest = (name: NameSet, feature: NameSet, shape: HandlerShape): s
 // process, so all three belong to the \`unit\` step. The contract projections are next door.
 ${sortedImports([
   ...(stores ? ["import { ctxOf, runWithContext } from '@ultimat3/core';"] : []),
-  "import { testActor } from '@ultimat3/policy';",
+  ...(known ? ["import { testActor } from '@ultimat3/policy';"] : []),
   `import { ${testing} } from '@ultimat3/testing';`,
   ...(stores ? [`import { driver } from '${shape.dbModule}';`] : []),
 ])}${stores ? "\nimport * as repo from '../repo';" : ''}
@@ -278,11 +298,15 @@ ${shape.isMutator ? `\n// The client store's table: the entity's own, so the twi
 // At boot \`registerActions(await import('./actions'))\` stamps the same name onto the same
 // object, so each projection of it works there with nothing to remember.
 const target = ${name.camel}.named('${name.camel}');
-
+${
+  known
+    ? `
 // Holds the grant in the org the input names: past the policy, so what answers is the handler.
-const grant = ['${feature.kebab}:write'];
+const grant = ['${shape.grant}'];
 const writer = testActor('writer', { orgId, permissions: grant }).actor;
-${
+`
+    : ''
+}${
   stores
     ? `
 // One store per process: without this, one test's rows are the next test's fixtures.
@@ -305,9 +329,11 @@ const actionContractTest = (
   name: NameSet,
   feature: NameSet,
   isMutator: boolean,
+  /** The slice's policy is the one this generator wrote, so its tenancy rule is known. */
+  scaffoldPolicy = true,
 ): string => `// ${name.camel}: the contract every action owes, and the foreign-org actor it denies before the
 // handler runs. One declaration, every surface.
-${preamble(name, feature, isMutator, 'contractTest, expect', true)}
+${preamble(name, feature, isMutator, 'contractTest, expect', scaffoldPolicy)}
 contractTest('${name.camel} passes the action contract', async () => {
   // Three assertions the framework makes for any action, without knowing what this one does:
   // garbage input is rejected, an anonymous actor is denied, and the operation reaches the
@@ -315,13 +341,19 @@ contractTest('${name.camel} passes the action contract', async () => {
   for (const contract of target.contract()) await contract.run();
 });
 
-contractTest('${name.camel} denies a foreign org', async () => {
+${
+  scaffoldPolicy
+    ? `contractTest('${name.camel} denies a foreign org', async () => {
   // \`.as()\` is the one execution path with the actor swapped, so this denial is the same one
   // HTTP, MCP and the job surface would produce — and no repo call happened to produce it.
   const denied = await target.as(outsider, input).catch((error: unknown) => error);
   expect(denied).toBeUltimateError('X_FORBIDDEN');
 });
-
+`
+    : `// No foreign-org assertion: ../policy.ts is hand-written, and whether it checks the org is the
+// author's rule to state — add that test here.
+`
+}
 // No MCP tool until it is described: a placeholder description misleads the agent reading it.
 contractTest('${name.camel} projects one operation and no tool', () => {
   expect(target.openapi().operationId).toBe('${name.camel}');
@@ -346,6 +378,12 @@ export interface ActionOptions extends FeatureTarget {
   readonly sliceEntity?: string;
   /** The slice's `repo.ts` as it stands on disk, or absent alongside `sliceEntity`. */
   readonly sliceRepo?: string;
+  /**
+   * The slice's `policy.ts` as it stands on disk, absent when the slice has none yet (and then the
+   * scaffolded one is written). Read for `sliceErrors`'s reason: the generated file IMPORTS from
+   * it, and what it exports is a fact about this app's disk.
+   */
+  readonly slicePolicy?: string;
 }
 
 export function actionFiles(rawName: string, target: ActionOptions): readonly GeneratedFile[] {
@@ -354,16 +392,26 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
   const dir = `${target.surfaceDir}/${target.feature}/actions`;
   const isMutator = target.mutator === true;
   const entity = target.sliceEntity !== undefined;
+  // Before a file is planned: a generated action that does not compile is refused, never written.
+  assertPolicyExports(target, feature, isMutator);
   const lookup =
     entity &&
     (target.sliceErrors === undefined ||
-      sliceExports(target.sliceErrors, `${feature.pascal}NotFoundError`));
+      sliceExports(target.sliceErrors, `${feature.pascal}NotFoundError`)) &&
+    // The lookup calls `repo.byId`: a `repo.ts` an author wrote without one gets the neutral body.
+    (target.sliceRepo === undefined || sliceExports(target.sliceRepo, 'byId'));
   return [
     // The three slice modules this action's source imports — `../errors`, `../policy`, `../repo`
     // (which comes with `../entity`, its row type). Composed rather than assumed: `x g action`
     // into a slice no `x g resource` had created emitted all three imports and wrote none of them.
     // With no entity, only the policy: a lookup-free body imports neither ../errors nor ../repo.
-    ...sliceFoundation(target, entity ? ['entity', 'policy', 'errors'] : ['policy']),
+    // And ONLY those: an action is not a resource scaffold. A module already on disk is its
+    // author's — it gets no test from here and no admin labels, both of which assert the shape
+    // `x g resource` writes, not the one that is there (`withoutOwned`).
+    ...withoutOwned(
+      sliceFoundation(target, entity ? ['entity', 'policy', 'errors'] : ['policy']),
+      target,
+    ),
     {
       path: `${dir}/${name.kebab}.ts`,
       contents: isMutator
@@ -381,11 +429,63 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
         lookup,
         storesRow: sliceTakesScaffoldRow(target, target.sliceEntity, target.sliceRepo),
         dbModule: target.dbModule ?? PLACEHOLDER_DB_MODULE,
+        // The policy this run writes grants `<feature>:write`; a handwritten one, what it says.
+        grant:
+          target.slicePolicy === undefined
+            ? `${feature.kebab}:write`
+            : grantOf(target.slicePolicy, `can${feature.pascal}Write`),
       }),
     },
     {
       path: `${dir}/${name.kebab}.contract.test.ts`,
-      contents: actionContractTest(name, feature, isMutator),
+      contents: actionContractTest(name, feature, isMutator, target.slicePolicy === undefined),
     },
   ];
 }
+
+/** The slice modules a run may find already written, and the files each would otherwise be handed. */
+const OWNED = [
+  ['sliceEntity', ['/entity.ts', '/entity.test.ts', '.json']],
+  ['sliceRepo', ['/repo.ts', '/repo.test.ts']],
+  ['slicePolicy', ['/policy.ts', '/policy.test.ts']],
+] as const;
+
+/**
+ * The planted slice files, minus everything that belongs to a module ALREADY on disk. `if-absent`
+ * protects a file; it does not know that `repo.test.ts` belongs to a `repo.ts` somebody wrote, so
+ * a hand-written slice was handed three tests asserting the scaffold's shape and six admin labels
+ * (the catalog `.json`) for an entity it had declared itself. A module this run does write keeps
+ * every companion.
+ */
+function withoutOwned(
+  files: readonly GeneratedFile[],
+  target: ActionOptions,
+): readonly GeneratedFile[] {
+  const owned = OWNED.flatMap(([module, suffixes]) =>
+    target[module] === undefined ? [] : suffixes,
+  );
+  return files.filter((file) => !owned.some((suffix) => file.path.endsWith(suffix)));
+}
+
+/**
+ * Refuse a slice whose own `policy.ts` lacks what the generated file imports from it. An absent
+ * `policy.ts` is not this case — the scaffolded one is written beside the action, with both names.
+ *
+ * Refused rather than adapted, unlike a missing `<Feature>NotFoundError`: there is no neutral
+ * policy to fall back to. An inline `can('<feature>:write')` names a permission the slice's
+ * `definePermissions()` never declared, which is a type error of its own.
+ */
+function assertPolicyExports(target: ActionOptions, feature: NameSet, isMutator: boolean): void {
+  const source = target.slicePolicy;
+  // A barrel re-exporting a module nobody could read: cannot tell, so never refused on a guess.
+  if (source === undefined || exportsUnknown(source)) return;
+  const needed = [`can${feature.pascal}Write`, ...(isMutator ? [] : [`${feature.camel}Tag`])];
+  const missing = needed.filter((name) => !sliceExports(source, name));
+  if (missing.length === 0) return;
+  throw new SlicePolicyIncompleteError({
+    policy: `${target.surfaceDir}/${target.feature}/policy.ts`,
+    feature: target.feature,
+    missing,
+    kind: isMutator ? 'mutator' : 'action',
+  });
+}

package/src/templates/scaffold-entries.ts

@@ -66,7 +66,13 @@ const prerender =
 // landed on disk — which is what \`x build --target static --json\` reads back.
 
 import { join } from 'node:path';
-import { loadSiteSettings, type PrerenderReport, prerenderSite, siteSeo } from '@ultimat3/cli';
+import {
+  loadSiteSettings,
+  type PrerenderReport,
+  prerenderSite,
+  siteSeo,
+  writeSiteSeo,
+} from '@ultimat3/cli';
 
 const root = join(import.meta.dir, '..', '..');
 const flag = Bun.argv.indexOf('--out');
@@ -84,9 +90,12 @@ const origin = Bun.env.SITE_ORIGIN;
  * page whose \`meta\` says \`robots: { index: false }\` left out — so a crawler reads one sitemap
  * from the CDN and from the container.
  *
- * A DYNAMIC route contributes exactly the URLs this build emitted for it, read back off the report
- * rather than by calling \`prerender()\` a second time: the sitemap then cannot name a page the
- * artifact does not contain.
+ * A DYNAMIC route contributes exactly the URLs this build emitted for it, read back off the report:
+ * the sitemap then cannot name a page the artifact does not contain. \`prerender()\` is asked again
+ * only for what each page says of itself — its \`lastmod\`, the \`locales\` it is listed in.
+ *
+ * With \`seo.sitemap.sections\` the answer is an index and its parts: \`/sitemap.xml\` plus
+ * \`/sitemaps/<name>-<n>.xml\`, every one written here.
  *
  * \`robots.txt\` fails closed — anything that is not \`ULTIMATE_ENV=production\` emits
  * \`Disallow: /\` and advertises no sitemap — so a preview build cannot outrank the real site.
@@ -104,9 +113,7 @@ async function writeSeoFiles(report: PrerenderReport): Promise<readonly string[]
     pagesFor: (route) =>
       report.pages.filter((page) => page.route === route).map((page) => page.path),
   });
-  for (const file of seo.sitemaps) await Bun.write(join(out, file.path), file.xml);
-  await Bun.write(join(out, 'robots.txt'), seo.robots);
-  return [...seo.sitemaps.map((file) => file.path), '/robots.txt'];
+  return await writeSiteSeo(out, seo);
 }
 
 if (import.meta.main) {

package/src/templates/slice-foundation.ts

@@ -131,7 +131,59 @@ export function sliceExports(source: string, name: string): boolean {
   const declared = new RegExp(
     `\\bexport\\s+(?:abstract\\s+)?(?:class|const|let|var|(?:async\\s+)?function|enum)\\s+${name}\\b`,
   );
-  return declared.test(code) || listedExports(code).includes(name);
+  return (
+    declared.test(code) || listedExports(code).includes(name) || destructured(code).includes(name)
+  );
+}
+
+/** The names an `export const { a, b: c } = …` declares — `a` and `c`, never `b`. */
+const destructured = (code: string): readonly string[] =>
+  [...code.matchAll(/\bexport\s+(?:const|let|var)\s*\{([^}]*)\}\s*=/g)].flatMap((match) =>
+    (match[1] ?? '')
+      .split(',')
+      .map((entry) => (entry.split(':').at(-1) ?? '').split('=')[0]?.trim() ?? '')
+      .filter((entry) => entry !== ''),
+  );
+
+const STAR = /\bexport\s*\*\s*from\s*['"]([^'"]+)['"]\s*;?/g;
+
+/**
+ * `source` with each `export * from '<specifier>'` replaced by the module `read` answers for it —
+ * ONE level, which is what a slice's barrel is. A specifier `read` cannot answer (a package, a
+ * missing file) is left as it stands, and that leftover is what `exportsUnknown` reports.
+ */
+export function inlineReexports(
+  source: string,
+  read: (specifier: string) => string | undefined,
+): string {
+  return stripComments(source).replace(STAR, (statement: string, specifier: string) => {
+    const inner = read(specifier);
+    // Its own `export *` lines are dropped rather than followed: one level, and a module that
+    // re-exports further is "cannot tell" only if THIS file still says so.
+    return inner === undefined ? statement : stripComments(inner).replace(STAR, '');
+  });
+}
+
+/** Whether `source` re-exports a module nobody read: what it exports cannot be known from here. */
+export const exportsUnknown = (source: string): boolean => {
+  const code = stripComments(source);
+  return /\bexport\s*\*\s*from\b/.test(code) || nestedPattern(code);
+};
+
+/**
+ * Whether an exported destructuring pattern is one the flat reader above cannot spell: a nested
+ * object or array pattern, or a rest element. Its names are then UNKNOWN — never "missing".
+ */
+function nestedPattern(code: string): boolean {
+  for (const match of code.matchAll(/\bexport\s+(?:const|let|var)\s*\{/g)) {
+    let depth = 1;
+    for (let at = (match.index ?? 0) + match[0].length; at < code.length && depth > 0; at += 1) {
+      const char = code[at];
+      if (char === '{' || char === '[' || code.startsWith('...', at)) return true;
+      if (char === '}') depth -= 1;
+    }
+  }
+  return false;
 }
 
 /** `    title: text({ max: 200 }),` — one column of an entity, as its name and its builder. */
@@ -162,3 +214,16 @@ export function sliceTakesScaffoldRow(
   if (wanted === '' || columnsOf(sliceEntity) !== wanted) return false;
   return sliceRepo === undefined || sliceExports(sliceRepo, 'insert');
 }
+
+/**
+ * The ONE permission `name` grants, when `source` declares it as a single literal call:
+ * `export const canBlogWrite = can('blog:publish');`. Anything else — a predicate argument,
+ * `and`/`or`, a function, a re-export — is `undefined`: the grant cannot be read, and a generated
+ * test must not assume one.
+ */
+export function grantOf(source: string, name: string): string | undefined {
+  const declared = new RegExp(
+    `\\bexport\\s+const\\s+${name}\\s*=\\s*can\\(\\s*(['"\`])([A-Za-z0-9_.*:-]+)\\1\\s*\\)\\s*;`,
+  );
+  return declared.exec(stripComments(source))?.[2];
+}