@human-synthesis/norns 0.0.7 → 0.0.8

package/README.md

@@ -2,7 +2,7 @@
 
 **AI-driven software architecture and development framework, based on Svelte.**
 
-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.
+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.
 
@@ -63,7 +63,7 @@ export default defineConfig({
 
 ## 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). Wire it in both places:
+`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
@@ -72,7 +72,13 @@ import { nornsPreprocess } from '@human-synthesis/norns/preprocess';
 import { nornsAutoImport } from '@human-synthesis/norns/auto-import';
 
 export default nornsConfig({
-  preprocess: [...nornsPreprocess(), nornsAutoImport()]
+  preprocess: [
+    ...nornsPreprocess(),
+    nornsAutoImport({
+      componentDirs: ['src/lib/components', 'src/routes'],
+      exportDirs: ['src/lib', 'src/routes']
+    })
+  ]
 });
 ```
 
@@ -81,24 +87,87 @@ export default nornsConfig({
 import { nornsCivetPlugin } from '@human-synthesis/norns/vite';
 import { nornsAutoImport } from '@human-synthesis/norns/auto-import';
 
-export default { plugins: [nornsCivetPlugin(), nornsAutoImport(), sveltekit()] };
+export default {
+  plugins: [
+    nornsCivetPlugin(),
+    nornsAutoImport({ exportDirs: ['src/lib', 'src/routes'] }),
+    sveltekit()
+  ]
+};
 ```
 
-With both in place:
+### What gets auto-imported
 
-- **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.
+| 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) |
 
-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.
+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:
 
-```coffee
+```civet
 # src/hooks.server.c
 import { boot } from '@human-synthesis/norns/server'
 
@@ -124,7 +193,7 @@ src/lib/notes/
 
 Routes use thin wrappers from `@human-synthesis/norns/server`:
 
-```coffee
+```civet
 # src/routes/notes/+page.server.c
 import { page } from '@human-synthesis/norns/server'
 import { notes } from '$lib/notes/server/public'
@@ -160,7 +229,7 @@ v1 supports SQLite via `better-sqlite3`. For Cloudflare D1 use `wrangler d1 migr
 
 The `db` helpers wire Drizzle across multiple targets:
 
-```coffee
+```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'] }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@human-synthesis/norns",
-  "version": "0.0.7",
+  "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)",

package/src/auto-import.js

@@ -208,11 +208,20 @@ function extractExports(source) {
 	return out;
 }
 
+// SvelteKit route conventions (`+page.server.c`, `+layout.c`, `+server.c`,
+// `+error.svelte`, …) and hooks (`hooks.server.c`, `hooks.client.c`) export
+// names like `load`, `actions`, `GET`, `handle`, `prerender` that are
+// CONSUMED BY THE FRAMEWORK — never meant to be imported by other code. If
+// they entered the export map, a user identifier called `load` would
+// auto-import a random route's load function. Excluded by basename.
+const ROUTE_FILE_RE = /^(\+|hooks\.)/;
+
 /**
  * Walk `dirs` and build a name → absolute-file-path map of every named
  * value export found. First-match-wins on collisions (same as the component
  * scanner) — silent because warnings would noise up the dev server on
- * intentional re-exports.
+ * intentional re-exports. SvelteKit route/hook files are excluded by
+ * basename so framework-consumed exports don't leak into the map.
  *
  * @param {string} root
  * @param {string[]} dirs
@@ -225,6 +234,7 @@ function buildExportMap(root, dirs, exts) {
 	for (const d of dirs) {
 		const abs = resolve(root, d);
 		for (const file of walk(abs, exts)) {
+			if (ROUTE_FILE_RE.test(basename(file))) continue;
 			let source;
 			try {
 				source = readFileSync(file, 'utf8');

package/src/config.js

@@ -14,7 +14,7 @@ import { nornsPreprocess } from '@human-synthesis/norns-core/preprocess';
  *   `.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
+ * - `preprocess: nornsPreprocess()`         — Pug + Civet
  *
  * Spread your own overrides at the call site to extend or replace defaults.
  *

package/src/server/validate.js

@@ -2,7 +2,7 @@
  * Validation glue. Norns doesn't bundle a schema library — it speaks the
  * Standard Schema interface (https://github.com/standard-schema/standard-schema)
  * supported by Valibot, Zod 3.24+, ArkType, etc. A plain function (`input -> parsed`)
- * also works, for ad-hoc cases or simple Coffee parsers.
+ * also works, for ad-hoc cases or simple hand-rolled parsers.
  */
 
 /** @typedef {{ '~standard': { validate: (input: unknown) => any } }} StandardSchema */

package/src/vite.js

@@ -68,7 +68,6 @@ async function resolveWorkspaceFrameworkSrcs(root) {
  *    Node's ESM module cache survives `server.restart()`.
  *
  * `.c` is recognised as an alias for `.civet` — both compile through Civet.
- * CoffeeScript is no longer supported.
  *
  * @returns {import('vite').Plugin}
  */