@human-synthesis/norns 0.0.6 → 0.0.8

package/README.md

@@ -2,15 +2,17 @@
 
 **AI-driven software architecture and development framework, based on Svelte.**
 
-SvelteKit with Pug, CoffeeScript, and `.n` / `.c` files — preconfigured.
+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.
+
+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
-- [CoffeeScript 2](https://coffeescript.org) — script
-- [Tailwind CSS v4](https://tailwindcss.com) — recommended styling
+- [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
 
@@ -39,10 +41,10 @@ export default nornsConfig({
 ```js
 import { defineConfig } from 'vite';
 import { sveltekit } from '@sveltejs/kit/vite';
-import { nornsCoffeePlugin } from '@human-synthesis/norns/vite';
+import { nornsCivetPlugin } from '@human-synthesis/norns/vite';
 
 export default defineConfig({
-  plugins: [nornsCoffeePlugin(), sveltekit()]
+  plugins: [nornsCivetPlugin(), sveltekit()]
 });
 ```
 
@@ -53,11 +55,189 @@ export default defineConfig({
   "scripts": {
     "dev": "norns dev",
     "build": "norns build",
-    "preview": "norns preview"
+    "preview": "norns preview",
+    "migrate": "norns migrate"
   }
 }
 ```
 
+## Auto-imports
+
+`nornsAutoImport()` returns an object that's both a Svelte preprocessor (for `.n` / `.svelte` files) and a Vite plugin (for standalone `.c` / `.civet` modules). The same instance has all four resolvers: framework helpers, project components, project utilities, and library presets. Wire it in both places — Svelte's compiler ignores the Vite hooks, Vite ignores the Svelte hooks:
+
+```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';
+
+export default nornsConfig({
+  preprocess: [
+    ...nornsPreprocess(),
+    nornsAutoImport({
+      componentDirs: ['src/lib/components', 'src/routes'],
+      exportDirs: ['src/lib', 'src/routes']
+    })
+  ]
+});
+```
+
+```js
+// vite.config.js
+import { nornsCivetPlugin } from '@human-synthesis/norns/vite';
+import { nornsAutoImport } from '@human-synthesis/norns/auto-import';
+
+export default {
+  plugins: [
+    nornsCivetPlugin(),
+    nornsAutoImport({ exportDirs: ['src/lib', 'src/routes'] }),
+    sveltekit()
+  ]
+};
+```
+
+### What gets auto-imported
+
+| Layer | Resolves | Examples |
+|-------|----------|----------|
+| Helpers | Hardcoded module-name lists, optionally path-gated | `onMount` from `svelte`, `redirect` from `@sveltejs/kit`, `page` from `$app/state` (client) or `@human-synthesis/norns/server` (server) |
+| Components (dir scan) | Capitalised basenames in `componentDirs` | `<Card>` → `$lib/components/Card.svelte`; `<Game>` → `./Game.n` (route-colocated, importer-relative) |
+| Components (preset map) | Bare-specifier `Record<name, importPath>` from a UI library | `<Btn>` → `'@human-synthesis/norns-ui/components/Btn.n'` (used verbatim) |
+| Project utilities | Named exports (`export const X`, `export X := …`, `export { a, b }`) discovered in `exportDirs` | `notes` from `$lib/notes/server/public`; `scheduleAiMove` from `./ai` (sibling) |
+
+Resolution priority is **helpers → component dir → component preset → exports**. A name picked up earlier shadows a later match silently — first-match-wins lets you override a library preset by dropping a file under your own `componentDirs`.
+
+Path emission:
+
+- Files inside `$lib` emit `$lib/...` paths (portable, friendly to the dts file).
+- Files outside `$lib` emit a path relative to the importer.
+- Project-utility paths are stripped of their file extension to match Norns/SvelteKit convention (`'$lib/notes/server/public'`, not `…/public.c`); the configured `extensions` array does the rest.
+
+Files without a `<script>` block get one prepended automatically when a known component is referenced from markup. Runes (`$state`, `$derived`, `$effect`, `$props`) are Svelte compiler globals — no import needed; the plugin doesn't touch them.
+
+### Defaults
+
+- **Helpers**: `svelte`, `svelte/store`, `@sveltejs/kit`, `$app/state` (non-server paths), `@human-synthesis/norns/server` (server paths only).
+- **Component dirs**: `['src/lib/components']`.
+- **Component extensions**: `['.svelte', '.n']`.
+- **Export dirs**: `false` (off) — opt in. SvelteKit route/hook files (`+*.{c,svelte,n}`, `hooks.*`) are excluded from the export scan since their named exports (`load`, `actions`, `handle`, …) are framework-consumed.
+- **Export extensions**: `['.c', '.civet', '.js']`. `.ts` is excluded by default — regex-based scanning can't reliably tell value exports from type-only ones under `verbatimModuleSyntax`.
+
+### UI library presets
+
+A preset is a function returning a config slice — typically a `components` map. Compose it with your own config:
+
+```js
+// vite.config.js
+import { presetUI } from '@human-synthesis/norns-ui/auto-import';
+
+const ui = presetUI();
+
+export default {
+  plugins: [
+    nornsCivetPlugin(),
+    nornsAutoImport({
+      exportDirs: ['src/lib', 'src/routes'],
+      components: ui.components   // { Btn: '@human-synthesis/norns-ui/components/Btn.n', … }
+    }),
+    sveltekit()
+  ]
+};
+```
+
+Drop `src/lib/components/Btn.n` in your project and it shadows the preset's `Btn` silently — `componentDirs` resolves first.
+
+> **Roadmap.** Helpers from a preset (e.g. `toast()` from a UI library) currently can't merge with the defaults — passing `helpers` to `nornsAutoImport` _replaces_ the default list. A `presets` (or `additionalHelpers`) option to extend without replacing is a planned follow-up; for now, presets only deliver components.
+
+### Full options reference
+
+| Option | Default | Notes |
+|--------|---------|-------|
+| `helpers` | `DEFAULT_HELPERS` (5 modules) | Pass `false` to disable. Each entry: `{ from, imports[], match? }` where `match` is a regex tested against the filename. |
+| `componentDirs` | `['src/lib/components']` | `false` or `[]` to disable. |
+| `componentExtensions` | `['.svelte', '.n']` | |
+| `components` | `null` | `Record<name, importPath>` — bare-specifier preset map. |
+| `exportDirs` | `false` | Off by default. Opt in with e.g. `['src/lib', 'src/routes']`. |
+| `exportExtensions` | `['.c', '.civet', '.js']` | |
+| `libRoot` | `'src/lib'` | Project-relative root that `libAlias` maps to. |
+| `libAlias` | `'$lib'` | Alias prefix emitted in import paths. |
+| `root` | `process.cwd()` | Project root. |
+
+## Runtime — feature folders + DI
+
+Wire your hooks once:
+
+```civet
+# 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 }
+```
+
+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`:
+
+```civet
+# 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:
+
+```civet
+# 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 © 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

@@ -1,8 +1,16 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process';
-import { watch, realpathSync, readFileSync } from 'node:fs';
+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'];
 
@@ -21,6 +29,66 @@ function resolveWorkspaceFrameworkSrcs(root) {
 	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');
@@ -32,6 +100,13 @@ function findViteBin(root) {
 
 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);
 
@@ -102,6 +177,12 @@ function devCommand(passthrough) {
 
 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,
@@ -111,6 +192,85 @@ function passthroughCommand(name, passthrough) {
 	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) {
@@ -121,14 +281,23 @@ switch (cmd) {
 	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
+  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:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@human-synthesis/norns",
-  "version": "0.0.6",
-  "description": "Norns — SvelteKit with CoffeeScript, Pug, and the .n / .c file extensions",
+  "version": "0.0.8",
+  "description": "Norns — SvelteKit with Civet, Pug, and the .n / .civet / .c file extensions",
   "license": "MIT",
   "author": "Daniel Teodoroiu (https://humansynthesis.ai)",
   "type": "module",
@@ -17,11 +17,16 @@
   "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",
+    "./server": "./src/server/index.js",
     "./package.json": "./package.json"
   },
   "peerDependencies": {
@@ -30,8 +35,8 @@
     "vite": "^5.0.0 || ^6.0.0"
   },
   "dependencies": {
-    "@human-synthesis/norns-core": "^0.0.6",
-    "coffeescript": "^2.7.0"
+    "@danielx/civet": "^0.11.0",
+    "@human-synthesis/norns-core": "^0.0.7"
   },
   "engines": {
     "node": ">=18"