@webtypen/webframez-core 0.3.35 → 0.3.37

package/README.md

@@ -20,14 +20,14 @@ This README reflects the current API in this repository and focuses on:
 npm i @webtypen/webframez-core
 ```
 
-## AGENTS.md fuer Codex und Copilot
+## Agent-Regeln fuer Codex und Copilot
 
-Das Paket enthaelt eine AGENTS.md mit empfohlenen Arbeitsregeln fuer AI-Coding-Agents in Webframez-Projekten.
+Das Paket enthaelt unter agents/webframez_rules.md empfohlene Arbeitsregeln fuer AI-Coding-Agents in Webframez-Projekten.
 
 Nach der Installation liegt die Datei im Paket unter:
 
 ```text
-node_modules/@webtypen/webframez-core/AGENTS.md
+node_modules/@webtypen/webframez-core/agents/webframez_rules.md
 ```
 
 Die Regeln beschreiben unter anderem:
@@ -35,7 +35,7 @@ Die Regeln beschreiben unter anderem:
 - bevorzugte Nutzung der vorhandenen Helper wie StringFunctions, NumericFunctions und DateFunctions
 - Verwendung der Webframez-Abstraktionen fuer Request, Response, Middleware, Storage, Datatables und Routes
 
-Wichtig: AGENTS.md-Dateien haben keine universell standardisierte Import-Funktion. Die praktikable Variante ist deshalb, die Paket-AGENTS.md in der AGENTS.md des eigenen Projekts explizit zu referenzieren und projektspezifische Regeln lokal zu ergaenzen.
+Wichtig: AGENTS.md-Dateien haben keine universell standardisierte Import-Funktion. Die praktikable Variante ist deshalb, die Regeldatei aus dem Paket in der AGENTS.md des eigenen Projekts explizit zu referenzieren und projektspezifische Regeln lokal zu ergaenzen.
 
 Beispiel fuer eine eigene AGENTS.md im Consumer-Projekt:
 
@@ -45,7 +45,7 @@ Beispiel fuer eine eigene AGENTS.md im Consumer-Projekt:
 Dieses Projekt verwendet @webtypen/webframez-core.
 
 Uebernimm fuer alle Webframez-bezogenen Implementierungen die Konventionen aus:
-./node_modules/@webtypen/webframez-core/AGENTS.md
+./node_modules/@webtypen/webframez-core/agents/webframez_rules.md
 
 Insbesondere gilt:
 - fuer ObjectId-Konvertierungen Model.objectId(...) oder die passende Model-Instanzmethode verwenden
@@ -57,7 +57,7 @@ Projektspezifische Ergaenzung:
 - Antworten im Backoffice sollen das Format { status, message, data } einhalten
 ```
 
-Wenn eine Regel aus der lokalen Projekt-AGENTS.md einer Regel aus der Paket-AGENTS.md widerspricht, sollte die lokale Projektregel Vorrang haben.
+Wenn eine Regel aus der lokalen Projekt-AGENTS.md einer Regel aus der Paketdatei widerspricht, sollte die lokale Projektregel Vorrang haben.
 
 ## Basic Web Setup
 

package/bin/webframez.cjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+require("../dist/Cli")
+    .runWebframezCli()
+    .catch((error) => {
+        console.error("[webframez]", error && error.stack ? error.stack : error);
+        process.exit(1);
+    });

package/dist/BuildApplication.d.ts

@@ -0,0 +1,70 @@
+export type WebframezBuildRuntimeFile = string | {
+    from: string;
+    to?: string;
+    optional?: boolean;
+};
+export type WebframezBuildContext = {
+    projectRoot: string;
+    stagingDir: string;
+    outDir: string;
+    config: WebframezAppConfig;
+    run: (binaryName: string, args: string[], envAdditions?: Record<string, string>) => Promise<number>;
+};
+export type WebframezBuildPlugin = {
+    name?: string;
+    beforeBuild?: (context: WebframezBuildContext) => Promise<void> | void;
+    afterTypescriptBuild?: (context: WebframezBuildContext) => Promise<void> | void;
+    afterRuntimeFilesCopied?: (context: WebframezBuildContext) => Promise<void> | void;
+    buildAssets?: (context: WebframezBuildContext) => Promise<void> | void;
+    validateBuild?: (context: WebframezBuildContext) => Promise<void> | void;
+};
+export type WebframezBuildConfig = {
+    dir?: string;
+    tsconfig?: string;
+    entry?: string;
+    runtimeFiles?: WebframezBuildRuntimeFile[];
+    prunePaths?: string[];
+    plugins?: Array<string | WebframezBuildPlugin | ((config: WebframezAppConfig) => WebframezBuildPlugin)>;
+};
+export type WebframezAppConfig = {
+    setup?: (context: {
+        mode: "web" | "console" | "build";
+        projectRoot: string;
+    }) => Promise<void> | void;
+    kernel?: any;
+    consoleKernel?: any;
+    kernelConsole?: any;
+    config?: Record<string, unknown>;
+    jobs?: any[];
+    modules?: any[];
+    datatables?: any;
+    errorHandler?: any;
+    onEnd?: (...args: any[]) => Promise<void> | void;
+    build?: WebframezBuildConfig;
+};
+type BuildApplicationOptions = {
+    outDir: string;
+};
+export declare class BuildApplication {
+    private readonly projectRoot;
+    private readonly config;
+    private readonly outDir;
+    private readonly buildRoot;
+    private readonly stagingDir;
+    private readonly buildId;
+    constructor(projectRoot: string, config: WebframezAppConfig, options: BuildApplicationOptions);
+    run(): Promise<void>;
+    private createContext;
+    private callHook;
+    private runTypescriptBuild;
+    private copyRuntimeFiles;
+    private validateCoreBuild;
+    private promoteBuild;
+    private loadPlugins;
+    private discoverPackagePlugins;
+    private resolvePlugin;
+    private runOrFail;
+    private runBinary;
+    private resolveBinary;
+}
+export {};

package/dist/BuildApplication.js

@@ -0,0 +1,251 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BuildApplication = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+function timestamp() {
+    return new Date().toISOString().replace(/[-:TZ.]/g, "");
+}
+function normalizePackageWebframezPlugins(value) {
+    if (!value) {
+        return [];
+    }
+    if (typeof value === "string") {
+        return [value];
+    }
+    if (Array.isArray(value)) {
+        return value.filter((entry) => typeof entry === "string");
+    }
+    if (typeof value.plugin === "string") {
+        return [value.plugin];
+    }
+    if (Array.isArray(value.plugins)) {
+        return value.plugins.filter((entry) => typeof entry === "string");
+    }
+    return [];
+}
+class BuildApplication {
+    constructor(projectRoot, config, options) {
+        var _a;
+        this.projectRoot = projectRoot;
+        this.config = config;
+        this.outDir = node_path_1.default.resolve(projectRoot, options.outDir || ((_a = config.build) === null || _a === void 0 ? void 0 : _a.dir) || "build");
+        this.buildId = timestamp();
+        this.buildRoot = node_path_1.default.resolve(projectRoot, ".webframez-build");
+        this.stagingDir = node_path_1.default.join(this.buildRoot, `.building-${this.buildId}`);
+    }
+    run() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const context = this.createContext();
+            const plugins = this.loadPlugins();
+            yield promises_1.default.rm(this.stagingDir, { recursive: true, force: true });
+            yield promises_1.default.mkdir(this.stagingDir, { recursive: true });
+            try {
+                yield this.callHook(plugins, "beforeBuild", context);
+                yield this.runTypescriptBuild(context);
+                yield this.callHook(plugins, "afterTypescriptBuild", context);
+                yield this.copyRuntimeFiles();
+                yield this.callHook(plugins, "afterRuntimeFilesCopied", context);
+                yield this.callHook(plugins, "buildAssets", context);
+                yield this.validateCoreBuild();
+                yield this.callHook(plugins, "validateBuild", context);
+                yield this.promoteBuild();
+                console.log(`[webframez] Build ready: ${node_path_1.default.relative(this.projectRoot, this.outDir) || this.outDir}`);
+            }
+            catch (error) {
+                yield promises_1.default.rm(this.stagingDir, { recursive: true, force: true });
+                throw error;
+            }
+        });
+    }
+    createContext() {
+        return {
+            projectRoot: this.projectRoot,
+            stagingDir: this.stagingDir,
+            outDir: this.outDir,
+            config: this.config,
+            run: (binaryName, args, envAdditions) => this.runBinary(binaryName, args, envAdditions),
+        };
+    }
+    callHook(plugins, hookName, context) {
+        return __awaiter(this, void 0, void 0, function* () {
+            for (const plugin of plugins) {
+                const hook = plugin[hookName];
+                if (typeof hook !== "function") {
+                    continue;
+                }
+                console.log(`[webframez] ${plugin.name || "plugin"}:${String(hookName)}`);
+                yield hook(context);
+            }
+        });
+    }
+    runTypescriptBuild(context) {
+        var _a;
+        const tsconfig = node_path_1.default.resolve(this.projectRoot, ((_a = this.config.build) === null || _a === void 0 ? void 0 : _a.tsconfig) || "tsconfig.json");
+        return this.runOrFail(context, "tsc", ["-p", tsconfig, "--outDir", this.stagingDir]);
+    }
+    copyRuntimeFiles() {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const runtimeFiles = ((_a = this.config.build) === null || _a === void 0 ? void 0 : _a.runtimeFiles) || [
+                { from: ".env", optional: true },
+                { from: "storage", optional: true },
+                "node_modules",
+            ];
+            for (const entry of runtimeFiles) {
+                const from = typeof entry === "string" ? entry : entry.from;
+                const to = typeof entry === "string" ? entry : entry.to || entry.from;
+                const optional = typeof entry === "string" ? false : entry.optional === true;
+                const sourcePath = node_path_1.default.resolve(this.projectRoot, from);
+                const targetPath = node_path_1.default.resolve(this.stagingDir, to);
+                if (!node_fs_1.default.existsSync(sourcePath)) {
+                    if (optional) {
+                        continue;
+                    }
+                    throw new Error(`Runtime file does not exist: ${from}`);
+                }
+                yield promises_1.default.rm(targetPath, { recursive: true, force: true });
+                yield promises_1.default.mkdir(node_path_1.default.dirname(targetPath), { recursive: true });
+                yield promises_1.default.cp(sourcePath, targetPath, {
+                    recursive: true,
+                    dereference: false,
+                });
+            }
+            for (const prunePath of ((_b = this.config.build) === null || _b === void 0 ? void 0 : _b.prunePaths) || []) {
+                yield promises_1.default.rm(node_path_1.default.resolve(this.stagingDir, prunePath), { recursive: true, force: true });
+            }
+        });
+    }
+    validateCoreBuild() {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            const entry = ((_a = this.config.build) === null || _a === void 0 ? void 0 : _a.entry) || "app.js";
+            const entryPath = node_path_1.default.resolve(this.stagingDir, entry);
+            if (!node_fs_1.default.existsSync(entryPath)) {
+                throw new Error(`Build entry missing: ${entry}`);
+            }
+        });
+    }
+    promoteBuild() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const previousDir = node_path_1.default.join(this.buildRoot, `.previous-${this.buildId}`);
+            yield promises_1.default.mkdir(node_path_1.default.dirname(this.outDir), { recursive: true });
+            yield promises_1.default.rm(previousDir, { recursive: true, force: true });
+            let movedPrevious = false;
+            try {
+                if (node_fs_1.default.existsSync(this.outDir)) {
+                    yield promises_1.default.rename(this.outDir, previousDir);
+                    movedPrevious = true;
+                }
+                yield promises_1.default.rename(this.stagingDir, this.outDir);
+                yield promises_1.default.rm(previousDir, { recursive: true, force: true });
+            }
+            catch (error) {
+                if (movedPrevious && !node_fs_1.default.existsSync(this.outDir) && node_fs_1.default.existsSync(previousDir)) {
+                    yield promises_1.default.rename(previousDir, this.outDir);
+                }
+                throw error;
+            }
+        });
+    }
+    loadPlugins() {
+        var _a;
+        const plugins = [];
+        for (const pluginInput of ((_a = this.config.build) === null || _a === void 0 ? void 0 : _a.plugins) || []) {
+            const plugin = this.resolvePlugin(pluginInput, this.projectRoot);
+            if (plugin) {
+                plugins.push(plugin);
+            }
+        }
+        for (const pluginSpec of this.discoverPackagePlugins()) {
+            const plugin = this.resolvePlugin(pluginSpec.spec, pluginSpec.packageRoot);
+            if (plugin) {
+                plugins.push(plugin);
+            }
+        }
+        return plugins;
+    }
+    discoverPackagePlugins() {
+        const packageJsonPath = node_path_1.default.resolve(this.projectRoot, "package.json");
+        if (!node_fs_1.default.existsSync(packageJsonPath)) {
+            return [];
+        }
+        const packageJson = JSON.parse(node_fs_1.default.readFileSync(packageJsonPath, "utf-8"));
+        const dependencyNames = new Set([
+            ...Object.keys(packageJson.dependencies || {}),
+            ...Object.keys(packageJson.devDependencies || {}),
+            ...Object.keys(packageJson.peerDependencies || {}),
+        ]);
+        const discovered = [];
+        for (const dependencyName of dependencyNames) {
+            const dependencyPackageJsonPath = node_path_1.default.resolve(this.projectRoot, "node_modules", dependencyName, "package.json");
+            if (!node_fs_1.default.existsSync(dependencyPackageJsonPath)) {
+                continue;
+            }
+            const dependencyPackageJson = JSON.parse(node_fs_1.default.readFileSync(dependencyPackageJsonPath, "utf-8"));
+            for (const plugin of normalizePackageWebframezPlugins(dependencyPackageJson.webframez)) {
+                discovered.push({
+                    spec: plugin,
+                    packageRoot: node_path_1.default.dirname(dependencyPackageJsonPath),
+                });
+            }
+        }
+        return discovered;
+    }
+    resolvePlugin(pluginInput, baseDir) {
+        let pluginModule = pluginInput;
+        if (typeof pluginInput === "string") {
+            const pluginPath = pluginInput.startsWith(".")
+                ? node_path_1.default.resolve(baseDir, pluginInput)
+                : require.resolve(pluginInput, { paths: [this.projectRoot, baseDir] });
+            pluginModule = require(pluginPath);
+        }
+        const pluginFactoryOrObject = pluginModule.default || pluginModule.createPlugin || pluginModule;
+        const plugin = typeof pluginFactoryOrObject === "function" ? pluginFactoryOrObject(this.config) : pluginFactoryOrObject;
+        return plugin || null;
+    }
+    runOrFail(context, binaryName, args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const code = yield context.run(binaryName, args);
+            if (code !== 0) {
+                throw new Error(`${binaryName} exited with code ${code}`);
+            }
+        });
+    }
+    runBinary(binaryName, args, envAdditions = {}) {
+        const binaryPath = this.resolveBinary(binaryName);
+        return new Promise((resolve, reject) => {
+            const child = (0, node_child_process_1.spawn)(binaryPath, args, {
+                cwd: this.projectRoot,
+                stdio: "inherit",
+                shell: false,
+                env: Object.assign(Object.assign({}, process.env), envAdditions),
+            });
+            child.on("error", reject);
+            child.on("close", (code) => resolve(code || 0));
+        });
+    }
+    resolveBinary(name) {
+        const extension = process.platform === "win32" ? ".cmd" : "";
+        const localBinary = node_path_1.default.resolve(this.projectRoot, "node_modules", ".bin", `${name}${extension}`);
+        if (node_fs_1.default.existsSync(localBinary)) {
+            return localBinary;
+        }
+        return name;
+    }
+}
+exports.BuildApplication = BuildApplication;

package/dist/Cli.d.ts

@@ -0,0 +1 @@
+export declare function runWebframezCli(argv?: string[], projectRoot?: string): Promise<void>;

package/dist/Cli.js

@@ -0,0 +1,124 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWebframezCli = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const ConsoleApplication_1 = require("./ConsoleApplication");
+const BuildApplication_1 = require("./BuildApplication");
+function printHelp() {
+    console.log([
+        "webframez CLI",
+        "",
+        "Usage:",
+        "  webframez run [command] [options]",
+        "  webframez build [--dir=./build]",
+        "",
+        "Options:",
+        "  --config=webframez.config.ts",
+        "  --dir=./build-target-dir",
+    ].join("\n"));
+}
+function readOption(args, name) {
+    const prefix = `--${name}=`;
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (value === `--${name}`) {
+            return args[index + 1] || null;
+        }
+        if (value.startsWith(prefix)) {
+            return value.slice(prefix.length);
+        }
+    }
+    return null;
+}
+function registerTsNode(projectRoot) {
+    const tsNodeRegister = require.resolve("ts-node/register/transpile-only", {
+        paths: [projectRoot, __dirname],
+    });
+    require(tsNodeRegister);
+}
+function loadConfig(projectRoot, args) {
+    const configuredPath = readOption(args, "config");
+    const candidates = configuredPath
+        ? [configuredPath]
+        : ["webframez.config.ts", "webframez.config.js", "webframez.config.cjs"];
+    for (const candidate of candidates) {
+        const configPath = node_path_1.default.resolve(projectRoot, candidate);
+        if (!node_fs_1.default.existsSync(configPath)) {
+            continue;
+        }
+        if (configPath.endsWith(".ts")) {
+            registerTsNode(projectRoot);
+        }
+        const imported = require(configPath);
+        return imported.default || imported;
+    }
+    throw new Error("Missing webframez.config.ts");
+}
+function runConsole(projectRoot, cliArgs) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const config = loadConfig(projectRoot, cliArgs);
+        if (config.setup) {
+            yield config.setup({ mode: "console", projectRoot });
+        }
+        const app = new ConsoleApplication_1.ConsoleApplication();
+        const originalArgv = process.argv;
+        process.argv = [process.argv[0], "webframez", ...cliArgs];
+        try {
+            app.boot({
+                kernel: config.consoleKernel || config.kernelConsole || config.kernel,
+                config: config.config,
+                jobs: config.jobs,
+                datatables: config.datatables,
+                errorHandler: config.errorHandler,
+                onEnd: config.onEnd,
+            });
+        }
+        finally {
+            process.argv = originalArgv;
+        }
+    });
+}
+function runBuild(projectRoot, cliArgs) {
+    var _a;
+    return __awaiter(this, void 0, void 0, function* () {
+        const config = loadConfig(projectRoot, cliArgs);
+        if (config.setup) {
+            yield config.setup({ mode: "build", projectRoot });
+        }
+        const outDir = readOption(cliArgs, "dir") || ((_a = config.build) === null || _a === void 0 ? void 0 : _a.dir) || "build";
+        const app = new BuildApplication_1.BuildApplication(projectRoot, config, { outDir });
+        yield app.run();
+    });
+}
+function runWebframezCli(argv = process.argv.slice(2), projectRoot = process.cwd()) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const command = argv[0];
+        if (!command || command === "--help" || command === "-h" || command === "help") {
+            printHelp();
+            return;
+        }
+        if (command === "run") {
+            yield runConsole(projectRoot, argv.slice(1));
+            return;
+        }
+        if (command === "build" || command === "buid") {
+            yield runBuild(projectRoot, argv.slice(1));
+            return;
+        }
+        throw new Error(`Unknown webframez command: ${command}`);
+    });
+}
+exports.runWebframezCli = runWebframezCli;

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export * from "./Controller/Controller";
 export * from "./Database/Model";
 export * from "./Database/DBConnection";
 export * from "./ConsoleApplication";
+export * from "./BuildApplication";
 export * from "./LambdaApplication";
 export * from "./WebApplication";
 export * from "./Router/Route";

package/dist/index.js

@@ -27,6 +27,7 @@ __exportStar(require("./Controller/Controller"), exports);
 __exportStar(require("./Database/Model"), exports);
 __exportStar(require("./Database/DBConnection"), exports);
 __exportStar(require("./ConsoleApplication"), exports);
+__exportStar(require("./BuildApplication"), exports);
 __exportStar(require("./LambdaApplication"), exports);
 __exportStar(require("./WebApplication"), exports);
 __exportStar(require("./Router/Route"), exports);

package/dist/info.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebframezInfo = void 0;
 exports.WebframezInfo = {
-    version: "0.3.32",
+    version: "0.3.36",
 };

package/package.json

@@ -1,10 +1,13 @@
 {
     "name": "@webtypen/webframez-core",
-    "version": "0.3.35",
+    "version": "0.3.37",
     "description": "The core package of the typescript based webframez (web-framework) by webtypen.de",
     "homepage": "https://webtypen.de/",
     "license": "MIT",
     "main": "dist/index.js",
+    "bin": {
+        "webframez": "./bin/webframez.cjs"
+    },
     "author": {
         "name": "Benedict Romp",
         "email": "b.romp@webtypen.de",
@@ -19,8 +22,9 @@
     },
     "files": [
         "dist",
+        "bin",
         "README.md",
-        "AGENTS.md"
+        "agents"
     ],
     "scripts": {
         "build": "tsc",