@human-synthesis/norns 0.0.6 → 0.0.7

package/src/config.js

@@ -1,3 +1,5 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { nornsPreprocess } from '@human-synthesis/norns-core/preprocess';
 
 /**
@@ -5,7 +7,13 @@ import { nornsPreprocess } from '@human-synthesis/norns-core/preprocess';
  *
  * Defaults:
  * - `extensions: ['.svelte', '.n']`         — both vanilla and Norns components
- * - `kit.moduleExtensions: ['.js', '.ts', '.c']` — Kit special files (`+page.c` etc.)
+ * - `kit.moduleExtensions: ['.js', '.ts', '.c', '.civet']` — Kit special files
+ *   (`+page.c`, `+page.civet`, etc.)
+ * - `kit.files.hooks.server` — set to `src/hooks.server.{c,civet}` if either
+ *   file exists. SvelteKit's upstream `resolve_entry` only searches `.js` /
+ *   `.ts` for hooks (it doesn't honor `moduleExtensions`), so the explicit
+ *   path is the non-invasive way to make `.c`/`.civet` hooks discoverable.
+ *   Same for the client and universal counterparts.
  * - `preprocess: nornsPreprocess()`         — Coffee + Pug + rune fusion + auto-close
  *
  * Spread your own overrides at the call site to extend or replace defaults.
@@ -20,13 +28,50 @@ export function nornsConfig(overrides = {}) {
 		extensions: extensionsOverride,
 		...rest
 	} = overrides;
+
+	const cwd = process.cwd();
+	const userFiles = kitOverrides.files ?? {};
+	const userHooks = userFiles.hooks ?? {};
+
+	const hooks = {
+		...userHooks,
+		server: userHooks.server ?? findHook(cwd, ['src/hooks.server.c', 'src/hooks.server.civet']),
+		client: userHooks.client ?? findHook(cwd, ['src/hooks.client.c', 'src/hooks.client.civet']),
+		universal: userHooks.universal ?? findHook(cwd, ['src/hooks.c', 'src/hooks.civet'])
+	};
+	// Drop keys whose value is undefined so SvelteKit applies its defaults
+	for (const k of /** @type {const} */ (['server', 'client', 'universal'])) {
+		if (hooks[k] === undefined) delete hooks[k];
+	}
+
+	const { files: _ignoredUserFiles, ...kitRest } = kitOverrides;
+
 	return {
 		extensions: extensionsOverride ?? ['.svelte', '.n'],
 		preprocess: preprocessOverride ?? nornsPreprocess(),
 		kit: {
-			moduleExtensions: ['.js', '.ts', '.c'],
-			...kitOverrides
+			moduleExtensions: ['.js', '.ts', '.c', '.civet'],
+			...kitRest,
+			files: {
+				...userFiles,
+				hooks
+			}
 		},
 		...rest
 	};
 }
+
+/**
+ * Return the first relative path whose file exists, or `undefined` so
+ * SvelteKit falls back to its default `.js` / `.ts` resolution.
+ *
+ * @param {string} cwd
+ * @param {string[]} candidates
+ * @returns {string | undefined}
+ */
+function findHook(cwd, candidates) {
+	for (const rel of candidates) {
+		if (existsSync(join(cwd, rel))) return rel;
+	}
+	return undefined;
+}

package/src/index.js

@@ -1,3 +1,4 @@
+export { nornsAutoImport } from './auto-import.js';
 export { nornsConfig } from './config.js';
-export { nornsCoffeePlugin } from './vite.js';
+export { nornsCivetPlugin } from './vite.js';
 export { nornsPreprocess } from './preprocess.js';

package/src/migrate.js

@@ -0,0 +1,212 @@
+/**
+ * Migration discovery + applier for the `norns migrate` CLI. Pure functions —
+ * `bin/norns.js` is a thin shell over these.
+ *
+ * Layout convention:
+ *   <project>/migrations/<feature>/<timestamp>_<slug>.sql
+ *
+ * Migrations live at the project root, OUTSIDE `src/lib/`, organised per
+ * feature. They aren't application code — they're operational artifacts that
+ * tooling (this CLI, wrangler for D1) reads. Keeping them out of `src/lib`
+ * also keeps SvelteKit's bundler from ever trying to ship them.
+ *
+ * v1 supports SQLite via `better-sqlite3`. Postgres/libSQL come later;
+ * Cloudflare D1 is intentionally out of scope here — use
+ * `wrangler d1 migrations apply <db>` for D1 deploys.
+ */
+
+import { existsSync, readdirSync, statSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+
+/**
+ * Reserved names under `src/lib/`. These are treated as utility folders, not
+ * features. Anything starting with `_` is also reserved.
+ */
+export const RESERVED_LIB_DIRS = new Set(['server', 'components', 'utils']);
+
+export const MIGRATION_TABLE = 'norns_migrations';
+
+/**
+ * List feature folder names under `src/lib/`. A folder is a feature iff it
+ * contains `server/module.c`.
+ *
+ * @param {string} libDir
+ * @returns {string[]}
+ */
+export function listFeatures(libDir) {
+	if (!existsSync(libDir)) return [];
+	const out = [];
+	for (const name of readdirSync(libDir)) {
+		if (name.startsWith('_')) continue;
+		if (RESERVED_LIB_DIRS.has(name)) continue;
+		const featureDir = join(libDir, name);
+		try {
+			if (!statSync(featureDir).isDirectory()) continue;
+		} catch {
+			continue;
+		}
+		const modulePath = join(featureDir, 'server', 'module.c');
+		if (existsSync(modulePath)) out.push(name);
+	}
+	out.sort();
+	return out;
+}
+
+/** @typedef {{ feature: string, file: string, path: string, id: string }} Migration */
+
+/** @param {string} cwd */
+export function migrationsRoot(cwd) {
+	return join(cwd, 'migrations');
+}
+
+/**
+ * Scan `<cwd>/migrations/<feature>/*.sql` across all features. Sorted by
+ * filename first (so timestamp-prefixed files apply chronologically across
+ * features) and feature name as a tiebreaker.
+ *
+ * @param {string} cwd
+ * @returns {Migration[]}
+ */
+export function listMigrations(cwd) {
+	const root = migrationsRoot(cwd);
+	if (!existsSync(root)) return [];
+	const out = [];
+	for (const feature of readdirSync(root)) {
+		const featDir = join(root, feature);
+		try {
+			if (!statSync(featDir).isDirectory()) continue;
+		} catch {
+			continue;
+		}
+		for (const file of readdirSync(featDir)) {
+			if (!file.endsWith('.sql')) continue;
+			out.push({
+				feature,
+				file,
+				path: join(featDir, file),
+				id: `${feature}/${file.replace(/\.sql$/, '')}`
+			});
+		}
+	}
+	out.sort((a, b) => {
+		const c = a.file.localeCompare(b.file);
+		return c !== 0 ? c : a.feature.localeCompare(b.feature);
+	});
+	return out;
+}
+
+/**
+ * Resolve `DATABASE_URL` to a connection. v1: only `file:` (SQLite via
+ * better-sqlite3). Defaults to `file:./data/app.db` if unset.
+ *
+ * @param {string} cwd
+ * @returns {{ kind: 'sqlite', path: string }}
+ */
+export function resolveDatabaseUrl(cwd) {
+	const url = process.env.DATABASE_URL || `file:${join(cwd, 'data', 'app.db')}`;
+	if (url.startsWith('file:')) return { kind: 'sqlite', path: url.slice(5) };
+	const scheme = url.split('://')[0];
+	throw new Error(
+		`norns migrate: only SQLite (file:...) is supported in v1; got "${scheme}://...".\n` +
+			'  For Cloudflare D1, use `wrangler d1 migrations apply <db>`.\n' +
+			'  Postgres/libSQL via the CLI are not yet wired.'
+	);
+}
+
+/**
+ * Open a better-sqlite3 db at `path` and ensure the migration tracking table
+ * exists.
+ *
+ * @param {string} cwd directory whose `package.json` is used to resolve
+ *                     better-sqlite3 from the consumer's node_modules
+ * @param {string} path SQLite file path
+ * @param {{ requireFrom?: string | URL }} [opts] override the require base
+ *                                                (used by tests)
+ * @returns {any}
+ */
+export function openSqliteDb(cwd, path, opts = {}) {
+	mkdirSync(dirname(path), { recursive: true });
+	const require = createRequire(opts.requireFrom ?? join(cwd, 'package.json'));
+	let Database;
+	try {
+		Database = require('better-sqlite3');
+	} catch {
+		throw new Error(
+			'norns migrate: `better-sqlite3` is not installed in this app. Run: bun add better-sqlite3'
+		);
+	}
+	const db = new Database(path);
+	db.pragma('journal_mode = WAL');
+	db.exec(`CREATE TABLE IF NOT EXISTS ${MIGRATION_TABLE} (
+		id TEXT PRIMARY KEY,
+		applied_at INTEGER NOT NULL
+	)`);
+	return db;
+}
+
+/**
+ * @param {any} db
+ * @returns {Set<string>}
+ */
+export function getApplied(db) {
+	const rows = db.prepare(`SELECT id FROM ${MIGRATION_TABLE}`).all();
+	return new Set(rows.map((r) => r.id));
+}
+
+/**
+ * Apply pending migrations to `db`. Returns the list of ids applied.
+ *
+ * @param {any} db
+ * @param {Migration[]} pending
+ * @returns {string[]}
+ */
+export function applyMigrations(db, pending) {
+	const insert = db.prepare(`INSERT INTO ${MIGRATION_TABLE} (id, applied_at) VALUES (?, ?)`);
+	const applied = [];
+	for (const m of pending) {
+		const sql = readFileSync(m.path, 'utf8');
+		const tx = db.transaction(() => {
+			db.exec(sql);
+			insert.run(m.id, Date.now());
+		});
+		tx();
+		applied.push(m.id);
+	}
+	return applied;
+}
+
+/**
+ * Scaffold a new migration file at `<cwd>/migrations/<feature>/<ts>_<slug>.sql`.
+ *
+ * No filesystem check on the feature name — both `src/lib/<feature>/` (the
+ * default convention) and nested layouts like `src/lib/<group>/<feature>/`
+ * (used by demos that mirror multiple variants side by side) are valid.
+ * Typo'd feature names produce orphan folders that are easy to spot under
+ * `migrations/`.
+ *
+ * @param {string} cwd
+ * @param {string} arg `<feature>/<name>` form
+ * @returns {string} the path of the created file
+ */
+export function createMigration(cwd, arg) {
+	if (!arg || !arg.includes('/')) {
+		throw new Error(
+			'Usage: norns migrate create <feature>/<name>\nExample: norns migrate create notes/add_pinned_column'
+		);
+	}
+	const [feature, ...rest] = arg.split('/');
+	const slug = rest.join('/').replace(/[^a-zA-Z0-9_]+/g, '_');
+	const migDir = join(migrationsRoot(cwd), feature);
+	mkdirSync(migDir, { recursive: true });
+	const ts = new Date()
+		.toISOString()
+		.replace(/[-:T]/g, '')
+		.replace(/\..+$/, '')
+		.slice(0, 14);
+	const file = join(migDir, `${ts}_${slug}.sql`);
+	writeFileSync(file, `-- ${feature}: ${slug}\n-- Created: ${new Date().toISOString()}\n\n`, {
+		flag: 'wx'
+	});
+	return file;
+}

package/src/server/boot.js

@@ -0,0 +1,74 @@
+import { sequence } from '@sveltejs/kit/hooks';
+import { Container } from './container.js';
+import { contextHandle } from './handle/context.js';
+import { errorHandle } from './handle/error.js';
+
+/**
+ * Create a fresh root container with no features registered. Useful for tests
+ * that want full control over what's bound.
+ *
+ * @returns {Container}
+ */
+export function createApp() {
+	return new Container();
+}
+
+/** @typedef {(app: Container) => void | Promise<void>} ModuleRegister */
+/** @typedef {{ default?: ModuleRegister } | ModuleRegister} FeatureModule */
+
+/**
+ * Boot a Norns app: builds the root container, runs every feature's
+ * `module.c` registration, and returns the SvelteKit hooks ready to wire into
+ * `src/hooks.server.c`.
+ *
+ * Typical use in a consumer app:
+ *
+ *   import { boot } from '@human-synthesis/norns/server';
+ *
+ *   const app = await boot({
+ *     features: import.meta.glob('./lib/*\/server/module.c', { eager: true })
+ *   });
+ *   export const { handle, handleError, container } = app;
+ *
+ * Each `module.c` must default-export a function `(app) -> ...` that calls
+ * `app.bind(...)` / `app.single(...)` / `app.migrations(...)`.
+ *
+ * @param {{
+ *   features?: Record<string, FeatureModule>,
+ *   extraHandle?: import('@sveltejs/kit').Handle | import('@sveltejs/kit').Handle[],
+ *   handleError?: import('@sveltejs/kit').HandleServerError
+ * }} [opts]
+ * @returns {Promise<{
+ *   container: Container,
+ *   handle: import('@sveltejs/kit').Handle,
+ *   handleError: import('@sveltejs/kit').HandleServerError
+ * }>}
+ */
+export async function boot(opts = {}) {
+	const container = createApp();
+
+	if (opts.features) {
+		for (const [path, mod] of Object.entries(opts.features)) {
+			const register = /** @type {ModuleRegister | undefined} */ (
+				typeof mod === 'function' ? mod : mod?.default
+			);
+			if (typeof register !== 'function') {
+				throw new Error(
+					`Norns: ${path} must default-export a function (app) -> ... — got ${typeof register}`
+				);
+			}
+			await register(container);
+		}
+	}
+
+	const extras = opts.extraHandle
+		? Array.isArray(opts.extraHandle)
+			? opts.extraHandle
+			: [opts.extraHandle]
+		: [];
+
+	const handle = sequence(contextHandle(container), ...extras);
+	const handleError = opts.handleError ?? errorHandle();
+
+	return { container, handle, handleError };
+}

package/src/server/container.js

@@ -0,0 +1,175 @@
+/**
+ * Norns DI container.
+ *
+ * Tokens are namespaced strings (e.g. `notes.repo`, `db`). Bindings register a
+ * factory that produces an instance; `single` bindings memoize at the level
+ * where they are declared, `bind` bindings re-run the factory on every resolve.
+ *
+ * A child scope (created via `scope()`) inherits its parent's bindings but
+ * tracks its own overrides and request-scoped singletons. Request scopes are
+ * the natural fit for things like `db` (a transactional handle for one
+ * request) or `user` (the authenticated principal).
+ *
+ * Overrides take precedence over bindings at every level — used in tests to
+ * swap a real service for a fake without rebinding the production module.
+ *
+ * Migration directories are tracked at the root container only; child scopes
+ * inherit visibility through the root walk.
+ */
+
+/** @typedef {(c: Container) => any} Factory */
+/** @typedef {{ factory: Factory, lifetime: 'transient' | 'singleton' }} Binding */
+
+export class Container {
+	/** @param {Container | null} [parent] */
+	constructor(parent = null) {
+		/** @type {Container | null} */
+		this.parent = parent;
+		/** @type {Map<string, Binding>} */
+		this.bindings = new Map();
+		/** @type {Map<string, any>} */
+		this.singletons = new Map();
+		/** @type {Map<string, Factory>} */
+		this.overrides = new Map();
+		/** @type {string[]} */
+		this.migrationDirs = [];
+	}
+
+	/**
+	 * Bind a transient factory — called on every `resolve(token)`.
+	 *
+	 * @param {string} token
+	 * @param {Factory} factory
+	 * @returns {this}
+	 */
+	bind(token, factory) {
+		this.bindings.set(token, { factory, lifetime: 'transient' });
+		return this;
+	}
+
+	/**
+	 * Bind a singleton factory — called once per container scope.
+	 *
+	 * @param {string} token
+	 * @param {Factory} factory
+	 * @returns {this}
+	 */
+	single(token, factory) {
+		this.bindings.set(token, { factory, lifetime: 'singleton' });
+		return this;
+	}
+
+	/**
+	 * Override a token at this scope. Wins over any binding in this or any
+	 * parent scope. Useful in tests.
+	 *
+	 * @param {string} token
+	 * @param {Factory} factory
+	 * @returns {this}
+	 */
+	override(token, factory) {
+		this.overrides.set(token, factory);
+		return this;
+	}
+
+	/**
+	 * Register a migration directory. Tracked at the root container.
+	 *
+	 * @param {string} dir absolute path to a `migrations/` directory containing
+	 *                     `*.sql` files
+	 * @returns {this}
+	 */
+	migrations(dir) {
+		let root = /** @type {Container} */ (this);
+		while (root.parent) root = root.parent;
+		root.migrationDirs.push(dir);
+		return this;
+	}
+
+	/**
+	 * Get all registered migration directories. Walks to root.
+	 *
+	 * @returns {string[]}
+	 */
+	getMigrationDirs() {
+		let root = /** @type {Container} */ (this);
+		while (root.parent) root = root.parent;
+		return [...root.migrationDirs];
+	}
+
+	/**
+	 * Resolve a token to a value. Walks the scope chain.
+	 *
+	 * Resolution order:
+	 *   1. nearest override (any scope)
+	 *   2. nearest binding (any scope) — singletons cache at that scope
+	 *   3. throw
+	 *
+	 * The factory is called with the leaf scope (the one `resolve` was called
+	 * on), so factories can resolve other tokens at the same level.
+	 *
+	 * @param {string} token
+	 * @returns {any}
+	 */
+	resolve(token) {
+		let node = /** @type {Container | null} */ (this);
+		while (node) {
+			if (node.overrides.has(token)) {
+				const factory = /** @type {Factory} */ (node.overrides.get(token));
+				return factory(this);
+			}
+			node = node.parent;
+		}
+
+		node = this;
+		while (node) {
+			const binding = node.bindings.get(token);
+			if (binding) {
+				if (binding.lifetime === 'singleton') {
+					if (!node.singletons.has(token)) {
+						node.singletons.set(token, binding.factory(this));
+					}
+					return node.singletons.get(token);
+				}
+				return binding.factory(this);
+			}
+			node = node.parent;
+		}
+
+		throw new Error(`Container: no binding for token "${String(token)}"`);
+	}
+
+	/**
+	 * Whether a binding or override is reachable for the given token.
+	 *
+	 * @param {string} token
+	 * @returns {boolean}
+	 */
+	has(token) {
+		let node = /** @type {Container | null} */ (this);
+		while (node) {
+			if (node.overrides.has(token) || node.bindings.has(token)) return true;
+			node = node.parent;
+		}
+		return false;
+	}
+
+	/**
+	 * Create a child scope. The child inherits bindings via the parent walk;
+	 * its own overrides and singletons are isolated.
+	 *
+	 * @returns {Container}
+	 */
+	scope() {
+		return new Container(this);
+	}
+}
+
+/**
+ * Create a fresh root container.
+ *
+ * @returns {Container}
+ */
+export function createContainer() {
+	return new Container();
+}

package/src/server/db.js

@@ -0,0 +1,131 @@
+/**
+ * Drizzle driver factories + a portable transaction helper.
+ *
+ * Drivers are imported lazily so consumers only need to install the ones they
+ * actually use. Drizzle and its driver packages are user-installed (not
+ * bundled in norns) — the framework just provides the assembly recipe.
+ *
+ * The dynamic `import()` paths are routed through a variable + `@vite-ignore`
+ * so Rollup doesn't try to resolve them at build time when the consumer
+ * hasn't installed the corresponding driver.
+ *
+ * Bind the result as `db` in your feature's `module.c`:
+ *
+ *   import { betterSqlite } from '@human-synthesis/norns/server';
+ *   module.exports = (app) ->
+ *     dbInstance = await betterSqlite('data/notes.db', pragma: ['journal_mode = WAL'])
+ *     app.single 'db', -> dbInstance
+ *
+ * For Cloudflare Workers, switch to `d1(env.DB)`. Same module.c shape.
+ */
+
+/**
+ * Pass-through dynamic import that hides the path from Rollup's static
+ * analyzer. Without this, building an app that doesn't have (say)
+ * `drizzle-orm/d1` installed fails even if the app never calls `d1()`.
+ *
+ * @param {string} mod
+ * @returns {Promise<any>}
+ */
+function importDynamic(mod) {
+	return import(/* @vite-ignore */ mod);
+}
+
+/**
+ * @typedef {Object} BetterSqliteOptions
+ * @property {Object} [connection] passed to `new Database(path, opts)`
+ * @property {string[]} [pragma] PRAGMA statements to run after open
+ * @property {Object} [drizzle] passed to `drizzle(sqlite, opts)`
+ */
+
+/**
+ * @typedef {Object} D1Options
+ * @property {Object} [drizzle] passed to `drizzle(binding, opts)`
+ */
+
+/**
+ * @typedef {Object} LibsqlOptions
+ * @property {Object} [client] passed to `createClient({ url, ...client })`
+ * @property {Object} [drizzle] passed to `drizzle(client, opts)`
+ */
+
+/**
+ * @typedef {Object} PostgresOptions
+ * @property {Object} [pool] passed to `new Pool({ connectionString: url, ...pool })`
+ * @property {Object} [drizzle] passed to `drizzle(pool, opts)`
+ */
+
+/**
+ * Open a Drizzle instance backed by `better-sqlite3`.
+ *
+ * @param {string} path SQLite file path (e.g. `data/notes.db`)
+ * @param {BetterSqliteOptions} [opts]
+ * @returns {Promise<any>}
+ */
+export async function betterSqlite(path, opts = {}) {
+	const [{ default: Database }, { drizzle }] = await Promise.all([
+		importDynamic('better-sqlite3'),
+		importDynamic('drizzle-orm/better-sqlite3')
+	]);
+	const sqlite = new Database(path, opts.connection);
+	if (opts.pragma) {
+		for (const p of opts.pragma) sqlite.pragma(p);
+	}
+	return drizzle(sqlite, opts.drizzle);
+}
+
+/**
+ * Open a Drizzle instance backed by Cloudflare D1.
+ *
+ * @param {any} binding D1 binding from `event.platform.env`
+ * @param {D1Options} [opts]
+ * @returns {Promise<any>}
+ */
+export async function d1(binding, opts = {}) {
+	const { drizzle } = await importDynamic('drizzle-orm/d1');
+	return drizzle(binding, opts.drizzle);
+}
+
+/**
+ * Open a Drizzle instance backed by libSQL (Turso, sqld).
+ *
+ * @param {string} url
+ * @param {LibsqlOptions} [opts]
+ * @returns {Promise<any>}
+ */
+export async function libsql(url, opts = {}) {
+	const [{ createClient }, { drizzle }] = await Promise.all([
+		importDynamic('@libsql/client'),
+		importDynamic('drizzle-orm/libsql')
+	]);
+	const client = createClient({ url, ...(opts.client ?? {}) });
+	return drizzle(client, opts.drizzle);
+}
+
+/**
+ * Open a Drizzle instance backed by node-postgres.
+ *
+ * @param {string} url
+ * @param {PostgresOptions} [opts]
+ * @returns {Promise<any>}
+ */
+export async function postgres(url, opts = {}) {
+	const [{ default: pgModule }, { drizzle }] = await Promise.all([
+		importDynamic('pg'),
+		importDynamic('drizzle-orm/node-postgres')
+	]);
+	const pool = new pgModule.Pool({ connectionString: url, ...(opts.pool ?? {}) });
+	return drizzle(pool, opts.drizzle);
+}
+
+/**
+ * Run `fn` inside a Drizzle transaction. Uniform across drivers.
+ *
+ * @template T
+ * @param {any} db Drizzle instance
+ * @param {(tx: any) => T | Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export function withTransaction(db, fn) {
+	return db.transaction(fn);
+}

package/src/server/handle/context.js

@@ -0,0 +1,24 @@
+import { withScope } from '../scope.js';
+
+/** @typedef {import('../container.js').Container} Container */
+/** @typedef {import('@sveltejs/kit').Handle} Handle */
+
+/**
+ * Per-request middleware: creates a child scope of the root container and
+ * attaches it to `event.locals.container`. Anything resolved through
+ * `event.locals.container` for the lifetime of the request hits this scope —
+ * overrides and request-scoped singletons (like `db`) live here.
+ *
+ * Also runs the rest of the pipeline inside `withScope()` so AsyncLocalStorage
+ * makes the scope available to callees that don't get `event` directly.
+ *
+ * @param {Container} app the root container produced by `createApp()`/`boot()`
+ * @returns {Handle}
+ */
+export function contextHandle(app) {
+	return async ({ event, resolve }) => {
+		const scope = app.scope();
+		event.locals.container = scope;
+		return withScope({ container: scope, event }, () => resolve(event));
+	};
+}