@nuraly/lumenjs 0.1.3 → 0.2.0

package/dist/shared/utils.d.ts

@@ -12,11 +12,6 @@ export declare function stripOuterLitMarkers(html: string): string;
  *   'app/[id]'  → 'layout-app-id'
  */
 export declare function dirToLayoutTagName(dir: string): string;
-/**
- * Find the custom element tag name from a page module.
- * Pages are auto-registered by the auto-define plugin based on file path.
- */
-export declare function findTagName(mod: Record<string, any>): string | null;
 /**
  * Convert a relative file path within pages/ to a page tag name.
  *   'index.ts'           → 'page-index'
@@ -32,13 +27,23 @@ export declare function isRedirectResponse(value: any): value is {
     status?: number;
 };
 /**
- * Read and parse the body of an HTTP request.
+ * Patch a custom element class's loaderData setter to also spread
+ * individual properties from the loader data object onto the element.
+ * This enables components to declare individual reactive properties
+ * (e.g., `stats: { type: Array }`) instead of using `this.loaderData.stats`.
+ *
+ * Must be called AFTER the element is registered and BEFORE SSR rendering.
  */
-export declare function readBody(req: any): Promise<any>;
+export declare function patchLoaderDataSpread(tagName: string): void;
+export declare function readBody(req: any, maxSize?: number): Promise<any>;
 /**
  * Escape HTML special characters for safe embedding.
  */
 export declare function escapeHtml(text: string): string;
+/**
+ * Check if a page file exports `export const prerender = true`.
+ */
+export declare function fileHasPrerender(filePath: string): boolean;
 /**
  * Check if a page/layout file exports a loader() function.
  */
@@ -47,6 +52,27 @@ export declare function fileHasLoader(filePath: string): boolean;
  * Check if a page/layout file exports a subscribe() function.
  */
 export declare function fileHasSubscribe(filePath: string): boolean;
+/**
+ * Check if a page file exports an `auth` constant (before the class definition).
+ */
+export declare function fileHasAuth(filePath: string): boolean;
+/**
+ * Check if a page file exports a `meta` object or function.
+ * Supports both `export const meta = { ... }` and `export function meta(...)`.
+ */
+export declare function fileHasMeta(filePath: string): boolean;
+/**
+ * Check if a page file exports a `socket` function or constant.
+ */
+export declare function fileHasSocket(filePath: string): boolean;
+/**
+ * Check if a page exports `standalone = true` (renders without any layout).
+ */
+export declare function fileHasStandalone(filePath: string): boolean;
+/**
+ * Return the HTTP methods exported by an API route file (e.g. ['GET', 'POST']).
+ */
+export declare function fileGetApiMethods(filePath: string): string[];
 /**
  * Convert a file path (relative to pages/) to a route path.
  */

package/dist/shared/utils.js

@@ -27,28 +27,6 @@ export function dirToLayoutTagName(dir) {
         .toLowerCase();
     return `layout-${name}`;
 }
-/**
- * Find the custom element tag name from a page module.
- * Pages are auto-registered by the auto-define plugin based on file path.
- */
-export function findTagName(mod) {
-    for (const key of Object.keys(mod)) {
-        const val = mod[key];
-        if (typeof val === 'function' && val.prototype) {
-            if (val.is)
-                return val.is;
-            if (val.elementProperties || val.properties) {
-                const className = val.name || key;
-                const tag = className
-                    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
-                    .toLowerCase();
-                if (tag.includes('-'))
-                    return tag;
-            }
-        }
-    }
-    return null;
-}
 /**
  * Convert a relative file path within pages/ to a page tag name.
  *   'index.ts'           → 'page-index'
@@ -71,13 +49,65 @@ export function filePathToTagName(filePath) {
 export function isRedirectResponse(value) {
     return value && typeof value === 'object' && typeof value.location === 'string' && value.__nk_redirect === true;
 }
+/**
+ * Patch a custom element class's loaderData setter to also spread
+ * individual properties from the loader data object onto the element.
+ * This enables components to declare individual reactive properties
+ * (e.g., `stats: { type: Array }`) instead of using `this.loaderData.stats`.
+ *
+ * Must be called AFTER the element is registered and BEFORE SSR rendering.
+ */
+export function patchLoaderDataSpread(tagName) {
+    const g = globalThis;
+    const ElementClass = g.customElements?.get?.(tagName);
+    if (!ElementClass)
+        return;
+    const proto = ElementClass.prototype;
+    const original = Object.getOwnPropertyDescriptor(proto, 'loaderData');
+    Object.defineProperty(proto, 'loaderData', {
+        set(value) {
+            if (original?.set) {
+                original.set.call(this, value);
+            }
+            else {
+                this.__nk_loaderData = value;
+            }
+            if (value && typeof value === 'object') {
+                const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype', 'loaderData',
+                    'render', 'connectedCallback', 'disconnectedCallback', 'attributeChangedCallback',
+                    'adoptedCallback', 'innerHTML', 'outerHTML', 'textContent']);
+                for (const [key, val] of Object.entries(value)) {
+                    if (!BLOCKED_KEYS.has(key)) {
+                        this[key] = val;
+                    }
+                }
+            }
+        },
+        get() {
+            if (original?.get)
+                return original.get.call(this);
+            return this.__nk_loaderData;
+        },
+        configurable: true
+    });
+}
 /**
  * Read and parse the body of an HTTP request.
  */
-export function readBody(req) {
+const DEFAULT_MAX_BODY = 1024 * 1024; // 1 MB
+export function readBody(req, maxSize = DEFAULT_MAX_BODY) {
     return new Promise((resolve, reject) => {
         let data = '';
-        req.on('data', (chunk) => { data += chunk.toString(); });
+        let size = 0;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > maxSize) {
+                req.destroy();
+                reject(new Error('Request body too large'));
+                return;
+            }
+            data += chunk.toString();
+        });
         req.on('end', () => {
             if (!data)
                 return resolve(undefined);
@@ -95,7 +125,33 @@ export function readBody(req) {
  * Escape HTML special characters for safe embedding.
  */
 export function escapeHtml(text) {
-    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+/**
+ * Check if code has a top-level export of a named function (before the class definition).
+ * In LumenJS, loader/subscribe are always declared before `export class`.
+ */
+function hasTopLevelExport(content, fnName) {
+    const classStart = content.search(/export\s+class\s+\w+/);
+    const fnRegex = new RegExp(`export\\s+(async\\s+)?function\\s+${fnName}\\s*\\(`);
+    const match = fnRegex.exec(content);
+    if (!match)
+        return false;
+    if (classStart >= 0 && match.index > classStart)
+        return false;
+    return true;
+}
+/**
+ * Check if a page file exports `export const prerender = true`.
+ */
+export function fileHasPrerender(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return /export\s+const\s+prerender\s*=\s*true/.test(content);
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * Check if a page/layout file exports a loader() function.
@@ -103,7 +159,7 @@ export function escapeHtml(text) {
 export function fileHasLoader(filePath) {
     try {
         const content = fs.readFileSync(filePath, 'utf-8');
-        return /export\s+(async\s+)?function\s+loader\s*\(/.test(content);
+        return hasTopLevelExport(content, 'loader');
     }
     catch {
         return false;
@@ -115,12 +171,93 @@ export function fileHasLoader(filePath) {
 export function fileHasSubscribe(filePath) {
     try {
         const content = fs.readFileSync(filePath, 'utf-8');
-        return /export\s+(async\s+)?function\s+subscribe\s*\(/.test(content);
+        return hasTopLevelExport(content, 'subscribe');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a page file exports an `auth` constant (before the class definition).
+ */
+export function fileHasAuth(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const classStart = content.search(/export\s+class\s+\w+/);
+        const match = /export\s+const\s+auth\s*=/.exec(content);
+        if (!match)
+            return false;
+        if (classStart >= 0 && match.index > classStart)
+            return false;
+        return true;
     }
     catch {
         return false;
     }
 }
+/**
+ * Check if a page file exports a `meta` object or function.
+ * Supports both `export const meta = { ... }` and `export function meta(...)`.
+ */
+export function fileHasMeta(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const classStart = content.search(/export\s+class\s+\w+/);
+        // Check for `export const meta` or `export function meta`
+        const match = /export\s+(const\s+meta\s*=|(async\s+)?function\s+meta\s*\()/.exec(content);
+        if (!match)
+            return false;
+        if (classStart >= 0 && match.index > classStart)
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a page file exports a `socket` function or constant.
+ */
+export function fileHasSocket(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return /export\s+(function|const)\s+socket[\s(=]/.test(content);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a page exports `standalone = true` (renders without any layout).
+ */
+export function fileHasStandalone(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const classStart = content.search(/export\s+class\s+\w+/);
+        const match = /export\s+const\s+standalone\s*=/.exec(content);
+        if (!match)
+            return false;
+        if (classStart >= 0 && match.index > classStart)
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Return the HTTP methods exported by an API route file (e.g. ['GET', 'POST']).
+ */
+export function fileGetApiMethods(filePath) {
+    const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return HTTP_METHODS.filter(m => new RegExp(`export\\s+(async\\s+)?function\\s+${m}[\\s(]`).test(content));
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * Convert a file path (relative to pages/) to a route path.
  */

package/dist/storage/adapters/local.d.ts

@@ -0,0 +1,44 @@
+import type { StorageAdapter, StoredFile, PutOptions, PresignPutOptions, PresignGetOptions, PresignedUpload } from './types.js';
+interface PendingUpload {
+    key: string;
+    mimeType?: string;
+    maxSize?: number;
+    /** Absolute expiry time in ms (Date.now()) */
+    expiresAt: number;
+}
+export interface LocalStorageOptions {
+    /** Directory to write uploaded files to. Default: './uploads' */
+    uploadDir: string;
+    /** URL path prefix for serving files. Default: '/uploads' */
+    publicPath: string;
+}
+/**
+ * Local-disk storage adapter for development.
+ *
+ * Files are written to `uploadDir` and served at `publicPath`.
+ * Presigned uploads use in-memory tokens consumed by `vite-plugin-storage`.
+ */
+export declare class LocalStorageAdapter implements StorageAdapter {
+    readonly uploadDir: string;
+    readonly publicPath: string;
+    /**
+     * Pending presigned upload tokens.
+     * Keyed by token → consumed by the Vite dev server plugin on upload.
+     */
+    readonly pendingUploads: Map<string, PendingUpload>;
+    constructor(options: LocalStorageOptions);
+    /** Resolve a storage key to an absolute path and ensure it stays within uploadDir. */
+    private safePath;
+    put(data: Buffer, options?: PutOptions): Promise<StoredFile>;
+    delete(key: string): Promise<void>;
+    presignPut(key: string, options?: PresignPutOptions): Promise<PresignedUpload>;
+    presignGet(_key: string, _options?: PresignGetOptions): Promise<string>;
+    publicUrl(key: string): string;
+    /**
+     * Consume a presigned upload token.
+     * Returns the pending upload metadata if the token is valid and unexpired, else undefined.
+     * Calling this removes the token (one-time use).
+     */
+    consumeUpload(token: string): PendingUpload | undefined;
+}
+export {};

package/dist/storage/adapters/local.js

@@ -0,0 +1,85 @@
+import path from 'path';
+import fs from 'fs';
+import crypto from 'crypto';
+/**
+ * Local-disk storage adapter for development.
+ *
+ * Files are written to `uploadDir` and served at `publicPath`.
+ * Presigned uploads use in-memory tokens consumed by `vite-plugin-storage`.
+ */
+export class LocalStorageAdapter {
+    constructor(options) {
+        /**
+         * Pending presigned upload tokens.
+         * Keyed by token → consumed by the Vite dev server plugin on upload.
+         */
+        this.pendingUploads = new Map();
+        this.uploadDir = path.resolve(options.uploadDir);
+        this.publicPath = options.publicPath.replace(/\/$/, '');
+        fs.mkdirSync(this.uploadDir, { recursive: true });
+    }
+    /** Resolve a storage key to an absolute path and ensure it stays within uploadDir. */
+    safePath(key) {
+        const resolved = path.resolve(this.uploadDir, key);
+        if (!resolved.startsWith(this.uploadDir + path.sep) && resolved !== this.uploadDir) {
+            throw new Error('Invalid storage key: path traversal detected');
+        }
+        return resolved;
+    }
+    async put(data, options) {
+        const key = options?.key ?? crypto.randomUUID();
+        const filePath = this.safePath(key);
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, data);
+        return {
+            key,
+            url: this.publicUrl(key),
+            size: data.length,
+            mimeType: options?.mimeType ?? 'application/octet-stream',
+            fileName: options?.fileName ?? key,
+        };
+    }
+    async delete(key) {
+        const filePath = this.safePath(key);
+        if (fs.existsSync(filePath)) {
+            fs.unlinkSync(filePath);
+        }
+    }
+    async presignPut(key, options) {
+        const expiresIn = options?.expiresIn ?? 3600;
+        const expiresAt = new Date(Date.now() + expiresIn * 1000);
+        const token = crypto.randomBytes(32).toString('hex');
+        this.pendingUploads.set(token, {
+            key,
+            mimeType: options?.mimeType,
+            maxSize: options?.maxSize,
+            expiresAt: expiresAt.getTime(),
+        });
+        return {
+            uploadUrl: `/__nk_storage/upload/${token}`,
+            key,
+            expiresAt: expiresAt.toISOString(),
+        };
+    }
+    async presignGet(_key, _options) {
+        // Local dev — files are served publicly at the static path.
+        return this.publicUrl(_key);
+    }
+    publicUrl(key) {
+        return `${this.publicPath}/${key}`;
+    }
+    /**
+     * Consume a presigned upload token.
+     * Returns the pending upload metadata if the token is valid and unexpired, else undefined.
+     * Calling this removes the token (one-time use).
+     */
+    consumeUpload(token) {
+        const pending = this.pendingUploads.get(token);
+        if (!pending)
+            return undefined;
+        this.pendingUploads.delete(token);
+        if (Date.now() > pending.expiresAt)
+            return undefined;
+        return pending;
+    }
+}

package/dist/storage/adapters/s3.d.ts

@@ -0,0 +1,32 @@
+import type { StorageAdapter, StoredFile, PutOptions, PresignPutOptions, PresignGetOptions, PresignedUpload } from './types.js';
+export interface S3StorageOptions {
+    bucket: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** Custom endpoint for S3-compatible APIs: MinIO, Cloudflare R2, etc. */
+    endpoint?: string;
+    /** Public CDN base URL. Defaults to https://{bucket}.s3.{region}.amazonaws.com */
+    publicBaseUrl?: string;
+}
+/**
+ * S3-compatible storage adapter.
+ * Works with AWS S3, Cloudflare R2, MinIO, and any S3-compatible API.
+ *
+ * Requires optional peer dependencies:
+ *   @aws-sdk/client-s3
+ *   @aws-sdk/s3-request-presigner
+ */
+export declare class S3StorageAdapter implements StorageAdapter {
+    private readonly options;
+    private _client;
+    private _getSignedUrl;
+    constructor(options: S3StorageOptions);
+    private getClient;
+    private getSignedUrl;
+    put(data: Buffer, options?: PutOptions): Promise<StoredFile>;
+    delete(key: string): Promise<void>;
+    presignPut(key: string, options?: PresignPutOptions): Promise<PresignedUpload>;
+    presignGet(key: string, options?: PresignGetOptions): Promise<string>;
+    publicUrl(key: string): string;
+}

package/dist/storage/adapters/s3.js

@@ -0,0 +1,119 @@
+import crypto from 'crypto';
+const SDK_INSTALL_HINT = 'Install with: npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner';
+/**
+ * S3-compatible storage adapter.
+ * Works with AWS S3, Cloudflare R2, MinIO, and any S3-compatible API.
+ *
+ * Requires optional peer dependencies:
+ *   @aws-sdk/client-s3
+ *   @aws-sdk/s3-request-presigner
+ */
+export class S3StorageAdapter {
+    constructor(options) {
+        this._client = null;
+        this._getSignedUrl = null;
+        this.options = options;
+    }
+    async getClient() {
+        if (this._client)
+            return this._client;
+        let S3Client, PutObjectCommand, DeleteObjectCommand, GetObjectCommand;
+        try {
+            const mod = await import('@aws-sdk/client-s3');
+            S3Client = mod.S3Client;
+            PutObjectCommand = mod.PutObjectCommand;
+            DeleteObjectCommand = mod.DeleteObjectCommand;
+            GetObjectCommand = mod.GetObjectCommand;
+        }
+        catch {
+            throw new Error(`[LumenJS:Storage] @aws-sdk/client-s3 is required for S3 storage. ${SDK_INSTALL_HINT}`);
+        }
+        this._client = {
+            s3: new S3Client({
+                region: this.options.region,
+                endpoint: this.options.endpoint,
+                credentials: {
+                    accessKeyId: this.options.accessKeyId,
+                    secretAccessKey: this.options.secretAccessKey,
+                },
+                forcePathStyle: !!this.options.endpoint, // required for MinIO
+            }),
+            PutObjectCommand,
+            DeleteObjectCommand,
+            GetObjectCommand,
+        };
+        return this._client;
+    }
+    async getSignedUrl() {
+        if (this._getSignedUrl)
+            return this._getSignedUrl;
+        try {
+            const mod = await import('@aws-sdk/s3-request-presigner');
+            this._getSignedUrl = mod.getSignedUrl;
+            return this._getSignedUrl;
+        }
+        catch {
+            throw new Error(`[LumenJS:Storage] @aws-sdk/s3-request-presigner is required for presigned URLs. ${SDK_INSTALL_HINT}`);
+        }
+    }
+    async put(data, options) {
+        const key = options?.key ?? crypto.randomUUID();
+        const mimeType = options?.mimeType ?? 'application/octet-stream';
+        const acl = options?.acl ?? 'public-read';
+        const { s3, PutObjectCommand } = await this.getClient();
+        const cmd = {
+            Bucket: this.options.bucket,
+            Key: key,
+            Body: data,
+            ContentType: mimeType,
+            ...(options?.fileName
+                ? { ContentDisposition: `inline; filename="${options.fileName.replace(/[\r\n"\\]/g, '_')}"` }
+                : {}),
+        };
+        // R2 and some S3-compatible APIs don't support ACL
+        if (!this.options.endpoint)
+            cmd.ACL = acl;
+        await s3.send(new PutObjectCommand(cmd));
+        return {
+            key,
+            url: this.publicUrl(key),
+            size: data.length,
+            mimeType,
+            fileName: options?.fileName ?? key,
+        };
+    }
+    async delete(key) {
+        const { s3, DeleteObjectCommand } = await this.getClient();
+        await s3.send(new DeleteObjectCommand({ Bucket: this.options.bucket, Key: key }));
+    }
+    async presignPut(key, options) {
+        const expiresIn = options?.expiresIn ?? 3600;
+        const expiresAt = new Date(Date.now() + expiresIn * 1000);
+        const { s3, PutObjectCommand } = await this.getClient();
+        const getSignedUrl = await this.getSignedUrl();
+        const command = new PutObjectCommand({
+            Bucket: this.options.bucket,
+            Key: key,
+            ...(options?.mimeType ? { ContentType: options.mimeType } : {}),
+        });
+        const uploadUrl = await getSignedUrl(s3, command, { expiresIn });
+        return { uploadUrl, key, expiresAt: expiresAt.toISOString() };
+    }
+    async presignGet(key, options) {
+        const expiresIn = options?.expiresIn ?? 3600;
+        const { s3, GetObjectCommand } = await this.getClient();
+        const getSignedUrl = await this.getSignedUrl();
+        const command = new GetObjectCommand({ Bucket: this.options.bucket, Key: key });
+        return getSignedUrl(s3, command, { expiresIn });
+    }
+    publicUrl(key) {
+        if (this.options.publicBaseUrl) {
+            return `${this.options.publicBaseUrl.replace(/\/$/, '')}/${key}`;
+        }
+        if (this.options.endpoint) {
+            // MinIO / R2: {endpoint}/{bucket}/{key}
+            return `${this.options.endpoint.replace(/\/$/, '')}/${this.options.bucket}/${key}`;
+        }
+        return `https://${this.options.bucket}.s3.${this.options.region}.amazonaws.com/${key}`;
+    }
+}

package/dist/storage/adapters/types.d.ts

@@ -0,0 +1,53 @@
+export interface StoredFile {
+    /** Storage key (path within bucket / upload-dir) */
+    key: string;
+    /** Publicly accessible URL (for public-read files) */
+    url: string;
+    size: number;
+    mimeType: string;
+    fileName: string;
+}
+export interface PutOptions {
+    /** Custom storage key. Auto-generated UUID if omitted. */
+    key?: string;
+    mimeType?: string;
+    fileName?: string;
+    /** Access control. Default: 'public-read' */
+    acl?: 'public-read' | 'private';
+}
+export interface PresignPutOptions {
+    /** Expected MIME type (enforced in local adapter; advisory on S3 via Content-Type condition) */
+    mimeType?: string;
+    /** URL expiry in seconds. Default: 3600 */
+    expiresIn?: number;
+    /** Maximum file size in bytes */
+    maxSize?: number;
+}
+export interface PresignGetOptions {
+    /** URL expiry in seconds. Default: 3600 */
+    expiresIn?: number;
+}
+export interface PresignedUpload {
+    /** Presigned URL the client should PUT the encrypted file to */
+    uploadUrl: string;
+    /** Storage key to reference the file after upload */
+    key: string;
+    /** ISO 8601 expiry timestamp */
+    expiresAt: string;
+}
+/** Storage adapter interface — implement for any backend (S3, R2, MinIO, local disk, etc.) */
+export interface StorageAdapter {
+    /** Upload a file buffer server-side. Returns stored file metadata with URL. */
+    put(data: Buffer, options?: PutOptions): Promise<StoredFile>;
+    /** Delete a file by its storage key. */
+    delete(key: string): Promise<void>;
+    /**
+     * Generate a presigned PUT URL for direct client-to-storage upload.
+     * Used for E2E-encrypted chat attachments — the server never sees the plaintext file.
+     */
+    presignPut(key: string, options?: PresignPutOptions): Promise<PresignedUpload>;
+    /** Generate a presigned GET URL for temporarily accessing a private file. */
+    presignGet(key: string, options?: PresignGetOptions): Promise<string>;
+    /** Return the permanent public URL for a public-read file. */
+    publicUrl(key: string): string;
+}

package/dist/storage/adapters/types.js

@@ -0,0 +1 @@
+export {};