@madhanmaaz/udane 0.0.0-stage → 0.1.0

package/app.js

@@ -0,0 +1,95 @@
+const path = require("node:path");
+const http = require("node:http");
+
+const fastify = require("fastify");
+const tarkine = require("tarkine");
+
+const {
+    listDirectory,
+    resolveDirectory,
+} = require("./helpers/directory.helper");
+const templateEngine = require("./helpers/templateEngine.helper");
+const { PUBLIC_DIR_PREFIX } = require("./constants/index.constant");
+
+const noStore = {
+    cacheControl: false,
+    setHeaders(reply) {
+        reply.header("cache-control", "no-store");
+    },
+};
+
+module.exports = function buildApp(appConfig = {}, fastifyOptions = {}) {
+    const app = fastify(fastifyOptions);
+
+    if (appConfig.cors) {
+        app.addHook("onRequest", async (request, reply) => {
+            reply.header("access-control-allow-origin", "*");
+        });
+    }
+
+    // plugins
+    app.decorateReply("render", tarkine.adapters.fastify(templateEngine));
+
+    // inject script
+    app.addHook("onSend", require("./middleware/inject.middleware"));
+
+    // udane's own assets. This is the first static instance, so it owns the reply decorator.
+    app.register(require("@fastify/static"), {
+        root: path.join(__dirname, "public"),
+        prefix: `/${PUBLIC_DIR_PREFIX}/`,
+    });
+
+    // extra folders from appConfig.mount
+    for (const [prefix, root] of Object.entries(appConfig.mount)) {
+        app.register(require("@fastify/static"), {
+            root,
+            prefix: `${prefix}/`,
+            decorateReply: false,
+            ...noStore,
+        });
+    }
+
+    // the project being served
+    app.register(require("@fastify/static"), {
+        root: appConfig.root,
+        index: appConfig.index,
+        decorateReply: false,
+        ...noStore,
+    });
+
+    app.setErrorHandler((error, request, reply) => {
+        const statusCode = error.statusCode || 500;
+        const title = http.STATUS_CODES[statusCode];
+
+        reply.render("/error", {
+            PUBLIC_DIR_PREFIX,
+            statusCode,
+            title,
+        });
+    });
+
+    app.setNotFoundHandler(async (request, reply) => {
+        const { pathname } = new URL(request.url, "http://localhost");
+
+        if (request.method === "GET") {
+            const folder = resolveDirectory(pathname, appConfig);
+
+            if (folder) {
+                const listing = await listDirectory(folder, pathname);
+
+                return reply.render("listing", {
+                    PUBLIC_DIR_PREFIX,
+                    listing,
+                });
+            }
+        }
+
+        return reply.render("/error", {
+            statusCode: 404,
+            title: "Not Found",
+            PUBLIC_DIR_PREFIX,
+        });
+    });
+
+    return app;
+};

package/config/udane.config.js

@@ -0,0 +1,47 @@
+// config/udane.config.js
+// Default configuration for udane.
+// Priority (lowest to highest): these defaults < udane.config.js in the user's cwd < CLI flags.
+// Every option is listed here so this file doubles as the reference.
+
+module.exports = {
+    // "0.0.0.0" exposes the server to the local network (phone testing, other devices).
+    // Use "127.0.0.1" to keep it private to this machine.
+    host: "0.0.0.0",
+
+    // Port to listen on. If it is busy, udane tries the next free port.
+    port: 5300,
+
+    // Folder to serve, relative to the current working directory.
+    root: ".",
+
+    // Extra folders served under a URL prefix. Empty by default, because with
+    // host "0.0.0.0" everything mounted here is visible to the whole network.
+    // Keys are URL prefixes, values are folders ("~" is expanded to the home directory).
+    // Example: { "/downloads": "~/Downloads" }
+    mount: {},
+
+    // Entry files tried for a directory, in order.
+    index: ["index.html"],
+
+    // Send "Access-Control-Allow-Origin: *" on every response.
+    cors: false,
+
+    // Swap changed CSS in place without a full page reload.
+    cssHotSwap: true,
+
+    // Milliseconds to wait after the last file change before notifying the browser.
+    // Prevents several reloads when an editor writes many files at once.
+    debounce: 100,
+
+    // Paths to watch, relative to root. Empty array means watch the whole root.
+    watch: [],
+
+    // Paths and patterns the watcher ignores.
+    ignore: ["node_modules", ".git", ".DS_Store", "*.log"],
+
+    // Print one line per request.
+    logRequests: true,
+
+    // Print a line when a watched file changes.
+    logChanges: true,
+};

package/constants/index.constant.js

@@ -0,0 +1,4 @@
+module.exports = {
+    PUBLIC_DIR_PREFIX: "__udane",
+    WS_PATH: "/__udane-ws",
+};

package/helpers/directory.helper.js

@@ -0,0 +1,74 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+// Maps a URL path to a real folder inside a mount or root. Returns null if it is not one.
+function resolveDirectory(pathname, config) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(pathname);
+    } catch {
+        return null;
+    }
+
+    // longest mount prefix first, root last
+    const targets = [
+        ...Object.entries(config.mount)
+            .map(([prefix, dir]) => ({ prefix, dir }))
+            .sort((a, b) => b.prefix.length - a.prefix.length),
+        { prefix: "", dir: config.root },
+    ];
+
+    for (const { prefix, dir } of targets) {
+        if (prefix && decoded !== prefix && !decoded.startsWith(`${prefix}/`))
+            continue;
+
+        const full = path.resolve(dir, `.${decoded.slice(prefix.length)}`);
+        const inside = path.relative(dir, full);
+
+        // blocks "../" traversal outside the served folder
+        if (inside.startsWith("..") || path.isAbsolute(inside)) continue;
+
+        try {
+            if (fs.statSync(full).isDirectory()) return full;
+        } catch {
+            // not found in this target, try the next one
+        }
+    }
+
+    return null;
+}
+
+async function listDirectory(full, pathname) {
+    const base = pathname.endsWith("/") ? pathname : `${pathname}/`;
+    const items = await fs.promises.readdir(full, { withFileTypes: true });
+
+    const entries = items
+        .filter((item) => !item.name.startsWith("."))
+        .map((item) => {
+            const isDirectory = item.isDirectory();
+            return {
+                name: isDirectory ? `${item.name}/` : item.name,
+                href:
+                    base +
+                    encodeURIComponent(item.name) +
+                    (isDirectory ? "/" : ""),
+                isDirectory,
+            };
+        })
+        .sort(
+            (a, b) =>
+                Number(b.isDirectory) - Number(a.isDirectory) ||
+                a.name.localeCompare(b.name),
+        );
+
+    return {
+        parent: base === "/" ? null : base.replace(/[^/]+\/$/, ""),
+        base,
+        entries,
+    };
+}
+
+module.exports = {
+    resolveDirectory,
+    listDirectory,
+};

package/helpers/getConfig.helper.js

@@ -0,0 +1,187 @@
+const process = require("node:process");
+const path = require("node:path");
+const fs = require("node:fs");
+const os = require("node:os");
+
+const { z } = require("zod");
+
+const defaults = require("../config/udane.config");
+const { PUBLIC_DIR_PREFIX } = require("../constants/index.constant");
+
+const NESTED = ["mount"];
+const CONFIG_NAME = "udane.config.js";
+const RESERVED_PREFIX = `/${PUBLIC_DIR_PREFIX}`;
+
+const configSchema = z
+    .object({
+        host: z.string(),
+        port: z.number().int().min(1).max(65535),
+        root: z.string(),
+        mount: z.record(z.string().startsWith("/"), z.string()),
+        index: z.array(z.string()),
+        cors: z.boolean(),
+        cssHotSwap: z.boolean(),
+        debounce: z.number().int().min(0),
+        watch: z.array(z.string()),
+        ignore: z.array(z.string()),
+        logRequests: z.boolean(),
+        logChanges: z.boolean(),
+    })
+    .strict();
+
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// Drops undefined values so an unset CLI flag never overwrites a real value.
+function clean(obj) {
+    return Object.fromEntries(
+        Object.entries(obj).filter(([, value]) => value !== undefined),
+    );
+}
+
+// Looks for udane.config.js inside a folder. Returns { path, config } or null.
+function loadConfigFile(dir) {
+    const file = path.join(dir, CONFIG_NAME);
+    if (!fs.existsSync(file)) return null;
+
+    let config;
+    try {
+        config = require(file);
+    } catch (err) {
+        throw new Error(`Failed to load ${file}: ${err.message}`);
+    }
+
+    if (!isPlainObject(config)) {
+        throw new Error(
+            `${file} must export an object (module.exports = { ... })`,
+        );
+    }
+
+    return { path: file, config };
+}
+
+function mergeConfigs(...sources) {
+    const result = {};
+
+    for (const source of sources) {
+        for (const [key, value] of Object.entries(source)) {
+            result[key] =
+                NESTED.includes(key) && isPlainObject(value)
+                    ? { ...result[key], ...value }
+                    : value;
+        }
+    }
+
+    return result;
+}
+
+function formatIssues(error, files) {
+    const where = files.length ? ` (config: ${files.join(", ")})` : "";
+    const lines = error.issues.map((issue) => {
+        const key =
+            issue.code === "unrecognized_keys"
+                ? issue.keys.join(", ")
+                : issue.path.join(".") || "(root)";
+        return `  ${key}: ${issue.message}`;
+    });
+
+    return `Invalid config${where}\n${lines.join("\n")}`;
+}
+
+// Expands "~" (Node does not) and resolves to an absolute path.
+function expandPath(target, cwd) {
+    let value = target;
+
+    if (value === "~") {
+        value = os.homedir();
+    } else if (value.startsWith("~/") || value.startsWith("~\\")) {
+        value = path.join(os.homedir(), value.slice(2));
+    }
+
+    return path.resolve(cwd, value);
+}
+
+function assertFolder(folder, label) {
+    let stat;
+
+    try {
+        stat = fs.statSync(folder);
+    } catch {
+        throw new Error(`${label} not found: ${folder}`);
+    }
+
+    if (!stat.isDirectory()) {
+        throw new Error(`${label} is not a folder: ${folder}`);
+    }
+}
+
+function normalizeMount(mount, cwd) {
+    const result = {};
+
+    for (const [prefix, target] of Object.entries(mount)) {
+        const key = prefix.replace(/\/+$/, "");
+
+        if (!key) {
+            throw new Error(`mount: "/" is not allowed as a prefix`);
+        }
+
+        if (key === RESERVED_PREFIX || key.startsWith(`${RESERVED_PREFIX}/`)) {
+            throw new Error(`mount: "${prefix}" is reserved by udane`);
+        }
+
+        const folder = expandPath(target, cwd);
+        assertFolder(folder, `mount "${prefix}"`);
+        result[key] = folder;
+    }
+
+    return result;
+}
+
+function normalize(config, cwd) {
+    const root = expandPath(config.root, cwd);
+    assertFolder(root, "root");
+
+    return {
+        ...config,
+        root,
+        mount: normalizeMount(config.mount, cwd),
+        // Empty list means watch the whole root.
+        watch: config.watch.length
+            ? config.watch.map((item) => path.resolve(root, item))
+            : [root],
+    };
+}
+
+// Priority (lowest to highest):
+// defaults < ~/.config/udane.config.js < udane.config.js in cwd < options (CLI flags)
+module.exports = function getConfig(options = {}) {
+    const cwd = process.cwd();
+
+    const files = [
+        loadConfigFile(path.join(os.homedir(), ".config")),
+        loadConfigFile(cwd),
+    ].filter(Boolean);
+
+    const merged = mergeConfigs(
+        defaults,
+        ...files.map((file) => file.config),
+        clean(options),
+    );
+
+    const result = configSchema.safeParse(merged);
+
+    if (!result.success) {
+        throw new Error(
+            formatIssues(
+                result.error,
+                files.map((file) => file.path),
+            ),
+        );
+    }
+
+    return Object.freeze({
+        ...normalize(result.data, cwd),
+        configFiles: files.map((file) => file.path),
+    });
+};

package/helpers/ignore.helper.js

@@ -0,0 +1,47 @@
+// Builds the `ignored` function for chokidar from config.ignore.
+// - a pattern without "/" matches any file or folder name ("node_modules", "*.log", ".git")
+// - a pattern with "/" matches a path fragment ("dist/cache")
+// - "*" matches any characters, "?" matches one character
+// Matching ignores the part of the path above the watched root, so serving a
+// project that lives inside a folder like "node_modules" still works.
+
+const escape = (text) => text.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+
+const toRegex = (pattern) =>
+    new RegExp(`^${escape(pattern).replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
+
+module.exports = function createIgnore(patterns, roots) {
+    const matchers = patterns.map((pattern) => {
+        const clean = pattern
+            .replace(/\\/g, "/")
+            .replace(/^\.?\//, "")
+            .replace(/\/+$/, "");
+
+        return { clean, hasSlash: clean.includes("/"), regex: toRegex(clean) };
+    });
+
+    const bases = roots.map((root) =>
+        root.replace(/\\/g, "/").replace(/\/+$/, ""),
+    );
+
+    return (filepath) => {
+        let normalized = filepath.replace(/\\/g, "/");
+
+        const base = bases.find(
+            (item) => normalized === item || normalized.startsWith(`${item}/`),
+        );
+
+        if (base) {
+            normalized = normalized.slice(base.length);
+        }
+
+        const segments = normalized.split("/").filter(Boolean);
+
+        return matchers.some(({ clean, hasSlash, regex }) =>
+            hasSlash
+                ? normalized.endsWith(`/${clean}`) ||
+                  normalized.includes(`/${clean}/`)
+                : segments.some((segment) => regex.test(segment)),
+        );
+    };
+};

package/helpers/templateEngine.helper.js

@@ -0,0 +1,10 @@
+const path = require("node:path");
+
+const tarkine = require("tarkine");
+
+const engine = tarkine.createEngine({
+    templateRoot: path.resolve(__dirname, "../views"),
+    cache: false
+});
+
+module.exports = engine;

package/lib/bin.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+const process = require("node:process");
+const { parseArgs } = require("node:util");
+const path = require("node:path");
+const fs = require("node:fs");
+
+const udane = require("./udane");
+const pkg = require("../package.json");
+
+const HELP = `
+udane v${pkg.version}
+Live-reload development server.
+
+Usage
+  udane [root] [options]
+  udane init [--force]
+
+Commands
+  init                     Copy the default config file into the current folder
+
+Options
+  -p, --port <number>      Port to listen on
+  -H, --host <address>     Interface to bind (0.0.0.0 = network, 127.0.0.1 = local only)
+      --cors               Send Access-Control-Allow-Origin: *
+      --debounce <ms>      Wait time after the last file change
+      --watch <path>       Path to watch (repeatable)
+      --ignore <pattern>   Pattern to ignore (repeatable)
+  -f, --force              Overwrite an existing config file (init only)
+  -h, --help               Show this help
+  -v, --version            Show the version
+`;
+
+function readArgs(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            port: { type: "string", short: "p" },
+            host: { type: "string", short: "H" },
+            cors: { type: "boolean" },
+            debounce: { type: "string" },
+            watch: { type: "string", multiple: true },
+            ignore: { type: "string", multiple: true },
+            force: { type: "boolean", short: "f" },
+            help: { type: "boolean", short: "h" },
+            version: { type: "boolean", short: "v" },
+        },
+    });
+
+    const number = (value) => (value === undefined ? undefined : Number(value));
+    const command = positionals[0] === "init" ? "init" : undefined;
+
+    return {
+        command,
+        force: values.force,
+        help: values.help,
+        version: values.version,
+
+        // undefined values are dropped by getConfig, so unset flags never override config
+        options: {
+            root: command ? undefined : positionals[0],
+            port: number(values.port),
+            host: values.host,
+            cors: values.cors,
+            debounce: number(values.debounce),
+            watch: values.watch,
+            ignore: values.ignore,
+        },
+    };
+}
+
+function init(force) {
+    const source = path.join(__dirname, "..", "config", "udane.config.js");
+    const target = path.join(process.cwd(), "udane.config.js");
+
+    if (fs.existsSync(target) && !force) {
+        throw new Error(
+            "udane.config.js already exists (use --force to overwrite)",
+        );
+    }
+
+    fs.copyFileSync(source, target);
+    console.log(`[+] Created ${target}`);
+}
+
+async function main() {
+    const { command, force, help, version, options } = readArgs(
+        process.argv.slice(2),
+    );
+
+    if (help) return console.log(HELP);
+    if (version) return console.log(pkg.version);
+    if (command === "init") return init(force);
+
+    const server = await udane(options);
+
+    if (server.port !== server.requestedPort) {
+        console.log(
+            `[+] Port ${server.requestedPort} is busy, using ${server.port}`,
+        );
+    }
+
+    console.log(
+        `\n[+] udane v${pkg.version} by https://madhanmaaz.netlify.app`,
+    );
+    console.log(`[+] Root: ${server.config.root}\n`);
+
+    let closing = false;
+    const shutdown = async () => {
+        if (closing) return;
+        closing = true;
+        await server.close();
+        process.exit(0);
+    };
+
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+
+main().catch((error) => {
+    // console.log(error);
+    console.error(`[-] ${error.message}`);
+    process.exit(1);
+});