@webtypen/webframez-core 0.3.85 → 0.3.93

package/README.md

@@ -9,6 +9,7 @@ This README reflects the current API in this repository and focuses on:
 - DataBuilder
 - Console Commands
 - Queue and Jobs
+- Structured error reporting and execution context
 - Session, browser and cross-instance authentication
 
 ## Requirements
@@ -680,6 +681,26 @@ app.boot({
 - `write`, `writeln`, `info`, `warning`, `success`, `error`
 - progress helpers (`progress`, `progressIncrement`, `progressFinish`)
 
+## Error reporting and execution context (0.3.88+)
+
+`ErrorHandler.onReport(listener)` observes reported errors independently of the
+existing logging handlers and returns an unsubscribe function. Replacing handlers
+with `setHandler` / `setHandlers` does not remove these subscriptions.
+`ErrorHandler.withContext(context, callback)` propagates request, command and queue
+context through asynchronous work; a distinct `operationId` separates executions
+and prevents duplicate reports of the same Error within one execution.
+
+Core reports errors at Router/middleware, ApiFunction, application boot, Console
+and queue boundaries. Unexpected HTTP failures receive a generic 500 response;
+failed console commands set a nonzero exit code. Error events include application
+type, process identity and the available route/API/command/job/worker context.
+
+Use `@webtypen/webframez-errors` for redaction, bounded durable buffering and
+Server Manager delivery. Core itself does not implement Manager authentication or
+transport. The SDK excludes expected errors, including HTTP 4xx, by default.
+See [Error reporting and execution context](docs/errors.md) for the subscription
+API, explicit reporting and the distinction between error events and job status.
+
 ## Queue and Jobs
 
 Queue workers run through console commands and use `queue_jobs` storage.
@@ -745,6 +766,29 @@ export default {
 };
 ```
 
+### Retry limits and long-running polling
+
+Console workers and the embedded `Queue` share finite limits. Defaults are
+`maxAttempts: 100`, `maxErrorRetries: 3`, `maxAgeSeconds: 86400` and
+`maxFinalizationAttempts: 3`; error retries require `error.retryable === true`.
+**Every execution counts toward maxAttempts, including successful status polls
+that return executeAgain().** Polling does not consume maxErrorRetries.
+
+Configure `queue.retry`, `static retry`, `queue.jobs[JobClass].retry` or the job's
+asynchronous `retryPolicy(job)` override. A policy can define delay stages and an
+absolute `deadlineAt`; both the job age and that deadline are enforced. Stages set
+minimum delays and also cap attempts at their summed attempt count.
+
+Long-running provider workflows such as SEPA settlement need an application-owned
+policy covering their settlement window. A generic 24-hour / 100-execution default
+is not a payment settlement deadline. Existing histories count after upgrades, so
+an older polling job can exhaust a newly introduced limit before its next handler
+call. Updating a policy does not reactivate failed jobs or reset their histories.
+
+See [Managed workers, retry policies and safe recovery](docs/queue-workers.md)
+for precedence, stages, finalization hooks and recovery without repeating external
+side effects. Core never automatically creates, cancels or retries a payment.
+
 ### Built-in Queue Commands
 
 - `queue:start`
@@ -938,3 +982,18 @@ Lifecycle hooks skip event normalization when no listeners are registered. Use
 Registered handlers retain their ordered, awaited execution and snapshot behavior.
 The router applies this check before building telemetry payloads. Middleware keeps
 its existing `next`/`reject` callback contract.
+
+### Persistent build caches
+
+Set `build.cacheDirectory` or `WEBFRAMEZ_BUILD_CACHE_DIRECTORY` to opt into
+incremental TypeScript compilation. Compiler output and build information live
+outside the published build. Resolved configuration, compiler version and source
+file list invalidate the cache; failed compilation discards it and leaves the
+previous successful release intact. Each directory requires an exclusive build
+owner. Linux runtime copies use independent reflinks where supported.
+
+Metro consumers can call
+`require('@webtypen/webframez-core/build-cache').configureMetroCache(config)`.
+It applies `WEBFRAMEZ_BUILD_MAX_WORKERS` and `WEBFRAMEZ_METRO_CACHE_DIRECTORY`,
+preserving Expo's FileStore implementation and supporting old/new file-map option
+names. Do not pass Expo `--clear` on normal cached builds.

package/build-cache.d.ts

@@ -0,0 +1 @@
+export function configureMetroCache<T extends {cacheStores?: any; maxWorkers?: number}>(config:T, env?:Record<string,string | undefined>):T;

package/build-cache.js

@@ -0,0 +1,30 @@
+const path = require("node:path");
+const fs = require("node:fs");
+
+/** Preserve the platform's FileStore subclass (including Expo CSS handling). */
+function configureMetroCache(config, env = process.env) {
+    if (env.WEBFRAMEZ_BUILD_MAX_WORKERS !== undefined) {
+        const workers = Number(env.WEBFRAMEZ_BUILD_MAX_WORKERS);
+        if (!Number.isInteger(workers) || workers < 1 || workers > 64) throw new Error("Invalid WEBFRAMEZ_BUILD_MAX_WORKERS");
+        config.maxWorkers = workers;
+    }
+    if (!env.WEBFRAMEZ_METRO_CACHE_DIRECTORY) return config;
+    const root = path.resolve(env.WEBFRAMEZ_METRO_CACHE_DIRECTORY);
+    const relocate = stores => stores.map((store, index) => {
+        // Leave remote and custom stores untouched; their constructors need other options.
+        if (!store || typeof store._root !== "string") return store;
+        return new store.constructor({root:path.join(root, `transform-${index}`)});
+    });
+    const stores = config.cacheStores;
+    config.cacheStores = typeof stores === "function" ? cache => relocate(stores(cache)) : relocate(stores || []);
+    // Some Metro releases accept these options at runtime but reject them in
+    // their schema. Only extend a field exposed by the caller/default config.
+    const field = "fileMapCacheDirectory" in config ? "fileMapCacheDirectory" : "hasteMapCacheDirectory" in config ? "hasteMapCacheDirectory" : null;
+    if (field) {
+        config[field] = path.join(root, "file-map");
+        fs.mkdirSync(config[field], {recursive:true});
+    }
+    return config;
+}
+
+module.exports = {configureMetroCache};

package/dist/Ai/AiTypes.d.ts

@@ -4,7 +4,10 @@ export type KernelAiApiRegistrations = {
     middleware?: string[];
     [key: string]: any;
 };
-export type KernelAiRegistrations = {
+/** Optional packages augment this map without introducing a Core -> AI dependency. */
+export interface KernelAiExtensions {
+}
+export type KernelAiRegistrations = KernelAiExtensions & {
     agents?: KernelAiAgentRegistration[];
     api?: KernelAiApiRegistrations;
 };

package/dist/Api/ApiScopeRegistry.js

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiScopeRegistry = void 0;
+const ErrorHandler_1 = require("../ErrorHandling/ErrorHandler");
 const Route_1 = require("../Router/Route");
 const ApiFunctionUtils_1 = require("./ApiFunctionUtils");
 function getModuleInstances(modulesLoader) {
@@ -92,14 +93,15 @@ class ApiScopeRegistryFacade {
                 const context = yield (0, ApiFunctionUtils_1.runApiScopeRegistrationMiddleware)(registration, req, res);
                 const paramsSource = (func.requestMethod || req.method).toUpperCase() === "GET" ? req.query : req.body;
                 const params = (0, ApiFunctionUtils_1.validateApiFunctionParams)(func.params || {}, paramsSource || {});
-                const result = yield func.handle({ context, params, request: req, response: res });
+                const result = yield ErrorHandler_1.ErrorHandler.withContext({ api: { scope: registration.scopeClass.name, function: func.key } }, () => func.handle({ context, params, request: req, response: res }));
                 return (0, ApiFunctionUtils_1.toApiFunctionHttpResult)(res, result);
             }
             catch (error) {
+                yield ErrorHandler_1.ErrorHandler.report(error, { scope: "controller", source: "api.function", api: { scope: registration.scopeClass.name, function: func.key } });
                 const statusCode = error && error.statusCode && !isNaN(parseInt(error.statusCode)) ? parseInt(error.statusCode) : 500;
                 return res.status(statusCode).send({
                     status: "error",
-                    message: (0, ApiFunctionUtils_1.getApiErrorMessage)(error),
+                    message: ErrorHandler_1.ErrorHandler.publicMessage(error, statusCode),
                 });
             }
         });

package/dist/BuildApplication.d.ts

@@ -21,6 +21,7 @@ export type WebframezBuildPlugin = {
 export type WebframezBuildConfig = {
     dir?: string;
     tsconfig?: string;
+    cacheDirectory?: string;
     entry?: string;
     runtimeFiles?: WebframezBuildRuntimeFile[];
     prunePaths?: string[];
@@ -59,6 +60,7 @@ export declare class BuildApplication {
     private createContext;
     private callHook;
     private runTypescriptBuild;
+    private copyTree;
     private copyRuntimeFiles;
     private validateCoreBuild;
     private promoteBuild;

package/dist/BuildApplication.js

@@ -17,6 +17,9 @@ 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");
+const node_util_1 = require("node:util");
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const exec = (0, node_util_1.promisify)(node_child_process_1.execFile);
 function timestamp() {
     return new Date().toISOString().replace(/[-:TZ.]/g, "");
 }
@@ -117,9 +120,46 @@ class BuildApplication {
         });
     }
     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]);
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const tsconfig = node_path_1.default.resolve(this.projectRoot, ((_a = this.config.build) === null || _a === void 0 ? void 0 : _a.tsconfig) || "tsconfig.json");
+            const configuredCache = ((_b = this.config.build) === null || _b === void 0 ? void 0 : _b.cacheDirectory) || process.env.WEBFRAMEZ_BUILD_CACHE_DIRECTORY;
+            if (!configuredCache)
+                return this.runOrFail(context, "tsc", ["-p", tsconfig, "--outDir", this.stagingDir]);
+            const root = node_path_1.default.resolve(this.projectRoot, configuredCache);
+            const scope = node_crypto_1.default.createHash("sha256").update(node_path_1.default.relative(root, tsconfig)).digest("hex").slice(0, 24);
+            const cache = node_path_1.default.join(root, "typescript", scope);
+            // Resolved options and the complete source list invalidate deleted/renamed outputs.
+            const { stdout: config } = yield exec(this.resolveBinary("tsc"), ["-p", tsconfig, "--outDir", node_path_1.default.join(cache, "output"), "--showConfig"], { cwd: this.projectRoot, maxBuffer: 8 * 1024 * 1024 });
+            const { stdout: version } = yield exec(this.resolveBinary("tsc"), ["--version"], { cwd: this.projectRoot });
+            const key = node_crypto_1.default.createHash("sha256").update(config).update(version).digest("hex");
+            const previous = yield promises_1.default.readFile(node_path_1.default.join(cache, "key"), "utf8").catch(() => "");
+            if (previous !== key)
+                yield promises_1.default.rm(cache, { recursive: true, force: true });
+            const output = node_path_1.default.join(cache, "output");
+            yield promises_1.default.mkdir(output, { recursive: true });
+            try {
+                yield this.runOrFail(context, "tsc", ["-p", tsconfig, "--outDir", output, "--incremental", "--tsBuildInfoFile", node_path_1.default.join(cache, "build.tsbuildinfo")]);
+                yield this.copyTree(output, this.stagingDir);
+                yield promises_1.default.writeFile(node_path_1.default.join(cache, "key"), key);
+            }
+            catch (error) {
+                yield promises_1.default.rm(cache, { recursive: true, force: true });
+                throw error;
+            }
+        });
+    }
+    copyTree(source, target) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (process.platform === "linux") {
+                yield promises_1.default.mkdir(target, { recursive: true });
+                // Reflinks are independent copies; never share writable hardlinks with dependencies.
+                yield exec("cp", ["-a", "--reflink=auto", "--", source + "/.", target], { maxBuffer: 65536 });
+            }
+            else {
+                yield promises_1.default.cp(source, target, { recursive: true, dereference: false, mode: node_fs_1.default.constants.COPYFILE_FICLONE });
+            }
+        });
     }
     copyRuntimeFiles() {
         var _a, _b;
@@ -143,10 +183,10 @@ class BuildApplication {
                 }
                 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,
-                });
+                if ((yield promises_1.default.lstat(sourcePath)).isDirectory())
+                    yield this.copyTree(sourcePath, targetPath);
+                else
+                    yield promises_1.default.cp(sourcePath, targetPath, { dereference: false, mode: node_fs_1.default.constants.COPYFILE_FICLONE });
             }
             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 });

package/dist/Commands/ConsoleCommand.d.ts

@@ -21,6 +21,7 @@ export declare class ConsoleCommand {
     });
     handle(): Promise<void>;
     handleSystem(): Promise<void>;
+    private handleSystemScoped;
     finallySystem(): Promise<void>;
     getArguments(): string[];
     getOptions(): {

package/dist/Commands/ConsoleCommand.js

@@ -34,6 +34,11 @@ class ConsoleCommand {
         return __awaiter(this, void 0, void 0, function* () { });
     }
     handleSystem() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return ErrorHandler_1.ErrorHandler.withContext({ applicationType: "ConsoleApplication", scope: "command", operationId: WebframezHooks_1.WebframezHooks.createOperationId("command"), command: { signature: this.constructor.signature, className: this.constructor.name } }, () => this.handleSystemScoped());
+        });
+    }
+    handleSystemScoped() {
         return __awaiter(this, void 0, void 0, function* () {
             const commandSignature = String(this.constructor.signature || this.constructor.name || "command");
             const operationId = WebframezHooks_1.WebframezHooks.createOperationId("command");
@@ -62,6 +67,7 @@ class ConsoleCommand {
                 });
             }
             catch (e) {
+                process.exitCode = process.exitCode || 1;
                 yield WebframezHooks_1.WebframezHooks.emit("console.command.error", {
                     operationId,
                     name: commandSignature,