@arkstack/common 0.5.2 → 0.5.3

package/dist/index.js

@@ -1,138 +1,54 @@
-import { Obj, str } from "@h3ravel/support";
-import { createJiti } from "jiti";
-import { createRequire } from "module";
-import path, { resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-import { readdirSync } from "fs";
+import { _ as ConfigLoader, a as env, c as nodeEnv, d as resolveRuntimeDir, f as resolveRuntimeModule, g as CONFIG_KEY, h as envLoader, i as discoverCommands, l as outputDir, m as EnvLoader, n as appUrl, o as importFile, p as toOutputPath, r as config, s as interopDefault, t as appKey, u as rebuildOutput, v as configLoader } from "./system-DUaI4u99.js";
+import { _ as Hash, c as abortIf, d as initializeGlobalContext, f as isClass, g as Exception, h as AppException, l as assertFound, m as RequestException, p as perPage, s as abort, u as getModel, v as Encryption } from "./utils-DLifcZWV.js";
+import { Hook as Hook$1 } from "@arkstack/foundry";
+import { Arkstack } from "@arkstack/contract";
+import { str } from "@h3ravel/support";
+import path from "node:path";
+import { ModelNotFoundException } from "arkormx";
 import { detect } from "detect-port";
 import pino from "pino";
 import chalk from "chalk";
-import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
-import { Secret, TOTP } from "otpauth";
-import { compare, genSalt, hash } from "bcryptjs";
-import { getUserConfig } from "arkormx";
+import { networkInterfaces } from "node:os";
 //#region src/lifecycle.ts
-const bindGracefulShutdown = (shutdown) => {
+const bindGracefulShutdown = (shutdown, defer) => {
+	if (defer) return;
 	[
 		"SIGINT",
 		"SIGTERM",
 		"SIGQUIT"
 	].forEach((signal) => {
 		process.on(signal, async () => {
+			if (Hook$1.has("shutdown", "before")) Hook$1.get("shutdown", "after", {});
 			await shutdown();
 		});
 	});
 };
 //#endregion
-//#region src/system.ts
-/**
-* Read the .env file
-*
-* @param env
-* @param def
-* @returns
-*/
-const env = (env, defaultValue) => {
-	let val = process.env[env] ?? "";
-	if ([
-		true,
-		"true",
-		"on",
-		false,
-		"false",
-		"off"
-	].includes(val)) val = [
-		true,
-		"true",
-		"on"
-	].includes(val);
-	if (!isNaN(Number(val)) && typeof val !== "boolean" && typeof val !== "undefined" && val !== "") val = Number(val);
-	if (val === "") val = void 0;
-	if (val === "null") val = null;
-	val ??= defaultValue;
-	return val;
-};
-/**
-* Build the app url
-*
-* @param link
-* @returns
-*/
-const appUrl = (link) => {
-	const port = env("PORT") || "3000";
-	const defaultUrl = `http://localhost:${port}`;
-	const appUrl = env("APP_URL") ?? defaultUrl;
-	try {
-		const url = new URL(appUrl);
-		if (url.port || url.hostname === "localhost") url.port = port;
-		const baseUrl = url.toString().replace(/\/$/, "");
-		if (link) return `${baseUrl}${`/${link.replace(/^\/+/, "")}`}`;
-		return baseUrl;
-	} catch {
-		return link ? `${defaultUrl}/${link.replace(/^\/+/, "")}` : defaultUrl;
-	}
-};
-/**
-* Gets the application configuration.
-* 
-* @param key             The configuration key to retrieve.
-* @param defaultValue    The default value to return if the key is not found.
-* @returns               The configuration value.
-*/
-const config = (key, defaultValue) => {
-	const dist = path.relative(process.cwd(), outputDir());
-	const require = createRequire(import.meta.url);
-	const config = readdirSync(path.join(process.cwd(), `${dist}/config`), { withFileTypes: true }).filter((file) => {
-		if (file.name.includes("middleware") && globalThis.arkctx.runtime === "CLI") return false;
-		return file.isFile() && (file.name.endsWith(".js") || file.name.endsWith(".ts"));
-	}).reduce((configs, file) => {
-		const configName = path.basename(file.name, path.extname(file.name));
-		configs[configName] = require(path.join(file.parentPath, file.name)).default(globalThis.app());
-		return configs;
-	}, {});
-	if (key) return Obj.get(config, key, defaultValue);
-	return config;
-};
-/**
-* Gets the current Node environment (development or production).
-* 
-* @returns 
-*/
-const nodeEnv = () => {
-	let envValue = env("NODE_ENV", "development");
-	if (envValue !== "development" && envValue !== "production") envValue = "development";
-	return envValue === "production" ? "prod" : "dev";
-};
+//#region src/network.ts
 /**
-* Gets the output directory for the application based on the current environment.
+* Boots the app using an available port close to the requested port 
+*when requested port is not available
 * 
-* @param cwd  The current working directory (optional, defaults to process.cwd()).
-* @returns 
+* @param boot 
+* @param preferredPort 
+* @param app 
+* @param defer 
 */
-const outputDir = (cwd = process.cwd()) => {
-	const NODE_ENV = nodeEnv();
-	const output = {
-		dev: env("OUTPUT_DIR_DEV", ".arkstack/build"),
-		prod: env("OUTPUT_DIR", "dist")
-	};
-	return path.isAbsolute(output[NODE_ENV] ?? output.dev) ? output[NODE_ENV] ?? output.dev : path.join(cwd, output[NODE_ENV] ?? output.dev);
-};
-const importFile = async (filePath) => {
-	const resolvedPath = resolve(filePath);
-	return await createJiti(pathToFileURL(resolvedPath).href, {
-		interopDefault: false,
-		tsconfigPaths: true
-	}).import(resolvedPath);
-};
-//#endregion
-//#region src/network.ts
-const bootWithDetectedPort = async (boot, preferredPort = 3e3, app) => {
+const bootWithDetectedPort = async (boot, preferredPort = 3e3, app, defer) => {
+	const port = await detect(preferredPort);
+	if (Hook$1.has("boot", "before")) Hook$1.get("boot", "before", port, app);
 	if (app && !globalThis.app) globalThis.app = () => app;
 	globalThis.env = env;
 	globalThis.config = config;
 	globalThis.str = str;
+	globalThis.abort = abort;
+	globalThis.abortIf = abortIf;
+	globalThis.assertFound = assertFound;
 	globalThis.arkctx = { runtime: "HTTP" };
-	await boot(await detect(preferredPort));
+	await boot(port);
+	await initializeGlobalContext();
+	bindGracefulShutdown(async () => await app?.shutdown(), defer);
+	if (Hook$1.has("boot", "after")) Hook$1.get("boot", "after", port, app);
 };
 const renderError = ({ message = "An unexpected error occurred.", stack, title, code = 500 }) => {
 	title = {
@@ -180,56 +96,6 @@ const loadPrototypes = () => {
 	};
 };
 //#endregion
-//#region src/Exceptions/Exception.ts
-var Exception = class extends Error {
-	name;
-	constructor(message, options) {
-		super(message, options);
-		this.name = "Exception";
-	}
-};
-//#endregion
-//#region src/Exceptions/AppException.ts
-var AppException = class extends Exception {
-	errors = void 0;
-	statusCode;
-	constructor(message, statusCode = 400, options) {
-		super(message, options);
-		this.statusCode = statusCode;
-	}
-};
-//#endregion
-//#region src/Exceptions/RequestException.ts
-var RequestException = class RequestException extends AppException {
-	statusCode;
-	constructor(message, statusCode = 400, options) {
-		super(message, statusCode, options);
-		this.statusCode = statusCode;
-	}
-	/**
-	* Asserts that a value is not null or undefined. 
-	* 
-	* @param value 
-	* @param message 
-	* @param code 
-	* @throws {RequestException} Throws if the value is null or undefined.
-	*/
-	static assertNotEmpty(value, message, code = 404) {
-		if (!value) throw new RequestException(message, code);
-	}
-	/**
-	* Asserts that a boolean condition is true. 
-	* 
-	* @param boolean 
-	* @param message 
-	* @param code 
-	* @throws {RequestException} Throws if the boolean condition is true.
-	*/
-	static abortIf(boolean, message, code) {
-		if (boolean) throw new RequestException(message, code);
-	}
-};
-//#endregion
 //#region src/ErrorHandler.ts
 var ErrorHandler = class ErrorHandler {
 	static loggerCache = /* @__PURE__ */ new Map();
@@ -244,7 +110,7 @@ var ErrorHandler = class ErrorHandler {
 		return Number.isInteger(code) && code >= 100 && code < 600 ? code : fallback;
 	}
 	static getErrorLogger() {
-		const destination = path.resolve(process.cwd(), "storage/logs/error.log");
+		const destination = path.resolve(Arkstack.rootDir(), "storage/logs/error.log");
 		if (!ErrorHandler.loggerCache.has(destination)) ErrorHandler.loggerCache.set(destination, pino({ level: "error" }, pino.destination({
 			dest: destination,
 			mkdir: true,
@@ -283,7 +149,12 @@ var ErrorHandler = class ErrorHandler {
 		return typeof ErrorHandler.toErrorShape(error)?.errors !== "undefined";
 	}
 	static isModelNotFoundError(error) {
-		return typeof ErrorHandler.toErrorShape(error)?.getModelName === "function";
+		const candidate = ErrorHandler.toErrorShape(error);
+		if (error.cause && error.cause instanceof ModelNotFoundException) {
+			error.getModelName = error.cause.getModelName;
+			return true;
+		}
+		return typeof candidate?.getModelName === "function" || error instanceof ModelNotFoundException;
 	}
 	static shouldHideStack() {
 		const value = process.env.HIDE_ERROR_STACK;
@@ -319,6 +190,7 @@ var ErrorHandler = class ErrorHandler {
 			delete payload.errors;
 			delete payload.stack;
 		}
+		if (detailedError?.body && typeof detailedError.body === "object") Object.assign(payload, detailedError.body);
 		return payload;
 	}
 	static logUnhandledError(err, request, message) {
@@ -341,6 +213,54 @@ const shouldLogError = ErrorHandler.shouldLogError;
 const createErrorPayload = ErrorHandler.createErrorPayload;
 const logUnhandledError = ErrorHandler.logUnhandledError;
 //#endregion
+//#region src/Publisher.ts
+const REGISTRY_KEY = Symbol.for("arkstack.publishables");
+/**
+* Registry of artifacts packages want to publish into the consuming application.
+*
+* Packages call {@link Publisher.publishes} from their `setup` module so that
+* `ark publish` can copy the artifacts (migrations, config stubs, assets, …)
+* into the app. The registry is backed by a global symbol so it stays a single
+* shared instance even across duplicated module copies.
+*/
+var Publisher = class {
+	/** The shared, global-symbol-backed registry of publishable groups. */
+	static get registry() {
+		return globalThis[REGISTRY_KEY] ??= [];
+	}
+	/**
+	* Register artifacts a package wants to publish into the application.
+	*
+	* @example
+	* ```ts
+	* Publisher.publishes({
+	*     package: '@arkstack/cache',
+	*     tag: 'cache-migrations',
+	*     entries: [{ from: join(here, '../stubs/...'), to: 'src/database/migrations/...' }],
+	* })
+	* ```
+	*
+	* @param group  The publishable group to register.
+	*/
+	static publishes(group) {
+		this.registry.push(group);
+	}
+	/**
+	* Read the registered publishable groups, optionally filtered by package or
+	* tag.
+	*
+	* @param filter  Restrict the result to a package and/or tag.
+	* @returns       The matching publishable groups.
+	*/
+	static publishables(filter = {}) {
+		return this.registry.filter((group) => (!filter.package || group.package === filter.package) && (!filter.tag || group.tag === filter.tag));
+	}
+	/** Remove every registered publishable group (primarily for tests). */
+	static clear() {
+		this.registry.length = 0;
+	}
+};
+//#endregion
 //#region src/Logger.ts
 var Console = class {
 	static log = (...args) => Logger.log(args.map((e) => [e, "white"]));
@@ -553,30 +473,30 @@ var Hook = class {
 	* @param name 
 	* @param value 
 	*/
-	static set = (name, hook) => {
+	static set(name, hook) {
 		const oldhook = this.hooks.get(name) ?? {};
 		this.hooks.set(name, {
 			...oldhook,
 			...hook
 		});
-	};
+	}
 	/**
 	* Check if a hook is defined by name
 	* 
 	* @param name 
 	*/
-	static has = (name, pos) => {
+	static has(name, pos) {
 		if (pos && this.hooks.has(name)) return Boolean(this.get(name, pos));
 		return this.hooks.has(name);
-	};
-	static get(name, pos) {
+	}
+	static get(name, pos, ...args) {
 		const hook = this.hooks.get(name);
 		if (!hook) return void 0;
-		if (pos !== void 0) {
-			if (!hook[pos]) return void 0;
-			return hook[pos];
-		}
-		return hook;
+		if (pos === void 0) return hook;
+		const fn = hook[pos];
+		if (!fn) return void 0;
+		if (args.length > 0) return fn(...args);
+		return fn;
 	}
 	/**
 	* Retrieve all defined hooks
@@ -593,7 +513,7 @@ var Hook = class {
 	* 
 	* @param name 
 	*/
-	static unset = (name, pos) => {
+	static unset(name, pos) {
 		if (name && this.hooks.has(name)) {
 			if (pos !== void 0) {
 				const hook = this.get(name);
@@ -603,7 +523,7 @@ var Hook = class {
 			}
 			this.hooks.delete(name);
 		} else this.clear();
-	};
+	}
 	/**
 	* Clear all the defined hooks
 	*/
@@ -612,107 +532,41 @@ var Hook = class {
 	};
 };
 //#endregion
-//#region src/utils/encryption.ts
-var Encryption = class {
-	static algorithm = "aes-256-gcm";
-	static getKey() {
-		const secret = env("TWO_FACTOR_ENCRYPTION_KEY");
-		if (!secret) throw new Error("TWO_FACTOR_ENCRYPTION_KEY is required to use two-factor authentication");
-		return createHash("sha256").update(secret).digest();
-	}
-	static encrypt(value) {
-		const iv = randomBytes(12);
-		const cipher = createCipheriv(this.algorithm, this.getKey(), iv);
-		const ciphertext = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
-		return [
-			iv,
-			cipher.getAuthTag(),
-			ciphertext
-		].map((part) => part.toString("base64url")).join(":");
-	}
-	static decrypt(payload) {
-		const [iv, authTag, ciphertext] = payload.split(":");
-		if (!iv || !authTag || !ciphertext) throw new Error("Invalid encrypted payload format");
-		const decipher = createDecipheriv(this.algorithm, this.getKey(), Buffer.from(iv, "base64url"));
-		decipher.setAuthTag(Buffer.from(authTag, "base64url"));
-		return Buffer.concat([decipher.update(Buffer.from(ciphertext, "base64url")), decipher.final()]).toString("utf8");
-	}
-};
-//#endregion
-//#region src/utils/hash.ts
-var Hash = class {
-	/**
-	* Hash a value using bcrypt
-	* 
-	* @param value 
-	* @returns 
-	*/
-	static async make(value) {
-		return await hash(value, await genSalt(10));
-	}
-	/**
-	* Verify a value against a hashed value
-	* 
-	* @param value 
-	* @param hashedValue 
-	* @returns 
-	*/
-	static async verify(value, hashedValue) {
-		return await compare(value, hashedValue);
-	}
-	/**
-	* Generate a one-time password (OTP) using TOTP algorithm
-	* 
-	* @param digits    The number of digits for the OTP, default is 6.
-	* @param label     A label to identify the OTP, can be an email or phone number.
-	* @param period    Interval of time for which a token is valid, in seconds.
-	* @returns 
-	*/
-	static otp(digits = 6, label = "Alice", period = 30) {
-		return new TOTP({
-			label,
-			digits,
-			issuer: env("APP_NAME", "Roseed"),
-			algorithm: "SHA1",
-			period,
-			secret: "US3WHSG7X5KAPV27VANWKQHF3SH3HULL"
-		});
-	}
-	static totp(secret, label, issuer = env("APP_NAME", "Roseed"), period = 30) {
-		return new TOTP({
-			issuer,
-			label,
-			algorithm: "SHA1",
-			digits: 6,
-			period,
-			secret: Secret.fromBase32(secret)
-		});
-	}
+//#region src/tls.ts
+let devCertCache;
+/**
+* Generate (and cache) an in-memory self-signed TLS certificate for local HTTPS
+* development. `selfsigned` is imported lazily so it's only loaded when secure
+* dev mode is actually used.
+*
+* The certificate is not trusted by browsers (expect the usual self-signed
+* warning); it exists only so the dev server can speak HTTPS.
+*
+* @param host  The common name for the certificate (defaults to `localhost`).
+*/
+const devTlsCredentials = async (host = "localhost") => {
+	if (devCertCache) return devCertCache;
+	const mod = await import("selfsigned");
+	const pems = (mod.default ?? mod).generate([{
+		name: "commonName",
+		value: host
+	}], {
+		days: 365,
+		keySize: 2048,
+		algorithm: "sha256"
+	});
+	devCertCache = {
+		key: pems.private,
+		cert: pems.cert
+	};
+	return devCertCache;
 };
-//#endregion
-//#region src/utils/helpers.ts
 /**
-* Determine the number of items to return per page based on the provided query parameters.
-* 
-* @param query 
-* @returns 
+* The machine's first non-internal IPv4 address — its address on the local
+* network — or `undefined` when only loopback interfaces are available.
 */
-const perPage = (query) => {
-	const requestedPerPage = Number(query.limit ?? query.perPage ?? 15);
-	return Number.isFinite(requestedPerPage) && requestedPerPage > 0 ? Math.min(requestedPerPage, 50) : 15;
+const localNetworkAddress = () => {
+	for (const list of Object.values(networkInterfaces())) for (const net of list ?? []) if (net.family === "IPv4" && !net.internal) return net.address;
 };
-async function getModel(modelName) {
-	const resolveModelExport = (module, modelName) => {
-		if (!isModelModule(module)) return module;
-		return module.default ?? module[modelName] ?? module;
-	};
-	const isModelModule = (value) => typeof value === "object" && value !== null;
-	const modelPath = getUserConfig().paths?.models || "./src/models";
-	const model = resolveModelExport(await importFile(path.join(path.isAbsolute(modelPath) ? modelPath : path.join(process.cwd(), modelPath), modelName)), path.basename(modelName, path.extname(modelName)));
-	if (typeof model !== "function") throw new Error(`Model "${modelName}" not found`);
-	return model;
-}
 //#endregion
-export { AppException, Encryption, ErrorHandler, Exception, Hash, Hook, Logger, RequestException, appUrl, bindGracefulShutdown, bootWithDetectedPort, config, createErrorPayload, env, getErrorLogger, getModel, getPrimaryError, getValidationErrors, importFile, isModelNotFoundError, isValidationError, loadPrototypes, logUnhandledError, nodeEnv, normalizeStatusCode, outputDir, perPage, renderError, serializeError, shouldHideStack, shouldLogError, toErrorShape };
-
-//# sourceMappingURL=index.js.map
+export { AppException, CONFIG_KEY, ConfigLoader, Encryption, EnvLoader, ErrorHandler, Exception, Hash, Hook, Logger, Publisher, RequestException, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, configLoader, createErrorPayload, devTlsCredentials, discoverCommands, env, envLoader, getErrorLogger, getModel, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, localNetworkAddress, logUnhandledError, nodeEnv, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolveRuntimeDir, resolveRuntimeModule, serializeError, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };