@human-synthesis/norns 0.0.16 → 0.1.0

package/src/kernel/meta.js

@@ -0,0 +1,237 @@
+/**
+ * Valibot meta-schemas — one per resource kind. These make invalid specs
+ * unrepresentable at the shape level: unknown keys are rejected
+ * (strictObject), expressions must parse, references must look like
+ * addresses. Cross-unit refinements (refs resolve, depends DAG, closed
+ * status machines) live in refine.js (K-06), not here.
+ */
+
+import * as v from 'valibot';
+
+import { isAddress } from './address.js';
+import { isExpr } from './expr.js';
+
+export const FIELD_TYPES = [
+	'text',
+	'number',
+	'int',
+	'money',
+	'bool',
+	'date',
+	'datetime',
+	'email',
+	'url',
+	'json',
+	'file',
+	'ref'
+];
+
+export const DIALECTS = ['d1', 'sqlite', 'postgres'];
+
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+const ident = v.pipe(v.string(), v.regex(IDENT_RE, 'must be an identifier'));
+const uid = v.optional(
+	v.pipe(v.string(), v.regex(/^[0-9A-HJKMNP-TV-Z]{26}$/, 'must be a 26-char ULID'))
+);
+const expr = v.pipe(
+	v.string(),
+	v.check(isExpr, 'must be a valid expression (see the CEL-subset grammar)')
+);
+const address = v.pipe(
+	v.string(),
+	v.check(isAddress, 'must be a unit address (module.Kind.name)')
+);
+/** Full address or a bare/dotted local name like `Order` or `Order.id`. */
+const unitRef = v.pipe(
+	v.string(),
+	v.check(
+		(s) => isAddress(s) || s.split('.').every((seg) => IDENT_RE.test(seg)),
+		'must be a unit reference'
+	)
+);
+
+const fieldObject = v.pipe(
+	v.strictObject({
+		type: v.picklist(FIELD_TYPES),
+		ref: v.optional(unitRef),
+		optional: v.optional(v.boolean()),
+		unique: v.optional(v.boolean()),
+		default: v.optional(v.unknown())
+	}),
+	v.check((f) => (f.type === 'ref') === (f.ref !== undefined), 'ref fields need `ref`, others must not have it')
+);
+const field = v.union([v.picklist(FIELD_TYPES), fieldObject]);
+
+const example = v.strictObject({
+	input: v.optional(v.unknown()),
+	expect: v.optional(v.unknown())
+});
+
+const requiresExamplesWhenCustom = (unit) =>
+	unit.impl !== 'custom' || (Array.isArray(unit.examples) && unit.examples.length > 0);
+const CUSTOM_NEEDS_EXAMPLES = '`impl: custom` requires at least one example';
+
+const Entity = v.strictObject({
+	uid,
+	owner: v.optional(ident),
+	fields: v.record(ident, field),
+	status: v.optional(v.record(ident, v.array(ident)))
+});
+
+const Query = v.strictObject({
+	uid,
+	from: unitRef,
+	live: v.optional(v.boolean()),
+	groupBy: v.optional(v.string()),
+	filter: v.optional(expr),
+	sort: v.optional(v.union([v.string(), v.array(v.string())])),
+	limit: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)))
+});
+
+const Action = v.pipe(
+	v.strictObject({
+		uid,
+		input: v.optional(v.record(ident, v.union([v.string(), v.record(v.string(), v.unknown())]))),
+		requires: v.optional(expr),
+		steps: v.optional(v.array(v.record(v.string(), v.unknown()))),
+		emits: v.optional(v.array(v.string())),
+		refresh: v.optional(v.array(address)),
+		examples: v.optional(v.array(example)),
+		impl: v.optional(v.picklist(['generated', 'custom'])),
+		transport: v.optional(v.picklist(['form', 'remote']))
+	}),
+	v.check(requiresExamplesWhenCustom, CUSTOM_NEEDS_EXAMPLES)
+);
+
+const Policy = v.strictObject({
+	uid,
+	roles: v.optional(v.array(ident)),
+	read: v.optional(expr),
+	write: v.optional(expr),
+	run: v.optional(v.record(ident, expr))
+});
+
+const Page = v.pipe(
+	v.strictObject({
+		uid,
+		route: v.pipe(v.string(), v.regex(/^\//, 'route must start with "/"')),
+		params: v.optional(v.record(ident, v.string())),
+		layout: v.optional(v.string()),
+		state: v.optional(v.record(ident, v.string())),
+		components: v.optional(v.array(v.record(v.string(), v.unknown()))),
+		slots: v.optional(v.array(ident)),
+		examples: v.optional(v.array(example)),
+		impl: v.optional(v.picklist(['generated', 'custom']))
+	}),
+	v.check(requiresExamplesWhenCustom, CUSTOM_NEEDS_EXAMPLES)
+);
+
+const Trigger = v.union([
+	address,
+	v.strictObject({
+		uid,
+		action: address,
+		schedule: v.optional(v.string()),
+		source: v.optional(v.string())
+	})
+]);
+
+const Function = v.strictObject({
+	uid,
+	input: v.optional(v.record(ident, v.union([v.string(), v.record(v.string(), v.unknown())]))),
+	output: v.optional(v.unknown()),
+	examples: v.pipe(v.array(example), v.minLength(1, 'functions require at least one example'))
+});
+
+const Component = v.strictObject({
+	uid,
+	props: v.optional(v.record(ident, v.unknown())),
+	events: v.optional(v.record(ident, address)),
+	slots: v.optional(v.array(ident))
+});
+
+// L3 kinds: whole Civet files with declared auth + capabilities.
+// `validate` refuses them without an auth declaration (PLAN §6).
+const level3 = (extra = {}) =>
+	v.strictObject({
+		uid,
+		source: v.string(),
+		auth: v.union([v.string(), v.record(v.string(), v.unknown())]),
+		capabilities: v.optional(v.array(v.string())),
+		...extra
+	});
+
+const Plugin = v.strictObject({
+	uid,
+	kind: v.picklist(['field', 'step', 'component', 'trigger']),
+	source: v.string(),
+	contract: v.optional(v.record(v.string(), v.unknown()))
+});
+
+/** Kind → valibot schema for one unit's spec value. */
+export const UNIT_SCHEMAS = {
+	Entity,
+	Query,
+	Action,
+	Policy,
+	Page,
+	Trigger,
+	Function,
+	Component,
+	Route: level3(),
+	Worker: level3({ room: v.optional(v.boolean()) }),
+	Adapter: level3(),
+	Middleware: level3(),
+	Plugin
+};
+
+const collection = v.optional(v.record(v.string(), v.unknown()));
+
+/** Module spec shape — collection contents are validated per unit. */
+export const MODULE_SCHEMA = v.strictObject({
+	module: ident,
+	depends: v.optional(v.array(ident)),
+	settings: v.optional(v.record(v.string(), v.unknown())),
+	entities: collection,
+	queries: collection,
+	actions: collection,
+	policies: collection,
+	pages: collection,
+	triggers: collection,
+	functions: collection,
+	components: collection,
+	routes: collection,
+	workers: collection,
+	adapters: collection,
+	middleware: collection,
+	plugins: collection
+});
+
+export const APP_SCHEMA = v.strictObject({
+	name: v.optional(v.string()),
+	modules: v.optional(v.array(ident)),
+	dialect: v.optional(v.picklist(DIALECTS)),
+	settings: v.optional(v.record(v.string(), v.unknown()))
+});
+
+/**
+ * Run a valibot schema and convert its issues to kernel Issues.
+ *
+ * @param {*} schema
+ * @param {*} value
+ * @param {string} addr issue address (unit address or module name)
+ * @returns {{ level: 'error', address: string, message: string }[]}
+ */
+export function schemaIssues(schema, value, addr) {
+	const result = v.safeParse(schema, value);
+	if (result.success) return [];
+	return result.issues.map((issue) => {
+		const path = v.getDotPath(issue);
+		return {
+			level: 'error',
+			address: addr,
+			message: path ? `${path}: ${issue.message}` : issue.message
+		};
+	});
+}

package/src/kernel/migrate.js

@@ -0,0 +1,134 @@
+/**
+ * Migration pipeline (K-11): generate → compile schema → drizzle-kit diff.
+ *
+ * Migrations are committed SQL under `migrations/<module>/`, produced by
+ * drizzle-kit (pinned) diffing the emitted Drizzle schema against its own
+ * snapshot journal. Additive by default: a diff that drops tables or
+ * columns is refused unless `force` — spec `remove` should go through a
+ * deprecation step first.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+import { GenerateError, generateApp } from './generate.js';
+import { loadSpecs } from './validate.js';
+
+const require = createRequire(import.meta.url);
+
+const DRIZZLE_DIALECTS = { d1: 'sqlite', sqlite: 'sqlite', postgres: 'postgresql' };
+
+const DESTRUCTIVE_SQL = /\bDROP TABLE\b|\bDROP COLUMN\b|__new_/i;
+
+function drizzleKitBin() {
+	return join(dirname(require.resolve('drizzle-kit')), 'bin.cjs');
+}
+
+function sqlFiles(dir) {
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir).filter((f) => f.endsWith('.sql')).sort();
+}
+
+/**
+ * Diff one module's emitted schema against its migration journal.
+ * Runs drizzle-kit in a scratch copy of `migrations/<module>` and only
+ * copies the result back when the new SQL is non-destructive (or forced).
+ *
+ * @returns {{ created: string[], refusals: import('./generate.js').Refusal[] }}
+ */
+function migrateModule({ moduleName, schemaFile, migrationsDir, workDir, dialect, name, force }) {
+	const scratch = join(workDir, moduleName);
+	rmSync(scratch, { recursive: true, force: true });
+	mkdirSync(scratch, { recursive: true });
+
+	const { compile } = require('@danielx/civet');
+	const schemaJs = join(scratch, 'schema.js');
+	writeFileSync(schemaJs, compile(readFileSync(schemaFile, 'utf-8'), { sync: true, js: true }));
+
+	const out = join(scratch, 'out');
+	if (existsSync(migrationsDir)) cpSync(migrationsDir, out, { recursive: true });
+
+	// drizzle-kit prefixes paths with './' internally, so absolute paths
+	// break snapshot reads — keep config paths relative to the scratch cwd.
+	const config = join(scratch, 'drizzle.config.js');
+	writeFileSync(
+		config,
+		`export default ${JSON.stringify({ dialect, schema: 'schema.js', out: 'out' }, null, '\t')}\n`
+	);
+
+	const before = new Set(sqlFiles(out));
+	const run = spawnSync(process.execPath, [drizzleKitBin(), 'generate', '--config', config, '--name', name], {
+		cwd: scratch,
+		encoding: 'utf-8'
+	});
+	const output = `${run.stdout ?? ''}${run.stderr ?? ''}`;
+	const created = sqlFiles(out).filter((f) => !before.has(f));
+	// drizzle-kit exits 0 even on load errors, so judge by outcome.
+	if (run.status !== 0 || (created.length === 0 && !/No schema changes/.test(output))) {
+		throw new Error(`norns migrate: drizzle-kit failed for module "${moduleName}"\n${output}`);
+	}
+	if (created.length === 0) return { created: [], refusals: [] };
+
+	const refusals = [];
+	if (!force) {
+		for (const file of created) {
+			const sql = readFileSync(join(out, file), 'utf-8');
+			if (DESTRUCTIVE_SQL.test(sql)) {
+				refusals.push({
+					address: moduleName,
+					path: `migrations/${moduleName}/${file}`,
+					code: 'DESTRUCTIVE_MIGRATION',
+					message: `migration drops tables or columns (${file})`,
+					fix: 'deprecate the field/entity first, or re-run with --force after reviewing the SQL'
+				});
+			}
+		}
+	}
+	if (refusals.length > 0) return { created: [], refusals };
+
+	cpSync(out, migrationsDir, { recursive: true });
+	return { created, refusals: [] };
+}
+
+/**
+ * Generate committed SQL migrations for every module with a schema.
+ *
+ * @param {string} [dir] specs directory, defaults to `<cwd>/specs`
+ * @param {{ out?: string, migrations?: string, force?: boolean }} [opts]
+ * @returns {{ version: string, created: Record<string, string[]>, unchanged: string[] }}
+ */
+export function migrateApp(dir, opts = {}) {
+	const specs = loadSpecs(dir);
+	const appRoot = dirname(specs.dir);
+	const genRoot = opts.out ?? join(appRoot, '.norns', 'generated');
+	const migrationsRoot = opts.migrations ?? join(appRoot, 'migrations');
+	const workDir = join(appRoot, '.norns', 'cache', 'migrate');
+
+	const dialect = DRIZZLE_DIALECTS[specs.app?.dialect ?? 'd1'];
+	generateApp(dir, { out: opts.out, force: opts.force });
+
+	const created = {};
+	const unchanged = [];
+	const refusals = [];
+	for (const moduleName of Object.keys(specs.modules)) {
+		const schemaFile = join(genRoot, 'lib', moduleName, 'schema.c');
+		if (!existsSync(schemaFile)) continue;
+		const result = migrateModule({
+			moduleName,
+			schemaFile,
+			migrationsDir: join(migrationsRoot, moduleName),
+			workDir,
+			dialect,
+			name: specs.hashes[moduleName].slice(0, 8),
+			force: opts.force === true
+		});
+		refusals.push(...result.refusals);
+		if (result.created.length > 0) created[moduleName] = result.created;
+		else unchanged.push(moduleName);
+	}
+	if (refusals.length > 0) throw new GenerateError(refusals);
+
+	return { version: specs.version, created, unchanged };
+}

package/src/kernel/refine.js

@@ -0,0 +1,199 @@
+/**
+ * Cross-unit refinements (K-06) — everything the per-kind meta-schemas
+ * cannot see because it spans units or modules: references resolve, the
+ * `depends:` graph is a DAG, status machines are closed, gated features
+ * stay refused.
+ *
+ * A module listed in `depends:` but not present in `specs/` is treated as
+ * external (e.g. the platform-provided `core` module before it is
+ * materialized); references into it are not resolvable and are skipped.
+ * References into modules that are neither loaded nor declared are errors.
+ */
+
+import { formatAddress, indexUnits, isAddress, parseAddress } from './address.js';
+
+/** @typedef {{ level: 'error' | 'warning', address: string, message: string }} Issue */
+
+/**
+ * @param {{ app: *, modules: Record<string, *> }} specs
+ * @returns {Issue[]}
+ */
+export function refineSpecs(specs) {
+	const { modules, app } = specs;
+	const index = indexUnits(modules);
+	/** @type {Issue[]} */
+	const issues = [];
+
+	const dependsOf = (moduleName) => {
+		const d = modules[moduleName]?.depends;
+		return Array.isArray(d) ? d : [];
+	};
+
+	/**
+	 * Resolve `ref` from `fromModule` expecting a unit of `kind`.
+	 * Bare names resolve within the module; full addresses anywhere.
+	 * Returns null when the ref points into an external (declared) module.
+	 */
+	function checkRef(at, fromModule, ref, kind, what) {
+		if (typeof ref !== 'string') return;
+		let target;
+		if (isAddress(ref)) {
+			const addr = parseAddress(ref);
+			if (!(addr.module in modules)) {
+				if (addr.module === fromModule || dependsOf(fromModule).includes(addr.module)) return;
+				issues.push({
+					level: 'error',
+					address: at,
+					message: `${what} "${ref}" points into unknown module "${addr.module}" (not loaded, not in depends)`
+				});
+				return;
+			}
+			if (addr.kind !== kind) {
+				issues.push({
+					level: 'error',
+					address: at,
+					message: `${what} "${ref}" must reference a ${kind}, not a ${addr.kind}`
+				});
+				return;
+			}
+			target = ref;
+		} else {
+			target = formatAddress({ module: fromModule, kind, name: ref.split('.')[0] });
+		}
+		if (!index.byAddress.has(target)) {
+			issues.push({
+				level: 'error',
+				address: at,
+				message: `${what} "${ref}" does not resolve (no ${target})`
+			});
+		}
+	}
+
+	// depends: modules exist (or are external-by-convention? no — depends
+	// names must be loaded or the well-known platform module "core") and form a DAG.
+	for (const [name, spec] of Object.entries(modules)) {
+		for (const dep of dependsOf(name)) {
+			if (!(dep in modules) && dep !== 'core') {
+				issues.push({
+					level: 'error',
+					address: name,
+					message: `depends: unknown module "${dep}"`
+				});
+			}
+		}
+	}
+	const visiting = new Set();
+	const done = new Set();
+	function visit(name, chain) {
+		if (done.has(name)) return;
+		if (visiting.has(name)) {
+			issues.push({
+				level: 'error',
+				address: name,
+				message: `depends: cycle ${[...chain, name].join(' -> ')}`
+			});
+			return;
+		}
+		visiting.add(name);
+		for (const dep of dependsOf(name)) {
+			if (dep in modules) visit(dep, [...chain, name]);
+		}
+		visiting.delete(name);
+		done.add(name);
+	}
+	for (const name of Object.keys(modules)) visit(name, []);
+
+	const remoteEnabled = app?.settings?.remoteTransport === true;
+
+	for (const unit of index.units) {
+		const { address: at, module: mod, kind, value } = unit;
+		switch (kind) {
+			case 'Entity': {
+				if (typeof value?.owner === 'string' && !(value.owner in (value.fields ?? {}))) {
+					issues.push({
+						level: 'error',
+						address: at,
+						message: `owner "${value.owner}" is not a field of this entity`
+					});
+				}
+				for (const [fname, f] of Object.entries(value?.fields ?? {})) {
+					if (f && typeof f === 'object' && f.type === 'ref') {
+						checkRef(at, mod, f.ref, 'Entity', `fields.${fname}.ref`);
+					}
+				}
+				const status = value?.status;
+				if (status && typeof status === 'object') {
+					for (const [state, nexts] of Object.entries(status)) {
+						for (const nxt of Array.isArray(nexts) ? nexts : []) {
+							if (!(nxt in status)) {
+								issues.push({
+									level: 'error',
+									address: at,
+									message: `status: transition ${state} -> ${nxt} targets an undeclared state`
+								});
+							}
+						}
+					}
+				}
+				break;
+			}
+			case 'Query':
+				checkRef(at, mod, value?.from, 'Entity', 'from');
+				break;
+			case 'Action': {
+				for (const ref of Array.isArray(value?.refresh) ? value.refresh : []) {
+					checkRef(at, mod, ref, 'Query', 'refresh');
+				}
+				if (value?.transport === 'remote' && !remoteEnabled) {
+					issues.push({
+						level: 'error',
+						address: at,
+						message:
+							'transport: remote is not enabled — opt in with app settings.remoteTransport: true (runtime support landed with R-11)'
+					});
+				}
+				break;
+			}
+			case 'Policy': {
+				const entityAddr = formatAddress({ module: mod, kind: 'Entity', name: unit.name });
+				if (!index.byAddress.has(entityAddr)) {
+					issues.push({
+						level: 'error',
+						address: at,
+						message: `policy "${unit.name}" does not match an entity in module "${mod}"`
+					});
+				}
+				for (const actionName of Object.keys(value?.run ?? {})) {
+					checkRef(at, mod, actionName, 'Action', 'run');
+				}
+				break;
+			}
+			case 'Page': {
+				for (const comp of Array.isArray(value?.components) ? value.components : []) {
+					if (comp && typeof comp === 'object') {
+						for (const [key, bound] of Object.entries(comp)) {
+							if (typeof bound === 'string' && isAddress(bound)) {
+								const addr = parseAddress(bound);
+								checkRef(at, mod, bound, addr.kind, `components.${key}`);
+							}
+						}
+					}
+				}
+				break;
+			}
+			case 'Trigger': {
+				const action = typeof value === 'string' ? value : value?.action;
+				checkRef(at, mod, action, 'Action', 'trigger action');
+				break;
+			}
+			case 'Component': {
+				for (const [event, target] of Object.entries(value?.events ?? {})) {
+					checkRef(at, mod, target, 'Action', `events.${event}`);
+				}
+				break;
+			}
+		}
+	}
+
+	return issues;
+}