@cocreate/file-server 1.19.1 → 1.21.0

package/.github/workflows/automated.yml

@@ -1,8 +1,10 @@
 name: Automated Workflow
+
 on:
   push:
     branches:
       - master
+
 jobs:
   about:
     runs-on: ubuntu-latest
@@ -18,52 +20,37 @@ jobs:
         with:
           direction: overwrite-github
           githubToken: "${{ secrets.GITHUB }}"
+
   release:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Required so semantic-release can trace git tags/history
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 22 # Required for the latest semantic-release plugins
-      - name: Semantic Release
-        uses: cycjimmy/semantic-release-action@v4 # Update to v4 for better Node 20+ support
-        id: semantic
-        with:
-          extra_plugins: |
-            @semantic-release/changelog
+          node-version: 22
+
+      - name: Install Semantic Release & Plugins
+        # Installs semantic-release and its plugins on the runner
+        run: |
+          npm install -g semantic-release \
+            @semantic-release/changelog \
+            @semantic-release/npm \
+            @semantic-release/github \
             @semantic-release/git
-            @semantic-release/github
+
+      - name: Run Semantic Release (Native)
+        id: semantic
+        # This will automatically pick up your export default config file in the repository root
+        run: npx semantic-release
         env:
-          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}" # Use the built-in token if possible
+          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
           NPM_TOKEN: "${{ secrets.NPM_TOKEN }}"
+
     outputs:
       new_release_published: "${{ steps.semantic.outputs.new_release_published }}"
-      new_release_version: "${{ steps.semantic.outputs.new_release_version }}"
-  upload:
-    runs-on: ubuntu-latest
-    needs: release
-    if: needs.release.outputs.new_release_published == 'true'
-    env:
-      VERSION: "${{ needs.release.outputs.new_release_version }}"
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: 16
-      - name: Set npm registry auth
-        run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc
-      - name: Install dependencies
-        run: yarn install
-
-      - name: Set Environment Variables
-        run: |
-          echo "organization_id=${{ secrets.COCREATE_ORGANIZATION_ID }}" >> $GITHUB_ENV
-          echo "key=${{ secrets.COCREATE_KEY }}" >> $GITHUB_ENV
-          echo "host=${{ secrets.COCREATE_HOST }}" >> $GITHUB_ENV
-      - name: CoCreate Upload
-        run: coc upload
-
+      new_release_version: "${{ steps.semantic.outputs.new_release_version }}"

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+# [1.21.0](https://github.com/CoCreate-app/CoCreate-file-server/compare/v1.20.0...v1.21.0) (2026-07-17)
+
+
+### Features
+
+* update automated workflow and release configuration for improved semantic release handling ([46e48c9](https://github.com/CoCreate-app/CoCreate-file-server/commit/46e48c906291f7939b69ff4064f4dd5413649d87))
+
+# [1.20.0](https://github.com/CoCreate-app/CoCreate-file-server/compare/v1.19.1...v1.20.0) (2026-07-14)
+
+
+### Bug Fixes
+
+* add redirects for missing and forbidden files to /404.html and /403.html ([906e874](https://github.com/CoCreate-app/CoCreate-file-server/commit/906e874fbf0790f3e08a119b5215f0e6e53c023b))
+* improve HTML request handling and response for 404 and 403 errors ([b78e21d](https://github.com/CoCreate-app/CoCreate-file-server/commit/b78e21de0887f37f3cc0156c339d6203c241a697))
+* removed post install ([95cc099](https://github.com/CoCreate-app/CoCreate-file-server/commit/95cc099f2e6d79755ded981543e7e1ea9b78a08d))
+* semantic version handling. Reorganize .gitignore for improved clarity and structure ([cabc86c](https://github.com/CoCreate-app/CoCreate-file-server/commit/cabc86c16a7a9ad6855e4bd529a4df060a6e11a8))
+* streamline error handling and response for missing files and improve status code management ([3f9b253](https://github.com/CoCreate-app/CoCreate-file-server/commit/3f9b25329e31d9736d635e22b5ff99244f698f53))
+* update module export to ES6 syntax in release.config.js ([ecee757](https://github.com/CoCreate-app/CoCreate-file-server/commit/ecee757539946a0304d6c8551b74969a8cf6c3f3))
+* update package.json and refactor index.js for module compatibility ([b140de1](https://github.com/CoCreate-app/CoCreate-file-server/commit/b140de1b20b727c37333be5cf8d36543c892daca))
+
+
+### Features
+
+* enforce trailing slash for directory paths in URL handling ([aab2d0e](https://github.com/CoCreate-app/CoCreate-file-server/commit/aab2d0eaf095efe302680f1ba5a5a4eeba1b0649))
+* update package.json and refactor index.js to use ES modules ([fd121ff](https://github.com/CoCreate-app/CoCreate-file-server/commit/fd121ffa438d174e3a11b2bec8d001718c193e08))
+
 ## [1.19.1](https://github.com/CoCreate-app/CoCreate-file-server/compare/v1.19.0...v1.19.1) (2026-04-15)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cocreate/file-server",
-  "version": "1.19.1",
+  "version": "1.21.0",
   "description": "A simple file-server component in vanilla javascript. Easily configured using HTML5 data-attributes and/or JavaScript API.",
   "keywords": [
     "file-server",
@@ -18,8 +18,7 @@
   "scripts": {
     "start": "npx webpack --config webpack.config.js",
     "build": "npx webpack --mode=production --config webpack.config.js",
-    "dev": "npx webpack --config webpack.config.js --watch",
-    "postinstall": "node -e \"const { execSync } = require('child_process'); try { execSync('coc --version', { stdio: 'ignore' }); } catch (error) { try { execSync('npm install -g @cocreate/cli', { stdio: 'inherit' }); console.log('Installed \"@cocreate/cli\" globally.'); } catch (error) { console.error('Failed to install \"@cocreate/cli\" globally:', error); } }\""
+    "dev": "npx webpack --config webpack.config.js --watch"
   },
   "repository": {
     "type": "git",
@@ -35,5 +34,10 @@
     "type": "GitHub Sponsors ❤",
     "url": "https://github.com/sponsors/CoCreate-app"
   },
-  "main": "./src/index.js"
+  "type": "module",
+  "main": "./src/index.js",
+  "dependencies": {
+    "@cocreate/server-side-render": "^1.12.8",
+    "@cocreate/sitemap": "^1.4.2"
+  }
 }

package/release.config.js

@@ -1,4 +1,4 @@
-module.exports = {
+export default {
   dryRun: false,
   branches: ["master"],
   plugins: [
@@ -10,12 +10,20 @@ module.exports = {
         changelogFile: "CHANGELOG.md",
       },
     ],
-    "@semantic-release/npm",
-    "@semantic-release/github",
+    "@semantic-release/npm", 
     [
-      "@semantic-release/git",
+      "@semantic-release/github", 
       {
+        successComment: false,
+        failTitle: false,
+      },
+    ],
+    [
+      "@semantic-release/git", 
+      {
+        // Only stage and commit the changelog and package.json
         assets: ["CHANGELOG.md", "package.json"],
+        message: "chore(release): ${nextRelease.version} [skip ci]",
       },
     ],
   ],

package/src/index.js

@@ -2,7 +2,7 @@
  * Copyright (C) 2023 CoCreate and Contributors.
  *
  * This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as published
+ * Wu under the terms of the GNU Affero General Public License as published
  * by the Free Software Foundation, either version 3 of the License, or
  * (at your option) any later version.
  *
@@ -13,6 +13,7 @@
  *
  * You should have received a copy of the GNU Affero General Public License
  * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
  ********************************************************************************/
 
 // Commercial Licensing Information:
@@ -20,467 +21,593 @@
 // you must obtain a commercial license from CoCreate LLC.
 // For details, visit <https://cocreate.app/licenses/> or contact us at sales@cocreate.app.
 
-class CoCreateFileSystem {
-    constructor(render, sitemap) {
-        this.render = render;
-        this.sitemap = sitemap;
-    }
+import * as render from '@cocreate/server-side-render';
+import * as sitemap from '@cocreate/sitemap';
 
-    async send(req, res, crud, organization, urlObject) {
-        try {
-            const hostname = urlObject.hostname;
-
-            // --- determine preferred color scheme from browser headers ---
-            let theme;
-            const headerValue =
-                (req && req.headers && (
-                    req.headers["sec-ch-prefers-color-scheme"] ||
-                    req.headers["prefers-color-scheme"] ||
-                    req.headers["x-prefers-color-scheme"] ||
-                    req.headers["x-color-scheme"]
-                ));
-            if (typeof headerValue === "string") {
-                // take first token, strip quotes, normalize
-                const token = headerValue.split(",")[0].trim().replace(/^"|"$/g, "").toLowerCase();
-                if (token === "dark" || token === "light") theme = token;
-            }
-            // optional: expose detected theme to clients / downstream code
-            if (theme) res.setHeader("X-Preferred-Color-Scheme", theme);
-            // --- end theme detection ---
+// Module-level reference injected on-demand during boot to prevent ESM circular loops
+let server = null;
 
-            let data = {
-                method: "object.read",
-                host: hostname,
-                array: "files",
-                $filter: {
-                    query: {
-                        host: { $in: [hostname, "*"] }
-                    },
-                    limit: 1
-                }
-            };
-
-            let organization_id;
-            if (!organization || organization.error) {
-                let hostNotFound = await getDefaultFile("/hostNotFound.html");
-                return sendResponse(hostNotFound.object[0].src, 404, {
-                    "Content-Type": "text/html"
-                });
+/**
+ * Initializes the File Server module by injecting the parent orchestrator context.
+ * Bypasses ESM static compile cycles entirely.
+ * @param {Object} Server - CoCreateServer context instance.
+ */
+export function init(Server) {    
+    server = Server;   
+    return FileServer 
+}
+
+/**
+ * Main stateless entry point for the CoCreate File System request handler.
+ * Now cleanly self-contained, handling its own urlObject parsing and organization lookups.
+ * @param {Object} req - Native Node HTTP request object
+ * @param {Object} res - Native Node HTTP response object
+ */
+export async function send(req, res) {
+    try {
+        const activeCrud = server ? server.crud : null;
+        
+        // Parse the URL structure internally from the incoming request
+        const urlObject = new URL(`http://${req.headers.host || 'localhost'}${req.url}`);
+        const hostname = urlObject.hostname;
+        let pathname = urlObject.pathname;
+
+        // Resolve Organization dynamically from the injected CRUD instance
+        let organization = null;
+        if (activeCrud) {
+            try {
+                organization = await activeCrud.getOrganization({ host: hostname });
+            } catch (err) {
+                console.error("[@cocreate/file-server] Failed to resolve organization details internally:", err);
             }
+        }
+
+        // 1. Check Organization active status
+        if (!organization || organization.error) {
+            const hostNotFound = await getDefaultFile({ fileName: "/hostNotFound.html", hostname, organizationId: null, crud: activeCrud });
+            sendResponse({
+                res,
+                src: hostNotFound.object[0].src,
+                statusCode: 404,
+                headers: { "Content-Type": hostNotFound.object[0]["content-type"] || "text/html" },
+                file: hostNotFound.object[0],
+                organizationId: null,
+                crud: activeCrud
+            });
+            return;
+        }
 
-            organization_id = organization._id;
-            data.organization_id = organization_id;
-
-            res.setHeader("organization", organization_id);
-            res.setHeader("storage", !!organization.storage);
-            res.setHeader("Access-Control-Allow-Origin", "*");
-            res.setHeader("Access-Control-Allow-Methods", "");
-            res.setHeader(
-                "Access-Control-Allow-Headers",
-                "Content-Type, Authorization"
-            );
-
-            let active = crud.wsManager.organizations.get(organization_id);
-            if (active === false) {
-                let balanceFalse = await getDefaultFile("/balanceFalse.html");
-                return sendResponse(balanceFalse.object[0].src, 403, {
-                    "Content-Type": "text/html",
+        const organizationId = organization._id;
+        res.setHeader("organization", organizationId);
+        res.setHeader("storage", !!organization.storage);
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Access-Control-Allow-Methods", "");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+
+        const wsManager = server ? server.wsManager : null;
+        const active = wsManager ? wsManager.organizations.get(organizationId) : true;
+        if (active === false) {
+            const balanceFalse = await getDefaultFile({ fileName: "/balanceFalse.html", hostname, organizationId, crud: activeCrud });
+            sendResponse({
+                res,
+                src: balanceFalse.object[0].src,
+                statusCode: 403,
+                headers: {
+                    "Content-Type": balanceFalse.object[0]["content-type"] || "text/html",
                     "Account-Balance": "false",
                     storage: organization.storage
-                });
-            }
+                },
+                file: balanceFalse.object[0],
+                organizationId,
+                crud: activeCrud
+            });
+            return;
+        }
+
+        // 2. Trailing Slash Redirect
+        if (handleTrailingSlash(pathname, urlObject, res)) {
+            return; // Redirect occurred, execution halted
+        }
 
-            let parameters = urlObject.searchParams;
-            if (parameters.size) {
-                console.log("parameters", parameters);
+        // 3. Theme Detection
+        const theme = detectTheme(req, res);
+
+        // 4. Resolve exact file resource and status code
+        const { file, src, statusCode, resolvedPathname } = await resolveFile({
+            pathname,
+            hostname,
+            organizationId,
+            crud: activeCrud
+        });
+
+        // 5. Language Localization Matching
+        const { lang, langRegion } = parseLanguage(resolvedPathname, req?.headers);
+
+        let contentType = file?.["content-type"] || "text/html";
+
+        // 6. Output Normalization and Rendering
+        const finalSrc = await normalizeSrc({
+            src,
+            contentType,
+            pathname: resolvedPathname,
+            file,
+            organization,
+            urlObject,
+            langRegion,
+            lang,
+            theme,
+            crud: activeCrud
+        });
+
+        let modifiedOn = file?.modified || file?.created;
+        if (modifiedOn) {
+            modifiedOn = modifiedOn.on;
+            if (modifiedOn instanceof Date) {
+                modifiedOn = modifiedOn.toISOString();
             }
+            res.setHeader("Last-Modified", modifiedOn);
+        }
 
-            let pathname = urlObject.pathname;
+        // 7. Send final response
+        sendResponse({
+            res,
+            src: finalSrc,
+            statusCode,
+            headers: { "Content-Type": contentType },
+            file,
+            organizationId: organizationId,
+            crud: activeCrud,
+            organizationCacheControl: organization["cache-control"]
+        });
+
+        // 8. Async Sitemap Check
+        if (file) {
+            await sitemap.check({ file, host: hostname, crud: activeCrud });
+        }
 
-            if (pathname.endsWith("/")) {
-                pathname += "index.html";
-            } else if (!pathname.startsWith("/.well-known/acme-challenge")) {
-                let directory = pathname.split("/").slice(-1)[0];
-                if (!directory.includes(".")) pathname += "/index.html";
-            }
+    } catch (error) {
+        console.error("Critical error in FileSystem handler:", error);
+        res.writeHead(400, { "Content-Type": "text/plain" });
+        res.end("Invalid host format");
+    }
+}
 
-            // Match both /en/ and /en-US/ style URLs
-            const bcp47Regex = /^\/([a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})?)\//;
-            const langMatch = pathname.match(bcp47Regex);
-            let lang, langRegion;
-            if (langMatch) {
-                langRegion = langMatch[1];
-                lang = langRegion.split("-")[0]; // Get just the base language (e.g., 'en', 'es', 'fr')
-                let basePathname = pathname.replace("/" + langRegion, "");
-                data.$filter.query.pathname = basePathname;
-            } else {
-                // No language in URL, try Accept-Language header
-                let acceptLang = req.headers && req.headers["accept-language"];
-                if (acceptLang) {
-                    // Parse the Accept-Language header, get the first language
-                    let preferred = acceptLang.split(",")[0].trim();
-                    if (preferred) {
-                        lang = preferred.split("-")[0];
-                        langRegion = preferred;
-                        // --- BEGIN OPTIONAL REDIRECT ---
-                        // Uncomment to enable automatic redirect to language-specific path
-                        // let newPath = `/${preferred}${pathname.startsWith('/') ? '' : '/'}${pathname.replace(/^\//, '')}`;
-                        // res.writeHead(302, { Location: newPath });
-                        // return res.end();
-                        // --- END OPTIONAL REDIRECT ---
-                    }
-                }
-                data.$filter.query.pathname = pathname;
-            }
+// ==========================================
+// Isolated Helper Functions
+// ==========================================
+
+/**
+ * Normalizes slash-ending paths, resolves files via wildcard mappings,
+ * handles 404/403 fallbacks, and fetches asset sources.
+ */
+export async function resolveFile({ pathname, hostname, organizationId, crud }) {
+    const activeCrud = crud || (server ? server.crud : null);
+    let statusCode = 200;
+    let file;
+
+    if (pathname.endsWith("/")) {
+        pathname += "index.html";
+    }
 
-            let file;
-            if (
-                pathname.startsWith("/dist") ||
-                pathname.startsWith("/admin") ||
-                [
-                    "/403.html",
-                    "/404.html",
-                    "/offline.html",
-                    "/manifest.webmanifest",
-                    "/service-worker.js"
-                ].includes(pathname)
-            ) {
-                file = await getDefaultFile(pathname);
-            } else {
-                file = await crud.send(data);
-            }
+    const queryData = {
+        method: "object.read",
+        host: hostname,
+        array: "files",
+        organization_id: organizationId,
+        $filter: {
+            query: {
+                host: { $in: [hostname, "*"] },
+                pathname
+            },
+            limit: 1
+        }
+    };
+
+    // 1. Fetch File
+    if (
+        pathname.startsWith("/dist") ||
+        pathname.startsWith("/admin") ||
+        [
+            "/403.html",
+            "/404.html",
+            "/offline.html",
+            "/manifest.webmanifest",
+            "/service-worker.js"
+        ].includes(pathname)
+    ) {
+        const defaultResult = await getDefaultFile({ fileName: pathname, hostname, organizationId, crud: activeCrud });
+        file = defaultResult?.object?.[0];
+    } else {
+        const result = await activeCrud.send(queryData);
+        file = result?.object?.[0];
+    }
 
-            // --- Wildcard fallback ---
-            if (!file || !file.object || !file.object[0]) {
-                pathname = urlObject.pathname;
-                let lastIndex = pathname.lastIndexOf("/");
-                let wildcardPath = pathname.substring(0, lastIndex + 1);
-                let wildcard = pathname.substring(lastIndex + 1);
-
-                if (wildcard.includes(".")) {
-                    let fileLastIndex = wildcard.lastIndexOf(".");
-                    let fileExtension = wildcard.substring(fileLastIndex);
-                    wildcard = wildcardPath + "*" + fileExtension; // Create wildcard for file name
-                } else {
-                    wildcard = wildcardPath + "*/index.html"; // Append '*' if it's just a path or folder
-                }
+    // 2. Wildcard fallback
+    if (!file) {
+        const wildcardPath = getWildcardPath(pathname);
+        queryData.$filter.query.pathname = wildcardPath;
+        const result = await activeCrud.send(queryData);
+        file = result?.object?.[0];
+    }
 
-                data.$filter.query.pathname = wildcard;
-                file = await crud.send(data);
-            }
+    // 3. Fallback to 404 if file completely missing
+    if (!file) {
+        statusCode = 404;
+        const pageNotFound = await getDefaultFile({ fileName: "/404.html", hostname, organizationId, crud: activeCrud });
+        file = pageNotFound?.object?.[0];
+    }
 
-            if (!file || !file.object || !file.object[0]) {
-                let pageNotFound = await getDefaultFile("/404.html");
-                return sendResponse(pageNotFound.object[0].src, 404, {
-                    "Content-Type": "text/html"
-                });
-            }
+    // 4. Fallback to 403 if not public
+    if (file && (!file["public"] || file["public"] === "false")) {
+        statusCode = 403;
+        const pageForbidden = await getDefaultFile({ fileName: "/403.html", hostname, organizationId, crud: activeCrud });
+        file = pageForbidden?.object?.[0];
+    }
 
-            file = file.object[0];
-            if (!file["public"] || file["public"] === "false") {
-                let pageForbidden = await getDefaultFile("/403.html");
-                return sendResponse(pageForbidden.object[0].src, 403, {
-                    "Content-Type": "text/html"
-                });
-            }
+    // 5. Fetch file source markup
+    let src = file?.src || "";
+    if (file && !file["src"]) {
+        try {
+            const fileSrc = await activeCrud.send({
+                method: "object.read",
+                host: hostname,
+                array: file["array"],
+                object: { _id: file._id },
+                organization_id: organizationId
+            });
+            src = fileSrc?.[file["name"]] || "";
+        } catch (err) {
+            console.error("Error fetching file src:", err);
+        }
+    }
 
-            let src;
-            if (file["src"]) {
-                src = file["src"];
-            } else {
-                let fileSrc = await crud.send({
-                    method: "object.read",
-                    host: hostname,
-                    array: file["array"],
-                    object: {
-                        _id: file._id
-                    },
-                    organization_id
-                });
-                src = fileSrc[file["name"]];
-            }
+    // 6. Ultimate 404 payload fallback if source resolves empty
+    if (!src && file) {
+        statusCode = 404;
+        const pageNotFound = await getDefaultFile({ fileName: "/404.html", hostname, organizationId, crud: activeCrud });
+        file = pageNotFound?.object?.[0];
+        src = file?.src || "";
+    }
 
-            if (!src) {
-                let pageNotFound = await getDefaultFile("/404.html");
-                return sendResponse(pageNotFound.object[0].src, 404, {
-                    "Content-Type": "text/html"
-                });
-            }
+    // Bind source markup and calculated status directly onto the file document for downstream consumers (like the SSR engine)
+    if (file) {
+        file.src = src;
+        file.status = statusCode;
+    }
 
-            let modifiedOn = file.modified || file.created;
-            if (modifiedOn) {
-                modifiedOn = modifiedOn.on;
-                if (modifiedOn instanceof Date)
-                    modifiedOn = modifiedOn.toISOString();
-                res.setHeader("Last-Modified", modifiedOn);
-            }
+    return { file, src, statusCode, resolvedPathname: pathname };
+}
 
-            let contentType = file["content-type"] || "text/html";
-
-            // Normalize and decode src based on content-type and pathname.
-            async function normalizeSrc(src, contentType, pathname) {
-                const isBase64Only = (s) =>
-                    typeof s === "string" && /^[A-Za-z0-9+/]+={0,2}$/.test(s) && s.length % 4 === 0;
-
-                const parseDataUri = (s) => {
-                    // returns { mime, isBase64, data } or null
-                    const m = /^data:([^;]+)(;base64)?,(.*)$/is.exec(s);
-                    if (!m) return null;
-                    return { mime: m[1].toLowerCase(), isBase64: !!m[2], data: m[3] };
-                };
-
-                // Fonts: data:font/...;base64 or plain base64 -> Buffer
-                if (contentType.startsWith("font/") || /\.(woff2?|ttf|otf)$/i.test(pathname)) {
-                    if (Buffer.isBuffer(src)) return src;
-                    if (typeof src !== "string") throw new Error("Invalid font src");
-                    const d = parseDataUri(src);
-                    if (d && d.isBase64) return Buffer.from(d.data, "base64");
-                    // maybe stored as bare base64
-                    if (isBase64Only(src)) return Buffer.from(src, "base64");
-                    throw new Error("Font data is not valid base64 or data URI");
-                }
+/**
+ * Specifically resolves, tracks, and mirrors system fallbacks from global scopes.
+ */
+export async function getDefaultFile({ fileName, hostname, organizationId, crud }) {
+    const activeCrud = crud || (server ? server.crud : null);
+    const queryData = {
+        method: "object.read",
+        host: hostname,
+        array: "files",
+        organization_id: organizationId,
+        $filter: {
+            query: {
+                host: { $in: [hostname, "*"] },
+                pathname: fileName
+            },
+            limit: 1
+        }
+    };
 
-                // Data URIs
-                if (typeof src === "string") {
-                    const d = parseDataUri(src);
-                    if (d) {
-                        // SVG: decode to utf8 string so browsers render SVG correctly
-                        if (d.mime === "image/svg+xml") {
-                            if (d.isBase64) return Buffer.from(d.data, "base64").toString("utf8");
-                            // URI-encoded SVG payload
-                            try {
-                                return decodeURIComponent(d.data);
-                            } catch (_) {
-                                return d.data;
-                            }
-                        }
-                        // Raster images, Icons, Video, and Audio -> Buffer
-                        // Added x-icon, vnd.microsoft.icon, and ico to process icon files properly
-                        if (/^(image\/(png|jpe?g|webp|bmp|gif|x-icon|vnd\.microsoft\.icon|ico)|video\/.*|audio\/.*)$/i.test(d.mime)) {
-                            if (d.isBase64) return Buffer.from(d.data, "base64");
-                        }
-                        // If it's a text data URI (e.g., xml) and not base64, return decoded text
-                        if (!d.isBase64) {
-                            try {
-                                return decodeURIComponent(d.data);
-                            } catch (_) {
-                                return d.data;
-                            }
-                        }
-                    }
-                }
+    let defaultFile;
+    if (fileName !== "/hostNotFound.html" && organizationId) {
+        defaultFile = await activeCrud.send(queryData);
+    }
 
-                // Plain base64-only string: decode to Buffer only for binary content types
-                if (isBase64Only(src)) {
-                    if (
-                        contentType.startsWith("image/") ||
-                        contentType.startsWith("font/") ||
-                        contentType.startsWith("video/") ||
-                        contentType.startsWith("audio/") ||
-                        contentType === "application/octet-stream"
-                    ) {
-                        return Buffer.from(src, "base64");
-                    }
-                    // textual content kept as-is
-                    return src;
-                }
+    if (defaultFile?.object?.[0]?.src) {
+        return defaultFile;
+    }
 
-                // HTML rendering
-                if (contentType === "text/html") {
-                    return await this.render.HTML(
-                        file,
-                        organization,
-                        urlObject,
-                        langRegion,
-                        lang,
-                        theme
-                    );
-                }
+    // Search global scope platform database
+    queryData.$filter.query.host.$in = ["*"];
+    queryData.organization_id = process.env.organization_id;
 
-                // XML host replacement if src is string
-                if ((contentType === "text/xml" || contentType === "application/xml") && typeof src === "string") {
-                    const protocol = "https://";
-                    return src.replaceAll("{{$host}}", `${protocol}${hostname}`);
-                }
+    if (fileName.startsWith("/admin")) {
+        queryData.$filter.query.pathname = "/superadmin" + fileName.replace("/admin", "");
+    }
 
-                // Otherwise return as-is (string, Buffer, object)
-                return src;
-            }
+    defaultFile = await activeCrud.send(queryData);
+
+    const wsManager = server ? server.wsManager : null;
+    if (fileName !== "/hostNotFound.html" && organizationId && wsManager) {
+        wsManager.emit("setBandwidth", {
+            type: "out",
+            data: queryData,
+            organization_id: organizationId
+        });
+
+        wsManager.emit("setBandwidth", {
+            type: "in",
+            data: defaultFile,
+            organization_id: organizationId
+        });
+    }
 
-            try {
-                src = await normalizeSrc.call(this, src, contentType, pathname);
-            } catch (err) {
-                console.error("Error processing file src:", err && err.message);
-                let pageNotFound = await getDefaultFile("/404.html");
-                return sendResponse(pageNotFound.object[0].src, 404, {
-                    "Content-Type": "text/html"
-                });
-            }
-            
-            sendResponse(src, 200, { "Content-Type": contentType });
-            this.sitemap.check(file, hostname);
+    if (defaultFile?.object?.[0]?.src) {
+        if (fileName.startsWith("/admin")) {
+            defaultFile.object[0].directory = "admin";
+            defaultFile.object[0].path = "/admin" + defaultFile.object[0].path.replace("/superadmin", "");
+            defaultFile.object[0].pathname = fileName;
+        }
+
+        if (organizationId) {
+            // Save local cloned copy inside this organization's database
+            await activeCrud.send({
+                method: "object.create",
+                host: hostname,
+                array: "files",
+                object: defaultFile.object[0],
+                organization_id: organizationId
+            });
+        }
+
+        return defaultFile;
+    }
+
+    // Hard fallback definitions in case DB collections are empty
+    const structuralFallback = { object: [{ src: "" }] };
+    switch (fileName) {
+        case "/403.html":
+            structuralFallback.object[0].src = `Access not allowed for ${organizationId}`;
+            break;
+        case "/404.html":
+            structuralFallback.object[0].src = `File could not be found for ${organizationId}`;
+            break;
+        case "/balanceFalse.html":
+            structuralFallback.object[0].src = "This organization's account balance has fallen below 0: ";
+            break;
+        case "/hostNotFound.html":
+            structuralFallback.object[0].src = `An organization could not be found using the host: ${hostname} in platformDB: ${process.env.organization_id}`;
+            break;
+    }
+    return structuralFallback;
+}
+
+/**
+ * Calculates a directory wildcard path pattern representation.
+ */
+export function getWildcardPath(pathname) {
+    const lastIndex = pathname.lastIndexOf("/");
+    const wildcardPath = pathname.substring(0, lastIndex + 1);
+    const wildcardName = pathname.substring(lastIndex + 1);
+
+    if (wildcardName.includes(".")) {
+        const fileLastIndex = wildcardName.lastIndexOf(".");
+        const fileExtension = wildcardName.substring(fileLastIndex);
+        return wildcardPath + "*" + fileExtension;
+    } else {
+        return wildcardPath + "*/index.html";
+    }
+}
+
+/**
+ * Detects color scheme from HTTP headers and updates client indicators.
+ */
+export function detectTheme(req, res) {
+    let theme;
+    const headerValue = req?.headers && (
+        req.headers["sec-ch-prefers-color-scheme"] ||
+        req.headers["prefers-color-scheme"] ||
+        req.headers["x-prefers-color-scheme"] ||
+        req.headers["x-color-scheme"]
+    );
+    if (typeof headerValue === "string") {
+        const token = headerValue.split(",")[0].trim().replace(/^"|"$/g, "").toLowerCase();
+        if (token === "dark" || token === "light") {
+            theme = token;
+        }
+    }
+    if (theme && res) {
+        res.setHeader("X-Preferred-Color-Scheme", theme);
+    }
+    return theme;
+}
+
+/**
+ * Standardizes directory matching redirection configurations.
+ */
+export function handleTrailingSlash(pathname, urlObject, res) {
+    if (!pathname.endsWith("/") && !pathname.startsWith("/.well-known/acme-challenge")) {
+        const lastSegment = pathname.split("/").slice(-1)[0];
+        if (!lastSegment.includes(".")) {
+            const search = urlObject.search || "";
+            res.writeHead(301, { Location: pathname + "/" + search });
+            res.end();
+            return true;
+        }
+    }
+    return false;
+}
 
-            function sendResponse(src, statusCode, headers) {
+/**
+ * Extracts explicit or implicit preferred localization tokens from endpoints.
+ */
+export function parseLanguage(pathname, headers) {
+    const bcp47Regex = /^\/([a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})?)\//;
+    const langMatch = pathname.match(bcp47Regex);
+    let lang, langRegion;
+
+    if (langMatch) {
+        langRegion = langMatch[1];
+        lang = langRegion.split("-")[0];
+        const basePathname = pathname.replace("/" + langRegion, "");
+        return { lang, langRegion, basePathname };
+    }
+
+    const acceptLang = headers?.["accept-language"];
+    if (acceptLang) {
+        const preferred = acceptLang.split(",")[0].trim();
+        if (preferred) {
+            lang = preferred.split("-")[0];
+            langRegion = preferred;
+        }
+    }
+    return { lang, langRegion, basePathname: pathname };
+}
+
+/**
+ * Formats, cleans, parses, and executes rendering transformations based on content types.
+ */
+export async function normalizeSrc({ src, contentType, pathname, file, organization, urlObject, langRegion, lang, theme, crud }) {
+    const activeCrud = crud || (server ? server.crud : null);
+    const isBase64Only = (s) =>
+        typeof s === "string" && /^[A-Za-z0-9+/]+={0,2}$/.test(s) && s.length % 4 === 0;
+
+    const parseDataUri = (s) => {
+        const m = /^data:([^;]+)(;base64)?,(.*)$/is.exec(s);
+        if (!m) return null;
+        return { mime: m[1].toLowerCase(), isBase64: !!m[2], data: m[3] };
+    };
+
+    // Fonts
+    if (contentType.startsWith("font/") || /\.(woff2?|ttf|otf)$/i.test(pathname)) {
+        if (Buffer.isBuffer(src)) return src;
+        if (typeof src !== "string") throw new Error("Invalid font src");
+        const d = parseDataUri(src);
+        if (d?.isBase64) return Buffer.from(d.data, "base64");
+        if (isBase64Only(src)) return Buffer.from(src, "base64");
+        throw new Error("Font data is not valid base64 or data URI");
+    }
+
+    // Data URIs
+    if (typeof src === "string") {
+        const d = parseDataUri(src);
+        if (d) {
+            if (d.mime === "image/svg+xml") {
+                if (d.isBase64) return Buffer.from(d.data, "base64").toString("utf8");
                 try {
-                    let cacheControl;
-                    if (statusCode >= 400) {
-                        cacheControl = "no-cache, no-store, must-revalidate";
-                    } else if (
-                        file &&
-                        file["cache-control"] !== undefined &&
-                        file["cache-control"] !== null
-                    ) {
-                        const val = file["cache-control"];
-                        if (typeof val === "number" || /^\s*\d+\s*$/.test(val)) {
-                            // If it's numeric (number or numeric string) treat it as max-age.
-                            cacheControl = `public, max-age=${String(
-                                val
-                            ).trim()};`;
-                        } else {
-                            // use the value verbatim (allow full Cache-Control strings like "no-cache" or "public, max-age=600")
-                            cacheControl = val;
-                        }
-                    } else {
-                        cacheControl = organization["cache-control"] || "public, max-age=3600";
-                    }
-
-                    // Always override/set Cache-Control header so the response aligns with the file metadata/defaults
-                    headers["Cache-Control"] = cacheControl;
-                    // Advertise that we accept the Sec-CH-Prefers-Color-Scheme client hint.
-                    // After the browser sees this in a response it may include
-                    // the Sec-CH-Prefers-Color-Scheme header on subsequent requests.
-                    headers["Accept-CH"] = "Sec-CH-Prefers-Color-Scheme";
-                    // optional: tell browser how long to remember this preference (seconds)
-                    headers["Accept-CH-Lifetime"] = "86400";
-                    // ensure caches/proxies vary responses by this hint
-                    headers["Vary"] = headers["Vary"]
-                        ? headers["Vary"] + ", Sec-CH-Prefers-Color-Scheme"
-                        : "Sec-CH-Prefers-Color-Scheme";
-
-                    if (src instanceof Uint8Array || Buffer.isBuffer(src)) {
-                        // Ensure binary data is sent as-is
-                    } else if (typeof src === "object") {
-                        src = JSON.stringify(src);
-                    }
-
-                    if (organization_id)
-                        crud.wsManager.emit("setBandwidth", {
-                            type: "out",
-                            data: src,
-                            organization_id
-                        });
-                    res.writeHead(statusCode, headers);
-                    return res.end(src);
-                } catch (error) {
-                    console.log(error);
+                    return decodeURIComponent(d.data);
+                } catch (_) {
+                    return d.data;
                 }
             }
-
-            async function getDefaultFile(fileName) {
-                data.$filter.query.pathname = fileName;
-                // data.$filter.query.$or[0] = { pathname: fileName }
-                let defaultFile;
-                if (fileName !== "/hostNotFound.html")
-                    defaultFile = await crud.send(data);
-
-                if (
-                    defaultFile &&
-                    defaultFile.object &&
-                    defaultFile.object[0] &&
-                    defaultFile.object[0].src
-                ) {
-                    return defaultFile;
-                } else {
-                    data.$filter.query.host.$in = ["*"];
-                    data.organization_id = process.env.organization_id;
-
-                    if (fileName.startsWith("/admin"))
-                        data.$filter.query.pathname =
-                            "/superadmin" + fileName.replace("/admin", "");
-
-                    defaultFile = await crud.send(data);
-
-                    if (fileName !== "/hostNotFound.html") {
-                        crud.wsManager.emit("setBandwidth", {
-                            type: "out",
-                            data,
-                            organization_id
-                        });
-
-                        crud.wsManager.emit("setBandwidth", {
-                            type: "in",
-                            data: defaultFile,
-                            organization_id
-                        });
-                    }
-
-                    if (
-                        defaultFile &&
-                        defaultFile.object &&
-                        defaultFile.object[0] &&
-                        defaultFile.object[0].src
-                    ) {
-                        if (fileName.startsWith("/admin")) {
-                            data.object[0].directory = "admin";
-                            data.object[0].path =
-                                "/admin" +
-                                data.object[0].path.replace("/superadmin", "");
-                            data.object[0].pathname = fileName;
-                        }
-
-                        crud.send({
-                            method: "object.create",
-                            host: hostname,
-                            array: "files",
-                            object: defaultFile.object[0],
-                            organization_id
-                        });
-
-                        return defaultFile;
-                    } else {
-                        switch (fileName) {
-                            case "/403.html":
-                                defaultFile.object = [
-                                    {
-                                        src: `${pathname} access not allowed for ${organization_id}`
-                                    }
-                                ];
-                                break;
-                            case "/404.html":
-                                defaultFile.object = [
-                                    {
-                                        src: `${pathname} could not be found for ${organization_id}`
-                                    }
-                                ];
-                                break;
-                            case "/balanceFalse.html":
-                                defaultFile.object = [
-                                    {
-                                        src: "This organizations account balance has fallen bellow 0: "
-                                    }
-                                ];
-                                break;
-                            case "/hostNotFound.html":
-                                defaultFile.object = [
-                                    {
-                                        src:
-                                            "An organization could not be found using the host: " +
-                                            hostname +
-                                            " in platformDB: " +
-                                            process.env.organization_id
-                                    }
-                                ];
-                                break;
-                        }
-                        return defaultFile;
-                    }
+            if (/^(image\/(png|jpe?g|webp|bmp|gif|x-icon|vnd\.microsoft\.icon|ico)|video\/.*|audio\/.*)$/i.test(d.mime)) {
+                if (d.isBase64) return Buffer.from(d.data, "base64");
+            }
+            if (!d.isBase64) {
+                try {
+                    return decodeURIComponent(d.data);
+                } catch (_) {
+                    return d.data;
                 }
             }
-        } catch (error) {
-            res.writeHead(400, { "Content-Type": "text/plain" });
-            res.end("Invalid host format");
         }
     }
+
+    // Plain base64-only string
+    if (isBase64Only(src)) {
+        if (
+            contentType.startsWith("image/") ||
+            contentType.startsWith("font/") ||
+            contentType.startsWith("video/") ||
+            contentType.startsWith("audio/") ||
+            contentType === "application/octet-stream"
+        ) {
+            return Buffer.from(src, "base64");
+        }
+        return src;
+    }
+
+    // HTML rendering
+    if (contentType === "text/html") {
+        // Adapter Closure to independently fetch isolated templates/chunks for SSR
+        const recursiveResolve = async (nestedPathname) => {
+            const resolved = await resolveFile({
+                pathname: nestedPathname,
+                hostname: urlObject.hostname,
+                organizationId: organization._id,
+                crud: activeCrud
+            });
+            return resolved?.file || null;
+        };
+
+        return await render.HTML({
+            file,
+            organization,
+            urlObject,
+            langRegion,
+            lang,
+            theme,
+            resolveFile: recursiveResolve,
+            crud: activeCrud
+        });
+    }
+
+    // XML host replacement
+    if ((contentType === "text/xml" || contentType === "application/xml") && typeof src === "string") {
+        const protocol = "https://";
+        return src.replaceAll("{{$host}}", `${protocol}${urlObject.hostname}`);
+    }
+
+    return src;
 }
 
-module.exports = CoCreateFileSystem;
+/**
+ * Handles setting response headers, caching guidelines, bandwidth tracking, and returning binary strings.
+ */
+export async function sendResponse({ res, src, statusCode, headers, file, organizationId, crud, organizationCacheControl }) {
+    try {
+        const activeCrud = crud || (server ? server.crud : null);
+        let cacheControl;
+        if (statusCode >= 400) {
+            cacheControl = "no-cache, no-store, must-revalidate";
+        } else if (file && file["cache-control"] !== undefined && file["cache-control"] !== null) {
+            const val = file["cache-control"];
+            if (typeof val === "number" || /^\s*\d+\s*$/.test(val)) {
+                cacheControl = `public, max-age=${String(val).trim()};`;
+            } else {
+                cacheControl = val;
+            }
+        } else {
+            cacheControl = organizationCacheControl || "public, max-age=3600";
+        }
+
+        headers["Cache-Control"] = cacheControl;
+        headers["Accept-CH"] = "Sec-CH-Prefers-Color-Scheme";
+        headers["Accept-CH-Lifetime"] = "86400";
+        headers["Vary"] = headers["Vary"]
+            ? headers["Vary"] + ", Sec-CH-Prefers-Color-Scheme"
+            : "Sec-CH-Prefers-Color-Scheme";
+
+        if (src instanceof Uint8Array || Buffer.isBuffer(src)) {
+            // Binary formats passed directly
+        } else if (typeof src === "object") {
+            src = JSON.stringify(src);
+        }
+
+        const wsManager = server ? server.wsManager : null;
+        if (organizationId && activeCrud && wsManager) {
+            wsManager.emit("setBandwidth", {
+                type: "out",
+                data: src,
+                organization_id: organizationId
+            });
+        }
+        res.writeHead(statusCode, headers);
+        res.end(src);
+    } catch (error) {
+        console.error("Error finalizing response payload:", error);
+    }
+}
+ const FileServer = {
+    init,
+    send,
+    resolveFile,
+    getDefaultFile,
+    getWildcardPath,
+    detectTheme,
+    handleTrailingSlash,
+    parseLanguage,
+    normalizeSrc,
+    sendResponse
+}
+// Default export added to enforce standard import convention across the platform
+export default FileServer;