@nuraly/lumenjs 0.1.2 → 0.1.4

package/README.md

@@ -1,57 +1,53 @@
+<p align="center">
+  <img src="https://img.shields.io/npm/v/@nuraly/lumenjs?color=7c3aed&label=npm" alt="npm version" />
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="license" />
+  <img src="https://img.shields.io/badge/lit-3.x-324fff" alt="Lit 3" />
+  <img src="https://img.shields.io/badge/node-%3E%3D18-green" alt="node" />
+</p>
+
 # LumenJS
 
-A full-stack web framework for [Lit](https://lit.dev/) web components. File-based routing, server loaders, SSR with hydration, nested layouts, API routes, and a Vite-powered dev server.
+A full-stack web framework for [Lit](https://lit.dev/) web components. File-based routing, server loaders, real-time subscriptions (SSE), SSR with hydration, nested layouts, API routes, i18n, and a visual editor — all powered by Vite.
 
-## Quick Start
+## Getting Started
 
 ```bash
-npx lumenjs dev --project ./my-app
+npx @nuraly/lumenjs create my-app
+cd my-app
+npm install
+npx lumenjs dev
 ```
 
-## Project Structure
-
-```
-my-app/
-├── lumenjs.config.ts       # Project config
-├── package.json
-├── pages/                  # File-based routes
-│   ├── _layout.ts          # Root layout
-│   ├── index.ts            # → /
-│   ├── about.ts            # → /about
-│   └── blog/
-│       ├── _layout.ts      # Nested layout (wraps blog/*)
-│       ├── index.ts         # → /blog
-│       └── [slug].ts       # → /blog/:slug
-├── api/                    # API routes
-│   └── hello.ts            # → /api/hello
-└── public/                 # Static assets
-```
+Open [http://localhost:3000](http://localhost:3000) — you're live.
 
-## Configuration
+### Templates
 
-```typescript
-// lumenjs.config.ts
-export default {
-  title: 'My App',
-  integrations: ['tailwind'],
-};
+```bash
+npx @nuraly/lumenjs create my-app                        # default starter
+npx @nuraly/lumenjs create my-blog --template blog       # blog with file-based posts
+npx @nuraly/lumenjs create my-dash --template dashboard  # real-time dashboard with SSE
 ```
 
-| Option | Type | Description |
-|---|---|---|
-| `title` | `string` | HTML page title |
-| `integrations` | `string[]` | Optional integrations: `'tailwind'`, `'nuralyui'` |
+## Features
+
+- **File-based routing** — `pages/about.ts` → `/about`, `pages/blog/[slug].ts` → `/blog/:slug`
+- **Server loaders** — fetch data server-side, hydrate on the client
+- **Live data (SSE)** — `subscribe()` pushes real-time updates to the browser
+- **SSR + hydration** — pre-rendered HTML with `@lit-labs/ssr`, zero flash
+- **Nested layouts** — `_layout.ts` wraps child routes, persists across navigation
+- **API routes** — `api/users.ts` → REST endpoints with file uploads
+- **i18n** — URL-prefix routing, JSON translations, SSR-safe
+- **Visual editor** — click-to-select, inline text editing, file browser
+- **Tailwind & NuralyUI** — one command to add integrations
 
 ## Pages
 
-Pages are Lit components in the `pages/` directory. The file path determines the URL.
+Pages are Lit components in `pages/`. The file path determines the URL.
 
 ```typescript
 // pages/index.ts
 import { LitElement, html, css } from 'lit';
-import { customElement } from 'lit/decorators.js';
 
-@customElement('page-index')
 export class PageIndex extends LitElement {
   static styles = css`:host { display: block; }`;
 
@@ -61,33 +57,28 @@ export class PageIndex extends LitElement {
 }
 ```
 
-### Routing
-
 | File | URL | Tag |
 |---|---|---|
 | `pages/index.ts` | `/` | `<page-index>` |
 | `pages/about.ts` | `/about` | `<page-about>` |
-| `pages/blog/index.ts` | `/blog` | `<page-blog-index>` |
 | `pages/blog/[slug].ts` | `/blog/:slug` | `<page-blog-slug>` |
 | `pages/[...slug].ts` | `/*` (catch-all) | `<page-slug>` |
 
-Static routes take priority over dynamic ones. Dynamic `[param]` routes take priority over catch-all `[...param]` routes.
-
 ## Loaders
 
-Export a `loader()` function from any page or layout to fetch data on the server.
+Export a `loader()` to fetch data server-side. It runs on SSR and via `/__nk_loader/<path>` during client-side navigation. Automatically stripped from client bundles.
 
 ```typescript
 // pages/blog/[slug].ts
-export async function loader({ params, headers, query, url }) {
+export async function loader({ params }) {
   const post = await db.posts.findOne({ slug: params.slug });
   if (!post) return { __nk_redirect: true, location: '/404', status: 302 };
   return { post };
 }
 
-@customElement('page-blog-slug')
 export class BlogPost extends LitElement {
-  @property({ type: Object }) loaderData: any = {};
+  static properties = { loaderData: { type: Object } };
+  loaderData: any = {};
 
   render() {
     return html`<h1>${this.loaderData.post?.title}</h1>`;
@@ -95,8 +86,6 @@ export class BlogPost extends LitElement {
 }
 ```
 
-Loaders run server-side on initial load (SSR) and are fetched via `/__nk_loader/<path>` during client-side navigation. The `loader()` export is automatically stripped from client bundles.
-
 ### Loader Context
 
 | Property | Type | Description |
@@ -107,62 +96,52 @@ Loaders run server-side on initial load (SSR) and are fetched via `/__nk_loader/
 | `headers` | `Record<string, any>` | Request headers |
 | `locale` | `string` | Current locale (when i18n is configured) |
 
-### Redirects
+## Live Data (subscribe)
+
+Export a `subscribe()` to push real-time data over Server-Sent Events.
 
 ```typescript
-export async function loader({ headers }) {
-  const user = await getUser(headers.authorization);
-  if (!user) return { __nk_redirect: true, location: '/login', status: 302 };
-  return { user };
+// pages/dashboard.ts
+export function subscribe({ push }) {
+  const interval = setInterval(() => {
+    push({ time: new Date().toISOString(), count: ++n });
+  }, 1000);
+  return () => clearInterval(interval);
 }
-```
 
-## Nested Layouts
+export class PageDashboard extends LitElement {
+  static properties = { liveData: { type: Object } };
+  liveData: any = null;
 
-Create `_layout.ts` in any directory to wrap all pages in that directory and its subdirectories.
-
-```typescript
-// pages/_layout.ts
-@customElement('layout-root')
-export class RootLayout extends LitElement {
   render() {
-    return html`
-      <header>My App</header>
-      <main><slot></slot></main>
-      <footer>Footer</footer>
-    `;
+    return html`<p>Server time: ${this.liveData?.time}</p>`;
   }
 }
 ```
 
-Layouts persist across navigation — when navigating between pages that share the same layout, only the page component is swapped.
+Return a cleanup function — it runs when the client disconnects.
 
-Layouts can have their own `loader()` function for shared data like auth or navigation:
+## Layouts
 
-```typescript
-// pages/dashboard/_layout.ts
-export async function loader({ headers }) {
-  const user = await getUser(headers.authorization);
-  if (!user) return { __nk_redirect: true, location: '/login', status: 302 };
-  return { user };
-}
-
-@customElement('layout-dashboard')
-export class DashboardLayout extends LitElement {
-  @property({ type: Object }) loaderData: any = {};
+Create `_layout.ts` in any directory. It wraps all pages below it and persists across navigation.
 
+```typescript
+// pages/_layout.ts
+export class RootLayout extends LitElement {
   render() {
     return html`
-      <nav>Welcome, ${this.loaderData.user?.name}</nav>
-      <slot></slot>
+      <header>My App</header>
+      <main><slot></slot></main>
     `;
   }
 }
 ```
 
+Layouts can have their own `loader()` and `subscribe()` for shared data (auth, notifications, etc.).
+
 ## API Routes
 
-Create files in `api/` and export named functions for each HTTP method.
+Files in `api/` become REST endpoints. Export named functions for each HTTP method.
 
 ```typescript
 // api/users/[id].ts
@@ -176,197 +155,59 @@ export async function POST(req) {
 }
 ```
 
-### Request Object
-
-| Property | Type | Description |
-|---|---|---|
-| `method` | `string` | HTTP method |
-| `url` | `string` | Request pathname |
-| `query` | `Record<string, string>` | Query string parameters |
-| `params` | `Record<string, string>` | Dynamic route parameters |
-| `body` | `any` | Parsed JSON body (non-GET) |
-| `files` | `NkUploadedFile[]` | Uploaded files (multipart) |
-| `headers` | `Record<string, any>` | Request headers |
-
-### Error Responses
-
-```typescript
-export async function GET(req) {
-  const item = await db.find(req.params.id);
-  if (!item) throw { status: 404, message: 'Not found' };
-  return item;
-}
-```
-
-### File Uploads
-
-Multipart form data is parsed automatically:
-
-```typescript
-export async function POST(req) {
-  for (const file of req.files) {
-    console.log(file.fileName, file.size, file.contentType);
-    // file.data is a Buffer
-  }
-  return { uploaded: req.files.length };
-}
-```
-
-## SSR & Hydration
-
-Pages with loaders are automatically server-rendered using `@lit-labs/ssr`:
+Supports JSON bodies, query params, dynamic routes, file uploads (`req.files`), and error handling via `throw { status, message }`.
 
-1. Loader runs on the server
-2. Lit component renders to HTML
-3. Loader data is embedded as JSON in the response
-4. Browser receives pre-rendered HTML (fast first paint)
-5. Client hydrates the existing DOM without re-rendering
-
-Pages without loaders render client-side only (SPA mode). If SSR fails, LumenJS falls back gracefully to client-side rendering.
-
-## Internationalization (i18n)
-
-LumenJS has built-in i18n support with URL-prefix-based locale routing.
-
-### Setup
-
-1. Add i18n config to `lumenjs.config.ts`:
+## i18n
 
 ```typescript
+// lumenjs.config.ts
 export default {
-  title: 'My App',
-  i18n: {
-    locales: ['en', 'fr'],
-    defaultLocale: 'en',
-    prefixDefault: false, // / instead of /en/
-  },
+  i18n: { locales: ['en', 'fr'], defaultLocale: 'en' },
 };
 ```
 
-2. Create translation files in `locales/`:
-
-```
-my-app/
-├── locales/
-│   ├── en.json    # { "home.title": "Welcome", "nav.docs": "Docs" }
-│   └── fr.json    # { "home.title": "Bienvenue", "nav.docs": "Documentation" }
-├── pages/
-└── lumenjs.config.ts
-```
-
-### Usage
-
 ```typescript
-import { t, getLocale, setLocale } from '@lumenjs/i18n';
+import { t, setLocale } from '@lumenjs/i18n';
 
-@customElement('page-index')
-export class PageIndex extends LitElement {
-  render() {
-    return html`<h1>${t('home.title')}</h1>`;
-  }
-}
+html`<h1>${t('home.title')}</h1>
+     <button @click=${() => setLocale('fr')}>FR</button>`;
 ```
 
-### API
-
-| Function | Description |
-|---|---|
-| `t(key)` | Returns the translated string for the key, or the key itself if not found |
-| `getLocale()` | Returns the current locale string |
-| `setLocale(locale)` | Switches locale — sets cookie, navigates to the localized URL |
-
-### Locale Resolution
-
-Locale is resolved in this order:
-
-1. URL prefix: `/fr/about` → locale `fr`, pathname `/about`
-2. Cookie `nk-locale` (set on explicit locale switch)
-3. `Accept-Language` header (SSR)
-4. Config `defaultLocale`
-
-### URL Routing
-
-With `prefixDefault: false`, the default locale uses clean URLs:
-
-| URL | Locale | Page |
-|---|---|---|
-| `/about` | `en` (default) | `pages/about.ts` |
-| `/fr/about` | `fr` | `pages/about.ts` |
-
-Routes are locale-agnostic — you don't need separate pages per locale. The router strips the locale prefix before matching and prepends it during navigation.
-
-### SSR
-
-Translations are server-rendered. The `<html lang="...">` attribute is set dynamically, and translations are inlined in the response for hydration without flash of untranslated content.
+Translations live in `locales/en.json`, `locales/fr.json`. URL routing: `/about` (default), `/fr/about` (French). Server-rendered, no flash.
 
 ## Integrations
 
-### Tailwind CSS
-
 ```bash
-npx lumenjs add tailwind
-```
-
-This installs `tailwindcss` and `@tailwindcss/vite`, creates `styles/tailwind.css`, and updates your config. For pages using Tailwind classes in light DOM:
-
-```typescript
-createRenderRoot() { return this; }
+npx lumenjs add tailwind    # Tailwind CSS via @tailwindcss/vite
 ```
 
-### NuralyUI
-
-Add `'nuralyui'` to integrations to enable auto-import of `<nr-*>` components:
-
 ```typescript
-// lumenjs.config.ts
-export default {
-  title: 'My App',
-  integrations: ['nuralyui'],
-};
+// lumenjs.config.ts — NuralyUI auto-import
+export default { integrations: ['nuralyui'] };
 ```
 
-NuralyUI components are detected in `html\`\`` templates and imported automatically, including implicit dependencies (e.g., `nr-button` auto-imports `nr-icon`).
-
 ## CLI
 
 ```
-lumenjs dev    [--project <dir>] [--port <port>] [--base <path>] [--editor-mode]
+lumenjs create <name> [--template <default|blog|dashboard>]
+lumenjs dev    [--project <dir>] [--port <port>] [--editor-mode]
 lumenjs build  [--project <dir>] [--out <dir>]
 lumenjs serve  [--project <dir>] [--port <port>]
 lumenjs add    <integration>
 ```
 
-| Command | Description |
-|---|---|
-| `dev` | Start Vite dev server with HMR, SSR, and API routes |
-| `build` | Bundle client assets and server modules for production |
-| `serve` | Serve the production build with SSR and gzip compression |
-| `add` | Add an integration (e.g., `tailwind`) |
-
-### Default Ports
-
-| Mode | Default |
-|---|---|
-| `dev` | 3000 |
-| `serve` | 3000 |
-
-## Production Build
+## Production
 
 ```bash
 npx lumenjs build --project ./my-app
 npx lumenjs serve --project ./my-app --port 8080
 ```
 
-The build outputs to `.lumenjs/`:
+Outputs to `.lumenjs/` — pre-built client assets, server modules, route manifest. The production server handles SSR, loaders, API routes, and gzip compression.
 
-```
-.lumenjs/
-├── client/           # Static assets (HTML, JS, CSS)
-├── server/           # Server modules (loaders, API routes, SSR runtime)
-└── manifest.json     # Route manifest
-```
+## Contributing
 
-The production server includes gzip compression and serves pre-built assets while executing loaders and API routes on demand.
+Contributions are welcome! Please open an issue or submit a pull request.
 
 ## License
 

package/dist/auth/config.d.ts

@@ -0,0 +1,23 @@
+import type { ResolvedAuthConfig, AuthProvider } from './types.js';
+/** Get a provider by name */
+export declare function getProvider(config: ResolvedAuthConfig, name: string): AuthProvider | undefined;
+/** Get the first OIDC provider */
+export declare function getOidcProvider(config: ResolvedAuthConfig): (AuthProvider & {
+    type: "oidc";
+}) | undefined;
+/** Get the native provider */
+export declare function getNativeProvider(config: ResolvedAuthConfig): (AuthProvider & {
+    type: "native";
+}) | undefined;
+/** Check if config has a native auth provider */
+export declare function hasNativeAuth(config: ResolvedAuthConfig): boolean;
+/** Check if config has any OIDC provider */
+export declare function hasOidcAuth(config: ResolvedAuthConfig): boolean;
+/**
+ * Load auth config in dev mode (via Vite's ssrLoadModule).
+ */
+export declare function loadAuthConfig(projectDir: string, ssrLoadModule?: (id: string) => Promise<any>): Promise<ResolvedAuthConfig | null>;
+/**
+ * Load auth config in production from bundled server output.
+ */
+export declare function loadAuthConfigProd(serverDir: string, configModule: string): Promise<ResolvedAuthConfig>;

package/dist/auth/config.js

@@ -0,0 +1,115 @@
+import path from 'path';
+const ROUTE_DEFAULTS = {
+    login: '/__nk_auth/login',
+    loginPage: '/auth/login',
+    callback: '/__nk_auth/callback',
+    logout: '/__nk_auth/logout',
+    signup: '/__nk_auth/signup',
+    postLogin: '/',
+    postLogout: '/',
+};
+const GUARD_DEFAULTS = {
+    defaultAuth: false,
+};
+const PERMISSIONS_DEFAULTS = {
+    enabled: false,
+    defaultOwnerGrants: ['read', 'write', 'delete', 'share'],
+};
+const TOKEN_DEFAULTS = {
+    enabled: true,
+    accessTokenTTL: 900,
+    refreshTokenTTL: 604800,
+};
+function validate(config) {
+    if (!config?.session?.secret)
+        throw new Error('[LumenJS Auth] session.secret is required');
+    // Normalize providers: support both legacy single-provider and multi-provider
+    let providers;
+    if (config.providers && Array.isArray(config.providers)) {
+        providers = config.providers;
+    }
+    else if (config.provider?.issuer) {
+        // Legacy single OIDC provider format
+        providers = [{
+                type: 'oidc',
+                name: 'default',
+                issuer: config.provider.issuer,
+                clientId: config.provider.clientId,
+                clientSecret: config.provider.clientSecret,
+                scopes: config.provider.scopes || ['openid', 'profile', 'email'],
+            }];
+    }
+    else {
+        throw new Error('[LumenJS Auth] Either providers[] or provider.issuer is required');
+    }
+    // Validate each provider
+    for (const p of providers) {
+        if (p.type === 'oidc') {
+            if (!p.issuer)
+                throw new Error(`[LumenJS Auth] Provider "${p.name}": issuer is required`);
+            if (!p.clientId)
+                throw new Error(`[LumenJS Auth] Provider "${p.name}": clientId is required`);
+        }
+        if (!p.name)
+            throw new Error('[LumenJS Auth] Each provider must have a name');
+    }
+    return {
+        providers,
+        session: {
+            secret: config.session.secret,
+            cookieName: config.session.cookieName || 'nk-session',
+            maxAge: config.session.maxAge || 60 * 60 * 24 * 7,
+            secure: config.session.secure ?? (process.env.NODE_ENV === 'production'),
+        },
+        routes: { ...ROUTE_DEFAULTS, ...config.routes },
+        guards: { ...GUARD_DEFAULTS, ...config.guards },
+        permissions: { ...PERMISSIONS_DEFAULTS, ...config.permissions },
+        token: { ...TOKEN_DEFAULTS, ...config.token },
+        ...(config.onEvent ? { onEvent: config.onEvent } : {}),
+    };
+}
+/** Get a provider by name */
+export function getProvider(config, name) {
+    return config.providers.find(p => p.name === name);
+}
+/** Get the first OIDC provider */
+export function getOidcProvider(config) {
+    return config.providers.find(p => p.type === 'oidc');
+}
+/** Get the native provider */
+export function getNativeProvider(config) {
+    return config.providers.find(p => p.type === 'native');
+}
+/** Check if config has a native auth provider */
+export function hasNativeAuth(config) {
+    return config.providers.some(p => p.type === 'native');
+}
+/** Check if config has any OIDC provider */
+export function hasOidcAuth(config) {
+    return config.providers.some(p => p.type === 'oidc');
+}
+/**
+ * Load auth config in dev mode (via Vite's ssrLoadModule).
+ */
+export async function loadAuthConfig(projectDir, ssrLoadModule) {
+    try {
+        if (ssrLoadModule) {
+            const mod = await ssrLoadModule(path.join(projectDir, 'lumenjs.auth.ts'));
+            return validate(mod.default || mod);
+        }
+        const mod = await import(path.join(projectDir, 'lumenjs.auth.ts'));
+        return validate(mod.default || mod);
+    }
+    catch (err) {
+        if (err.code === 'ERR_MODULE_NOT_FOUND' || err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+/**
+ * Load auth config in production from bundled server output.
+ */
+export async function loadAuthConfigProd(serverDir, configModule) {
+    const mod = await import(path.join(serverDir, configModule));
+    return validate(mod.default || mod);
+}

package/dist/auth/guard.d.ts

@@ -0,0 +1,12 @@
+import type { NkAuth } from './types.js';
+export type GuardResult = {
+    allowed: true;
+} | {
+    redirect: string;
+} | {
+    forbidden: true;
+};
+/**
+ * Enforce auth guard — pure function, caller handles the HTTP response.
+ */
+export declare function enforceGuard(authExport: any, nkAuth: NkAuth | null | undefined, loginUrl: string, pathname: string): GuardResult;

package/dist/auth/guard.js

@@ -0,0 +1,28 @@
+/**
+ * Enforce auth guard — pure function, caller handles the HTTP response.
+ */
+export function enforceGuard(authExport, nkAuth, loginUrl, pathname) {
+    if (!authExport)
+        return { allowed: true };
+    const user = nkAuth?.user;
+    // auth = true → require any authenticated user
+    if (authExport === true) {
+        if (!user) {
+            return { redirect: `${loginUrl}?returnTo=${encodeURIComponent(pathname)}` };
+        }
+        return { allowed: true };
+    }
+    // auth = { roles: [...] } → require specific roles
+    if (authExport.roles && Array.isArray(authExport.roles)) {
+        if (!user) {
+            return { redirect: `${loginUrl}?returnTo=${encodeURIComponent(pathname)}` };
+        }
+        const userRoles = user.roles || [];
+        const hasRole = authExport.roles.some((r) => userRoles.includes(r));
+        if (!hasRole) {
+            return { forbidden: true };
+        }
+        return { allowed: true };
+    }
+    return { allowed: true };
+}

package/dist/auth/index.d.ts

@@ -0,0 +1,3 @@
+export { googleProvider } from './providers/google.js';
+export type { GoogleProviderOptions } from './providers/google.js';
+export type { AuthConfig, AuthUser, AuthProvider, AuthEvent, OIDCProvider, NativeProvider, ResolvedAuthConfig, SessionData, NkAuth, TokenResponse, } from './types.js';

package/dist/auth/index.js

@@ -0,0 +1 @@
+export { googleProvider } from './providers/google.js';

package/dist/auth/middleware.d.ts

@@ -0,0 +1,23 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { ResolvedAuthConfig, NkAuth } from './types.js';
+type NextFn = (err?: any) => void;
+/** Type augmentation — makes `req.nkAuth` available without casting */
+declare module 'http' {
+    interface IncomingMessage {
+        nkAuth?: NkAuth | null;
+    }
+}
+export type ConnectMiddleware = (req: IncomingMessage, res: ServerResponse, next: NextFn) => Promise<void>;
+/**
+ * Create Connect middleware that parses the session cookie and attaches req.nkAuth.
+ * Works with both OIDC and native auth sessions — the cookie format is identical.
+ *
+ * Behavior:
+ * 1. Skip non-page requests (/@, /node_modules, static files with `.`)
+ * 2. Check Bearer token (mobile/API clients)
+ * 3. Parse + decrypt session cookie → attach req.nkAuth
+ * 4. Refresh OIDC tokens if expiring within 5 minutes
+ * 5. Always call next() — never blocks the middleware chain
+ */
+export declare function createAuthMiddleware(config: ResolvedAuthConfig, db?: any): ConnectMiddleware;
+export {};