@arkstack/common 0.14.18 → 0.14.20

package/dist/system-DUaI4u99.js

@@ -0,0 +1,475 @@
+import { createJiti } from "jiti";
+import { existsSync, readdirSync } from "fs";
+import { Arkstack } from "@arkstack/contract";
+import { Arr, Obj, undot } from "@h3ravel/support";
+import { readdirSync as readdirSync$1 } from "node:fs";
+import { createRequire } from "module";
+import path, { resolve } from "node:path";
+import { config } from "dotenv";
+import { pathToFileURL } from "node:url";
+import { rm } from "node:fs/promises";
+import { spawn } from "node:child_process";
+//#region src/ConfigLoader.ts
+const CONFIG_KEY = Symbol("globalConfig");
+globalThis[CONFIG_KEY] = {};
+/**
+* Loads and resolves application configuration from the config directory.
+*
+* Config modules are read once (lazily) from the output directory and cached on
+* a global symbol, then queried by dot-path. A partial config object can also be
+* merged in at runtime.
+*/
+var ConfigLoader = class {
+	/** 
+	* The cached config store, shared across instances via a global symbol.
+	*/
+	get store() {
+		return globalThis[CONFIG_KEY];
+	}
+	set store(value) {
+		globalThis[CONFIG_KEY] = value;
+	}
+	/** 
+	* Read and cache config modules from the config directory on first use.
+	*/
+	load() {
+		if (Object.entries(this.store).length >= 1) return;
+		let files;
+		const require = createRequire(import.meta.url);
+		const configDir = this.resolveConfigDir();
+		try {
+			files = readdirSync$1(configDir, { 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"));
+			});
+		} catch {
+			files = [];
+		}
+		Object.assign(this.store, files.reduce((configs, file) => {
+			const configName = path.basename(file.name, path.extname(file.name));
+			try {
+				configs[configName] = require(path.join(file.parentPath, file.name)).default(typeof globalThis.app === "function" ? globalThis.app() : {});
+			} catch (error) {
+				console.warn(`[arkstack] Skipped config "${configName}": ${error.message}`);
+			}
+			return configs;
+		}, {}));
+	}
+	/**
+	* Resolve the directory to load config modules from.
+	*
+	* Prefers an explicit `CONFIG_PATH`, then the environment-selected output
+	* directory. Falls back to the other build output (`dist` ⇄
+	* `.arkstack/build`) so config still loads if the selected directory is
+	* missing or transiently emptied — e.g. a concurrent rebuild (`clean: true`)
+	* during a test run.
+	*/
+	resolveConfigDir() {
+		const root = Arkstack.rootDir();
+		const explicit = env("CONFIG_PATH");
+		if (explicit) return explicit;
+		const candidates = [
+			path.join(outputDir(), "config"),
+			path.join(root, env("OUTPUT_DIR", "dist"), "config"),
+			path.join(root, env("OUTPUT_DIR_DEV", ".arkstack/build"), "config")
+		];
+		return candidates.find((dir) => {
+			try {
+				return readdirSync$1(dir).some((file) => file.endsWith(".js") || file.endsWith(".ts"));
+			} catch {
+				return false;
+			}
+		}) ?? candidates[0];
+	}
+	/**
+	* Resolve configuration: read a dot-path value, merge a partial config
+	* object, or return the whole config.
+	*
+	* @param key           Dot-path to read, or an object to merge in.
+	* @param defaultValue  Returned when a string key is not found.
+	*/
+	resolve(key, defaultValue) {
+		if (typeof globalThis.env === "undefined") globalThis.env = (k, def) => k ? process.env[k] ?? def : process.env;
+		this.load();
+		if (typeof key === "object" && key !== null) this.store = undot(Object.assign({}, Arr.dot(this.store), Arr.dot(key)));
+		else if (typeof key === "string") return Obj.get(this.store, key, defaultValue);
+		return this.store;
+	}
+};
+/** 
+* Shared config loader backing {@link config}.
+*/
+const configLoader = new ConfigLoader();
+//#endregion
+//#region src/EnvLoader.ts
+/**
+* Loads environment variables, reading the `.env` file on first access.
+*
+* The `.env` file is loaded lazily the first time a variable is read, so
+* environment access never depends on a side-effect `import 'dotenv/config'`
+* running first. Import ordering — which linters and bundlers may rewrite —
+* could otherwise place an env-reading module before dotenv has populated
+* `process.env`, leaving that module with default/stale values.
+* `dotenv.config()` never overrides variables already set, so the lazy load is
+* safe alongside other loaders.
+*/
+var EnvLoader = class {
+	loaded = false;
+	/**
+	* Load the `.env` file once.
+	* 
+	* @returns 
+	*/
+	ensureLoaded() {
+		if (this.loaded) return;
+		this.loaded = true;
+		try {
+			config({ quiet: true });
+		} catch {}
+	}
+	/**
+	* Read an environment variable, coercing booleans, numbers and `null`, and
+	* falling back to `defaultValue` when it is unset.
+	*
+	* @param name          The variable name.
+	* @param defaultValue  Returned when the variable is unset.
+	*/
+	get(name, defaultValue) {
+		this.ensureLoaded();
+		let val = process.env[name] ?? "";
+		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;
+	}
+};
+/** 
+* Shared environment loader backing {@link env}.
+*/
+const envLoader = new EnvLoader();
+//#endregion
+//#region src/system.ts
+/**
+* Read the .env file
+*
+* @param env
+* @param def
+* @returns
+*/
+const env$1 = (env, defaultValue) => envLoader.get(env, defaultValue);
+/**
+* Build the app url
+*
+* @param link
+* @returns
+*/
+const appUrl = (link) => {
+	const port = env$1("PORT", env$1("APP_PORT", "3000"));
+	const defaultUrl = `http://localhost:${port}`;
+	const appUrl = env$1("APP_URL", `http://localhost:${port}`);
+	try {
+		const url = new URL(appUrl);
+		if (url.port || url.hostname === "localhost") url.port = String(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$1 = (key, defaultValue) => configLoader.resolve(key, defaultValue);
+/**
+* Resolve the unified application key.
+*
+* `APP_KEY` (exposed as `config('app.key')`) is the single secret used for
+* signing and encryption across the framework. Resolution order:
+*
+*   1. An explicit `APP_KEY` environment variable.
+*   2. Any legacy environment variable(s) passed in, for backward compatibility
+*      with apps that predate `APP_KEY` (e.g. `JWT_SECRET`,
+*      `TWO_FACTOR_ENCRYPTION_KEY`).
+*   3. `config('app.key')` — the value from `src/config/app.ts`, which may itself
+*      be a placeholder default when no config is loaded.
+*
+* @param legacy  Legacy env var name(s) to fall back to.
+* @returns       The resolved key, or `undefined` when none is configured.
+*/
+const appKey = (legacy = []) => {
+	const explicit = env$1("APP_KEY");
+	if (explicit) return explicit;
+	for (const name of Array.isArray(legacy) ? legacy : [legacy]) {
+		const value = env$1(name);
+		if (value) return value;
+	}
+	return config$1("app.key") || void 0;
+};
+/**
+* Gets the current Node environment (development or production).
+*
+* @returns
+*/
+const nodeEnv = () => {
+	let envValue = env$1("NODE_ENV", "development");
+	if (envValue !== "development" && envValue !== "production") envValue = "development";
+	return envValue === "production" ? "prod" : "dev";
+};
+/**
+* Gets the output directory for the application based on the current environment.
+*
+* @param cwd  The current working directory (optional, defaults to Arkstack.rootDir()).
+* @returns
+*/
+const outputDir = (cwd) => {
+	cwd ??= Arkstack.rootDir();
+	const NODE_ENV = nodeEnv();
+	const output = {
+		dev: env$1("OUTPUT_DIR_DEV", ".arkstack/build"),
+		prod: env$1("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 SOURCE_DIR = "src";
+const SOURCE_EXTENSIONS = [
+	".ts",
+	".tsx",
+	".mts",
+	".cts",
+	".js",
+	".mjs",
+	".cjs"
+];
+const OUTPUT_EXTENSIONS = [
+	".js",
+	".mjs",
+	".cjs",
+	".ts"
+];
+/** 
+* Strip a trailing known source/compiled extension from a path. 
+* 
+* @param value 
+* @returns 
+*/
+const stripKnownExtension = (value) => value.replace(/\.(ts|tsx|mts|cts|js|mjs|cjs)$/i, "");
+/**
+* Build the list of concrete file candidates for a base path. Any existing
+* source/compiled extension is dropped first so the correct runtime extension
+* can be tried (e.g. a `.ts` source maps to a `.js` candidate under `dist`).
+* 
+* @param base 
+* @param extensions 
+* @returns 
+*/
+const moduleCandidates = (base, extensions) => {
+	const bare = stripKnownExtension(base);
+	return extensions.map((ext) => bare + ext);
+};
+/**
+* Map an application source path to its build-output counterpart.
+*
+* Application code is authored under `src/` and compiled into {@link outputDir},
+* which strips the leading `src/` segment and emits JavaScript (e.g.
+* `src/app/models/User.ts` -> `dist/app/models/User.js`). A TypeScript source
+* extension is rewritten to `.js`; paths without one (directories) keep their
+* shape. Absolute or root-relative paths outside the app root are returned
+* unchanged.
+*
+* This is a pure path transform — it does not touch the filesystem. Use
+* {@link resolveRuntimeModule} / {@link resolveRuntimeDir} when you need an
+* existing file/dir for the current environment.
+*
+* @param sourcePath  Absolute or root-relative source path.
+*/
+const toOutputPath = (sourcePath) => {
+	const root = Arkstack.rootDir();
+	const abs = path.isAbsolute(sourcePath) ? sourcePath : path.join(root, sourcePath);
+	const rel = path.relative(root, abs);
+	if (!rel || rel.startsWith("..")) return abs;
+	return path.join(outputDir(), rel.replace(new RegExp(`^${SOURCE_DIR}[\\\\/]`), "")).replace(/\.(ts|tsx|mts|cts)$/i, ".js");
+};
+/**
+* Resolve an application module's source path to a file that can be imported at
+* runtime.
+*
+* In development the TypeScript source is loaded directly (jiti compiles on the
+* fly); in production only the build output ships, so the path is remapped into
+* {@link outputDir} with a compiled extension. The first existing candidate
+* wins — production prefers the build output, development prefers source — so a
+* deploy that ships only `dist` never reaches for `src`.
+*
+* @param sourcePath  Absolute or root-relative source path, with or without extension.
+* @returns           An existing importable path, or `sourcePath` unchanged when none exists.
+*/
+const resolveRuntimeModule = (sourcePath) => {
+	const root = Arkstack.rootDir();
+	const abs = path.isAbsolute(sourcePath) ? sourcePath : path.join(root, sourcePath);
+	const sourceCandidates = moduleCandidates(abs, SOURCE_EXTENSIONS);
+	const outputCandidates = moduleCandidates(toOutputPath(abs), OUTPUT_EXTENSIONS);
+	return (nodeEnv() === "prod" ? [...outputCandidates, ...sourceCandidates] : [...sourceCandidates, ...outputCandidates]).find((candidate) => existsSync(candidate)) ?? abs;
+};
+/**
+* Resolve an application source directory to the directory that exists at
+* runtime.
+*
+* The directory counterpart of {@link resolveRuntimeModule}: it maps the source
+* directory into {@link outputDir} (stripping the leading `src/` segment) but
+* appends no file extension. Production prefers the build output, development
+* prefers source, and the absolute source path is returned when neither exists.
+*
+* @param sourcePath  Absolute or root-relative source directory.
+* @returns           An existing directory path, or the absolute source path when none exists.
+*/
+const resolveRuntimeDir = (sourcePath) => {
+	const root = Arkstack.rootDir();
+	const abs = path.isAbsolute(sourcePath) ? sourcePath : path.join(root, sourcePath);
+	const mapped = toOutputPath(abs);
+	return (nodeEnv() === "prod" ? [mapped, abs] : [abs, mapped]).find((candidate) => existsSync(candidate)) ?? abs;
+};
+/**
+* Rebuild the application output (tsdown) into {@link outputDir}, wiping it first
+* so no stale emitted modules survive a source change. Standalone — it does NOT
+* boot the app — so the console kernel can call it to self-heal a stale or
+* incomplete build artifact that would otherwise wedge startup. Build-only: it
+* sets `CLI_BUILD` so tsdown emits without starting a watcher/dev server, and
+* inherits the current `NODE_ENV` so it targets the same dir the kernel reads.
+*/
+const rebuildOutput = async () => {
+	await rm(outputDir(), {
+		recursive: true,
+		force: true
+	});
+	await new Promise((resolveBuild, reject) => {
+		const child = spawn(process.platform === "win32" ? "pnpm.cmd" : "pnpm", [
+			"exec",
+			"tsdown",
+			"--log-level",
+			"silent"
+		], {
+			cwd: Arkstack.rootDir(),
+			stdio: "inherit",
+			env: Object.assign({}, process.env, { CLI_BUILD: "true" })
+		});
+		child.on("error", reject);
+		child.on("exit", (code) => {
+			if (code === 0 || code === null) {
+				resolveBuild();
+				return;
+			}
+			reject(/* @__PURE__ */ new Error(`tsdown exited with code ${code}`));
+		});
+	});
+};
+/**
+* 
+* Dynamically imports a file at the given path with full TypeScript support,
+* including `tsconfig.json` path aliases. 
+*
+* @param filePath - The path to the file to import. 
+* @returns The imported module typed as `T`.
+*
+* @example
+* const config = await importFile<AppConfig>('./config/app.ts')
+*/
+const importFile = async (filePath, userOptions, resolveOptions) => {
+	const resolvedPath = resolve(filePath);
+	return await createJiti(pathToFileURL(resolvedPath).href, {
+		...userOptions,
+		interopDefault: false,
+		tsconfigPaths: true
+	}).import(resolvedPath, resolveOptions);
+};
+/**
+* Picks the command class out of an imported module. Prefers the export named
+* after the file (musket's discovery convention), then a default export, then
+* the first exported constructor it finds.
+*
+* @param mod        The imported module namespace.
+* @param basename   The file name without extension.
+* @returns          The resolved command class, or undefined when none is found.
+*/
+const resolveCommandExport = (mod, basename) => {
+	const named = mod[basename];
+	if (typeof named === "function") return named;
+	if (typeof mod.default === "function") return mod.default;
+	return Object.values(mod).find((value) => typeof value === "function");
+};
+/**
+* Discover console command classes from the application's command directory.
+*
+* Commands are loaded straight from TypeScript source through {@link importFile}
+* (jiti), so they are picked up without a build and reflect edits on every run.
+* The built output is only used as a fallback when the source directory is
+* absent — e.g. a production deploy that ships `dist` without `src`.
+*
+* This exists because musket's own glob discovery imports paths with native
+* `import()`, which silently skips `.ts` files — the reason commands previously
+* only appeared after a `build --dev` and never reflected later edits.
+*
+* @param subPath   Command directory relative to the app root (src/dist aware).
+* @returns         The discovered command classes.
+*/
+const discoverCommands = async (subPath = path.join("app", "console", "commands")) => {
+	const root = Arkstack.rootDir();
+	const sourceDir = path.join(root, SOURCE_DIR, subPath);
+	const outputCommandDir = path.join(outputDir(), subPath);
+	const candidateDirs = nodeEnv() === "prod" ? [outputCommandDir, sourceDir] : [sourceDir, outputCommandDir];
+	let commandsDir;
+	let files = [];
+	for (const dir of candidateDirs) try {
+		const entries = readdirSync(dir, { withFileTypes: true }).filter((file) => file.isFile() && [
+			".ts",
+			".js",
+			".mjs"
+		].includes(path.extname(file.name)));
+		if (entries.length > 0) {
+			commandsDir = dir;
+			files = entries;
+			break;
+		}
+	} catch {}
+	if (!commandsDir) return [];
+	const commands = [];
+	for (const file of files) {
+		const basename = path.basename(file.name, path.extname(file.name));
+		try {
+			const command = resolveCommandExport(await importFile(path.join(commandsDir, file.name)), basename);
+			if (command) commands.push(command);
+		} catch (error) {
+			console.error(`[arkstack] Failed to load command "${file.name}":`, error);
+		}
+	}
+	return commands;
+};
+/**
+* Resolves the default export from a module, handling both CJS and ESM interop.
+* In CJS modules, the default export is often the module itself (a function or object),
+* while in ESM the default is nested under the `default` property.
+*
+* @param imp - The imported module
+* @returns The resolved default export
+*/
+const interopDefault = (imp) => {
+	return typeof imp === "function" ? imp : imp.default;
+};
+//#endregion
+export { ConfigLoader as _, env$1 as a, nodeEnv as c, resolveRuntimeDir as d, resolveRuntimeModule as f, CONFIG_KEY as g, envLoader as h, discoverCommands as i, outputDir as l, EnvLoader as m, appUrl as n, importFile as o, toOutputPath as p, config$1 as r, interopDefault as s, appKey as t, rebuildOutput as u, configLoader as v };

package/dist/utils/index.d.ts

@@ -1,4 +1,4 @@
-import { a as abortIf, c as initializeGlobalContext, d as Hash, f as Encryption, i as abort, l as isClass, n as ModelConstructor, o as assertFound, r as ModelRegistry, s as getModel, t as AbstractModelConstructor, u as perPage } from "../helpers-CfQxt_q2.js";
+import { a as abortIf, c as initializeGlobalContext, d as Hash, f as Encryption, i as abort, l as isClass, n as ModelConstructor, o as assertFound, r as ModelRegistry, s as getModel, t as AbstractModelConstructor, u as perPage } from "../helpers-BrQ0B-EX.js";
 import { Model } from "arkormx";
 
 //#region src/utils/traits.d.ts

package/dist/utils/index.js

@@ -1,2 +1,2 @@
-import { _ as Hash, a as use, c as abortIf, d as initializeGlobalContext, f as isClass, i as trait, l as assertFound, n as crc32, o as uses, p as perPage, r as getTraitMethods, s as abort, t as callTraitMethods, u as getModel, v as Encryption } from "../utils-DJQAOLbx.js";
+import { _ as Hash, a as use, c as abortIf, d as initializeGlobalContext, f as isClass, i as trait, l as assertFound, n as crc32, o as uses, p as perPage, r as getTraitMethods, s as abort, t as callTraitMethods, u as getModel, v as Encryption } from "../utils-Df3nH1sG.js";
 export { Encryption, Hash, abort, abortIf, assertFound, callTraitMethods, crc32, getModel, getTraitMethods, initializeGlobalContext, isClass, perPage, trait, use, uses };