@arkstack/common 0.14.15 → 0.14.17

package/dist/index.d.ts

@@ -324,6 +324,50 @@ declare const nodeEnv: () => "prod" | "dev";
  * @returns
  */
 declare const outputDir: (cwd?: string) => string;
+/**
+ * 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.
+ */
+declare const toOutputPath: (sourcePath: string) => string;
+/**
+ * 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.
+ */
+declare const resolveRuntimeModule: (sourcePath: string) => string;
+/**
+ * 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.
+ */
+declare const resolveRuntimeDir: (sourcePath: string) => string;
 /**
  * Rebuild the application output (tsdown) into {@link outputDir}, wiping it first
  * so no stale emitted modules survive a source change. Standalone — it does NOT
@@ -545,4 +589,4 @@ declare class Hook {
   static clear: () => void;
 }
 //#endregion
-export { AbstractModelConstructor, AppException, ArkstackErrorPayload, ArkstackErrorShape, CONFIG_KEY, ConfigRegistry, ConfigShape, DotPath, DotPathValue, Encryption, EnvRegistry, ErrorHandler, Exception, FileImporter, GlobalConfig, GlobalEnv, Hash, Hook, HookArgs, HookFor, HookName, HookPos, HookPositions, HookRegistry, IHook, Logger, LoggerChalk, LoggerLog, LoggerParseSignature, MergedConfig, ModelConstructor, ModelRegistry, Primitive, PublishEntry, PublishFilter, PublishGroup, Publisher, RequestException, UnionToIntersection, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, createErrorPayload, discoverCommands, env, getErrorLogger, getModel, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, logUnhandledError, nodeEnv, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, serializeError, shouldHideStack, shouldLogError, toErrorShape };
+export { AbstractModelConstructor, AppException, ArkstackErrorPayload, ArkstackErrorShape, CONFIG_KEY, ConfigRegistry, ConfigShape, DotPath, DotPathValue, Encryption, EnvRegistry, ErrorHandler, Exception, FileImporter, GlobalConfig, GlobalEnv, Hash, Hook, HookArgs, HookFor, HookName, HookPos, HookPositions, HookRegistry, IHook, Logger, LoggerChalk, LoggerLog, LoggerParseSignature, MergedConfig, ModelConstructor, ModelRegistry, Primitive, PublishEntry, PublishFilter, PublishGroup, Publisher, RequestException, UnionToIntersection, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, createErrorPayload, discoverCommands, env, getErrorLogger, getModel, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, logUnhandledError, nodeEnv, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolveRuntimeDir, resolveRuntimeModule, serializeError, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { C as discoverCommands, D as nodeEnv, E as interopDefault, O as outputDir, S as config, T as importFile, _ as Hash, b as appKey, c as abortIf, d as initializeGlobalContext, f as isClass, g as Exception, h as AppException, k as rebuildOutput, l as assertFound, m as RequestException, p as perPage, s as abort, u as getModel, v as Encryption, w as env, x as appUrl, y as CONFIG_KEY } from "./utils-CL_FD72V.js";
+import { A as resolveRuntimeDir, C as discoverCommands, D as nodeEnv, E as interopDefault, M as toOutputPath, O as outputDir, S as config, T as importFile, _ as Hash, b as appKey, c as abortIf, d as initializeGlobalContext, f as isClass, g as Exception, h as AppException, j as resolveRuntimeModule, k as rebuildOutput, l as assertFound, m as RequestException, p as perPage, s as abort, u as getModel, v as Encryption, w as env, x as appUrl, y as CONFIG_KEY } from "./utils-DJQAOLbx.js";
 import { Hook as Hook$1 } from "@arkstack/foundry";
 import { str } from "@h3ravel/support";
 import { Arkstack } from "@arkstack/contract";
@@ -529,4 +529,4 @@ var Hook = class {
 	};
 };
 //#endregion
-export { AppException, CONFIG_KEY, Encryption, ErrorHandler, Exception, Hash, Hook, Logger, Publisher, RequestException, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, createErrorPayload, discoverCommands, env, getErrorLogger, getModel, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, logUnhandledError, nodeEnv, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, serializeError, shouldHideStack, shouldLogError, toErrorShape };
+export { AppException, CONFIG_KEY, Encryption, ErrorHandler, Exception, Hash, Hook, Logger, Publisher, RequestException, abort, abortIf, appKey, appUrl, assertFound, bindGracefulShutdown, bootWithDetectedPort, config, createErrorPayload, discoverCommands, env, getErrorLogger, getModel, getPrimaryError, getValidationErrors, importFile, initializeGlobalContext, interopDefault, isClass, isModelNotFoundError, isValidationError, loadPrototypes, logUnhandledError, nodeEnv, normalizeStatusCode, outputDir, perPage, rebuildOutput, renderError, resolveRuntimeDir, resolveRuntimeModule, serializeError, shouldHideStack, shouldLogError, toErrorShape, toOutputPath };

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-CL_FD72V.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-DJQAOLbx.js";
 export { Encryption, Hash, abort, abortIf, assertFound, callTraitMethods, crc32, getModel, getTraitMethods, initializeGlobalContext, isClass, perPage, trait, use, uses };

package/dist/{utils-CL_FD72V.js → utils-DJQAOLbx.js}

@@ -1,11 +1,11 @@
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
 import { Arr, Obj, undot } from "@h3ravel/support";
 import { createJiti } from "jiti";
+import { existsSync, readdirSync } from "fs";
 import { Arkstack } from "@arkstack/contract";
 import { createRequire } from "module";
 import path, { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { readdirSync } from "fs";
 import { rm } from "node:fs/promises";
 import { spawn } from "node:child_process";
 import { Secret, TOTP } from "otpauth";
@@ -147,6 +147,103 @@ const outputDir = (cwd) => {
 	};
 	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
@@ -232,8 +329,9 @@ const resolveCommandExport = (mod, basename) => {
 */
 const discoverCommands = async (subPath = path.join("app", "console", "commands")) => {
 	const root = Arkstack.rootDir();
-	const dist = path.relative(root, outputDir());
-	const candidateDirs = [path.join(root, "src", subPath), path.join(root, dist, subPath)];
+	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 {
@@ -440,7 +538,7 @@ async function getModel(modelName) {
 	};
 	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(Arkstack.rootDir(), modelPath), modelName)), path.basename(modelName, path.extname(modelName)));
+	const model = resolveModelExport(await importFile(resolveRuntimeModule(path.join(path.isAbsolute(modelPath) ? modelPath : path.join(Arkstack.rootDir(), modelPath), modelName))), path.basename(modelName, path.extname(modelName)));
 	if (typeof model !== "function") throw new Error(`Model "${modelName}" not found`);
 	return model;
 }
@@ -702,4 +800,4 @@ function uses(instance, trait) {
 	return false;
 }
 //#endregion
-export { discoverCommands as C, nodeEnv as D, interopDefault as E, outputDir as O, config as S, importFile as T, Hash as _, use as a, appKey as b, abortIf as c, initializeGlobalContext as d, isClass as f, Exception as g, AppException as h, trait as i, rebuildOutput as k, assertFound as l, RequestException as m, crc32 as n, uses as o, perPage as p, getTraitMethods as r, abort as s, callTraitMethods as t, getModel as u, Encryption as v, env as w, appUrl as x, CONFIG_KEY as y };
+export { resolveRuntimeDir as A, discoverCommands as C, nodeEnv as D, interopDefault as E, toOutputPath as M, outputDir as O, config as S, importFile as T, Hash as _, use as a, appKey as b, abortIf as c, initializeGlobalContext as d, isClass as f, Exception as g, AppException as h, trait as i, resolveRuntimeModule as j, rebuildOutput as k, assertFound as l, RequestException as m, crc32 as n, uses as o, perPage as p, getTraitMethods as r, abort as s, callTraitMethods as t, getModel as u, Encryption as v, env as w, appUrl as x, CONFIG_KEY as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/common",
-  "version": "0.14.15",
+  "version": "0.14.17",
   "type": "module",
   "description": "Core utilities, primitives, and shared infrastructure for the Arkstack ecosystem.",
   "homepage": "https://arkstack.toneflix.net",
@@ -42,8 +42,8 @@
   "peerDependencies": {
     "@h3ravel/support": "^2.1.4",
     "arkormx": "^2.9.3",
-    "@arkstack/foundry": "^0.14.15",
-    "@arkstack/contract": "^0.14.15"
+    "@arkstack/foundry": "^0.14.17",
+    "@arkstack/contract": "^0.14.17"
   },
   "scripts": {
     "build": "tsdown --config-loader unrun",