@arkstack/common 0.13.2 → 0.14.0

package/dist/index.d.ts

@@ -236,6 +236,38 @@ type HookFor<N extends string> = N extends keyof HookRegistry ? HookRegistry[N]
 type HookPos<N extends string, P extends string> = N extends keyof HookRegistry ? P extends keyof HookRegistry[N] ? HookRegistry[N][P] : (...args: any[]) => void : (...args: any[]) => void;
 type HookPositions<N extends string> = N extends keyof HookRegistry ? keyof HookRegistry[N] : Position;
 type HookArgs<N extends string, P extends string> = N extends keyof HookRegistry ? P extends keyof HookRegistry[N] ? HookRegistry[N][P] extends ((...args: infer A) => any) ? A : any[] : any[] : any[];
+/**
+* A single source → destination mapping a package wants to publish into the
+* consuming application.
+*/
+interface PublishEntry {
+  /** Absolute path to the file or directory shipped by the package. */
+  from: string;
+  /**
+   * Destination path, relative to the application root, where the artifact is
+   * written when published.
+   */
+  to: string;
+}
+/**
+ * A group of publishable artifacts registered by a package.
+ */
+interface PublishGroup {
+  /** The package registering the artifacts, e.g. `@arkstack/cache`. */
+  package: string;
+  /**
+   * Optional tag for selective publishing (`ark publish --tag <tag>`). A
+   * package may register several groups under different tags.
+   */
+  tag?: string;
+  /** The files/directories to publish. */
+  entries: PublishEntry[];
+}
+/** Optional filter applied when reading the registry. */
+interface PublishFilter {
+  package?: string;
+  tag?: string;
+}
 //#endregion
 //#region src/system.d.ts
 /**
@@ -262,6 +294,23 @@ declare const CONFIG_KEY: unique symbol;
  * @returns               The configuration value.
  */
 declare const config: GlobalConfig;
+/**
+ * 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.
+ */
+declare const appKey: (legacy?: string | string[]) => string | undefined;
 /**
  * Gets the current Node environment (development or production).
  *
@@ -403,6 +452,45 @@ declare const shouldLogError: typeof ErrorHandler.shouldLogError;
 declare const createErrorPayload: typeof ErrorHandler.createErrorPayload;
 declare const logUnhandledError: typeof ErrorHandler.logUnhandledError;
 //#endregion
+//#region src/Publisher.d.ts
+/**
+ * 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.
+ */
+declare class Publisher {
+  /** The shared, global-symbol-backed registry of publishable groups. */
+  private static get registry();
+  /**
+   * 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: PublishGroup): void;
+  /**
+   * 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?: PublishFilter): PublishGroup[];
+  /** Remove every registered publishable group (primarily for tests). */
+  static clear(): void;
+}
+//#endregion
 //#region src/Hook.d.ts
 declare class Hook {
   private static hooks;
@@ -457,4 +545,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, RequestException, UnionToIntersection, abort, abortIf, 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, serializeError, shouldHideStack, shouldLogError, toErrorShape };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { C as env, D as outputDir, E as nodeEnv, O as rebuildOutput, S as discoverCommands, T as interopDefault, _ as Hash, b as appUrl, 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, w as importFile, x as config, y as CONFIG_KEY } from "./utils-yPBhsll_.js";
+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 { Hook as Hook$1 } from "@arkstack/foundry";
 import { str } from "@h3ravel/support";
 import { Arkstack } from "@arkstack/contract";
@@ -210,6 +210,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"]));
@@ -481,4 +529,4 @@ var Hook = class {
 	};
 };
 //#endregion
-export { AppException, CONFIG_KEY, Encryption, ErrorHandler, Exception, Hash, Hook, Logger, RequestException, abort, abortIf, 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, serializeError, shouldHideStack, shouldLogError, toErrorShape };

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

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

@@ -98,6 +98,31 @@ const config = (key, defaultValue) => {
 	return globalThis[CONFIG_KEY];
 };
 /**
+* 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("APP_KEY");
+	if (explicit) return explicit;
+	for (const name of Array.isArray(legacy) ? legacy : [legacy]) {
+		const value = env(name);
+		if (value) return value;
+	}
+	return config("app.key") || void 0;
+};
+/**
 * Gets the current Node environment (development or production).
 *
 * @returns
@@ -252,8 +277,8 @@ const interopDefault = (imp) => {
 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");
+		const secret = appKey("TWO_FACTOR_ENCRYPTION_KEY");
+		if (!secret) throw new Error("APP_KEY is required to use two-factor authentication. Run `ark key:generate`.");
 		return createHash("sha256").update(secret).digest();
 	}
 	static encrypt(value) {
@@ -677,4 +702,4 @@ function uses(instance, trait) {
 	return false;
 }
 //#endregion
-export { env as C, outputDir as D, nodeEnv as E, rebuildOutput as O, discoverCommands as S, interopDefault as T, Hash as _, use as a, appUrl as b, abortIf as c, initializeGlobalContext as d, isClass as f, Exception as g, AppException as h, trait as i, 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, importFile as w, config as x, CONFIG_KEY as y };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/common",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "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.2",
-    "@arkstack/foundry": "^0.13.2",
-    "@arkstack/contract": "^0.13.2"
+    "@arkstack/foundry": "^0.14.0",
+    "@arkstack/contract": "^0.14.0"
   },
   "scripts": {
     "build": "tsdown --config-loader unrun",