@human-synthesis/norns 0.0.5 → 0.0.7

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Human Synthesis
+Copyright (c) 2026 Daniel Teodoroiu / Human Synthesis
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,16 +1,30 @@
-# @human-synthesis/norns
+# Norns
 
-SvelteKit with CoffeeScript, Pug, and UnoCSS preconfigured.
+**AI-driven software architecture and development framework, based on Svelte.**
 
-Builds on top of [`@human-synthesis/norns-core`](https://github.com/human-synthesis/norns-core) and adds first-class support for `.coffee` SvelteKit special files (`+page.coffee`, `+page.server.coffee`, `hooks.server.coffee`, `+server.coffee`, etc.).
+SvelteKit with **Pug + Civet** and the `.n` / `.c` file extensions — preconfigured. The `.c` extension is recognised as an alias for `.civet`; both compile through Civet. CoffeeScript is no longer supported.
+
+Includes a small runtime layer: feature-folder modularity, a DI container, route/page wrappers with valibot validation, and a migrations CLI.
+
+## Stack
+
+- [Svelte 5](https://svelte.dev) — components and runes
+- [SvelteKit 2](https://kit.svelte.dev) — file-system routing, SSR, endpoints
+- [Pug](https://pugjs.org) — templates
+- [Civet](https://civet.dev) — script (TypeScript-flavored, indented)
+- [Tailwind CSS v4](https://tailwindcss.com) — recommended styling (consumer-installed)
+- [Vite](https://vitejs.dev) — bundler
+- [bun](https://bun.sh) — runtime / package manager
 
 ## Install
 
 ```sh
-pnpm add -D @human-synthesis/norns @sveltejs/kit svelte unocss vite
+bun add -D @human-synthesis/norns @sveltejs/kit svelte
 ```
 
-## Usage
+Or use the [`norns-app`](https://github.com/human-synthesis/norns-app) starter, which has everything wired up.
+
+## Setup
 
 `svelte.config.js`:
 
@@ -18,8 +32,7 @@ pnpm add -D @human-synthesis/norns @sveltejs/kit svelte unocss vite
 import { nornsConfig } from '@human-synthesis/norns/config';
 
 export default nornsConfig({
-  // your overrides here, e.g.:
-  // kit: { adapter: adapterNode() }
+  // your overrides here
 });
 ```
 
@@ -28,42 +41,134 @@ export default nornsConfig({
 ```js
 import { defineConfig } from 'vite';
 import { sveltekit } from '@sveltejs/kit/vite';
-import { nornsCoffeePlugin, nornsUno } from '@human-synthesis/norns';
+import { nornsCivetPlugin } from '@human-synthesis/norns/vite';
 
 export default defineConfig({
-  plugins: [nornsCoffeePlugin(), nornsUno(), sveltekit()]
+  plugins: [nornsCivetPlugin(), sveltekit()]
 });
 ```
 
-## What this gives you
+`package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "norns dev",
+    "build": "norns build",
+    "preview": "norns preview",
+    "migrate": "norns migrate"
+  }
+}
+```
+
+## Auto-imports
 
-- **`.svelte` files** with `<script lang="coffee">`, `<template lang="pug">`, and UnoCSS class attributes
-- **`.coffee` Kit modules** — write `+page.coffee`, `+page.server.coffee`, `+layout.coffee`, `+server.coffee`, `hooks.server.coffee` instead of `.js`/`.ts`
-- **UnoCSS** preset stack (Uno, Attributify, Icons, Typography) wired into Vite
+`nornsAutoImport()` returns an object that's both a Svelte preprocessor (for `.n` / `.svelte` files) and a Vite plugin (for standalone `.c` / `.civet` modules). Wire it in both places:
 
-## Example route
+```js
+// svelte.config.js
+import { nornsConfig } from '@human-synthesis/norns/config';
+import { nornsPreprocess } from '@human-synthesis/norns/preprocess';
+import { nornsAutoImport } from '@human-synthesis/norns/auto-import';
 
-`src/routes/+page.svelte`:
+export default nornsConfig({
+  preprocess: [...nornsPreprocess(), nornsAutoImport()]
+});
+```
 
-```svelte
-<template lang="pug">
-  h1.text-3xl.font-bold Hello {data.name}
-  button(on:click="{() => count++}") count is {count}
-</template>
+```js
+// vite.config.js
+import { nornsCivetPlugin } from '@human-synthesis/norns/vite';
+import { nornsAutoImport } from '@human-synthesis/norns/auto-import';
 
-<script lang="coffee">
-  export let data
-  count = 0
-</script>
+export default { plugins: [nornsCivetPlugin(), nornsAutoImport(), sveltekit()] };
 ```
 
-`src/routes/+page.server.coffee`:
+With both in place:
+
+- **Svelte helpers** — `onMount`, `tick`, `getContext`, …, plus `svelte/store` (`writable`, `readable`, `derived`, `get`).
+- **SvelteKit helpers** — `error`, `redirect`, `fail`, `json`, `text`, … from `@sveltejs/kit`. Plus `page`, `navigating`, `updated` from `$app/state` — gated to non-server paths so it doesn't collide with the Norns server `page` (different shape, same name).
+- **Norns server helpers** — `boot`, `page`, `route`, `Container`, `validate`, `betterSqlite`, … from `@human-synthesis/norns/server`. Gated to server paths (`*.server.{c,civet}`, `**/server/**`, `+server.{c,civet}`).
+- **Project components** — capitalised references like `<Card>` or `<Modal>` resolve to files under `src/lib/components/**` by default. Components inside `$lib` emit `$lib/...` import paths; components outside (e.g. route-colocated under `src/routes/**`, when you add it to `componentDirs`) emit a path relative to the importer. Files without a `<script>` block get one prepended automatically.
+- **Runes** (`$state`, `$derived`, `$effect`, `$props`) are Svelte compiler globals — no import needed; the plugin doesn't touch them.
+
+Configurable on `nornsAutoImport({ … })`: `helpers` (each entry can carry an optional `match: RegExp` to gate by filename), `componentDirs`, `componentExtensions`, `libRoot`, `libAlias`. Pass `helpers: false` or `componentDirs: false` to disable either layer.
+
+## Runtime — feature folders + DI
+
+Wire your hooks once:
 
 ```coffee
-export load = ->
-  name: 'Norns'
+# src/hooks.server.c
+import { boot } from '@human-synthesis/norns/server'
+
+features := import.meta.glob './lib/*/server/module.c', { eager: true }
+app := await boot { features }
+
+{ handle, handleError } := app
+export { handle, handleError }
 ```
 
-## License & attribution
+Each feature is a folder under `src/lib/<feature>/`:
+
+```
+src/lib/notes/
+  server/
+    module.c        # registers DI bindings + migrations
+    repo.c          # SQL / data access
+    service.c       # business logic
+    public.c        # the ONLY file other features may import
+  shared/
+    schema.c        # valibot validation schemas
+```
+
+Routes use thin wrappers from `@human-synthesis/norns/server`:
+
+```coffee
+# src/routes/notes/+page.server.c
+import { page } from '@human-synthesis/norns/server'
+import { notes } from '$lib/notes/server/public'
+import { createNoteSchema } from '$lib/notes/shared/schema'
+
+export load := page.load
+  handler: ({ container }) =>
+    notes: notes(container).list()
+
+export actions := page.actions
+  create:
+    input: createNoteSchema
+    run: ({ input, container }) =>
+      id := notes(container).create input
+      throw redirect 303, `/notes/${id}`
+```
+
+The wrappers handle: input parsing, [valibot](https://valibot.dev) validation, container resolution, and consistent error mapping.
+
+## Migrations
+
+```sh
+bun run migrate create notes/add_pinned    # scaffold migrations/notes/<ts>_add_pinned.sql
+bun run migrate up                         # apply pending migrations
+bun run migrate status                     # list applied + pending
+```
+
+Migration files live at `<project>/migrations/<feature>/*.sql`. The CLI tracks applied migrations in a `norns_migrations` table.
+
+v1 supports SQLite via `better-sqlite3`. For Cloudflare D1 use `wrangler d1 migrations apply`. Postgres / libSQL via the CLI are planned.
+
+## Drivers
+
+The `db` helpers wire Drizzle across multiple targets:
+
+```coffee
+# module.c — Node + better-sqlite3 in dev
+import { betterSqlite } from '@human-synthesis/norns/server'
+db := await betterSqlite 'data/app.db', { pragma: ['journal_mode = WAL'] }
+app.single 'db', => db
+```
+
+D1, libSQL, and Postgres factories ship in the same module; the driver packages are user-installed (peer-style).
+
+## License
 
-MIT © Human Synthesis. Built on top of [SvelteKit](https://github.com/sveltejs/kit) and [Svelte](https://github.com/sveltejs/svelte) © Svelte Contributors, MIT licensed.
+MIT © Daniel Teodoroiu / [Human Synthesis](https://humansynthesis.ai). Built on top of [SvelteKit](https://github.com/sveltejs/kit) and [Svelte](https://github.com/sveltejs/svelte) © Svelte Contributors, MIT licensed.

package/bin/norns.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { watch, realpathSync, readFileSync, lstatSync, readdirSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
+import {
+	listMigrations,
+	resolveDatabaseUrl,
+	openSqliteDb,
+	getApplied,
+	applyMigrations,
+	createMigration
+} from '../src/migrate.js';
+
+const FRAMEWORK_PKGS = ['@human-synthesis/norns-core', '@human-synthesis/norns'];
+
+function resolveWorkspaceFrameworkSrcs(root) {
+	const require = createRequire(join(root, 'package.json'));
+	const out = [];
+	for (const pkg of FRAMEWORK_PKGS) {
+		try {
+			const real = realpathSync(require.resolve(`${pkg}/package.json`));
+			const pkgDir = dirname(real);
+			if (!pkgDir.includes(`${join('/', 'node_modules', '/')}`)) {
+				out.push(join(pkgDir, 'src'));
+			}
+		} catch {}
+	}
+	return out;
+}
+
+/**
+ * In workspace mode (a parent node_modules has framework packages as symlinks),
+ * a `bun add <pkg>` from the consumer dir often drops the *published* version
+ * of @human-synthesis/* into the local node_modules, which then shadows the
+ * workspace symlinks. The shadow is the npm-published code, not the local
+ * source — silently breaks dev. This detects the shadow and removes it.
+ *
+ * Only acts when both conditions hold:
+ *   1. some ancestor node_modules has the framework package as a symlink
+ *      (proves we're in workspace mode)
+ *   2. the cwd-local node_modules has the same package as a real directory
+ *      (the shadow that's overriding the symlink)
+ *
+ * No-op for normal installs (no symlinked ancestor → nothing to shadow).
+ *
+ * @param {string} cwd
+ * @returns {string[]} package names that were cleaned
+ */
+function cleanShadowedFrameworkPkgs(cwd) {
+	// Walk up from cwd looking for a parent with a framework package as symlink.
+	let workspaceMode = false;
+	let dir = dirname(cwd);
+	while (dir !== dirname(dir)) {
+		for (const pkg of FRAMEWORK_PKGS) {
+			try {
+				const stat = lstatSync(join(dir, 'node_modules', ...pkg.split('/')));
+				if (stat.isSymbolicLink()) {
+					workspaceMode = true;
+					break;
+				}
+			} catch {}
+		}
+		if (workspaceMode) break;
+		dir = dirname(dir);
+	}
+	if (!workspaceMode) return [];
+
+	const removed = [];
+	for (const pkg of FRAMEWORK_PKGS) {
+		const shadowPath = join(cwd, 'node_modules', ...pkg.split('/'));
+		try {
+			const stat = lstatSync(shadowPath);
+			// lstat doesn't follow symlinks — a symlinked dir reports
+			// isDirectory() === false, so this only matches real dirs.
+			if (stat.isDirectory()) {
+				rmSync(shadowPath, { recursive: true, force: true });
+				removed.push(pkg);
+			}
+		} catch {}
+	}
+
+	// Tidy up an emptied @human-synthesis/ scope dir if it has no other content.
+	const scopeDir = join(cwd, 'node_modules', '@human-synthesis');
+	try {
+		if (readdirSync(scopeDir).length === 0) rmSync(scopeDir, { recursive: true, force: true });
+	} catch {}
+
+	return removed;
+}
+
+function findViteBin(root) {
+	const require = createRequire(join(root, 'package.json'));
+	const pkgPath = require.resolve('vite/package.json');
+	const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+	const binEntry = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.vite;
+	if (!binEntry) throw new Error('vite package has no bin entry');
+	return join(dirname(pkgPath), binEntry);
+}
+
+function devCommand(passthrough) {
+	const cwd = process.cwd();
+	const cleaned = cleanShadowedFrameworkPkgs(cwd);
+	if (cleaned.length > 0) {
+		console.log(
+			`[norns] removed shadowed framework packages from local node_modules: ${cleaned.join(', ')} ` +
+				`— the workspace symlinks at the parent will be used instead.`
+		);
+	}
+	const viteBin = findViteBin(cwd);
+	const watchSrcs = resolveWorkspaceFrameworkSrcs(cwd);
+
+	let child = null;
+	let restarting = false;
+	let pendingRestart = false;
+
+	function spawnVite() {
+		child = spawn(process.execPath, [viteBin, 'dev', ...passthrough], {
+			cwd,
+			stdio: 'inherit',
+			env: process.env
+		});
+		child.on('exit', (code, signal) => {
+			child = null;
+			if (restarting) {
+				restarting = false;
+				if (pendingRestart) {
+					pendingRestart = false;
+				}
+				spawnVite();
+				return;
+			}
+			process.exit(code ?? (signal ? 1 : 0));
+		});
+	}
+
+	function restart(reason) {
+		if (restarting) {
+			pendingRestart = true;
+			return;
+		}
+		restarting = true;
+		console.log(`\n[norns] ${reason} — respawning vite dev for fresh module cache.\n`);
+		if (child && child.exitCode === null) child.kill('SIGTERM');
+		else spawnVite();
+	}
+
+	let debounce = null;
+	function onChange(file) {
+		clearTimeout(debounce);
+		debounce = setTimeout(() => {
+			restart(`framework source changed (${file})`);
+		}, 100);
+	}
+
+	for (const src of watchSrcs) {
+		try {
+			watch(src, { recursive: true }, (_event, filename) => {
+				if (!filename) return;
+				onChange(join(src, filename));
+			});
+			console.log(`[norns] watching framework src: ${src}`);
+		} catch (err) {
+			console.warn(`[norns] could not watch ${src}: ${err.message}`);
+		}
+	}
+
+	for (const sig of ['SIGINT', 'SIGTERM']) {
+		process.on(sig, () => {
+			if (child && child.exitCode === null) child.kill(sig);
+			else process.exit(0);
+		});
+	}
+
+	spawnVite();
+}
+
+function passthroughCommand(name, passthrough) {
+	const cwd = process.cwd();
+	const cleaned = cleanShadowedFrameworkPkgs(cwd);
+	if (cleaned.length > 0) {
+		console.log(
+			`[norns] removed shadowed framework packages from local node_modules: ${cleaned.join(', ')}`
+		);
+	}
+	const viteBin = findViteBin(cwd);
+	const child = spawn(process.execPath, [viteBin, name, ...passthrough], {
+		cwd,
+		stdio: 'inherit',
+		env: process.env
+	});
+	child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
+}
+
+function migrateCommand(rest) {
+	const sub = rest[0] || 'status';
+	const cwd = process.cwd();
+	const cleaned = cleanShadowedFrameworkPkgs(cwd);
+	if (cleaned.length > 0) {
+		console.log(
+			`[norns] removed shadowed framework packages from local node_modules: ${cleaned.join(', ')}`
+		);
+	}
+	try {
+		switch (sub) {
+			case 'status':
+				return runMigrateStatus(cwd);
+			case 'up':
+				return runMigrateUp(cwd);
+			case 'create': {
+				const file = createMigration(cwd, rest[1]);
+				console.log(`Created ${file}`);
+				return;
+			}
+			default:
+				console.error(`norns migrate: unknown subcommand "${sub}"`);
+				console.error('Usage: norns migrate <status|up|create <feature>/<name>>');
+				process.exit(1);
+		}
+	} catch (err) {
+		console.error(err.message);
+		process.exit(1);
+	}
+}
+
+function runMigrateStatus(cwd) {
+	const all = listMigrations(cwd);
+	if (all.length === 0) {
+		console.log('No migrations found.');
+		return;
+	}
+	const db = openTargetDb(cwd);
+	const applied = getApplied(db);
+	console.log(`Found ${all.length} migration(s):`);
+	for (const m of all) {
+		const tag = applied.has(m.id) ? '[applied]' : '[pending]';
+		console.log(`  ${tag} ${m.id}`);
+	}
+	const pending = all.filter((m) => !applied.has(m.id)).length;
+	console.log(`\n${pending} pending, ${all.length - pending} applied.`);
+}
+
+function runMigrateUp(cwd) {
+	const all = listMigrations(cwd);
+	if (all.length === 0) {
+		console.log('No migrations found.');
+		return;
+	}
+	const db = openTargetDb(cwd);
+	const applied = getApplied(db);
+	const pending = all.filter((m) => !applied.has(m.id));
+	if (pending.length === 0) {
+		console.log('Nothing to apply — all migrations are up to date.');
+		return;
+	}
+	console.log(`Applying ${pending.length} migration(s)...`);
+	for (const m of pending) {
+		try {
+			applyMigrations(db, [m]);
+			console.log(`  [ok] ${m.id}`);
+		} catch (err) {
+			console.error(`  [fail] ${m.id}: ${err.message}`);
+			process.exit(1);
+		}
+	}
+	console.log('Done.');
+}
+
+function openTargetDb(cwd) {
+	const target = resolveDatabaseUrl(cwd);
+	return openSqliteDb(cwd, target.path);
+}
+
+const [, , cmd = 'dev', ...rest] = process.argv;
+
+switch (cmd) {
+	case 'dev':
+		devCommand(rest);
+		break;
+	case 'build':
+	case 'preview':
+		passthroughCommand(cmd, rest);
+		break;
+	case 'migrate':
+		migrateCommand(rest);
+		break;
+	case '-h':
+	case '--help':
+		console.log(`norns <command>
+
+Commands:
+  dev                                start vite dev with framework-source watching (default)
+  build                              run vite build
+  preview                            run vite preview
+  migrate status                     list applied + pending migrations
+  migrate up                         apply pending migrations
+  migrate create <feature>/<name>    scaffold a new SQL migration
+
+Migration db is read from \$DATABASE_URL (default: file:./data/app.db).
+Only file: (better-sqlite3) is supported in v1; for D1 use \`wrangler d1 migrations apply\`.
+`);
+		break;
+	default:
+		console.error(`norns: unknown command "${cmd}"`);
+		process.exit(1);
+}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@human-synthesis/norns",
-  "version": "0.0.5",
-  "description": "Norns — SvelteKit with CoffeeScript, Pug, and UnoCSS preconfigured",
+  "version": "0.0.7",
+  "description": "Norns — SvelteKit with Civet, Pug, and the .n / .civet / .c file extensions",
   "license": "MIT",
-  "author": "Human Synthesis",
+  "author": "Daniel Teodoroiu (https://humansynthesis.ai)",
   "type": "module",
   "repository": {
     "type": "git",
@@ -11,25 +11,32 @@
   },
   "files": [
     "src",
+    "bin",
     "README.md"
   ],
+  "bin": {
+    "norns": "./bin/norns.js"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
   "exports": {
     ".": "./src/index.js",
+    "./auto-import": "./src/auto-import.js",
     "./config": "./src/config.js",
     "./vite": "./src/vite.js",
     "./preprocess": "./src/preprocess.js",
-    "./uno": "./src/uno.js",
+    "./server": "./src/server/index.js",
     "./package.json": "./package.json"
   },
   "peerDependencies": {
     "@sveltejs/kit": "^2.0.0",
     "svelte": "^5.0.0",
-    "unocss": "^0.65.0",
     "vite": "^5.0.0 || ^6.0.0"
   },
   "dependencies": {
-    "@human-synthesis/norns-core": "^0.0.5",
-    "coffeescript": "^2.7.0"
+    "@danielx/civet": "^0.11.0",
+    "@human-synthesis/norns-core": "^0.0.7"
   },
   "engines": {
     "node": ">=18"