mates-fullstack 1.0.0-beta.1

package/dist/docs-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-page.js","sourceRoot":"","sources":["../src/docs-page.ts"],"names":[],"mappings":"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"}

package/dist/download.d.ts

@@ -0,0 +1,78 @@
+/**
+ * mates-fullstack — download.ts
+ *
+ * The Download class for server functions that return file downloads.
+ * Returned by a server function, detected by rpc-runner,
+ * and written as a binary response with Content-Disposition: attachment.
+ *
+ * Usage:
+ *   import { Download } from "mates-fullstack/server";
+ *
+ *   export async function downloadReport(
+ *     payload: { id: string },
+ *     ctx: Context
+ *   ) {
+ *     const pdf = await generatePdf(payload.id);
+ *     return new Download(pdf, { filename: "report.pdf" });
+ *   }
+ *
+ * On the client, the RPC stub detects the binary response and
+ * triggers a browser download automatically — no client-side code needed.
+ */
+/// <reference types="node" />
+/// <reference types="node" />
+import type { ServerResponse } from "node:http";
+/**
+ * Returned from a server function to trigger a file download in the browser.
+ *
+ * @example
+ * return new Download(pdfBuffer, { filename: "report.pdf" });
+ * return new Download(csvString, { filename: "export.csv", contentType: "text/csv" });
+ * return new Download(imageBuffer, { filename: "photo.jpg", contentType: "image/jpeg" });
+ */
+export declare class Download {
+    readonly data: Buffer;
+    readonly filename: string;
+    readonly contentType: string;
+    constructor(data: Buffer | Uint8Array | string, options: {
+        filename: string;
+        /**
+         * MIME type for the Content-Type header.
+         * Defaults to "application/octet-stream" (generic binary).
+         * Common values:
+         *   - "application/pdf"
+         *   - "text/csv"
+         *   - "application/json"
+         *   - "image/png"
+         *   - "application/zip"
+         */
+        contentType?: string;
+    });
+}
+/**
+ * Write a Download to a Node.js ServerResponse.
+ * Sets Content-Type, Content-Length, and Content-Disposition headers.
+ * Writes the binary data and ends the response.
+ */
+export declare function writeDownload(download: Download, res: ServerResponse): void;
+/**
+ * Trigger a file download in the browser from a fetch Response.
+ * Called by the RPC stub when it detects Content-Disposition: attachment.
+ *
+ * Creates a temporary blob URL, clicks a hidden <a> element, then cleans up.
+ */
+export declare function triggerBrowserDownload(response: Response, fallbackFilename?: string): void;
+/**
+ * Returns true if the value is a Download instance.
+ * Used by rpc-runner to detect download returns.
+ */
+export declare function isDownload(value: unknown): value is Download;
+/**
+ * Build a Content-Disposition header for a file download.
+ * Uses RFC 5987 encoding for filenames with non-ASCII characters.
+ *
+ * Always includes both the ASCII fallback (filename=) and
+ * the encoded form (filename*=) for maximum compatibility.
+ */
+export declare function buildContentDisposition(filename: string): string;
+//# sourceMappingURL=download.d.ts.map

package/dist/download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../src/download.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAIhD;;;;;;;GAOG;AACH,qBAAa,QAAQ;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAG3B,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,EAClC,OAAO,EAAE;QACP,QAAQ,EAAE,MAAM,CAAC;QACjB;;;;;;;;;WASG;QACH,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB;CAcJ;AAID;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,cAAc,GAClB,IAAI,CAaN;AAID;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,SAAa,GAC5B,IAAI,CAoBN;AAID;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAID;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAuBhE"}

package/dist/download.js

@@ -0,0 +1,202 @@
+/**
+ * mates-fullstack — download.ts
+ *
+ * The Download class for server functions that return file downloads.
+ * Returned by a server function, detected by rpc-runner,
+ * and written as a binary response with Content-Disposition: attachment.
+ *
+ * Usage:
+ *   import { Download } from "mates-fullstack/server";
+ *
+ *   export async function downloadReport(
+ *     payload: { id: string },
+ *     ctx: Context
+ *   ) {
+ *     const pdf = await generatePdf(payload.id);
+ *     return new Download(pdf, { filename: "report.pdf" });
+ *   }
+ *
+ * On the client, the RPC stub detects the binary response and
+ * triggers a browser download automatically — no client-side code needed.
+ */
+// ─── Download class ───────────────────────────────────────────────────────────
+/**
+ * Returned from a server function to trigger a file download in the browser.
+ *
+ * @example
+ * return new Download(pdfBuffer, { filename: "report.pdf" });
+ * return new Download(csvString, { filename: "export.csv", contentType: "text/csv" });
+ * return new Download(imageBuffer, { filename: "photo.jpg", contentType: "image/jpeg" });
+ */
+export class Download {
+    data;
+    filename;
+    contentType;
+    constructor(data, options) {
+        // Normalize all data types to Buffer
+        if (typeof data === "string") {
+            this.data = Buffer.from(data, "utf-8");
+        }
+        else if (data instanceof Uint8Array) {
+            this.data = Buffer.from(data);
+        }
+        else {
+            this.data = data;
+        }
+        this.filename = options.filename;
+        this.contentType = options.contentType ?? _guessContentType(options.filename);
+    }
+}
+// ─── Response writer ──────────────────────────────────────────────────────────
+/**
+ * Write a Download to a Node.js ServerResponse.
+ * Sets Content-Type, Content-Length, and Content-Disposition headers.
+ * Writes the binary data and ends the response.
+ */
+export function writeDownload(download, res) {
+    if (res.headersSent)
+        return;
+    res.writeHead(200, {
+        "Content-Type": download.contentType,
+        "Content-Length": download.data.length,
+        "Content-Disposition": buildContentDisposition(download.filename),
+        // Prevent browser from caching downloads
+        "Cache-Control": "no-store",
+        "Pragma": "no-cache",
+    });
+    res.end(download.data);
+}
+// ─── Client-side helper ───────────────────────────────────────────────────────
+/**
+ * Trigger a file download in the browser from a fetch Response.
+ * Called by the RPC stub when it detects Content-Disposition: attachment.
+ *
+ * Creates a temporary blob URL, clicks a hidden <a> element, then cleans up.
+ */
+export function triggerBrowserDownload(response, fallbackFilename = "download") {
+    // Extract filename from Content-Disposition header if present
+    const disposition = response.headers.get("content-disposition") ?? "";
+    const filename = _extractFilename(disposition) ?? fallbackFilename;
+    response.blob().then((blob) => {
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement("a");
+        a.href = url;
+        a.download = filename;
+        a.style.display = "none";
+        document.body.appendChild(a);
+        a.click();
+        // Clean up after a short delay to allow the download to start
+        setTimeout(() => {
+            document.body.removeChild(a);
+            URL.revokeObjectURL(url);
+        }, 100);
+    });
+}
+// ─── Type guard ───────────────────────────────────────────────────────────────
+/**
+ * Returns true if the value is a Download instance.
+ * Used by rpc-runner to detect download returns.
+ */
+export function isDownload(value) {
+    return value instanceof Download;
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Build a Content-Disposition header for a file download.
+ * Uses RFC 5987 encoding for filenames with non-ASCII characters.
+ *
+ * Always includes both the ASCII fallback (filename=) and
+ * the encoded form (filename*=) for maximum compatibility.
+ */
+export function buildContentDisposition(filename) {
+    // Strip path separators and null bytes for security
+    const safe = filename
+        .replace(/[\\/]/g, "_")
+        .replace(/\0/g, "")
+        .trim();
+    // Check if filename is pure ASCII
+    const isAscii = /^[\x20-\x7E]+$/.test(safe);
+    if (isAscii) {
+        // Simple case — quote the filename in case it has spaces or special chars
+        const escaped = safe.replace(/["\\]/g, "\\$&");
+        return `attachment; filename="${escaped}"`;
+    }
+    // Non-ASCII filename — use RFC 5987 encoding
+    const encoded = encodeURIComponent(safe);
+    // ASCII fallback (replace non-ASCII with "?")
+    const asciiFallback = safe.replace(/[^\x20-\x7E]/g, "?");
+    const asciiEscaped = asciiFallback.replace(/["\\]/g, "\\$&");
+    return `attachment; filename="${asciiEscaped}"; filename*=UTF-8''${encoded}`;
+}
+/**
+ * Extract filename from a Content-Disposition header string.
+ * Tries filename*= (RFC 5987) first, then filename=.
+ * Returns null if no filename is found.
+ */
+function _extractFilename(disposition) {
+    if (!disposition)
+        return null;
+    // Try filename*= (RFC 5987 encoded)
+    const encodedMatch = disposition.match(/filename\*=UTF-8''([^;]+)/i);
+    if (encodedMatch?.[1]) {
+        try {
+            return decodeURIComponent(encodedMatch[1]);
+        }
+        catch {
+            // Fall through to plain filename
+        }
+    }
+    // Try filename= (plain, possibly quoted)
+    const plainMatch = disposition.match(/filename="?([^";]+)"?/i);
+    if (plainMatch?.[1]) {
+        return plainMatch[1].trim();
+    }
+    return null;
+}
+/**
+ * Guess Content-Type from file extension.
+ * Falls back to application/octet-stream for unknown extensions.
+ */
+function _guessContentType(filename) {
+    const ext = filename.toLowerCase().split(".").pop() ?? "";
+    const mimeTypes = {
+        // Documents
+        pdf: "application/pdf",
+        doc: "application/msword",
+        docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        xls: "application/vnd.ms-excel",
+        xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        ppt: "application/vnd.ms-powerpoint",
+        pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        // Text
+        txt: "text/plain",
+        csv: "text/csv",
+        html: "text/html",
+        htm: "text/html",
+        xml: "application/xml",
+        json: "application/json",
+        // Images
+        png: "image/png",
+        jpg: "image/jpeg",
+        jpeg: "image/jpeg",
+        gif: "image/gif",
+        webp: "image/webp",
+        svg: "image/svg+xml",
+        ico: "image/x-icon",
+        avif: "image/avif",
+        // Archives
+        zip: "application/zip",
+        gz: "application/gzip",
+        tar: "application/x-tar",
+        // Audio / Video
+        mp3: "audio/mpeg",
+        mp4: "video/mp4",
+        webm: "video/webm",
+        // Fonts
+        woff: "font/woff",
+        woff2: "font/woff2",
+        ttf: "font/ttf",
+    };
+    return mimeTypes[ext] ?? "application/octet-stream";
+}
+//# sourceMappingURL=download.js.map

package/dist/download.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.js","sourceRoot":"","sources":["../src/download.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,iFAAiF;AAEjF;;;;;;;GAOG;AACH,MAAM,OAAO,QAAQ;IACV,IAAI,CAAS;IACb,QAAQ,CAAS;IACjB,WAAW,CAAS;IAE7B,YACE,IAAkC,EAClC,OAaC;QAED,qCAAqC;QACrC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACzC,CAAC;aAAM,IAAI,IAAI,YAAY,UAAU,EAAE,CAAC;YACtC,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACnB,CAAC;QAED,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,iBAAiB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChF,CAAC;CACF;AAED,iFAAiF;AAEjF;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAkB,EAClB,GAAmB;IAEnB,IAAI,GAAG,CAAC,WAAW;QAAE,OAAO;IAE5B,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE;QACjB,cAAc,EAAE,QAAQ,CAAC,WAAW;QACpC,gBAAgB,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM;QACtC,qBAAqB,EAAE,uBAAuB,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACjE,yCAAyC;QACzC,eAAe,EAAE,UAAU;QAC3B,QAAQ,EAAE,UAAU;KACrB,CAAC,CAAC;IAEH,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,iFAAiF;AAEjF;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,QAAkB,EAClB,gBAAgB,GAAG,UAAU;IAE7B,8DAA8D;IAC9D,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,IAAI,EAAE,CAAC;IACtE,MAAM,QAAQ,GAAG,gBAAgB,CAAC,WAAW,CAAC,IAAI,gBAAgB,CAAC;IAEnE,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;QAC5B,MAAM,GAAG,GAAG,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QACtC,MAAM,CAAC,GAAG,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;QACtC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC;QACb,CAAC,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACtB,CAAC,CAAC,KAAK,CAAC,OAAO,GAAG,MAAM,CAAC;QACzB,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;QAC7B,CAAC,CAAC,KAAK,EAAE,CAAC;QAEV,8DAA8D;QAC9D,UAAU,CAAC,GAAG,EAAE;YACd,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YAC7B,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC,EAAE,GAAG,CAAC,CAAC;IACV,CAAC,CAAC,CAAC;AACL,CAAC;AAED,iFAAiF;AAEjF;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,KAAK,YAAY,QAAQ,CAAC;AACnC,CAAC;AAED,iFAAiF;AAEjF;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAgB;IACtD,oDAAoD;IACpD,MAAM,IAAI,GAAG,QAAQ;SAClB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;SACtB,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;SAClB,IAAI,EAAE,CAAC;IAEV,kCAAkC;IAClC,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE5C,IAAI,OAAO,EAAE,CAAC;QACZ,0EAA0E;QAC1E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC/C,OAAO,yBAAyB,OAAO,GAAG,CAAC;IAC7C,CAAC;IAED,6CAA6C;IAC7C,MAAM,OAAO,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACzC,8CAA8C;IAC9C,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC;IACzD,MAAM,YAAY,GAAG,aAAa,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAE7D,OAAO,yBAAyB,YAAY,uBAAuB,OAAO,EAAE,CAAC;AAC/E,CAAC;AAED;;;;GAIG;AACH,SAAS,gBAAgB,CAAC,WAAmB;IAC3C,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAE9B,oCAAoC;IACpC,MAAM,YAAY,GAAG,WAAW,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;IACrE,IAAI,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtB,IAAI,CAAC;YACH,OAAO,kBAAkB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,iCAAiC;QACnC,CAAC;IACH,CAAC;IAED,yCAAyC;IACzC,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC/D,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpB,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9B,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB,CAAC,QAAgB;IACzC,MAAM,GAAG,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;IAE1D,MAAM,SAAS,GAA2B;QACxC,YAAY;QACZ,GAAG,EAAE,iBAAiB;QACtB,GAAG,EAAE,oBAAoB;QACzB,IAAI,EAAE,yEAAyE;QAC/E,GAAG,EAAE,0BAA0B;QAC/B,IAAI,EAAE,mEAAmE;QACzE,GAAG,EAAE,+BAA+B;QACpC,IAAI,EAAE,2EAA2E;QACjF,OAAO;QACP,GAAG,EAAE,YAAY;QACjB,GAAG,EAAE,UAAU;QACf,IAAI,EAAE,WAAW;QACjB,GAAG,EAAE,WAAW;QAChB,GAAG,EAAE,iBAAiB;QACtB,IAAI,EAAE,kBAAkB;QACxB,SAAS;QACT,GAAG,EAAE,WAAW;QAChB,GAAG,EAAE,YAAY;QACjB,IAAI,EAAE,YAAY;QAClB,GAAG,EAAE,WAAW;QAChB,IAAI,EAAE,YAAY;QAClB,GAAG,EAAE,eAAe;QACpB,GAAG,EAAE,cAAc;QACnB,IAAI,EAAE,YAAY;QAClB,WAAW;QACX,GAAG,EAAE,iBAAiB;QACtB,EAAE,EAAE,kBAAkB;QACtB,GAAG,EAAE,mBAAmB;QACxB,gBAAgB;QAChB,GAAG,EAAE,YAAY;QACjB,GAAG,EAAE,WAAW;QAChB,IAAI,EAAE,YAAY;QAClB,QAAQ;QACR,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,YAAY;QACnB,GAAG,EAAE,UAAU;KAChB,CAAC;IAEF,OAAO,SAAS,CAAC,GAAG,CAAC,IAAI,0BAA0B,CAAC;AACtD,CAAC"}

package/dist/env-loader.d.ts

@@ -0,0 +1,76 @@
+/**
+ * mates-fullstack — env-loader.ts
+ *
+ * Loads .env files into process.env at startup.
+ * No external dependencies — pure Node.js fs + path.
+ *
+ * Loading order (later overrides earlier):
+ *   1. .env
+ *   2. .env.local
+ *   3. .env.{mode}          (e.g. .env.production)
+ *   4. .env.{mode}.local    (e.g. .env.production.local)
+ *   5. Existing process.env (always wins — platform/CI vars take precedence)
+ *
+ * MATES_PUBLIC_ prefix:
+ *   Variables prefixed with MATES_PUBLIC_ are safe to expose to the
+ *   browser bundle. All other variables stay server-only.
+ *   The build plugin uses getPublicEnv() to inject them as
+ *   import.meta.env.MATES_PUBLIC_* in the client bundle.
+ *
+ * Parsing rules:
+ *   - Lines starting with # are comments
+ *   - Empty lines are skipped
+ *   - KEY=VALUE (split on first = only)
+ *   - Quoted values: KEY="value with spaces" → strips quotes
+ *   - Existing process.env values are never overwritten
+ *   - Invalid lines (no =) are skipped with a warning
+ */
+/**
+ * Load .env files for the given mode into process.env.
+ * Call once at startup before anything reads process.env.
+ *
+ * Order: .env (base, lowest priority), .env.local, .env.{mode}, .env.{mode}.local (highest priority).
+ * Later files override earlier files. Original platform/CI env vars always win.
+ *
+ * @param projectRoot - Absolute path to the project root.
+ * @param mode - "development" or "production".
+ */
+export declare function loadEnv(projectRoot: string, mode: "development" | "production"): void;
+/**
+ * Returns only the MATES_PUBLIC_ prefixed variables from process.env.
+ * These are safe to inject into the client bundle.
+ *
+ * Keys are returned as-is (with the MATES_PUBLIC_ prefix).
+ *
+ * @example
+ * // .env
+ * MATES_PUBLIC_STRIPE_KEY=pk_live_...
+ * DATABASE_URL=postgres://...   ← not included
+ *
+ * getPublicEnv()
+ * // { MATES_PUBLIC_STRIPE_KEY: "pk_live_..." }
+ */
+export declare function getPublicEnv(): Record<string, string>;
+/**
+ * Returns a define map for the bundler (esbuild/rolldown).
+ * Maps import.meta.env.MATES_PUBLIC_* to the actual values.
+ *
+ * Only MATES_PUBLIC_ variables are included — other env vars
+ * are never injected into the client bundle.
+ *
+ * @example
+ * // Returns:
+ * {
+ *   "import.meta.env.MATES_PUBLIC_STRIPE_KEY": '"pk_live_..."',
+ *   "import.meta.env.NODE_ENV": '"development"',
+ * }
+ */
+export declare function getBundlerDefines(mode: "development" | "production"): Record<string, string>;
+/**
+ * Parse a .env file string into a key-value map.
+ * Exported for testing.
+ *
+ * Does NOT modify process.env — use loadEnv() for that.
+ */
+export declare function parseEnvFile(content: string): Record<string, string>;
+//# sourceMappingURL=env-loader.d.ts.map

package/dist/env-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-loader.d.ts","sourceRoot":"","sources":["../src/env-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAQH;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CACrB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,aAAa,GAAG,YAAY,GACjC,IAAI,CAUN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUrD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,aAAa,GAAG,YAAY,GACjC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAaxB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoDpE"}

package/dist/env-loader.js

@@ -0,0 +1,213 @@
+/**
+ * mates-fullstack — env-loader.ts
+ *
+ * Loads .env files into process.env at startup.
+ * No external dependencies — pure Node.js fs + path.
+ *
+ * Loading order (later overrides earlier):
+ *   1. .env
+ *   2. .env.local
+ *   3. .env.{mode}          (e.g. .env.production)
+ *   4. .env.{mode}.local    (e.g. .env.production.local)
+ *   5. Existing process.env (always wins — platform/CI vars take precedence)
+ *
+ * MATES_PUBLIC_ prefix:
+ *   Variables prefixed with MATES_PUBLIC_ are safe to expose to the
+ *   browser bundle. All other variables stay server-only.
+ *   The build plugin uses getPublicEnv() to inject them as
+ *   import.meta.env.MATES_PUBLIC_* in the client bundle.
+ *
+ * Parsing rules:
+ *   - Lines starting with # are comments
+ *   - Empty lines are skipped
+ *   - KEY=VALUE (split on first = only)
+ *   - Quoted values: KEY="value with spaces" → strips quotes
+ *   - Existing process.env values are never overwritten
+ *   - Invalid lines (no =) are skipped with a warning
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { devWarn } from "./log.js";
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Load .env files for the given mode into process.env.
+ * Call once at startup before anything reads process.env.
+ *
+ * Order: .env (base, lowest priority), .env.local, .env.{mode}, .env.{mode}.local (highest priority).
+ * Later files override earlier files. Original platform/CI env vars always win.
+ *
+ * @param projectRoot - Absolute path to the project root.
+ * @param mode - "development" or "production".
+ */
+export function loadEnv(projectRoot, mode) {
+    // Snapshot original env vars so platform/CI values are never overwritten
+    const originalKeys = new Set(Object.keys(process.env));
+    const files = [".env", ".env.local", `.env.${mode}`, `.env.${mode}.local`];
+    for (const filename of files) {
+        const filePath = path.join(projectRoot, filename);
+        _loadEnvFile(filePath, originalKeys);
+    }
+}
+/**
+ * Returns only the MATES_PUBLIC_ prefixed variables from process.env.
+ * These are safe to inject into the client bundle.
+ *
+ * Keys are returned as-is (with the MATES_PUBLIC_ prefix).
+ *
+ * @example
+ * // .env
+ * MATES_PUBLIC_STRIPE_KEY=pk_live_...
+ * DATABASE_URL=postgres://...   ← not included
+ *
+ * getPublicEnv()
+ * // { MATES_PUBLIC_STRIPE_KEY: "pk_live_..." }
+ */
+export function getPublicEnv() {
+    const result = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (key.startsWith("MATES_PUBLIC_") && typeof value === "string") {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Returns a define map for the bundler (esbuild/rolldown).
+ * Maps import.meta.env.MATES_PUBLIC_* to the actual values.
+ *
+ * Only MATES_PUBLIC_ variables are included — other env vars
+ * are never injected into the client bundle.
+ *
+ * @example
+ * // Returns:
+ * {
+ *   "import.meta.env.MATES_PUBLIC_STRIPE_KEY": '"pk_live_..."',
+ *   "import.meta.env.NODE_ENV": '"development"',
+ * }
+ */
+export function getBundlerDefines(mode) {
+    const defines = {};
+    // Always inject NODE_ENV
+    defines["import.meta.env.NODE_ENV"] = JSON.stringify(mode);
+    defines["process.env.NODE_ENV"] = JSON.stringify(mode);
+    // Inject MATES_PUBLIC_ vars
+    for (const [key, value] of Object.entries(getPublicEnv())) {
+        defines[`import.meta.env.${key}`] = JSON.stringify(value);
+    }
+    return defines;
+}
+/**
+ * Parse a .env file string into a key-value map.
+ * Exported for testing.
+ *
+ * Does NOT modify process.env — use loadEnv() for that.
+ */
+export function parseEnvFile(content) {
+    const result = {};
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        // Skip empty lines and comments
+        if (!line || line.startsWith("#"))
+            continue;
+        // Find the first = sign
+        const eqIndex = line.indexOf("=");
+        if (eqIndex === -1) {
+            // No = found — malformed line, skip with warning
+            devWarn(`.env line ${i + 1} has no "=" — skipped: ${line}`);
+            continue;
+        }
+        const key = line.slice(0, eqIndex).trim();
+        let value = line.slice(eqIndex + 1).trim();
+        // Skip empty keys
+        if (!key)
+            continue;
+        // Validate key — must be a valid env var name
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+            devWarn(`.env line ${i + 1} has invalid key "${key}" — skipped`);
+            continue;
+        }
+        // Strip inline comments — only strip if # is preceded by whitespace
+        // e.g. KEY=value # comment → "value"
+        // but KEY=value#nospace stays as "value#nospace"
+        const commentMatch = value.match(/^(.*?)\s+#.*$/);
+        if (commentMatch) {
+            value = commentMatch[1].trim();
+        }
+        // Handle quoted values
+        value = _stripQuotes(value);
+        // Handle escaped characters inside double-quoted strings
+        // \n → newline, \t → tab, \\ → backslash
+        if (_isDoubleQuoted(line.slice(eqIndex + 1).trim())) {
+            value = _unescapeDoubleQuoted(value);
+        }
+        result[key] = value;
+    }
+    return result;
+}
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+/**
+ * Load a single .env file into process.env.
+ * Silently skips if the file does not exist.
+ * Later .env files can override earlier ones, but original platform/CI env vars always win.
+ */
+function _loadEnvFile(filePath, originalKeys) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf-8");
+    }
+    catch (err) {
+        // ENOENT → file doesn't exist, skip silently
+        if (err.code === "ENOENT")
+            return;
+        // Other read errors → warn but don't crash
+        devWarn(`could not read ${filePath}: ${err.message}`);
+        return;
+    }
+    const parsed = parseEnvFile(content);
+    for (const [key, value] of Object.entries(parsed)) {
+        // Original platform/CI env vars always win — never overwrite
+        if (originalKeys?.has(key))
+            continue;
+        // For other keys, later files override earlier ones
+        process.env[key] = value;
+    }
+}
+/**
+ * Strip surrounding single or double quotes from a value string.
+ * Handles:
+ *   "hello world" → hello world
+ *   'hello world' → hello world
+ *   "it's fine"   → it's fine
+ *   unquoted      → unquoted (unchanged)
+ */
+function _stripQuotes(value) {
+    if (value.length < 2)
+        return value;
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+/**
+ * Returns true if the raw value string (before stripping quotes) is double-quoted.
+ * Used to decide whether to unescape \n, \t etc.
+ */
+function _isDoubleQuoted(rawValue) {
+    return (rawValue.length >= 2 && rawValue.startsWith('"') && rawValue.endsWith('"'));
+}
+/**
+ * Process escape sequences inside a double-quoted .env value.
+ * Only handles common cases: \n, \r, \t, \\, \".
+ */
+function _unescapeDoubleQuoted(value) {
+    return value
+        .replace(/\\n/g, "\n")
+        .replace(/\\r/g, "\r")
+        .replace(/\\t/g, "\t")
+        .replace(/\\"/g, '"')
+        .replace(/\\\\/g, "\\");
+}
+//# sourceMappingURL=env-loader.js.map

package/dist/env-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-loader.js","sourceRoot":"","sources":["../src/env-loader.ts"],"names":[],"mappings":"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"}