@human-synthesis/norns 0.1.0 → 0.2.1

package/src/kernel/generate.js

@@ -22,14 +22,20 @@ import { isAddress, listUnits, parseAddress } from './address.js';
 import { schemaEmitter } from './emit-schema.js';
 import {
 	actionsEmitter,
+	componentKey,
+	endpointsEmitter,
+	jobsEmitter,
+	humanizeName,
 	pagesEmitter,
 	policiesEmitter,
 	queriesEmitter,
 	remotesEmitter,
+	servicesEmitter,
 	triggersEmitter
 } from './emit-units.js';
 import { machinesEmitter } from './emit-machines.js';
 import { wranglerFile } from './emit-wrangler.js';
+import { emitFlow } from './flow.js';
 import { buildGraph } from './graph.js';
 import { loadSpecs, validateSpecs } from './validate.js';
 
@@ -49,6 +55,10 @@ export function checkGenerate(specs, opts = {}) {
 	const refusals = [];
 	const graph = buildGraph(specs.modules);
 	if (opts.contracts) refusals.push(...checkBindings(specs, opts.contracts));
+	refusals.push(...checkLiveBindings(specs));
+	refusals.push(...checkSnippetBindings(specs, opts.snippetSlots ?? null));
+	refusals.push(...checkTokenOverrides(specs, opts.tokens ?? null));
+	refusals.push(...checkNetworkInBodies(specs));
 
 	for (const [moduleName, spec] of Object.entries(specs.modules)) {
 		for (const unit of listUnits(moduleName, spec)) {
@@ -81,6 +91,9 @@ export function checkGenerate(specs, opts = {}) {
 					});
 				}
 			}
+			if (unit.kind === 'Service' || unit.kind === 'Endpoint') {
+				refusals.push(...checkServiceSecrets(unit));
+			}
 			if (unit.kind === 'Query') {
 				const q = unit.value;
 				if (q && typeof q === 'object' && !q.live && !q.groupBy && q.limit === undefined) {
@@ -98,6 +111,128 @@ export function checkGenerate(specs, opts = {}) {
 	return refusals;
 }
 
+const SECRET_SHAPE_RE =
+	/(?:^|[^A-Za-z0-9])(?:sk|pk|rk)_(?:live|test|prod)_[A-Za-z0-9]{8,}|^(?:ghp|gho|github_pat)_|^xox[a-z]-|^AKIA[0-9A-Z]{12}|^eyJ[A-Za-z0-9_-]{10,}/;
+
+/** Token-shaped: known prefixes, or long spaceless mixed-class strings that are not URLs. */
+function looksLikeSecret(s) {
+	if (typeof s !== 'string') return false;
+	if (SECRET_SHAPE_RE.test(s)) return true;
+	return (
+		s.length >= 32 &&
+		!/\s/.test(s) &&
+		/[A-Z]/.test(s) &&
+		/[a-z]/.test(s) &&
+		/[0-9]/.test(s) &&
+		!/^https?:\/\//.test(s)
+	);
+}
+
+function* stringLeaves(value, path = '') {
+	if (typeof value === 'string') yield [path, value];
+	else if (value && typeof value === 'object') {
+		for (const [k, child] of Object.entries(value)) {
+			yield* stringLeaves(child, path ? `${path}.${k}` : k);
+		}
+	}
+}
+
+/**
+ * D15: credentials never in spec. Refuses userinfo/query params in a
+ * service base URL and any token-shaped literal anywhere in the unit —
+ * `auth.binding` is a binding *name*; the value lives in the environment
+ * (`wrangler secret put`).
+ *
+ * @param {{ address: string, value: * }} unit a Service unit
+ * @returns {Refusal[]}
+ */
+export function checkServiceSecrets(unit) {
+	/** @type {Refusal[]} */
+	const refusals = [];
+	const svc = unit.value ?? {};
+	const push = (path, message) =>
+		refusals.push({
+			address: unit.address,
+			path: `${unit.address}.${path}`,
+			code: 'SECRET_IN_SPEC',
+			message,
+			fix: 'keep only an UPPER_SNAKE binding name in spec and set the value with `wrangler secret put`'
+		});
+	if (typeof svc.base === 'string') {
+		try {
+			const u = new URL(svc.base);
+			if (u.username || u.password) push('base', 'base URL embeds userinfo credentials');
+			if (u.search) push('base', 'base URL embeds query parameters — move keys/tokens to an env binding');
+		} catch {
+			// meta-schema already rejects non-URL bases
+		}
+	}
+	for (const [path, s] of stringLeaves(svc)) {
+		if (path !== 'base' && looksLikeSecret(s)) {
+			push(path, `"${s.slice(0, 8)}…" looks like a literal secret — credentials never go in spec`);
+		}
+	}
+	return refusals;
+}
+
+/** Global `fetch(` — not `.fetch(` (DO stubs, service bindings) or `myfetch(`. */
+const GLOBAL_FETCH_RE = /(?<![.\w])fetch\s*\(/;
+
+function* customBodyFiles(moduleName, spec) {
+	for (const [name, a] of Object.entries(spec.actions ?? {})) {
+		if (a?.impl === 'custom') yield [`${moduleName}.Action.${name}`, `src/${moduleName}/actions/${name}.c`];
+	}
+	for (const [name, j] of Object.entries(spec.jobs ?? {})) {
+		if (j?.impl === 'custom') yield [`${moduleName}.Job.${name}`, `src/${moduleName}/jobs/${name}.c`];
+	}
+	for (const name of Object.keys(spec.functions ?? {})) {
+		yield [`${moduleName}.Function.${name}`, `src/${moduleName}/functions/${name}.c`];
+	}
+	for (const name of Object.keys(spec.endpoints ?? {})) {
+		yield [`${moduleName}.Endpoint.${name}`, `src/${moduleName}/endpoints/${name}.c`];
+	}
+	for (const [name, w] of Object.entries(spec.workers ?? {})) {
+		if (typeof w?.source === 'string') yield [`${moduleName}.Worker.${name}`, w.source];
+	}
+	for (const [name, r] of Object.entries(spec.routes ?? {})) {
+		if (typeof r?.source === 'string') yield [`${moduleName}.Route.${name}`, r.source];
+	}
+}
+
+/**
+ * X-07: the generated service client is the only network path a custom
+ * body may take. Scans declared L3 bodies (custom actions/jobs, functions,
+ * endpoints, worker/route sources) for direct global `fetch(` calls.
+ * No-op for in-memory specs (no `dir`) — the lint needs files on disk.
+ *
+ * @param {{ dir?: string, modules: Record<string, *> }} specs
+ * @returns {Refusal[]}
+ */
+export function checkNetworkInBodies(specs) {
+	if (typeof specs.dir !== 'string') return [];
+	const appRoot = dirname(specs.dir);
+	/** @type {Refusal[]} */
+	const refusals = [];
+	for (const [moduleName, spec] of Object.entries(specs.modules)) {
+		for (const [address, rel] of customBodyFiles(moduleName, spec)) {
+			const file = join(appRoot, rel);
+			if (!existsSync(file)) continue;
+			const hit = readFileSync(file, 'utf-8')
+				.split('\n')
+				.findIndex((line) => GLOBAL_FETCH_RE.test(line));
+			if (hit === -1) continue;
+			refusals.push({
+				address,
+				path: `${rel}:${hit + 1}`,
+				code: 'UNDECLARED_NETWORK',
+				message: `custom body calls global fetch() at ${rel}:${hit + 1} — the generated service client is the only network path`,
+				fix: 'declare the host as a Service (with auth binding + operations) and call it through the generated client'
+			});
+		}
+	}
+	return refusals;
+}
+
 /**
  * Validate page `components:` entries against palette props contracts
  * (U-02). Each entry is normalized the way the pages emitter binds it: the
@@ -117,7 +252,8 @@ export function checkBindings(specs, contracts) {
 			(page.components ?? []).forEach((entry, i) => {
 				const keys = Object.keys(entry);
 				if (keys.length === 0) return;
-				const [first, ...rest] = keys;
+				const first = componentKey(entry);
+				const rest = keys.filter((k) => k !== first);
 				const tag = first[0].toUpperCase() + first.slice(1);
 				const contract = contracts[tag];
 				if (!contract) return;
@@ -127,6 +263,12 @@ export function checkBindings(specs, contracts) {
 					typeof primary === 'string' && isAddress(primary) ? parseAddress(primary) : null;
 				const props = {};
 				if (parsed) props[parsed.kind === 'Action' ? 'action' : 'data'] = primary;
+				else if (primary && typeof primary === 'object' && !Array.isArray(primary)) {
+					// realtime bindings (K-27) — the emitter turns these into
+					// streamSource/roomChannel props, so validate that shape
+					if (typeof primary.stream === 'string') props.streamSource = primary.stream;
+					if (typeof primary.room === 'string') props.roomChannel = primary.room;
+				}
 				for (const key of rest) props[key] = entry[key];
 
 				const result = v.safeParse(contract, props);
@@ -146,6 +288,254 @@ export function checkBindings(specs, contracts) {
 	return refusals;
 }
 
+/**
+ * Validate realtime page bindings (K-27) — object-primary component
+ * entries like `{ streamText: { stream: "m.Endpoint.x" } }` and
+ * `{ chatThread: { room: "m.Worker.x", sends: [...], receives: [...] } }`.
+ * `stream` must target an Endpoint with a `stream` output mode; `room` a
+ * Worker declared `room: true`. Optional `sends`/`receives` message-name
+ * lists are cross-checked against the Room's declared message schemas
+ * (`in` for sends, `out` for receives). Needs no palette contracts — the
+ * target shape lives in the spec itself.
+ *
+ * @param {{ modules: Record<string, *> }} specs
+ * @returns {Refusal[]}
+ */
+export function checkLiveBindings(specs) {
+	/** @type {Refusal[]} */
+	const refusals = [];
+	for (const [moduleName, moduleSpec] of Object.entries(specs.modules)) {
+		for (const [pageName, page] of Object.entries(moduleSpec.pages ?? {})) {
+			(page.components ?? []).forEach((entry, i) => {
+				const first = componentKey(entry);
+				if (!first) return;
+				const binding = entry[first];
+				if (!binding || typeof binding !== 'object' || Array.isArray(binding)) return;
+				const tag = first[0].toUpperCase() + first.slice(1);
+				const refuse = (sub, message, fix) =>
+					refusals.push({
+						address: `${moduleName}.Page.${pageName}`,
+						path: `${moduleName}.Page.${pageName}.components[${i}].${first}.${sub}`,
+						code: 'INVALID_BINDING',
+						message,
+						fix
+					});
+
+				if ('stream' in binding) {
+					const addr = binding.stream;
+					const parsed = typeof addr === 'string' && isAddress(addr) ? parseAddress(addr) : null;
+					const target =
+						parsed?.kind === 'Endpoint'
+							? specs.modules[parsed.module]?.endpoints?.[parsed.name]
+							: undefined;
+					if (!parsed || parsed.kind !== 'Endpoint' || !target) {
+						refuse(
+							'stream',
+							`<${tag}> \`stream\` binding needs an existing Endpoint address, got ${JSON.stringify(addr)}`,
+							'point `stream` at a declared module.Endpoint.name'
+						);
+					} else if (!target.stream) {
+						refuse(
+							'stream',
+							`${addr} has no \`stream\` output mode — <${tag}> consumes typed SSE frames`,
+							'declare `stream: { frame: { … } }` on the Endpoint (output and stream are exclusive)'
+						);
+					}
+				}
+
+				if ('room' in binding) {
+					const addr = binding.room;
+					const parsed = typeof addr === 'string' && isAddress(addr) ? parseAddress(addr) : null;
+					const target =
+						parsed?.kind === 'Worker'
+							? specs.modules[parsed.module]?.workers?.[parsed.name]
+							: undefined;
+					if (!parsed || parsed.kind !== 'Worker' || !target) {
+						refuse(
+							'room',
+							`<${tag}> \`room\` binding needs an existing Worker address, got ${JSON.stringify(addr)}`,
+							'point `room` at a declared module.Worker.name'
+						);
+						return;
+					}
+					if (target.room !== true) {
+						refuse(
+							'room',
+							`${addr} is not a Room — <${tag}> needs a Worker declared \`room: true\``,
+							'set `room: true` (plus `messages`/`state`) on the Worker'
+						);
+						return;
+					}
+					const messages = target.messages ?? {};
+					for (const [listKey, dir] of [
+						['sends', 'in'],
+						['receives', 'out']
+					]) {
+						for (const name of Array.isArray(binding[listKey]) ? binding[listKey] : []) {
+							if (messages[name]?.[dir]) continue;
+							refuse(
+								listKey,
+								`${addr} declares no \`${dir}\` schema for message ${JSON.stringify(name)}`,
+								`declare \`messages.${name}.${dir}\` on the Worker or drop it from \`${listKey}\``
+							);
+						}
+					}
+				}
+			});
+		}
+	}
+	return refusals;
+}
+
+/**
+ * Validate Snippet bindings (U-07): a page component prop bound to a
+ * `m.Snippet.n` address must reference a declared Snippet unit, and — when
+ * palette slot metadata is available — its declared `args` must match the
+ * slot's calling convention (the emitter forwards those args as props to
+ * the custom body, so a mismatch is a broken render, not a style issue).
+ *
+ * @param {{ modules: Record<string, *> }} specs
+ * @param {Record<string, Record<string, string[]>> | null} [slots]
+ *   `snippetSlots` from @human-synthesis/norns-ui/contracts: tag → prop → args
+ * @returns {Refusal[]}
+ */
+export function checkSnippetBindings(specs, slots = null) {
+	/** @type {Refusal[]} */
+	const refusals = [];
+	for (const [moduleName, moduleSpec] of Object.entries(specs.modules)) {
+		for (const [pageName, page] of Object.entries(moduleSpec.pages ?? {})) {
+			(page.components ?? []).forEach((entry, i) => {
+				const keys = Object.keys(entry ?? {});
+				if (keys.length === 0) return;
+				const first = componentKey(entry);
+				const tag = first[0].toUpperCase() + first.slice(1);
+				for (const key of keys) {
+					const value = entry[key];
+					if (typeof value !== 'string' || !isAddress(value)) continue;
+					const parsed = parseAddress(value);
+					if (parsed.kind !== 'Snippet') continue;
+					const refuse = (message, fix) =>
+						refusals.push({
+							address: `${moduleName}.Page.${pageName}`,
+							path: `${moduleName}.Page.${pageName}.components[${i}].${key}`,
+							code: 'INVALID_BINDING',
+							message,
+							fix
+						});
+					const target = specs.modules[parsed.module]?.snippets?.[parsed.name];
+					if (!target) {
+						refuse(
+							`no Snippet declared at ${value}`,
+							`declare \`snippets.${parsed.name}\` (with \`args\`) in module "${parsed.module}" — the body lives in src/${parsed.module}/snippets/${parsed.name}.n`
+						);
+						continue;
+					}
+					const want = slots?.[tag]?.[key];
+					if (!want) continue;
+					const got = target.args ?? [];
+					if (want.length !== got.length || want.some((a, j) => a !== got[j])) {
+						refuse(
+							`<${tag}> \`${key}\` slot passes (${want.join(', ')}) but ${value} declares args (${got.join(', ')})`,
+							`set \`args: [${want.map((a) => `"${a}"`).join(', ')}]\` on the Snippet — the emitter forwards them as same-named props`
+						);
+					}
+				}
+			});
+		}
+	}
+	return refusals;
+}
+
+const TOKEN_NAME_RE = /^--[a-z][a-z0-9-]*$/;
+
+const asVarName = (name) => (name.startsWith('--') ? name : `--${name}`);
+
+/**
+ * Validate app-level design-token overrides (U-10): `app.settings.tokens`
+ * is a record of token name → CSS value, emitted verbatim into a
+ * generated stylesheet — so names must be kebab-case custom properties
+ * (checked against the palette token manifest when available) and values
+ * must not be able to escape their declaration.
+ *
+ * @param {{ app?: * }} specs
+ * @param {{ vars?: Record<string, string> } | null} [tokens]
+ *   `tokens` section of @human-synthesis/norns-ui/manifest
+ * @returns {Refusal[]}
+ */
+export function checkTokenOverrides(specs, tokens = null) {
+	const overrides = specs.app?.settings?.tokens;
+	if (overrides === undefined) return [];
+	const at = (name) => ({
+		address: 'app.settings.tokens',
+		path: name ? `app.settings.tokens.${name}` : 'app.settings.tokens'
+	});
+	if (overrides === null || typeof overrides !== 'object' || Array.isArray(overrides)) {
+		return [
+			{
+				...at(''),
+				code: 'INVALID_TOKEN',
+				message: 'settings.tokens must be a record of design-token name → CSS value',
+				fix: 'e.g. `"settings": { "tokens": { "color-primary-500": "oklch(55% 0.2 260)" } }`'
+			}
+		];
+	}
+	/** @type {Refusal[]} */
+	const refusals = [];
+	const known = tokens?.vars ? new Set(Object.keys(tokens.vars)) : null;
+	for (const [name, value] of Object.entries(overrides)) {
+		const varName = asVarName(name);
+		if (!TOKEN_NAME_RE.test(varName)) {
+			refusals.push({
+				...at(name),
+				code: 'INVALID_TOKEN',
+				message: `"${name}" is not a token name (lowercase kebab-case, optional leading --)`
+			});
+			continue;
+		}
+		if (known && !known.has(varName)) {
+			refusals.push({
+				...at(name),
+				code: 'UNKNOWN_TOKEN',
+				message: `"${varName}" is not a palette design token`,
+				fix: 'browse `tokens.vars` in @human-synthesis/norns-ui/manifest for the addressable set'
+			});
+			continue;
+		}
+		if (typeof value !== 'string' || value.trim() === '') {
+			refusals.push({
+				...at(name),
+				code: 'INVALID_TOKEN',
+				message: `override for "${varName}" must be a non-empty CSS value string`
+			});
+			continue;
+		}
+		// eslint-disable-next-line no-control-regex
+		if (/[;{}]|url\s*\(|[-]/i.test(value)) {
+			refusals.push({
+				...at(name),
+				code: 'INVALID_TOKEN',
+				message: `override for "${varName}" is not a plain CSS value — \`;\`, braces, \`url()\` and control characters are refused`
+			});
+		}
+	}
+	return refusals;
+}
+
+/**
+ * Normalized `--name → value` record from `app.settings.tokens`, or null
+ * when the app declares no overrides.
+ *
+ * @param {{ app?: * }} specs
+ * @returns {Record<string, string> | null}
+ */
+export function tokenOverrides(specs) {
+	const raw = specs.app?.settings?.tokens;
+	if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+	const entries = Object.entries(raw);
+	if (entries.length === 0) return null;
+	return Object.fromEntries(entries.map(([name, value]) => [asVarName(name), value]));
+}
+
 /**
  * Emitters (K-10..K-12). Each: { name, emit(ctx) } where ctx =
  * { moduleName, moduleSpec, specs, graph } and the return value is a list
@@ -158,9 +548,12 @@ export const EMITTERS = [
 	machinesEmitter,
 	queriesEmitter,
 	actionsEmitter,
+	servicesEmitter,
+	jobsEmitter,
 	triggersEmitter,
 	pagesEmitter,
-	remotesEmitter
+	remotesEmitter,
+	endpointsEmitter
 ];
 
 const require = createRequire(import.meta.url);
@@ -171,6 +564,8 @@ const FILE_KINDS = {
 	'actions.c': 'Action',
 	'machines.c': 'Action',
 	'policies.c': 'Policy',
+	'services.c': 'Service',
+	'jobs.c': 'Job',
 	'triggers.c': 'Trigger'
 };
 
@@ -233,18 +628,26 @@ export class GenerateError extends Error {
 }
 
 /**
- * Load palette props contracts from the app's own dependency tree. Apps
- * that don't use norns-ui simply skip binding validation.
+ * Load palette props contracts + snippet slot metadata from the app's own
+ * dependency tree. Apps that don't use norns-ui simply skip binding
+ * validation.
  *
  * @param {string} appRoot
- * @returns {Record<string, *> | null}
+ * @returns {{ contracts: Record<string, *> | null, snippetSlots: Record<string, *> | null, tokens: { vars?: Record<string, string> } | null }}
  */
-function loadContracts(appRoot) {
+function loadPalette(appRoot) {
 	try {
 		const appRequire = createRequire(join(appRoot, 'package.json'));
-		return appRequire('@human-synthesis/norns-ui/contracts').contracts ?? null;
+		const mod = appRequire('@human-synthesis/norns-ui/contracts');
+		let tokens = null;
+		try {
+			tokens = appRequire('@human-synthesis/norns-ui/manifest')?.tokens ?? null;
+		} catch {
+			tokens = null;
+		}
+		return { contracts: mod.contracts ?? null, snippetSlots: mod.snippetSlots ?? null, tokens };
 	} catch {
-		return null;
+		return { contracts: null, snippetSlots: null, tokens: null };
 	}
 }
 
@@ -280,22 +683,78 @@ export function liveRouteFile() {
 /**
  * Root layout for the generated route tree (app-level, like wrangler.json).
  * Plain `.svelte` — no Pug/Civet — so it stays outside the vetted-subset
- * surface. Imports the app's global stylesheet when `src/app.css` exists.
+ * surface. Imports the app's global stylesheet when `src/app.css` exists,
+ * then the generated token-override sheet (after, so `app.settings.tokens`
+ * wins over library defaults pulled in via app.css).
  *
+ * When the specs declare statically-routed Pages, the layout is an admin
+ * shell: sidebar nav (one link per Page, active state via aria-current)
+ * around the content. Styled by the `.norns-*` atoms in norns-ui; override
+ * through `app.settings.tokens` or `src/app.css`.
+ *
+ * @param {{ app?: *, modules: Record<string, *> }} specs
  * @param {boolean} hasAppCss
+ * @param {boolean} [hasTokens]
  * @returns {{ path: string, text: string }}
  */
-export function layoutFile(hasAppCss) {
+export function layoutFile(specs, hasAppCss, hasTokens = false) {
+	const nav = [];
+	for (const [moduleName, spec] of Object.entries(specs?.modules ?? {})) {
+		for (const [name, p] of Object.entries(spec?.pages ?? {})) {
+			const route = p?.route;
+			if (typeof route !== 'string' || route.includes('[') || route.includes(':')) continue;
+			// Generic page names label as their module: companies.Page.index → "Companies".
+			const label = ['index', 'home', 'main', 'page'].includes(name) ? moduleName : name;
+			nav.push({ href: route, label: humanizeName(label) });
+		}
+	}
+	nav.sort((a, b) => a.href.localeCompare(b.href));
+	const brand = humanizeName(specs?.app?.name ?? 'App');
+
+	const script = [
+		'<script>',
+		...(hasAppCss ? ["\timport '$custom/app.css';"] : []),
+		...(hasTokens ? ["\timport './tokens.css';"] : []),
+		...(nav.length ? ["\timport { page } from '$app/state';"] : []),
+		'\tlet { children } = $props();',
+		...(nav.length ? [`\tconst nav = ${JSON.stringify(nav)};`] : []),
+		'</script>'
+	];
+	const body = nav.length
+		? [
+				'<div class="norns-shell">',
+				'\t<aside class="norns-sidebar">',
+				`\t\t<div class="norns-brand">${brand}</div>`,
+				'\t\t<nav class="norns-nav">',
+				'\t\t\t{#each nav as item (item.href)}',
+				"\t\t\t\t<a href={item.href} aria-current={page.url.pathname === item.href ? 'page' : undefined}>{item.label}</a>",
+				'\t\t\t{/each}',
+				'\t\t</nav>',
+				'\t</aside>',
+				'\t<main class="norns-main">{@render children()}</main>',
+				'</div>'
+			]
+		: ['{@render children()}'];
 	return {
 		path: 'routes/+layout.svelte',
+		text: ['<!-- GENERATED by `norns generate` — do not edit. -->', ...script, '', ...body, ''].join('\n')
+	};
+}
+
+/**
+ * App-level stylesheet applying `app.settings.tokens` overrides (U-10).
+ *
+ * @param {Record<string, string>} overrides normalized `--name → value`
+ * @returns {{ path: string, text: string }}
+ */
+export function tokensFile(overrides) {
+	return {
+		path: 'routes/tokens.css',
 		text: [
-			'<!-- GENERATED by `norns generate` — do not edit. -->',
-			'<script>',
-			...(hasAppCss ? ["\timport '$custom/app.css';"] : []),
-			'\tlet { children } = $props();',
-			'</script>',
-			'',
-			'{@render children()}',
+			'/* GENERATED by `norns generate` — do not edit. */',
+			':root {',
+			...Object.entries(overrides).map(([name, value]) => `\t${name}: ${value};`),
+			'}',
 			''
 		].join('\n')
 	};
@@ -330,8 +789,15 @@ export function generateApp(dir, opts = {}) {
 				.map((i) => ({ address: i.address, code: 'INVALID_SPEC', message: i.message }))
 		);
 	}
-	const contracts = opts.contracts ?? loadContracts(appRoot);
-	const refusals = checkGenerate(specs, contracts ? { contracts } : {});
+	const palette = loadPalette(appRoot);
+	const contracts = opts.contracts ?? palette.contracts;
+	const snippetSlots = opts.snippetSlots ?? palette.snippetSlots;
+	const tokens = opts.tokens ?? palette.tokens;
+	const refusals = checkGenerate(specs, {
+		...(contracts ? { contracts } : {}),
+		...(snippetSlots ? { snippetSlots } : {}),
+		...(tokens ? { tokens } : {})
+	});
 	if (refusals.length > 0) throw new GenerateError(refusals);
 
 	const cache = opts.force ? { moduleHashes: {} } : readCache(cacheFile);
@@ -351,11 +817,14 @@ export function generateApp(dir, opts = {}) {
 		cache.moduleHashes[moduleName] = specs.hashes[moduleName];
 	}
 
-	// App-level: the wrangler config derives from all modules, so refresh it
-	// whenever anything re-emitted (or it's missing entirely).
-	if (pending.length > 0 || !existsSync(join(outRoot, 'wrangler.json'))) {
+	// App-level: the wrangler config derives from all modules AND app.tron
+	// (name, dialect, cloudflare settings), so refresh it whenever anything
+	// re-emitted, the app spec itself changed, or it's missing entirely.
+	const appChanged = cache.appHash !== specs.hashes.app;
+	if (pending.length > 0 || appChanged || !existsSync(join(outRoot, 'wrangler.json'))) {
 		pending.push(wranglerFile(specs));
 	}
+	cache.appHash = specs.hashes.app;
 
 	// App-level: the live SSE route exists iff any query is live.
 	if (
@@ -365,9 +834,15 @@ export function generateApp(dir, opts = {}) {
 		pending.push(liveRouteFile());
 	}
 
+	// App-level: token overrides from `app.settings.tokens` (U-10).
+	const overrides = tokenOverrides(specs);
+	if (overrides && (pending.length > 0 || !existsSync(join(outRoot, 'routes', 'tokens.css')))) {
+		pending.push(tokensFile(overrides));
+	}
+
 	// App-level: a root layout so generated routes render inside a shell.
 	if (pending.length > 0 || !existsSync(join(outRoot, 'routes', '+layout.svelte'))) {
-		pending.push(layoutFile(existsSync(join(appRoot, 'src', 'app.css'))));
+		pending.push(layoutFile(specs, existsSync(join(appRoot, 'src', 'app.css')), Boolean(overrides)));
 	}
 
 	const failures = selfCheck(pending);
@@ -393,5 +868,7 @@ export function generateApp(dir, opts = {}) {
 	mkdirSync(dirname(cacheFile), { recursive: true });
 	writeFileSync(cacheFile, JSON.stringify(cache, null, '\t') + '\n');
 
+	emitFlow(specs, { force: opts.force });
+
 	return { version: specs.version, written, skipped, refusals: [] };
 }

package/src/kernel/index.js

@@ -49,7 +49,8 @@ export {
 } from './absorb.js';
 export { inferKind, inferCapabilities, inferAuth, adoptUnit, adoptFiles } from './adopt.js';
 export { loadSpecs, validateSpecs } from './validate.js';
-export { generateApp, checkGenerate, checkBindings, layoutFile, liveRouteFile, selfCheck, GenerateError, EMITTERS } from './generate.js';
+export { generateApp, checkGenerate, checkBindings, checkServiceSecrets, checkNetworkInBodies, checkTokenOverrides, tokenOverrides, tokensFile, layoutFile, liveRouteFile, selfCheck, GenerateError, EMITTERS } from './generate.js';
+export { indexBody, unitFlow, buildModuleFlow, emitFlow, flowApp, flowDelta } from './flow.js';
 export { wranglerConfig, wranglerFile } from './emit-wrangler.js';
 export { emitModuleMachines, machinesEmitter } from './emit-machines.js';
 export { migrateApp } from './migrate.js';
@@ -59,13 +60,19 @@ export {
 	emitModulePolicies,
 	emitModuleQueries,
 	emitModuleActions,
+	emitModuleServices,
+	emitModuleJobs,
 	emitModuleTriggers,
 	emitModulePages,
 	emitModuleRemotes,
+	emitModuleEndpoints,
 	policiesEmitter,
 	queriesEmitter,
 	actionsEmitter,
+	servicesEmitter,
+	jobsEmitter,
 	triggersEmitter,
 	pagesEmitter,
-	remotesEmitter
+	remotesEmitter,
+	endpointsEmitter
 } from './emit-units.js';