x4js 2.2.74 → 2.3.2

package/bin/x4js.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "../cli/main.mjs";

package/cli/build-options.mjs

@@ -0,0 +1,68 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { sassPlugin } from "esbuild-sass-plugin";
+import { lessPlugin } from "./less-plugin.mjs";
+import { copyPlugin } from "./copy-plugin.mjs";
+
+const cliDir = path.dirname(fileURLToPath(import.meta.url));
+const devClient = path.join(cliDir, "dev-client.js");
+
+function versionId() {
+    const now = new Date();
+    const pad = (value) => String(value).padStart(2, "0");
+    return `${pad(now.getFullYear() - 2000)}${pad(now.getMonth() + 1)}${pad(now.getDate())}`;
+}
+
+export function createBuildOptions(config, mode) {
+    const production = mode === "production";
+    const dev = mode === "dev";
+
+    const defaults = {
+        absWorkingDir: config.root,
+        entryPoints: config.entryPoints,
+        outdir: config.outdir,
+        bundle: true,
+        charset: "utf8",
+        keepNames: true,
+        platform: "browser",
+        format: "iife",
+        target: "es2020",
+        minify: production,
+        sourcemap: production ? false : "inline",
+        logLevel: "info",
+        external: config.external,
+        assetNames: "assets/[name]-[hash]",
+        loader: {
+            ".svg": "dataurl",
+            ".jpg": "file",
+            ".jpeg": "file",
+            ".png": "file",
+            ".ttf": "file",
+            ".woff": "file",
+            ".woff2": "file",
+        },
+        define: {
+            ...config.define,
+            DEBUG_MODE: production ? "false" : "true",
+            VERSION_ID: versionId(),
+        },
+        plugins: [
+            sassPlugin({
+                type: "css",
+                filter: /\.s[ac]ss$/,
+            }),
+            lessPlugin(config.root),
+            copyPlugin(config, { dev }),
+        ],
+    };
+
+    if (dev)
+        defaults.inject = [devClient];
+
+    // x4.esbuild is intentionally last: it is the escape hatch for projects
+    // that need native esbuild options not modeled by x4js.
+    return {
+        ...defaults,
+        ...config.esbuild,
+    };
+}

package/cli/build.mjs

@@ -0,0 +1,33 @@
+import fs from "node:fs/promises";
+import { parseArgs } from "node:util";
+import esbuild from "esbuild";
+import { loadConfig } from "./config.mjs";
+import { createBuildOptions } from "./build-options.mjs";
+import { info, success } from "./log.mjs";
+
+export async function build(argv = [], root = process.cwd()) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            debug: { type: "boolean", default: false },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+
+    if (positionals.length)
+        throw new Error(`Unexpected argument: ${positionals[0]}`);
+
+    const config = loadConfig(root);
+    const mode = values.debug ? "debug" : "production";
+
+    info("mode", mode);
+    info("outdir", config.outdir);
+
+    await fs.rm(config.outdir, { recursive: true, force: true });
+    await fs.mkdir(config.outdir, { recursive: true });
+
+    const started = performance.now();
+    await esbuild.build(createBuildOptions(config, mode));
+    success("built", `${Math.round(performance.now() - started)}ms`);
+}

package/cli/config.mjs

@@ -0,0 +1,165 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULTS = Object.freeze({
+    entryPoints: ["src/main.ts"],
+    outdir: "./bin",
+    copy: [],
+    external: [],
+    define: {},
+    dev: {
+        host: "127.0.0.1",
+        https: false,
+    },
+});
+
+export function expandEnv(value, env = process.env) {
+    if (typeof value !== "string")
+        return value;
+
+    return value.replace(
+        /\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g,
+        (_, braced, plain) => {
+            const name = braced ?? plain;
+            const result = env[name];
+            if (result === undefined)
+                throw new Error(`Environment variable '${name}' is not defined`);
+            return result;
+        },
+    );
+}
+
+export function resolvePath(root, value, env = process.env) {
+    const expanded = expandEnv(value, env);
+    return path.isAbsolute(expanded)
+        ? path.normalize(expanded)
+        : path.resolve(root, expanded);
+}
+
+function validateCopy(copy) {
+    if (!Array.isArray(copy))
+        throw new Error("x4.copy must be an array");
+
+    for (const item of copy) {
+        if (!item || typeof item !== "object" || typeof item.from !== "string" || typeof item.to !== "string")
+            throw new Error("Each x4.copy entry must contain string 'from' and 'to' fields");
+        if (path.isAbsolute(item.to))
+            throw new Error(`x4.copy destination must be relative to outdir: '${item.to}'`);
+        const normalized = path.normalize(item.to);
+        if (normalized === ".." || normalized.startsWith(`..${path.sep}`))
+            throw new Error(`x4.copy destination escapes outdir: '${item.to}'`);
+    }
+}
+
+export function loadConfig(root = process.cwd(), env = process.env) {
+    root = path.resolve(root);
+    const packageFile = path.join(root, "package.json");
+
+    if (!fs.existsSync(packageFile))
+        throw new Error(`Cannot find package.json in '${root}'`);
+
+    let pkg;
+    try {
+        pkg = JSON.parse(fs.readFileSync(packageFile, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Cannot read package.json: ${error.message}`);
+    }
+
+    const cfg = pkg.x4 ?? {};
+    if (cfg === null || typeof cfg !== "object" || Array.isArray(cfg))
+        throw new Error("package.json field 'x4' must be an object");
+
+    const entryPoints = cfg.entryPoints ?? DEFAULTS.entryPoints;
+    if (!Array.isArray(entryPoints) || !entryPoints.length || entryPoints.some((entry) => typeof entry !== "string"))
+        throw new Error("x4.entryPoints must be a non-empty array of strings");
+
+    const copy = cfg.copy ?? DEFAULTS.copy;
+    validateCopy(copy);
+
+    const external = cfg.external ?? DEFAULTS.external;
+    if (!Array.isArray(external) || external.some((entry) => typeof entry !== "string"))
+        throw new Error("x4.external must be an array of strings");
+
+    const define = cfg.define ?? DEFAULTS.define;
+    if (!define || typeof define !== "object" || Array.isArray(define))
+        throw new Error("x4.define must be an object");
+    if (Object.values(define).some((value) => typeof value !== "string"))
+        throw new Error("x4.define values must be strings containing esbuild define expressions");
+
+    const devCfg = cfg.dev ?? {};
+    if (!devCfg || typeof devCfg !== "object" || Array.isArray(devCfg))
+        throw new Error("x4.dev must be an object");
+
+    const host = devCfg.host ?? DEFAULTS.dev.host;
+    if (typeof host !== "string" || !host)
+        throw new Error("x4.dev.host must be a non-empty string");
+
+    const port = devCfg.port;
+    if (port !== undefined && (!Number.isInteger(port) || port < 0 || port > 65535))
+        throw new Error("x4.dev.port must be an integer between 0 and 65535");
+
+    const https = devCfg.https ?? DEFAULTS.dev.https;
+    if (typeof https !== "boolean")
+        throw new Error("x4.dev.https must be a boolean");
+
+    if (devCfg.tls !== undefined) {
+        if (!devCfg.tls || typeof devCfg.tls !== "object" || Array.isArray(devCfg.tls))
+            throw new Error("x4.dev.tls must be an object");
+        if (typeof devCfg.tls.cert !== "string" || typeof devCfg.tls.key !== "string")
+            throw new Error("x4.dev.tls requires string 'cert' and 'key' fields");
+    }
+
+    const outdirRaw = cfg.outdir ?? DEFAULTS.outdir;
+    if (typeof outdirRaw !== "string")
+        throw new Error("x4.outdir must be a string");
+
+    const outdir = resolvePath(root, outdirRaw, env);
+    if (outdir === root)
+        throw new Error("x4.outdir cannot be the project root");
+    if (outdir === path.parse(outdir).root)
+        throw new Error("x4.outdir cannot be a filesystem root");
+
+    return {
+        root,
+        packageFile,
+        package: pkg,
+        entryPoints: entryPoints.map((entry) => resolvePath(root, entry, env)),
+        outdir,
+        copy: copy.map((item) => ({
+            from: resolvePath(root, item.from, env),
+            to: path.normalize(item.to),
+        })),
+        external: [...external],
+        define: { ...define },
+        dev: {
+            host,
+            port,
+            https,
+            tls: devCfg.tls ? { ...devCfg.tls } : undefined,
+        },
+        esbuild: (() => {
+            if (cfg.esbuild === undefined)
+                return {};
+            if (!cfg.esbuild || typeof cfg.esbuild !== "object" || Array.isArray(cfg.esbuild))
+                throw new Error("x4.esbuild must be an object");
+            return { ...cfg.esbuild };
+        })(),
+    };
+}
+
+export function resolveTls(config, env = process.env) {
+    const tls = config.dev.tls;
+    if (!tls)
+        throw new Error("HTTPS is enabled but x4.dev.tls.cert/key are not configured");
+
+    const certfile = resolvePath(config.root, tls.cert, env);
+    const keyfile = resolvePath(config.root, tls.key, env);
+
+    if (!fs.existsSync(certfile))
+        throw new Error(`TLS certificate not found: ${certfile}`);
+    if (!fs.existsSync(keyfile))
+        throw new Error(`TLS private key not found: ${keyfile}`);
+
+    return { certfile, keyfile };
+}

package/cli/copy-plugin.mjs

@@ -0,0 +1,115 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+async function walk(source) {
+    const files = [];
+    const dirs = [];
+
+    async function visit(current) {
+        const stat = await fs.stat(current);
+        if (!stat.isDirectory()) {
+            files.push({ path: current, stat });
+            return;
+        }
+
+        dirs.push(current);
+        const entries = await fs.readdir(current, { withFileTypes: true });
+        for (const entry of entries)
+            await visit(path.join(current, entry.name));
+    }
+
+    try {
+        await visit(source);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+
+    return { files, dirs, isDirectory: dirs.includes(source) };
+}
+
+function destinationFor(entry, sourceFile) {
+    if (!entry.sourceIsDirectory)
+        return entry.destRoot;
+    return path.join(entry.destRoot, path.relative(entry.from, sourceFile));
+}
+
+export function copyPlugin(config, { dev = false } = {}) {
+    const entries = config.copy.map((entry) => ({
+        ...entry,
+        destRoot: path.resolve(config.outdir, entry.to),
+    }));
+    let previousDestinations = new Set();
+    let snapshot = { files: [], dirs: [], fingerprint: "0" };
+
+    async function scan() {
+        const files = [];
+        const dirs = [];
+        const fingerprint = [];
+
+        for (const entry of entries) {
+            const result = await walk(entry.from);
+            entry.sourceIsDirectory = result.isDirectory;
+            dirs.push(...result.dirs);
+            for (const item of result.files) {
+                files.push({ entry, ...item });
+                fingerprint.push(`${item.path}\0${item.stat.size}\0${item.stat.mtimeMs}`);
+            }
+        }
+
+        snapshot = {
+            files,
+            dirs,
+            fingerprint: fingerprint.sort().join("\n"),
+        };
+    }
+
+    async function copyFiles() {
+        const destinations = new Set();
+
+        for (const item of snapshot.files) {
+            const dest = destinationFor(item.entry, item.path);
+            destinations.add(dest);
+            await fs.mkdir(path.dirname(dest), { recursive: true });
+            await fs.copyFile(item.path, dest);
+        }
+
+        for (const stale of previousDestinations) {
+            if (!destinations.has(stale)) {
+                try { await fs.rm(stale, { force: true }); }
+                catch { /* ignored */ }
+            }
+        }
+
+        previousDestinations = destinations;
+    }
+
+    return {
+        name: "x4-copy",
+        setup(build) {
+            build.onStart(async () => {
+                await scan();
+            });
+
+            if (dev) {
+                build.onResolve({ filter: /^x4:copy-state$/ }, () => ({
+                    path: "copy-state",
+                    namespace: "x4-internal",
+                }));
+
+                build.onLoad({ filter: /^copy-state$/, namespace: "x4-internal" }, async () => ({
+                    contents: `export default ${JSON.stringify(snapshot.fingerprint)};`,
+                    loader: "js",
+                    watchFiles: snapshot.files.map((item) => item.path),
+                    watchDirs: snapshot.dirs,
+                }));
+            }
+
+            build.onEnd(async (result) => {
+                if (result.errors.length === 0)
+                    await copyFiles();
+            });
+        },
+    };
+}

package/cli/create.mjs

@@ -0,0 +1,159 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { parseArgs } from "node:util";
+import { fetchTemplates, fetchTemplateFiles, downloadTemplateFile } from "./templates-source.mjs";
+import { info, success } from "./log.mjs";
+
+function x4Minor(version) {
+    const match = /^(\d+)\.(\d+)/.exec(version);
+    if (!match)
+        throw new Error(`Invalid x4js version '${version}'`);
+    return `${match[1]}.${match[2]}`;
+}
+
+function validatePackageName(name) {
+    if (!/^[a-z0-9][a-z0-9._-]*$/.test(name))
+        throw new Error(`Invalid project name '${name}'. Use lowercase letters, digits, '.', '_' or '-'.`);
+}
+
+async function ensureEmptyTarget(target) {
+    try {
+        const entries = await fs.readdir(target);
+        if (entries.length)
+            throw new Error(`Target directory is not empty: ${target}`);
+        return false;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            await fs.mkdir(target, { recursive: true });
+            return true;
+        }
+        throw error;
+    }
+}
+
+
+async function patchPackage(target, projectName, version) {
+    const filename = path.join(target, "package.json");
+    let pkg;
+    try {
+        pkg = JSON.parse(await fs.readFile(filename, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Template package.json is missing or invalid: ${error.message}`);
+    }
+
+    pkg.name = projectName;
+    const minor = x4Minor(version);
+
+    if (pkg.dependencies?.x4js !== undefined)
+        pkg.dependencies.x4js = minor;
+    else if (pkg.devDependencies?.x4js !== undefined)
+        pkg.devDependencies.x4js = minor;
+    else {
+        pkg.dependencies ??= {};
+        pkg.dependencies.x4js = minor;
+    }
+
+    await fs.writeFile(filename, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+async function npmInstall(target) {
+    let command;
+    let args;
+
+    if (process.platform === "win32") {
+        command = process.env.ComSpec || "cmd.exe";
+        args = ["/d", "/s", "/c", "npm install"];
+    }
+    else {
+        command = "npm";
+        args = ["install"];
+    }
+
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: target,
+            stdio: "inherit",
+        });
+
+        child.on("error", reject);
+
+        child.on("exit", (code, signal) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+
+            reject(
+                new Error(
+                    `npm install failed${
+                        signal ? ` (${signal})` : ` (exit ${code})`
+                    }`
+                )
+            );
+        });
+    });
+}
+
+export async function create(argv = [], { version = "unknown", cwd = process.cwd() } = {}) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        options: {
+            template: { type: "string", short: "t", default: "app" },
+            "no-install": { type: "boolean", default: false },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+
+    if (positionals.length !== 1)
+        throw new Error("Usage: x4js create <project> [--template <name>] [--no-install]");
+
+    const target = path.resolve(cwd, positionals[0]);
+    const projectName = path.basename(target);
+    validatePackageName(projectName);
+
+    const manifest = await fetchTemplates(version);
+    if (!(values.template in manifest))
+        throw new Error(`Unknown template '${values.template}'. Run 'x4js templates' to list templates.`);
+
+    const targetCreated = await ensureEmptyTarget(target);
+    let projectReady = false;
+    info("create", target);
+    info("template", values.template);
+
+    try {
+        const files = await fetchTemplateFiles(values.template, version);
+
+        await Promise.all(files.map(async (file) => {
+            if (!file.path || file.path.split("/").includes(".."))
+                throw new Error(`Unsafe template path '${file.path}'`);
+            const destination = path.join(target, ...file.path.split("/"));
+            await fs.mkdir(path.dirname(destination), { recursive: true });
+            const data = await downloadTemplateFile(file.url, version);
+            await fs.writeFile(destination, data);
+        }));
+
+        await patchPackage(target, projectName, version);
+        projectReady = true;
+
+        if (!values["no-install"]) {
+            info("install", "npm");
+            await npmInstall(target);
+        }
+
+        success("created", target);
+    }
+    catch (error) {
+        // Never remove a directory that existed before `x4js create`.
+        // Once package.json has been patched, the project is considered
+        // created and is also kept if `npm install` fails.
+        if (targetCreated && !projectReady)
+            await fs.rm(target, { recursive: true, force: true });
+        throw error;
+    }
+}
+
+export { x4Minor };

package/cli/dev-client.js

@@ -0,0 +1,41 @@
+import copyState from "x4:copy-state";
+
+// Keep the copy-state module in the bundle so changes to copied files also
+// produce a changed JS output and therefore a live-reload event.
+const events = new EventSource("/esbuild");
+Object.defineProperty(events, "__x4CopyState", { value: copyState });
+
+events.addEventListener("change", (event) => {
+    const change = JSON.parse(event.data);
+    const changed = [...change.added, ...change.removed, ...change.updated];
+
+    if (
+        change.added.length === 0 &&
+        change.removed.length === 0 &&
+        change.updated.length > 0 &&
+        change.updated.every((file) => file.endsWith(".css"))
+    ) {
+        const pending = new Set(change.updated);
+        const links = document.querySelectorAll('link[rel="stylesheet"]');
+
+        for (const link of links) {
+            const current = new URL(link.href);
+            if (!pending.has(current.pathname))
+                continue;
+
+            const next = link.cloneNode();
+            const url = new URL(link.href);
+            url.searchParams.set("x4", Date.now().toString());
+            next.href = url.href;
+            next.onload = () => link.remove();
+            link.after(next);
+            pending.delete(current.pathname);
+        }
+
+        if (pending.size === 0)
+            return;
+    }
+
+    if (changed.length)
+        location.reload();
+});