nukejs 0.0.1 → 0.0.2

package/dist/http-server.d.ts

@@ -0,0 +1,99 @@
+/**
+ * http-server.ts — API Route Dispatcher
+ *
+ * Handles discovery and dispatch of API routes inside `serverDir`.
+ *
+ * Directory conventions (mirrors Next.js):
+ *   server/
+ *     users/           → prefix /users  (directory)
+ *       index.ts       →   GET /users   (method exports: GET, POST, …)
+ *       [id].ts        →   GET /users/:id
+ *     auth.ts          → prefix /auth   (top-level file)
+ *     index.ts         → prefix /       (root handler)
+ *
+ * Route handler exports:
+ *   export function GET(req, res) { … }
+ *   export function POST(req, res) { … }
+ *   export default function(req, res) { … }  // matches any method
+ *
+ * Request augmentation:
+ *   req.body    — parsed JSON or raw string (10 MB limit)
+ *   req.params  — dynamic route segments (e.g. { id: '42' })
+ *   req.query   — URL search params
+ *
+ * Response augmentation:
+ *   res.json(data, status?)  — JSON response shorthand
+ *   res.status(code)         — sets statusCode, returns res for chaining
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+/** Describes a single API prefix discovered in serverDir. */
+export interface ApiPrefixInfo {
+    /** URL prefix this entry handles (e.g. '/users', ''). */
+    prefix: string;
+    /** Directory to scan for route files. */
+    directory: string;
+    /** Set when the prefix comes from a top-level file (not a directory). */
+    filePath?: string;
+}
+/** Node's IncomingMessage with parsed body, params, and query. */
+export interface ApiRequest extends IncomingMessage {
+    params?: Record<string, string | string[]>;
+    query?: Record<string, string>;
+    body?: any;
+}
+/** Node's ServerResponse with json() and status() convenience methods. */
+export interface ApiResponse extends ServerResponse {
+    json: (data: any, status?: number) => void;
+    status: (code: number) => ApiResponse;
+}
+/**
+ * Scans `serverDir` and returns one ApiPrefixInfo per directory, top-level
+ * file, and root index.ts.  Directories are returned before same-stem files
+ * so `/a/b` routes resolve to the directory tree before any flat file.
+ *
+ * Called at startup and again whenever the server directory changes (in dev).
+ */
+export declare function discoverApiPrefixes(serverDir: string): ApiPrefixInfo[];
+/**
+ * Buffers the request body and returns:
+ *   - Parsed JSON object if Content-Type is application/json.
+ *   - Raw string otherwise.
+ *
+ * Rejects with an error if the body exceeds MAX_BODY_BYTES to prevent
+ * memory exhaustion attacks.  Deletes __proto__ and constructor from parsed
+ * JSON objects to guard against prototype pollution.
+ */
+export declare function parseBody(req: IncomingMessage): Promise<any>;
+/** Extracts URL search params into a plain string map. */
+export declare function parseQuery(url: string, port: number): Record<string, string>;
+/**
+ * Adds `json()` and `status()` convenience methods to a raw ServerResponse,
+ * mirroring the Express API surface that most API handlers expect.
+ */
+export declare function enhanceResponse(res: ServerResponse): ApiResponse;
+/**
+ * Finds the first ApiPrefixInfo whose prefix is a prefix of `url`.
+ *
+ * The empty-string prefix ('') acts as a catch-all and only matches when no
+ * other prefix claims the URL.
+ *
+ * Returns `null` when no prefix matches (request should fall through to SSR).
+ */
+export declare function matchApiPrefix(url: string, apiPrefixes: ApiPrefixInfo[]): {
+    prefix: ApiPrefixInfo;
+    apiPath: string;
+} | null;
+interface ApiHandlerOptions {
+    apiPrefixes: ApiPrefixInfo[];
+    port: number;
+}
+/**
+ * Creates the main API request dispatcher.  The returned function:
+ *
+ *   1. Finds the matching prefix for the URL.
+ *   2. Resolves the exact handler file (direct file path, index, or dynamic route).
+ *   3. Dynamically imports the module (always fresh in dev thanks to file: URLs).
+ *   4. Calls the method-specific export (GET, POST, …) or `default`.
+ */
+export declare function createApiHandler({ apiPrefixes, port }: ApiHandlerOptions): (url: string, req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export {};

package/dist/http-server.js

@@ -0,0 +1,166 @@
+import path from "path";
+import fs from "fs";
+import { pathToFileURL } from "url";
+import { log } from "./logger.js";
+import { matchRoute } from "./router.js";
+function discoverApiPrefixes(serverDir) {
+  if (!fs.existsSync(serverDir)) {
+    log.warn("Server directory not found:", serverDir);
+    return [];
+  }
+  const entries = fs.readdirSync(serverDir, { withFileTypes: true });
+  const prefixes = [];
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      prefixes.push({ prefix: `/${e.name}`, directory: path.join(serverDir, e.name) });
+    }
+  }
+  for (const e of entries) {
+    if (e.isFile() && (e.name.endsWith(".ts") || e.name.endsWith(".tsx")) && e.name !== "index.ts" && e.name !== "index.tsx") {
+      const stem = e.name.replace(/\.tsx?$/, "");
+      prefixes.push({
+        prefix: `/${stem}`,
+        directory: serverDir,
+        filePath: path.join(serverDir, e.name)
+      });
+    }
+  }
+  if (fs.existsSync(path.join(serverDir, "index.ts"))) {
+    prefixes.push({ prefix: "", directory: serverDir });
+  }
+  return prefixes;
+}
+const MAX_BODY_BYTES = 10 * 1024 * 1024;
+async function parseBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = "";
+    let bytes = 0;
+    req.on("data", (chunk) => {
+      bytes += chunk.length;
+      if (bytes > MAX_BODY_BYTES) {
+        req.destroy();
+        return reject(new Error("Request body too large"));
+      }
+      body += chunk.toString();
+    });
+    req.on("end", () => {
+      try {
+        if (body && req.headers["content-type"]?.includes("application/json")) {
+          const parsed = JSON.parse(body);
+          if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            delete parsed.__proto__;
+            delete parsed.constructor;
+          }
+          resolve(parsed);
+        } else {
+          resolve(body);
+        }
+      } catch (err) {
+        reject(err);
+      }
+    });
+    req.on("error", reject);
+  });
+}
+function parseQuery(url, port) {
+  const query = {};
+  new URL(url, `http://localhost:${port}`).searchParams.forEach((v, k) => {
+    query[k] = v;
+  });
+  return query;
+}
+function enhanceResponse(res) {
+  const apiRes = res;
+  apiRes.json = function(data, statusCode = 200) {
+    this.statusCode = statusCode;
+    this.setHeader("Content-Type", "application/json");
+    this.end(JSON.stringify(data));
+  };
+  apiRes.status = function(code) {
+    this.statusCode = code;
+    return this;
+  };
+  return apiRes;
+}
+function respondOptions(res) {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, PATCH, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+  res.statusCode = 204;
+  res.end();
+}
+function matchApiPrefix(url, apiPrefixes) {
+  for (const prefix of apiPrefixes) {
+    if (prefix.prefix === "") {
+      const claimedByOther = apiPrefixes.some(
+        (p) => p.prefix !== "" && url.startsWith(p.prefix)
+      );
+      if (!claimedByOther) return { prefix, apiPath: url || "/" };
+    } else if (url.startsWith(prefix.prefix)) {
+      return { prefix, apiPath: url.slice(prefix.prefix.length) || "/" };
+    }
+  }
+  return null;
+}
+function createApiHandler({ apiPrefixes, port }) {
+  return async function handleApiRoute(url, req, res) {
+    const apiRes = enhanceResponse(res);
+    const apiMatch = matchApiPrefix(url, apiPrefixes);
+    if (!apiMatch) {
+      apiRes.json({ error: "API endpoint not found" }, 404);
+      return;
+    }
+    const { prefix, apiPath } = apiMatch;
+    let filePath = null;
+    let params = {};
+    if (prefix.filePath) {
+      filePath = prefix.filePath;
+    }
+    if (!filePath && prefix.prefix === "" && apiPath === "/") {
+      const indexPath = path.join(prefix.directory, "index.ts");
+      if (fs.existsSync(indexPath)) filePath = indexPath;
+    }
+    if (!filePath) {
+      const routeMatch = matchRoute(apiPath, prefix.directory, ".ts") ?? matchRoute(apiPath, prefix.directory, ".tsx");
+      if (routeMatch) {
+        filePath = routeMatch.filePath;
+        params = routeMatch.params;
+      }
+    }
+    if (!filePath) {
+      apiRes.json({ error: "API endpoint not found" }, 404);
+      return;
+    }
+    try {
+      const method = (req.method || "GET").toUpperCase();
+      log.verbose(`API ${method} ${url} -> ${path.relative(process.cwd(), filePath)}`);
+      if (method === "OPTIONS") {
+        respondOptions(apiRes);
+        return;
+      }
+      const apiReq = req;
+      apiReq.body = await parseBody(req);
+      apiReq.params = params;
+      apiReq.query = parseQuery(url, port);
+      const apiModule = await import(pathToFileURL(filePath).href);
+      const handler = apiModule[method] ?? apiModule.default;
+      if (!handler) {
+        apiRes.json({ error: `Method ${method} not allowed` }, 405);
+        return;
+      }
+      await handler(apiReq, apiRes);
+    } catch (error) {
+      log.error("API Error:", error);
+      apiRes.json({ error: "Internal server error" }, 500);
+    }
+  };
+}
+export {
+  createApiHandler,
+  discoverApiPrefixes,
+  enhanceResponse,
+  matchApiPrefix,
+  parseBody,
+  parseQuery
+};
+//# sourceMappingURL=http-server.js.map

package/dist/http-server.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/http-server.ts"],
+  "sourcesContent": ["/**\r\n * http-server.ts \u2014 API Route Dispatcher\r\n *\r\n * Handles discovery and dispatch of API routes inside `serverDir`.\r\n *\r\n * Directory conventions (mirrors Next.js):\r\n *   server/\r\n *     users/           \u2192 prefix /users  (directory)\r\n *       index.ts       \u2192   GET /users   (method exports: GET, POST, \u2026)\r\n *       [id].ts        \u2192   GET /users/:id\r\n *     auth.ts          \u2192 prefix /auth   (top-level file)\r\n *     index.ts         \u2192 prefix /       (root handler)\r\n *\r\n * Route handler exports:\r\n *   export function GET(req, res) { \u2026 }\r\n *   export function POST(req, res) { \u2026 }\r\n *   export default function(req, res) { \u2026 }  // matches any method\r\n *\r\n * Request augmentation:\r\n *   req.body    \u2014 parsed JSON or raw string (10 MB limit)\r\n *   req.params  \u2014 dynamic route segments (e.g. { id: '42' })\r\n *   req.query   \u2014 URL search params\r\n *\r\n * Response augmentation:\r\n *   res.json(data, status?)  \u2014 JSON response shorthand\r\n *   res.status(code)         \u2014 sets statusCode, returns res for chaining\r\n */\r\n\r\nimport path from 'path';\r\nimport fs from 'fs';\r\nimport { pathToFileURL } from 'url';\r\nimport type { IncomingMessage, ServerResponse } from 'http';\r\nimport { log } from './logger';\r\nimport { matchRoute } from './router';\r\n\r\n// \u2500\u2500\u2500 Types \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/** Describes a single API prefix discovered in serverDir. */\r\nexport interface ApiPrefixInfo {\r\n  /** URL prefix this entry handles (e.g. '/users', ''). */\r\n  prefix:     string;\r\n  /** Directory to scan for route files. */\r\n  directory:  string;\r\n  /** Set when the prefix comes from a top-level file (not a directory). */\r\n  filePath?:  string;\r\n}\r\n\r\n/** Node's IncomingMessage with parsed body, params, and query. */\r\nexport interface ApiRequest extends IncomingMessage {\r\n  params?: Record<string, string | string[]>;\r\n  query?:  Record<string, string>;\r\n  body?:   any;\r\n}\r\n\r\n/** Node's ServerResponse with json() and status() convenience methods. */\r\nexport interface ApiResponse extends ServerResponse {\r\n  json:   (data: any, status?: number) => void;\r\n  status: (code: number) => ApiResponse;\r\n}\r\n\r\ntype HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS';\r\ntype ApiHandler = (req: ApiRequest, res: ApiResponse) => void | Promise<void>;\r\n\r\ninterface ApiModule {\r\n  default?: ApiHandler;\r\n  GET?:     ApiHandler;\r\n  POST?:    ApiHandler;\r\n  PUT?:     ApiHandler;\r\n  DELETE?:  ApiHandler;\r\n  PATCH?:   ApiHandler;\r\n  OPTIONS?: ApiHandler;\r\n}\r\n\r\n// \u2500\u2500\u2500 Route discovery \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/**\r\n * Scans `serverDir` and returns one ApiPrefixInfo per directory, top-level\r\n * file, and root index.ts.  Directories are returned before same-stem files\r\n * so `/a/b` routes resolve to the directory tree before any flat file.\r\n *\r\n * Called at startup and again whenever the server directory changes (in dev).\r\n */\r\nexport function discoverApiPrefixes(serverDir: string): ApiPrefixInfo[] {\r\n  if (!fs.existsSync(serverDir)) {\r\n    log.warn('Server directory not found:', serverDir);\r\n    return [];\r\n  }\r\n\r\n  const entries  = fs.readdirSync(serverDir, { withFileTypes: true });\r\n  const prefixes: ApiPrefixInfo[] = [];\r\n\r\n  // Directories first (higher specificity than same-stem files).\r\n  for (const e of entries) {\r\n    if (e.isDirectory()) {\r\n      prefixes.push({ prefix: `/${e.name}`, directory: path.join(serverDir, e.name) });\r\n    }\r\n  }\r\n\r\n  // Top-level .ts/.tsx files (excluding index which is handled separately below).\r\n  for (const e of entries) {\r\n    if (\r\n      e.isFile() &&\r\n      (e.name.endsWith('.ts') || e.name.endsWith('.tsx')) &&\r\n      e.name !== 'index.ts' &&\r\n      e.name !== 'index.tsx'\r\n    ) {\r\n      const stem = e.name.replace(/\\.tsx?$/, '');\r\n      prefixes.push({\r\n        prefix:    `/${stem}`,\r\n        directory: serverDir,\r\n        filePath:  path.join(serverDir, e.name),\r\n      });\r\n    }\r\n  }\r\n\r\n  // index.ts/tsx at the root of serverDir handles unmatched paths (prefix '').\r\n  if (fs.existsSync(path.join(serverDir, 'index.ts'))) {\r\n    prefixes.push({ prefix: '', directory: serverDir });\r\n  }\r\n\r\n  return prefixes;\r\n}\r\n\r\n// \u2500\u2500\u2500 Body parsing \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\nconst MAX_BODY_BYTES = 10 * 1024 * 1024; // 10 MB\r\n\r\n/**\r\n * Buffers the request body and returns:\r\n *   - Parsed JSON object if Content-Type is application/json.\r\n *   - Raw string otherwise.\r\n *\r\n * Rejects with an error if the body exceeds MAX_BODY_BYTES to prevent\r\n * memory exhaustion attacks.  Deletes __proto__ and constructor from parsed\r\n * JSON objects to guard against prototype pollution.\r\n */\r\nexport async function parseBody(req: IncomingMessage): Promise<any> {\r\n  return new Promise((resolve, reject) => {\r\n    let body  = '';\r\n    let bytes = 0;\r\n\r\n    req.on('data', chunk => {\r\n      bytes += chunk.length;\r\n      if (bytes > MAX_BODY_BYTES) {\r\n        req.destroy();\r\n        return reject(new Error('Request body too large'));\r\n      }\r\n      body += chunk.toString();\r\n    });\r\n\r\n    req.on('end', () => {\r\n      try {\r\n        if (body && req.headers['content-type']?.includes('application/json')) {\r\n          const parsed = JSON.parse(body);\r\n          // Guard against prototype pollution via __proto__ / constructor.\r\n          if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {\r\n            delete parsed.__proto__;\r\n            delete parsed.constructor;\r\n          }\r\n          resolve(parsed);\r\n        } else {\r\n          resolve(body);\r\n        }\r\n      } catch (err) {\r\n        reject(err);\r\n      }\r\n    });\r\n\r\n    req.on('error', reject);\r\n  });\r\n}\r\n\r\n// \u2500\u2500\u2500 Query parsing \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/** Extracts URL search params into a plain string map. */\r\nexport function parseQuery(url: string, port: number): Record<string, string> {\r\n  const query: Record<string, string> = {};\r\n  new URL(url, `http://localhost:${port}`)\r\n    .searchParams\r\n    .forEach((v, k) => { query[k] = v; });\r\n  return query;\r\n}\r\n\r\n// \u2500\u2500\u2500 Response enhancement \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/**\r\n * Adds `json()` and `status()` convenience methods to a raw ServerResponse,\r\n * mirroring the Express API surface that most API handlers expect.\r\n */\r\nexport function enhanceResponse(res: ServerResponse): ApiResponse {\r\n  const apiRes    = res as ApiResponse;\r\n  apiRes.json   = function (data, statusCode = 200) {\r\n    this.statusCode = statusCode;\r\n    this.setHeader('Content-Type', 'application/json');\r\n    this.end(JSON.stringify(data));\r\n  };\r\n  apiRes.status = function (code) {\r\n    this.statusCode = code;\r\n    return this;\r\n  };\r\n  return apiRes;\r\n}\r\n\r\n/** Responds to an OPTIONS preflight with permissive CORS headers. */\r\nfunction respondOptions(res: ApiResponse): void {\r\n  res.setHeader('Access-Control-Allow-Origin', '*');\r\n  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS');\r\n  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');\r\n  res.statusCode = 204;\r\n  res.end();\r\n}\r\n\r\n// \u2500\u2500\u2500 Prefix matching \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/**\r\n * Finds the first ApiPrefixInfo whose prefix is a prefix of `url`.\r\n *\r\n * The empty-string prefix ('') acts as a catch-all and only matches when no\r\n * other prefix claims the URL.\r\n *\r\n * Returns `null` when no prefix matches (request should fall through to SSR).\r\n */\r\nexport function matchApiPrefix(\r\n  url: string,\r\n  apiPrefixes: ApiPrefixInfo[],\r\n): { prefix: ApiPrefixInfo; apiPath: string } | null {\r\n  for (const prefix of apiPrefixes) {\r\n    if (prefix.prefix === '') {\r\n      // Empty prefix \u2014 only match if no other prefix has claimed this URL.\r\n      const claimedByOther = apiPrefixes.some(\r\n        p => p.prefix !== '' && url.startsWith(p.prefix),\r\n      );\r\n      if (!claimedByOther) return { prefix, apiPath: url || '/' };\r\n    } else if (url.startsWith(prefix.prefix)) {\r\n      return { prefix, apiPath: url.slice(prefix.prefix.length) || '/' };\r\n    }\r\n  }\r\n  return null;\r\n}\r\n\r\n// \u2500\u2500\u2500 Request handler factory \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\ninterface ApiHandlerOptions {\r\n  apiPrefixes: ApiPrefixInfo[];\r\n  port:        number;\r\n}\r\n\r\n/**\r\n * Creates the main API request dispatcher.  The returned function:\r\n *\r\n *   1. Finds the matching prefix for the URL.\r\n *   2. Resolves the exact handler file (direct file path, index, or dynamic route).\r\n *   3. Dynamically imports the module (always fresh in dev thanks to file: URLs).\r\n *   4. Calls the method-specific export (GET, POST, \u2026) or `default`.\r\n */\r\nexport function createApiHandler({ apiPrefixes, port }: ApiHandlerOptions) {\r\n  return async function handleApiRoute(\r\n    url: string,\r\n    req: IncomingMessage,\r\n    res: ServerResponse,\r\n  ): Promise<void> {\r\n    const apiRes    = enhanceResponse(res);\r\n    const apiMatch  = matchApiPrefix(url, apiPrefixes);\r\n\r\n    if (!apiMatch) {\r\n      apiRes.json({ error: 'API endpoint not found' }, 404);\r\n      return;\r\n    }\r\n\r\n    const { prefix, apiPath } = apiMatch;\r\n    let filePath: string | null = null;\r\n    let params:   Record<string, string | string[]> = {};\r\n\r\n    // 1. Direct file match (top-level file prefix, e.g. server/auth.ts \u2192 /auth).\r\n    if (prefix.filePath) {\r\n      filePath = prefix.filePath;\r\n    }\r\n\r\n    // 2. Root index.ts (prefix === '' and path === '/').\r\n    if (!filePath && prefix.prefix === '' && apiPath === '/') {\r\n      const indexPath = path.join(prefix.directory, 'index.ts');\r\n      if (fs.existsSync(indexPath)) filePath = indexPath;\r\n    }\r\n\r\n    // 3. Dynamic route matching inside the prefix directory.\r\n    if (!filePath) {\r\n      const routeMatch =\r\n        matchRoute(apiPath, prefix.directory, '.ts') ??\r\n        matchRoute(apiPath, prefix.directory, '.tsx');\r\n      if (routeMatch) { filePath = routeMatch.filePath; params = routeMatch.params; }\r\n    }\r\n\r\n    if (!filePath) {\r\n      apiRes.json({ error: 'API endpoint not found' }, 404);\r\n      return;\r\n    }\r\n\r\n    try {\r\n      const method = (req.method || 'GET').toUpperCase() as HttpMethod;\r\n      log.verbose(`API ${method} ${url} -> ${path.relative(process.cwd(), filePath)}`);\r\n\r\n      // OPTIONS preflight \u2014 respond immediately with CORS headers.\r\n      if (method === 'OPTIONS') { respondOptions(apiRes); return; }\r\n\r\n      // Augment the request object with parsed body, params, and query.\r\n      const apiReq    = req as ApiRequest;\r\n      apiReq.body   = await parseBody(req);\r\n      apiReq.params = params;\r\n      apiReq.query  = parseQuery(url, port);\r\n\r\n      // Dynamic import is always fresh because each path includes a unique\r\n      // file:// URL \u2014 Node will not serve a stale cached module.\r\n      const apiModule: ApiModule = await import(pathToFileURL(filePath).href);\r\n      const handler = apiModule[method] ?? apiModule.default;\r\n\r\n      if (!handler) {\r\n        apiRes.json({ error: `Method ${method} not allowed` }, 405);\r\n        return;\r\n      }\r\n\r\n      await handler(apiReq, apiRes);\r\n    } catch (error) {\r\n      log.error('API Error:', error);\r\n      apiRes.json({ error: 'Internal server error' }, 500);\r\n    }\r\n  };\r\n}\r\n"],
+  "mappings": "AA4BA,OAAO,UAAU;AACjB,OAAO,QAAQ;AACf,SAAS,qBAAqB;AAE9B,SAAS,WAAW;AACpB,SAAS,kBAAkB;AAiDpB,SAAS,oBAAoB,WAAoC;AACtE,MAAI,CAAC,GAAG,WAAW,SAAS,GAAG;AAC7B,QAAI,KAAK,+BAA+B,SAAS;AACjD,WAAO,CAAC;AAAA,EACV;AAEA,QAAM,UAAW,GAAG,YAAY,WAAW,EAAE,eAAe,KAAK,CAAC;AAClE,QAAM,WAA4B,CAAC;AAGnC,aAAW,KAAK,SAAS;AACvB,QAAI,EAAE,YAAY,GAAG;AACnB,eAAS,KAAK,EAAE,QAAQ,IAAI,EAAE,IAAI,IAAI,WAAW,KAAK,KAAK,WAAW,EAAE,IAAI,EAAE,CAAC;AAAA,IACjF;AAAA,EACF;AAGA,aAAW,KAAK,SAAS;AACvB,QACE,EAAE,OAAO,MACR,EAAE,KAAK,SAAS,KAAK,KAAK,EAAE,KAAK,SAAS,MAAM,MACjD,EAAE,SAAS,cACX,EAAE,SAAS,aACX;AACA,YAAM,OAAO,EAAE,KAAK,QAAQ,WAAW,EAAE;AACzC,eAAS,KAAK;AAAA,QACZ,QAAW,IAAI,IAAI;AAAA,QACnB,WAAW;AAAA,QACX,UAAW,KAAK,KAAK,WAAW,EAAE,IAAI;AAAA,MACxC,CAAC;AAAA,IACH;AAAA,EACF;AAGA,MAAI,GAAG,WAAW,KAAK,KAAK,WAAW,UAAU,CAAC,GAAG;AACnD,aAAS,KAAK,EAAE,QAAQ,IAAI,WAAW,UAAU,CAAC;AAAA,EACpD;AAEA,SAAO;AACT;AAIA,MAAM,iBAAiB,KAAK,OAAO;AAWnC,eAAsB,UAAU,KAAoC;AAClE,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,QAAI,OAAQ;AACZ,QAAI,QAAQ;AAEZ,QAAI,GAAG,QAAQ,WAAS;AACtB,eAAS,MAAM;AACf,UAAI,QAAQ,gBAAgB;AAC1B,YAAI,QAAQ;AACZ,eAAO,OAAO,IAAI,MAAM,wBAAwB,CAAC;AAAA,MACnD;AACA,cAAQ,MAAM,SAAS;AAAA,IACzB,CAAC;AAED,QAAI,GAAG,OAAO,MAAM;AAClB,UAAI;AACF,YAAI,QAAQ,IAAI,QAAQ,cAAc,GAAG,SAAS,kBAAkB,GAAG;AACrE,gBAAM,SAAS,KAAK,MAAM,IAAI;AAE9B,cAAI,WAAW,QAAQ,OAAO,WAAW,YAAY,CAAC,MAAM,QAAQ,MAAM,GAAG;AAC3E,mBAAO,OAAO;AACd,mBAAO,OAAO;AAAA,UAChB;AACA,kBAAQ,MAAM;AAAA,QAChB,OAAO;AACL,kBAAQ,IAAI;AAAA,QACd;AAAA,MACF,SAAS,KAAK;AACZ,eAAO,GAAG;AAAA,MACZ;AAAA,IACF,CAAC;AAED,QAAI,GAAG,SAAS,MAAM;AAAA,EACxB,CAAC;AACH;AAKO,SAAS,WAAW,KAAa,MAAsC;AAC5E,QAAM,QAAgC,CAAC;AACvC,MAAI,IAAI,KAAK,oBAAoB,IAAI,EAAE,EACpC,aACA,QAAQ,CAAC,GAAG,MAAM;AAAE,UAAM,CAAC,IAAI;AAAA,EAAG,CAAC;AACtC,SAAO;AACT;AAQO,SAAS,gBAAgB,KAAkC;AAChE,QAAM,SAAY;AAClB,SAAO,OAAS,SAAU,MAAM,aAAa,KAAK;AAChD,SAAK,aAAa;AAClB,SAAK,UAAU,gBAAgB,kBAAkB;AACjD,SAAK,IAAI,KAAK,UAAU,IAAI,CAAC;AAAA,EAC/B;AACA,SAAO,SAAS,SAAU,MAAM;AAC9B,SAAK,aAAa;AAClB,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAGA,SAAS,eAAe,KAAwB;AAC9C,MAAI,UAAU,+BAA+B,GAAG;AAChD,MAAI,UAAU,gCAAgC,wCAAwC;AACtF,MAAI,UAAU,gCAAgC,cAAc;AAC5D,MAAI,aAAa;AACjB,MAAI,IAAI;AACV;AAYO,SAAS,eACd,KACA,aACmD;AACnD,aAAW,UAAU,aAAa;AAChC,QAAI,OAAO,WAAW,IAAI;AAExB,YAAM,iBAAiB,YAAY;AAAA,QACjC,OAAK,EAAE,WAAW,MAAM,IAAI,WAAW,EAAE,MAAM;AAAA,MACjD;AACA,UAAI,CAAC,eAAgB,QAAO,EAAE,QAAQ,SAAS,OAAO,IAAI;AAAA,IAC5D,WAAW,IAAI,WAAW,OAAO,MAAM,GAAG;AACxC,aAAO,EAAE,QAAQ,SAAS,IAAI,MAAM,OAAO,OAAO,MAAM,KAAK,IAAI;AAAA,IACnE;AAAA,EACF;AACA,SAAO;AACT;AAiBO,SAAS,iBAAiB,EAAE,aAAa,KAAK,GAAsB;AACzE,SAAO,eAAe,eACpB,KACA,KACA,KACe;AACf,UAAM,SAAY,gBAAgB,GAAG;AACrC,UAAM,WAAY,eAAe,KAAK,WAAW;AAEjD,QAAI,CAAC,UAAU;AACb,aAAO,KAAK,EAAE,OAAO,yBAAyB,GAAG,GAAG;AACpD;AAAA,IACF;AAEA,UAAM,EAAE,QAAQ,QAAQ,IAAI;AAC5B,QAAI,WAA0B;AAC9B,QAAI,SAA8C,CAAC;AAGnD,QAAI,OAAO,UAAU;AACnB,iBAAW,OAAO;AAAA,IACpB;AAGA,QAAI,CAAC,YAAY,OAAO,WAAW,MAAM,YAAY,KAAK;AACxD,YAAM,YAAY,KAAK,KAAK,OAAO,WAAW,UAAU;AACxD,UAAI,GAAG,WAAW,SAAS,EAAG,YAAW;AAAA,IAC3C;AAGA,QAAI,CAAC,UAAU;AACb,YAAM,aACJ,WAAW,SAAS,OAAO,WAAW,KAAK,KAC3C,WAAW,SAAS,OAAO,WAAW,MAAM;AAC9C,UAAI,YAAY;AAAE,mBAAW,WAAW;AAAU,iBAAS,WAAW;AAAA,MAAQ;AAAA,IAChF;AAEA,QAAI,CAAC,UAAU;AACb,aAAO,KAAK,EAAE,OAAO,yBAAyB,GAAG,GAAG;AACpD;AAAA,IACF;AAEA,QAAI;AACF,YAAM,UAAU,IAAI,UAAU,OAAO,YAAY;AACjD,UAAI,QAAQ,OAAO,MAAM,IAAI,GAAG,OAAO,KAAK,SAAS,QAAQ,IAAI,GAAG,QAAQ,CAAC,EAAE;AAG/E,UAAI,WAAW,WAAW;AAAE,uBAAe,MAAM;AAAG;AAAA,MAAQ;AAG5D,YAAM,SAAY;AAClB,aAAO,OAAS,MAAM,UAAU,GAAG;AACnC,aAAO,SAAS;AAChB,aAAO,QAAS,WAAW,KAAK,IAAI;AAIpC,YAAM,YAAuB,MAAM,OAAO,cAAc,QAAQ,EAAE;AAClE,YAAM,UAAU,UAAU,MAAM,KAAK,UAAU;AAE/C,UAAI,CAAC,SAAS;AACZ,eAAO,KAAK,EAAE,OAAO,UAAU,MAAM,eAAe,GAAG,GAAG;AAC1D;AAAA,MACF;AAEA,YAAM,QAAQ,QAAQ,MAAM;AAAA,IAC9B,SAAS,OAAO;AACd,UAAI,MAAM,cAAc,KAAK;AAC7B,aAAO,KAAK,EAAE,OAAO,wBAAwB,GAAG,GAAG;AAAA,IACrD;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { useHtml } from './use-html';
+export type { HtmlOptions, TitleValue, HtmlAttrs, BodyAttrs, MetaTag, LinkTag, ScriptTag, StyleTag, } from './use-html';
+export { default as useRouter } from './as-is/useRouter';
+export { default as Link } from './as-is/Link';
+export { setupLocationChangeMonitor, initRuntime } from './bundle';
+export type { RuntimeData } from './bundle';
+export { escapeHtml } from './utils';
+export { ansi, c, log, setDebugLevel, getDebugLevel } from './logger';
+export type { DebugLevel } from './logger';

package/dist/index.js

@@ -0,0 +1,20 @@
+import { useHtml } from "./use-html.js";
+import { default as default2 } from "./as-is/useRouter";
+import { default as default3 } from "./as-is/Link";
+import { setupLocationChangeMonitor, initRuntime } from "./bundle.js";
+import { escapeHtml } from "./utils.js";
+import { ansi, c, log, setDebugLevel, getDebugLevel } from "./logger.js";
+export {
+  default3 as Link,
+  ansi,
+  c,
+  escapeHtml,
+  getDebugLevel,
+  initRuntime,
+  log,
+  setDebugLevel,
+  setupLocationChangeMonitor,
+  useHtml,
+  default2 as useRouter
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["// \u2500\u2500\u2500 Client-side hooks & components \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\nexport { useHtml } from './use-html';\r\nexport type {\r\n    HtmlOptions,\r\n    TitleValue,\r\n    HtmlAttrs,\r\n    BodyAttrs,\r\n    MetaTag,\r\n    LinkTag,\r\n    ScriptTag,\r\n    StyleTag,\r\n} from './use-html';\r\n\r\nexport { default as useRouter } from './as-is/useRouter';\r\n\r\nexport { default as Link } from './as-is/Link';\r\n\r\n// \u2500\u2500\u2500 Client runtime (browser bootstrap) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\nexport { setupLocationChangeMonitor, initRuntime } from './bundle';\r\nexport type { RuntimeData } from './bundle';\r\n\r\n// \u2500\u2500\u2500 Shared utilities \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\nexport { escapeHtml } from './utils';\r\n\r\nexport { ansi, c, log, setDebugLevel, getDebugLevel } from './logger';\r\nexport type { DebugLevel } from './logger';\r\n"],
+  "mappings": "AACA,SAAS,eAAe;AAYxB,SAAoB,WAAXA,gBAA4B;AAErC,SAAoB,WAAXA,gBAAuB;AAGhC,SAAS,4BAA4B,mBAAmB;AAIxD,SAAS,kBAAkB;AAE3B,SAAS,MAAM,GAAG,KAAK,eAAe,qBAAqB;",
+  "names": ["default"]
+}

package/dist/logger.d.ts

@@ -0,0 +1,58 @@
+/**
+ * logger.ts — ANSI-Coloured Levelled Logger
+ *
+ * Provides a small set of server-side logging utilities used throughout NukeJS.
+ *
+ * Debug levels (set via nuke.config.ts `debug` field):
+ *   false      — silent, nothing printed
+ *   'error'    — error() only
+ *   'info'     — info(), warn(), error()
+ *   true       — verbose: all of the above plus verbose()
+ *
+ * The level can be read back with `getDebugLevel()` and is also forwarded to
+ * the browser client (as a string) so server and client log at the same level.
+ */
+/** Map of named ANSI colour/style escape codes. */
+export declare const ansi: {
+    readonly reset: "\u001B[0m";
+    readonly bold: "\u001B[1m";
+    readonly dim: "\u001B[2m";
+    readonly black: "\u001B[30m";
+    readonly red: "\u001B[31m";
+    readonly green: "\u001B[32m";
+    readonly yellow: "\u001B[33m";
+    readonly blue: "\u001B[34m";
+    readonly magenta: "\u001B[35m";
+    readonly cyan: "\u001B[36m";
+    readonly white: "\u001B[37m";
+    readonly gray: "\u001B[90m";
+    readonly bgBlue: "\u001B[44m";
+    readonly bgGreen: "\u001B[42m";
+    readonly bgMagenta: "\u001B[45m";
+};
+/**
+ * Wraps `text` in the ANSI sequence for `color`, optionally bold.
+ * Always appends the reset sequence so colour does not bleed into surrounding
+ * terminal output.
+ */
+export declare function c(color: keyof typeof ansi, text: string, bold?: boolean): string;
+/** false = silent | 'error' = errors only | 'info' = startup + errors | true = verbose */
+export type DebugLevel = false | 'error' | 'info' | true;
+/** Sets the active log level.  Called once after the config is loaded. */
+export declare function setDebugLevel(level: DebugLevel): void;
+/** Returns the currently active log level. */
+export declare function getDebugLevel(): DebugLevel;
+/**
+ * Structured log object with four severity methods.
+ * Each method is a no-op unless the current `_level` allows it.
+ */
+export declare const log: {
+    /** Trace-level detail: component IDs, route matching, bundle paths. */
+    verbose(...args: any[]): void;
+    /** Startup messages, route tables, config summary. */
+    info(...args: any[]): void;
+    /** Non-fatal issues: missing middleware, unrecognised config keys. */
+    warn(...args: any[]): void;
+    /** Errors that produce a 500 response or crash the build. */
+    error(...args: any[]): void;
+};

package/dist/logger.js

@@ -0,0 +1,53 @@
+const ansi = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  black: "\x1B[30m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  magenta: "\x1B[35m",
+  cyan: "\x1B[36m",
+  white: "\x1B[37m",
+  gray: "\x1B[90m",
+  bgBlue: "\x1B[44m",
+  bgGreen: "\x1B[42m",
+  bgMagenta: "\x1B[45m"
+};
+function c(color, text, bold = false) {
+  return `${bold ? ansi.bold : ""}${ansi[color]}${text}${ansi.reset}`;
+}
+let _level = false;
+function setDebugLevel(level) {
+  _level = level;
+}
+function getDebugLevel() {
+  return _level;
+}
+const log = {
+  /** Trace-level detail: component IDs, route matching, bundle paths. */
+  verbose(...args) {
+    if (_level === true) console.log(c("gray", "[verbose]"), ...args);
+  },
+  /** Startup messages, route tables, config summary. */
+  info(...args) {
+    if (_level === true || _level === "info") console.log(c("cyan", "[info]"), ...args);
+  },
+  /** Non-fatal issues: missing middleware, unrecognised config keys. */
+  warn(...args) {
+    if (_level === true || _level === "info") console.warn(c("yellow", "[warn]"), ...args);
+  },
+  /** Errors that produce a 500 response or crash the build. */
+  error(...args) {
+    if (_level !== false) console.error(c("red", "[error]"), ...args);
+  }
+};
+export {
+  ansi,
+  c,
+  getDebugLevel,
+  log,
+  setDebugLevel
+};
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/logger.ts"],
+  "sourcesContent": ["/**\r\n * logger.ts \u2014 ANSI-Coloured Levelled Logger\r\n *\r\n * Provides a small set of server-side logging utilities used throughout NukeJS.\r\n *\r\n * Debug levels (set via nuke.config.ts `debug` field):\r\n *   false      \u2014 silent, nothing printed\r\n *   'error'    \u2014 error() only\r\n *   'info'     \u2014 info(), warn(), error()\r\n *   true       \u2014 verbose: all of the above plus verbose()\r\n *\r\n * The level can be read back with `getDebugLevel()` and is also forwarded to\r\n * the browser client (as a string) so server and client log at the same level.\r\n */\r\n\r\n// \u2500\u2500\u2500 ANSI escape codes \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/** Map of named ANSI colour/style escape codes. */\r\nexport const ansi = {\r\n  reset:     '\\x1b[0m',\r\n  bold:      '\\x1b[1m',\r\n  dim:       '\\x1b[2m',\r\n  black:     '\\x1b[30m',\r\n  red:       '\\x1b[31m',\r\n  green:     '\\x1b[32m',\r\n  yellow:    '\\x1b[33m',\r\n  blue:      '\\x1b[34m',\r\n  magenta:   '\\x1b[35m',\r\n  cyan:      '\\x1b[36m',\r\n  white:     '\\x1b[37m',\r\n  gray:      '\\x1b[90m',\r\n  bgBlue:    '\\x1b[44m',\r\n  bgGreen:   '\\x1b[42m',\r\n  bgMagenta: '\\x1b[45m',\r\n} as const;\r\n\r\n/**\r\n * Wraps `text` in the ANSI sequence for `color`, optionally bold.\r\n * Always appends the reset sequence so colour does not bleed into surrounding\r\n * terminal output.\r\n */\r\nexport function c(color: keyof typeof ansi, text: string, bold = false): string {\r\n  return `${bold ? ansi.bold : ''}${ansi[color]}${text}${ansi.reset}`;\r\n}\r\n\r\n// \u2500\u2500\u2500 Debug level \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/** false = silent | 'error' = errors only | 'info' = startup + errors | true = verbose */\r\nexport type DebugLevel = false | 'error' | 'info' | true;\r\n\r\nlet _level: DebugLevel = false;\r\n\r\n/** Sets the active log level.  Called once after the config is loaded. */\r\nexport function setDebugLevel(level: DebugLevel): void { _level = level; }\r\n\r\n/** Returns the currently active log level. */\r\nexport function getDebugLevel(): DebugLevel { return _level; }\r\n\r\n// \u2500\u2500\u2500 Logger \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\r\n\r\n/**\r\n * Structured log object with four severity methods.\r\n * Each method is a no-op unless the current `_level` allows it.\r\n */\r\nexport const log = {\r\n  /** Trace-level detail: component IDs, route matching, bundle paths. */\r\n  verbose(...args: any[]): void {\r\n    if (_level === true) console.log(c('gray', '[verbose]'), ...args);\r\n  },\r\n  /** Startup messages, route tables, config summary. */\r\n  info(...args: any[]): void {\r\n    if (_level === true || _level === 'info') console.log(c('cyan', '[info]'), ...args);\r\n  },\r\n  /** Non-fatal issues: missing middleware, unrecognised config keys. */\r\n  warn(...args: any[]): void {\r\n    if (_level === true || _level === 'info') console.warn(c('yellow', '[warn]'), ...args);\r\n  },\r\n  /** Errors that produce a 500 response or crash the build. */\r\n  error(...args: any[]): void {\r\n    if (_level !== false) console.error(c('red', '[error]'), ...args);\r\n  },\r\n};\r\n"],
+  "mappings": "AAkBO,MAAM,OAAO;AAAA,EAClB,OAAW;AAAA,EACX,MAAW;AAAA,EACX,KAAW;AAAA,EACX,OAAW;AAAA,EACX,KAAW;AAAA,EACX,OAAW;AAAA,EACX,QAAW;AAAA,EACX,MAAW;AAAA,EACX,SAAW;AAAA,EACX,MAAW;AAAA,EACX,OAAW;AAAA,EACX,MAAW;AAAA,EACX,QAAW;AAAA,EACX,SAAW;AAAA,EACX,WAAW;AACb;AAOO,SAAS,EAAE,OAA0B,MAAc,OAAO,OAAe;AAC9E,SAAO,GAAG,OAAO,KAAK,OAAO,EAAE,GAAG,KAAK,KAAK,CAAC,GAAG,IAAI,GAAG,KAAK,KAAK;AACnE;AAOA,IAAI,SAAqB;AAGlB,SAAS,cAAc,OAAyB;AAAE,WAAS;AAAO;AAGlE,SAAS,gBAA4B;AAAE,SAAO;AAAQ;AAQtD,MAAM,MAAM;AAAA;AAAA,EAEjB,WAAW,MAAmB;AAC5B,QAAI,WAAW,KAAM,SAAQ,IAAI,EAAE,QAAQ,WAAW,GAAG,GAAG,IAAI;AAAA,EAClE;AAAA;AAAA,EAEA,QAAQ,MAAmB;AACzB,QAAI,WAAW,QAAQ,WAAW,OAAQ,SAAQ,IAAI,EAAE,QAAQ,QAAQ,GAAG,GAAG,IAAI;AAAA,EACpF;AAAA;AAAA,EAEA,QAAQ,MAAmB;AACzB,QAAI,WAAW,QAAQ,WAAW,OAAQ,SAAQ,KAAK,EAAE,UAAU,QAAQ,GAAG,GAAG,IAAI;AAAA,EACvF;AAAA;AAAA,EAEA,SAAS,MAAmB;AAC1B,QAAI,WAAW,MAAO,SAAQ,MAAM,EAAE,OAAO,SAAS,GAAG,GAAG,IAAI;AAAA,EAClE;AACF;",
+  "names": []
+}

package/dist/metadata.d.ts

@@ -0,0 +1,50 @@
+/**
+ * metadata.ts — Legacy Metadata Helpers
+ *
+ * @deprecated  Use the `useHtml()` hook instead.
+ *
+ * This module provided an earlier metadata API where pages exported a
+ * `metadata` object alongside their default component.  It is retained for
+ * backwards compatibility but new projects should use useHtml().
+ *
+ * Example (old pattern):
+ *   export const metadata = {
+ *     title: 'My Page',
+ *     scripts: [{ src: '/analytics.js', defer: true }],
+ *   };
+ */
+export interface ScriptTag {
+    src?: string;
+    content?: string;
+    type?: string;
+    defer?: boolean;
+    async?: boolean;
+}
+export interface StyleTag {
+    href?: string;
+    content?: string;
+}
+export interface Metadata {
+    title?: string;
+    scripts?: ScriptTag[];
+    styles?: StyleTag[];
+}
+/**
+ * Dynamically imports a page/layout module and returns its exported `metadata`
+ * object, or an empty object if none is found or the import fails.
+ */
+export declare function loadMetadata(filePath: string): Promise<Metadata>;
+/**
+ * Merges metadata from an array of modules in render order (outermost layout
+ * first, page last).
+ *
+ * Merge strategy:
+ *   title   — last non-empty value wins (page overrides layout)
+ *   scripts — concatenated in order
+ *   styles  — concatenated in order
+ */
+export declare function mergeMetadata(ordered: Metadata[]): Required<Metadata>;
+/** Renders a ScriptTag to an HTML string. */
+export declare function renderScriptTag(s: ScriptTag): string;
+/** Renders a StyleTag to an HTML string. */
+export declare function renderStyleTag(s: StyleTag): string;

package/dist/metadata.js

@@ -0,0 +1,43 @@
+import { pathToFileURL } from "url";
+import { escapeHtml } from "./utils.js";
+async function loadMetadata(filePath) {
+  try {
+    const mod = await import(pathToFileURL(filePath).href);
+    return mod.metadata ?? {};
+  } catch {
+    return {};
+  }
+}
+function mergeMetadata(ordered) {
+  const result = { title: "", scripts: [], styles: [] };
+  for (const m of ordered) {
+    if (m.title) result.title = m.title;
+    if (m.scripts?.length) result.scripts.push(...m.scripts);
+    if (m.styles?.length) result.styles.push(...m.styles);
+  }
+  return result;
+}
+function renderScriptTag(s) {
+  if (s.src) {
+    const attrs = [
+      `src="${escapeHtml(s.src)}"`,
+      s.type ? `type="${escapeHtml(s.type)}"` : "",
+      s.defer ? "defer" : "",
+      s.async ? "async" : ""
+    ].filter(Boolean).join(" ");
+    return `<script ${attrs}></script>`;
+  }
+  const typeAttr = s.type ? ` type="${escapeHtml(s.type)}"` : "";
+  return `<script${typeAttr}>${s.content ?? ""}</script>`;
+}
+function renderStyleTag(s) {
+  if (s.href) return `<link rel="stylesheet" href="${escapeHtml(s.href)}" />`;
+  return `<style>${s.content ?? ""}</style>`;
+}
+export {
+  loadMetadata,
+  mergeMetadata,
+  renderScriptTag,
+  renderStyleTag
+};
+//# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/metadata.ts"],
+  "sourcesContent": ["/**\r\n * metadata.ts \u2014 Legacy Metadata Helpers\r\n *\r\n * @deprecated  Use the `useHtml()` hook instead.\r\n *\r\n * This module provided an earlier metadata API where pages exported a\r\n * `metadata` object alongside their default component.  It is retained for\r\n * backwards compatibility but new projects should use useHtml().\r\n *\r\n * Example (old pattern):\r\n *   export const metadata = {\r\n *     title: 'My Page',\r\n *     scripts: [{ src: '/analytics.js', defer: true }],\r\n *   };\r\n */\r\n\r\nimport { pathToFileURL } from 'url';\r\nimport { escapeHtml } from './utils';\r\n\r\nexport interface ScriptTag {\r\n  src?:     string;\r\n  content?: string;\r\n  type?:    string;\r\n  defer?:   boolean;\r\n  async?:   boolean;\r\n}\r\n\r\nexport interface StyleTag {\r\n  href?:    string;\r\n  content?: string;\r\n}\r\n\r\nexport interface Metadata {\r\n  title?:   string;\r\n  scripts?: ScriptTag[];\r\n  styles?:  StyleTag[];\r\n}\r\n\r\n/**\r\n * Dynamically imports a page/layout module and returns its exported `metadata`\r\n * object, or an empty object if none is found or the import fails.\r\n */\r\nexport async function loadMetadata(filePath: string): Promise<Metadata> {\r\n  try {\r\n    const mod = await import(pathToFileURL(filePath).href);\r\n    return (mod.metadata as Metadata) ?? {};\r\n  } catch {\r\n    return {};\r\n  }\r\n}\r\n\r\n/**\r\n * Merges metadata from an array of modules in render order (outermost layout\r\n * first, page last).\r\n *\r\n * Merge strategy:\r\n *   title   \u2014 last non-empty value wins (page overrides layout)\r\n *   scripts \u2014 concatenated in order\r\n *   styles  \u2014 concatenated in order\r\n */\r\nexport function mergeMetadata(ordered: Metadata[]): Required<Metadata> {\r\n  const result: Required<Metadata> = { title: '', scripts: [], styles: [] };\r\n  for (const m of ordered) {\r\n    if (m.title)          result.title = m.title;\r\n    if (m.scripts?.length) result.scripts.push(...m.scripts);\r\n    if (m.styles?.length)  result.styles.push(...m.styles);\r\n  }\r\n  return result;\r\n}\r\n\r\n/** Renders a ScriptTag to an HTML string. */\r\nexport function renderScriptTag(s: ScriptTag): string {\r\n  if (s.src) {\r\n    const attrs = [\r\n      `src=\"${escapeHtml(s.src)}\"`,\r\n      s.type  ? `type=\"${escapeHtml(s.type)}\"` : '',\r\n      s.defer ? 'defer'  : '',\r\n      s.async ? 'async'  : '',\r\n    ].filter(Boolean).join(' ');\r\n    return `<script ${attrs}></script>`;\r\n  }\r\n  const typeAttr = s.type ? ` type=\"${escapeHtml(s.type)}\"` : '';\r\n  return `<script${typeAttr}>${s.content ?? ''}</script>`;\r\n}\r\n\r\n/** Renders a StyleTag to an HTML string. */\r\nexport function renderStyleTag(s: StyleTag): string {\r\n  if (s.href) return `<link rel=\"stylesheet\" href=\"${escapeHtml(s.href)}\" />`;\r\n  return `<style>${s.content ?? ''}</style>`;\r\n}\r\n"],
+  "mappings": "AAgBA,SAAS,qBAAqB;AAC9B,SAAS,kBAAkB;AAyB3B,eAAsB,aAAa,UAAqC;AACtE,MAAI;AACF,UAAM,MAAM,MAAM,OAAO,cAAc,QAAQ,EAAE;AACjD,WAAQ,IAAI,YAAyB,CAAC;AAAA,EACxC,QAAQ;AACN,WAAO,CAAC;AAAA,EACV;AACF;AAWO,SAAS,cAAc,SAAyC;AACrE,QAAM,SAA6B,EAAE,OAAO,IAAI,SAAS,CAAC,GAAG,QAAQ,CAAC,EAAE;AACxE,aAAW,KAAK,SAAS;AACvB,QAAI,EAAE,MAAgB,QAAO,QAAQ,EAAE;AACvC,QAAI,EAAE,SAAS,OAAQ,QAAO,QAAQ,KAAK,GAAG,EAAE,OAAO;AACvD,QAAI,EAAE,QAAQ,OAAS,QAAO,OAAO,KAAK,GAAG,EAAE,MAAM;AAAA,EACvD;AACA,SAAO;AACT;AAGO,SAAS,gBAAgB,GAAsB;AACpD,MAAI,EAAE,KAAK;AACT,UAAM,QAAQ;AAAA,MACZ,QAAQ,WAAW,EAAE,GAAG,CAAC;AAAA,MACzB,EAAE,OAAQ,SAAS,WAAW,EAAE,IAAI,CAAC,MAAM;AAAA,MAC3C,EAAE,QAAQ,UAAW;AAAA,MACrB,EAAE,QAAQ,UAAW;AAAA,IACvB,EAAE,OAAO,OAAO,EAAE,KAAK,GAAG;AAC1B,WAAO,WAAW,KAAK;AAAA,EACzB;AACA,QAAM,WAAW,EAAE,OAAO,UAAU,WAAW,EAAE,IAAI,CAAC,MAAM;AAC5D,SAAO,UAAU,QAAQ,IAAI,EAAE,WAAW,EAAE;AAC9C;AAGO,SAAS,eAAe,GAAqB;AAClD,MAAI,EAAE,KAAM,QAAO,gCAAgC,WAAW,EAAE,IAAI,CAAC;AACrE,SAAO,UAAU,EAAE,WAAW,EAAE;AAClC;",
+  "names": []
+}

package/dist/middleware-loader.d.ts

@@ -0,0 +1,50 @@
+/**
+ * middleware-loader.ts — Middleware Chain Manager
+ *
+ * Loads and runs the NukeJS middleware stack.  Two layers are supported:
+ *
+ *   1. Built-in middleware   — shipped with the nukejs package.
+ *                              Currently handles the /__hmr and /__hmr.js
+ *                              routes required by the HMR client.
+ *                              Located next to this file as `middleware.ts`
+ *                              (or `middleware.js` in the compiled dist/).
+ *
+ *   2. User middleware       — `middleware.ts` in the project root (cwd).
+ *                              Runs after the built-in layer so it can inspect
+ *                              or short-circuit every incoming request, including
+ *                              API and page routes.
+ *
+ * Each middleware function receives (req, res) and may either:
+ *   - End the response (res.end / res.json) to short-circuit further handling.
+ *   - Return without touching res to pass control to the next layer.
+ *
+ * runMiddleware() returns `true` if any middleware ended the response,
+ * allowing app.ts to skip its own routing logic.
+ *
+ * Restart behaviour:
+ *   When nuke.config.ts or middleware.ts change in dev, app.ts restarts the
+ *   process.  The new process calls loadMiddleware() fresh so stale module
+ *   caches are not an issue.
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+export type MiddlewareFunction = (req: IncomingMessage, res: ServerResponse) => Promise<void> | void;
+/**
+ * Discovers and loads all middleware in priority order:
+ *   1. Built-in (this package's own middleware.ts / middleware.js)
+ *   2. User-supplied (cwd/middleware.ts)
+ *
+ * Duplicate paths (e.g. if cwd === package dir in a monorepo) are deduplicated
+ * via a Set so the same file is never loaded twice.
+ *
+ * Should be called once at startup after the config is loaded.
+ */
+export declare function loadMiddleware(): Promise<void>;
+/**
+ * Runs all loaded middleware in registration order.
+ *
+ * Stops and returns `true` as soon as any middleware ends or sends a response
+ * (res.writableEnded or res.headersSent), allowing app.ts to skip routing.
+ *
+ * Returns `false` if no middleware handled the request.
+ */
+export declare function runMiddleware(req: IncomingMessage, res: ServerResponse): Promise<boolean>;