@cldmv/slothlet 3.0.1 → 3.1.0

package/README.md

@@ -55,23 +55,20 @@ Every feature has been hardened with a comprehensive test suite - over **5,300 t
 
 ## ✨ What's New
 
-### Latest: v3.0.0 (February 2026)
+### Latest: v3.1.0 (March 2026)
 
-- **Unified Wrapper Architecture** - consistent proxy surface for all modes and operations
-- **Hook System Redesigned** - `hook:` config key, `api.slothlet.hook.*`, three-phase subset ordering
-- **Full i18n Support** - 9 languages for all error and debug messages
-- **Background Materialization** - pre-load lazy modules without blocking startup
-- **Lifecycle Event System** - `api.slothlet.lifecycle.on/off()` for module lifecycle events
-- **Collision Modes** - fine-grained control over API namespace conflicts
-- **Mutation Controls** - per-operation access restrictions for API mutations
-- [View full v3.0 Changelog](./docs/changelog/v3.0.md)
+- **Environment Snapshot** — `api.slothlet.env` exposes a frozen copy of `process.env` captured at initialization time; every module accesses it via `self.slothlet.env`
+- **`env.include` Allowlist** — restrict the snapshot to specific keys with `env: { include: ["NODE_ENV", "PORT"] }`; empty array falls back to full snapshot
+- **Reload Immunity** — snapshot is captured once on first `load()` and never replaced on subsequent `api.slothlet.reload()` calls (including partial `api.slothlet.api.reload()` calls)
+- [View full v3.1.0 Changelog](./docs/changelog/v3/v3.1.0.md)
 
 ### Recent Releases
 
-- **v2.11.0** - AddApi Special File Pattern (Rule 11), smart flattening enhancements ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.11.md))
-- **v2.10.0** - Function metadata tagging and introspection capabilities ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.10.md))
-- **v2.9** - Per-Request Context Isolation ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.9.md))
-- **v2.7** - Hook system introduced ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.7.md))
+- **v3.0.1** (March 2026) — Resolver fix for user `index.mjs` mis-classified as internal; CI `slothlet-dev` stripping hardening; respawn race fix; resilient `build:dist` script ([Changelog](./docs/changelog/v3/v3.0.1.md))
+- **v3.0.0** (February 2026) — Unified Wrapper architecture, redesigned hook system, full i18n, background materialization, lifecycle events, collision modes, mutation controls ([Changelog](./docs/changelog/v3.0.md))
+- **v2.11.0** — AddApi Special File Pattern (Rule 11), smart flattening enhancements ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.11.md))
+- **v2.10.0** — Function metadata tagging and introspection capabilities ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.10.md))
+- **v2.9** — Per-Request Context Isolation ([Changelog](https://github.com/CLDMV/slothlet/blob/master/docs/changelog/v2.9.md))
 
 📚 **For complete version history and detailed release notes, see [docs/changelog/](./docs/changelog/) folder.**
 

package/dist/lib/builders/api_builder.mjs

@@ -636,7 +636,10 @@ export class ApiBuilder extends ComponentBase {
 					on: handler.on.bind(handler),
 					off: handler.off.bind(handler)
 				};
-			})()
+			})(),
+
+			
+			env: slothlet.envSnapshot
 		};
 
 		

package/dist/lib/helpers/config.mjs

@@ -299,7 +299,8 @@ export class Config extends ComponentBase {
 			tracking: trackingConfig,
 			backgroundMaterialize: config.backgroundMaterialize === true,
 			silent: config.silent === true,
-			typescript: this.normalizeTypeScript(config.typescript)
+			typescript: this.normalizeTypeScript(config.typescript),
+			env: this.normalizeEnv(config.env)
 		};
 	}
 
@@ -340,4 +341,16 @@ export class Config extends ComponentBase {
 		
 		return null;
 	}
+
+	
+	normalizeEnv(env) {
+		if (!env || typeof env !== "object") {
+			return null; 
+		}
+		const include = Array.isArray(env.include) ? env.include.filter((k) => typeof k === "string") : null;
+		if (include && include.length > 0) {
+			return { include };
+		}
+		return null; 
+	}
 }

package/dist/lib/i18n/translations.mjs

@@ -42,6 +42,8 @@ function i18n_detectLanguage() {
 		const lang = envLang.split(".")[0].split("_")[0].toLowerCase();
 		
 		if (lang === "en") return "en-us";
+		
+		if (lang === "c" || lang === "posix") return "en-us";
 		if (lang === "es") return "es-mx";
 		return lang;
 	}

package/dist/slothlet.mjs

@@ -58,6 +58,9 @@ class Slothlet {
 		this.context = null;
 
 		
+		this.envSnapshot = null;
+
+		
 		this._totalLazyCount = 0; 
 		this._unmaterializedLazyCount = 0; 
 		this._materializationComplete = false; 
@@ -291,6 +294,22 @@ class Slothlet {
 	}
 
 	
+	_captureEnvSnapshot(envConfig) {
+		const rawInclude = envConfig?.include;
+		const include = Array.isArray(rawInclude) ? rawInclude.filter((key) => typeof key === "string") : null;
+		const useAllowlist = include !== null && include.length > 0;
+		const raw = useAllowlist
+			? include.reduce((acc, key) => {
+					if (Object.prototype.hasOwnProperty.call(process.env, key)) {
+						acc[key] = process.env[key];
+					}
+					return acc;
+				}, Object.create(null))
+			: { ...process.env };
+		return Object.freeze(raw);
+	}
+
+	
 	async load(config = {}, preservedInstanceID = null) {
 		
 		this.config = config;
@@ -298,6 +317,15 @@ class Slothlet {
 		
 		
 		
+		
+		
+		if (!this.envSnapshot) {
+			this.envSnapshot = this._captureEnvSnapshot(config.env);
+		}
+
+		
+		
+		
 		this.debugLogger = new SlothletDebug(config);
 
 		

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cldmv/slothlet",
-	"version": "3.0.1",
+	"version": "3.1.0",
 	"moduleVersions": {
 		"lazy": "3.0.0",
 		"eager": "3.0.0",

package/types/dist/lib/builders/api_builder.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"api_builder.d.mts","sourceRoot":"","sources":["../../../../dist/lib/builders/api_builder.mjs"],"names":[],"mappings":"AAkEA;;;;;;;;;;;;;GAaG;AACH;IACC,gCAAuC;IAcvC;;;;;OAKG;IACH,oCAHa,OAAO,KAAQ,CAiG3B;IAED;;;;;;;;;;;OAWG;IACH,gCAghCC;IAED;;;;OAIG;IACH,+BAYC;IAED;;;;OAIG;IACH,0BAgCC;IAED;;;;OAIG;IACH,4BAoMC;IAED;;;;;OAKG;IACH,8BAyCC;IAED;;;;;OAKG;IACH,uBAgCC;CACD;;;;;;;;;;;;;;;;;;;;;;;;;;8BAriD6B,0CAA0C"}
+{"version":3,"file":"api_builder.d.mts","sourceRoot":"","sources":["../../../../dist/lib/builders/api_builder.mjs"],"names":[],"mappings":"AAkEA;;;;;;;;;;;;;GAaG;AACH;IACC,gCAAuC;IAcvC;;;;;OAKG;IACH,oCAHa,OAAO,KAAQ,CAiG3B;IAED;;;;;;;;;;;OAWG;IACH,gCAijCC;IAED;;;;OAIG;IACH,+BAYC;IAED;;;;OAIG;IACH,0BAgCC;IAED;;;;OAIG;IACH,4BAoMC;IAED;;;;;OAKG;IACH,8BAyCC;IAED;;;;;OAKG;IACH,uBAgCC;CACD;;;;;;;;;;;;;;;;;;;;;;;;;;8BAtkD6B,0CAA0C"}

package/types/dist/lib/helpers/config.d.mts

@@ -91,6 +91,39 @@ export class Config extends ComponentBase {
      * @public
      */
     public normalizeTypeScript(typescript: boolean | string | any): any | null;
+    /**
+     * Normalize env snapshot configuration.
+     *
+     * @description
+     * Validates the `env` option from user config. When `include` is a non-empty
+     * string array, returns `{ include }` (the allowlist used by `_captureEnvSnapshot`).
+     * Any other value — including `undefined`, `null`, `{}`, or an empty `include`
+     * array — is normalised to `null`, meaning the full `process.env` snapshot is used.
+     *
+     * @param {Object|null|undefined} env - Raw env option from user config.
+     * @param {string[]} [env.include] - Allowlist of env variable names to capture.
+     * @returns {{ include: string[] }|null} Normalized env config, or `null` for full snapshot.
+     * @public
+     *
+     * @example
+     * // No restriction — full snapshot
+     * normalizeEnv(undefined); // => null
+     * normalizeEnv(null);      // => null
+     * normalizeEnv({});        // => null
+     *
+     * @example
+     * // Include allowlist
+     * normalizeEnv({ include: ["NODE_ENV", "PORT"] });
+     * // => { include: ["NODE_ENV", "PORT"] }
+     *
+     * @example
+     * // Non-string keys in the include array are filtered out
+     * normalizeEnv({ include: ["NODE_ENV", 42, null] });
+     * // => { include: ["NODE_ENV"] }
+     */
+    public normalizeEnv(env: any | null | undefined): {
+        include: string[];
+    } | null;
 }
 import { ComponentBase } from "@cldmv/slothlet/factories/component-base";
 //# sourceMappingURL=config.d.mts.map

package/types/dist/lib/helpers/config.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/config.mjs"],"names":[],"mappings":"AAoBA;;;;;GAKG;AACH;IACC,gCAAmC;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,qCAxBW,MAAM,MAAO,OAkDvB;IAED;;;;;OAKG;IACH,iCAJW,MAAM,GACJ,MAAM,CAsBlB;IAED;;;;;OAKG;IACH,2BAJW,MAAM,GACJ,MAAM,CAsBlB;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,+CAcC;IAED;;;;;OAKG;IACH,6BAJW,OAAO,MAAO,OA6DxB;IAED;;;;;;OAMG;IACH,0CA+HC;IAED;;;;;OAKG;IACH,uCAJW,OAAO,GAAC,MAAM,MAAO,GACnB,MAAO,IAAI,CAsCvB;CACD;8BA/Y6B,0CAA0C"}
+{"version":3,"file":"config.d.mts","sourceRoot":"","sources":["../../../../dist/lib/helpers/config.mjs"],"names":[],"mappings":"AAoBA;;;;;GAKG;AACH;IACC,gCAAmC;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,qCAxBW,MAAM,MAAO,OAkDvB;IAED;;;;;OAKG;IACH,iCAJW,MAAM,GACJ,MAAM,CAsBlB;IAED;;;;;OAKG;IACH,2BAJW,MAAM,GACJ,MAAM,CAsBlB;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,+CAcC;IAED;;;;;OAKG;IACH,6BAJW,OAAO,MAAO,OA6DxB;IAED;;;;;;OAMG;IACH,0CAgIC;IAED;;;;;OAKG;IACH,uCAJW,OAAO,GAAC,MAAM,MAAO,GACnB,MAAO,IAAI,CAsCvB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,yBArBW,MAAO,IAAI,GAAC,SAAS,GAEnB;QAAE,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,GAAC,IAAI,CA4BtC;CACD;8BAzb6B,0CAA0C"}

package/types/dist/lib/i18n/translations.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"translations.d.mts","sourceRoot":"","sources":["../../../../dist/lib/i18n/translations.mjs"],"names":[],"mappings":"AAqFA;;;;;GAKG;AACH,kCAHW,MAAM,QAsBhB;AAED;;;;GAIG;AACH,+BAHa,MAAM,CAKlB;AAED;;;;;;GAMG;AACH,qCALW,MAAM,iBAEJ,MAAM,CAyBlB;AAED;;;;;GAKG;AACH,mCAHG;IAAyB,QAAQ,GAAzB,MAAM;CACd,QAiBF;AApDD;;;;;;GAMG;AACH,6BALW,MAAM,iBAEJ,MAAM,CAyBlB"}
+{"version":3,"file":"translations.d.mts","sourceRoot":"","sources":["../../../../dist/lib/i18n/translations.mjs"],"names":[],"mappings":"AAuFA;;;;;GAKG;AACH,kCAHW,MAAM,QAsBhB;AAED;;;;GAIG;AACH,+BAHa,MAAM,CAKlB;AAED;;;;;;GAMG;AACH,qCALW,MAAM,iBAEJ,MAAM,CAyBlB;AAED;;;;;GAKG;AACH,mCAHG;IAAyB,QAAQ,GAAzB,MAAM;CACd,QAiBF;AApDD;;;;;;GAMG;AACH,6BALW,MAAM,iBAEJ,MAAM,CAyBlB"}

package/types/dist/slothlet.d.mts

@@ -123,6 +123,15 @@ export type SlothletOptions = {
      * `{ language: string }` — selects the locale for framework messages (e.g. `"en-us"`, `"fr-fr"`, `"ja-jp"`).
      */
     i18n?: object;
+    /**
+     * - Environment variable snapshot configuration.
+     * Pass `{ include: ["KEY"] }` to capture only the listed variable names in `api.slothlet.env`.
+     * Omit (or pass `undefined`) to capture a full frozen snapshot of `process.env`.
+     * Non-string entries in `include` are silently ignored; an all-non-string array falls back to the full snapshot.
+     */
+    env?: {
+        include?: string[];
+    };
     /**
      * - TypeScript support.
      * - `false` — disabled (default).
@@ -149,6 +158,7 @@ export type SlothletAPI = {
      * - Built-in control namespace. All framework internals live here to avoid collisions with loaded modules.
      */
     slothlet: {
+        env: Readonly<Record<string, string | undefined>>;
         api: {
             add: Function;
             reload: Function;

package/types/dist/slothlet.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"slothlet.d.mts","sourceRoot":"","sources":["../../dist/slothlet.mjs"],"names":[],"mappings":"AAk2BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,iCAjCW,eAAe,GACb,OAAO,CAAC,WAAW,CAAC,CAsChC;;;;;;;;;SAWa,MAAM;;;;;;;WACN,OAAO,GAAC,MAAM;;;;;;;cAId,OAAO,GAAC,MAAM;;;;eAId,MAAM;;;;cACN,MAAM,GAAC,IAAI;;;;gBACX,MAAM,GAAC,IAAI;;;;YACX;QAAC,KAAK,EAAE,SAAS,GAAC,MAAM,CAAA;KAAC;;;;UAEpC;QAAuD,SAAS,GAArD,MAAM,GAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAC;QAGxB,SAAS,GAAtB,MAAM;KAEjB;;;;;;;;WAAW,OAAO,GAAC,MAAM,GAAC,MAAM;;;;;YAKrB,OAAO,GAAC,MAAM;;;;aAEd,OAAO;;;;kBACP,OAAO;;;;eACP,OAAO,GAAC,MAAM;;;;4BACd,OAAO;;;;;WACP,MAAM;;;;;;;;iBAEN,OAAO,GAAC,MAAM,GAAC,QAAQ,GAAC,MAAM;;;;;;;;;;aAW9B,MAAY,IAAI;;;;cAChB,MAAY,IAAI;;;;cAE3B;QAA4B,GAAG,EAC/B;YAAkC,GAAG;YACH,MAAM;YACN,MAAM;SACxC;QAA4B,OAAO,EACnC;YAAsC,GAAG;YACO,OAAO,EAA5C,SAAkB;YACS,GAAG;YACH,KAAK;YACL,GAAG;SACzC;QAA6B,IAAI,GACjC;YAAkC,MAAM,GACxC;gBAAqD,GAAG,GAA7C,SAAkB;gBAC0B,eAAe,GAA3D,MAAY,MAAM,EAAE;gBACY,GAAG;aAC9C;YAAkC,OAAO,GAA9B,MAAM;YACmB,QAAQ;YACE,MAAM,GAAzC,SAAkB;YACiB,YAAY,GAA/C,SAAkB;YACK,IAAI,GAA3B,MAAM;YAC6B,OAAO,GAA1C,SAAkB;YACK,KAAK,GACvC;gBAA0C,GAAG;aAC7C;YAAkC,SAAS,GAAhC,MAAM;YACsC,eAAe,GAA3D,MAAY,eAAe;SACtC;QAA4B,IAAI,EAChC;YAAmC,KAAK;YACL,OAAO;YACP,MAAM;YACN,IAAI;YACJ,GAAG;YACH,EAAE;YACF,MAAM;SACzC;QAA4B,SAAS,EACrC;YAAwC,GAAG;YACH,EAAE;SAC1C;QAA4B,WAAW,EACvC;YAAoD,GAAG,EAA5C,SAAkB;YACY,YAAY,EAA1C,OAAO;YAC0C,IAAI,EAArD,MAAY,OAAO,CAAE,IAAI,CAAC;SACrC;QAA4B,QAAQ,EACpC;YAAsD,MAAM,EAAjD,MAAY,MAAO,IAAI;YACK,GAAG;YACH,MAAM;YACN,SAAS;YACM,IAAI,EAA/C,MAAY,MAAO,IAAI;YACK,GAAG;YACH,MAAM;YACN,SAAS;SAChD;QAA4B,KAAK,EACjC;YAAoC,GAAG;SACvC;QAA4B,SAAS,EACrC;YAAwC,GAAG;YACH,UAAU;SAClD;QAA6B,SAAS,GAA3B,MAAM;QACa,MAAM;QACN,GAAG;QACH,KAAK;QACa,QAAQ,EAA7C,MAAY,OAAO,CAAE,IAAI,CAAC;KACvC;;gCA56B6D,wBAAwB"}
+{"version":3,"file":"slothlet.d.mts","sourceRoot":"","sources":["../../dist/slothlet.mjs"],"names":[],"mappings":"AAq5BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,iCAjCW,eAAe,GACb,OAAO,CAAC,WAAW,CAAC,CAsChC;;;;;;;;;SAWa,MAAM;;;;;;;WACN,OAAO,GAAC,MAAM;;;;;;;cAId,OAAO,GAAC,MAAM;;;;eAId,MAAM;;;;cACN,MAAM,GAAC,IAAI;;;;gBACX,MAAM,GAAC,IAAI;;;;YACX;QAAC,KAAK,EAAE,SAAS,GAAC,MAAM,CAAA;KAAC;;;;UAEpC;QAAuD,SAAS,GAArD,MAAM,GAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAC;QAGxB,SAAS,GAAtB,MAAM;KAEjB;;;;;;;;WAAW,OAAO,GAAC,MAAM,GAAC,MAAM;;;;;YAKrB,OAAO,GAAC,MAAM;;;;aAEd,OAAO;;;;kBACP,OAAO;;;;eACP,OAAO,GAAC,MAAM;;;;4BACd,OAAO;;;;;WACP,MAAM;;;;;;;UAMjB;QAA0B,OAAO,GAAtB,MAAM,EAAE;KACnB;;;;;;;;iBAAW,OAAO,GAAC,MAAM,GAAC,QAAQ,GAAC,MAAM;;;;;;;;;;aAW9B,MAAY,IAAI;;;;cAChB,MAAY,IAAI;;;;cAE3B;QAAgE,GAAG,EAAxD,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAC,SAAS,CAAC,CAAC;QACzB,GAAG,EAC/B;YAAkC,GAAG;YACH,MAAM;YACN,MAAM;SACxC;QAA4B,OAAO,EACnC;YAAsC,GAAG;YACO,OAAO,EAA5C,SAAkB;YACS,GAAG;YACH,KAAK;YACL,GAAG;SACzC;QAA6B,IAAI,GACjC;YAAkC,MAAM,GACxC;gBAAqD,GAAG,GAA7C,SAAkB;gBAC0B,eAAe,GAA3D,MAAY,MAAM,EAAE;gBACY,GAAG;aAC9C;YAAkC,OAAO,GAA9B,MAAM;YACmB,QAAQ;YACE,MAAM,GAAzC,SAAkB;YACiB,YAAY,GAA/C,SAAkB;YACK,IAAI,GAA3B,MAAM;YAC6B,OAAO,GAA1C,SAAkB;YACK,KAAK,GACvC;gBAA0C,GAAG;aAC7C;YAAkC,SAAS,GAAhC,MAAM;YACsC,eAAe,GAA3D,MAAY,eAAe;SACtC;QAA4B,IAAI,EAChC;YAAmC,KAAK;YACL,OAAO;YACP,MAAM;YACN,IAAI;YACJ,GAAG;YACH,EAAE;YACF,MAAM;SACzC;QAA4B,SAAS,EACrC;YAAwC,GAAG;YACH,EAAE;SAC1C;QAA4B,WAAW,EACvC;YAAoD,GAAG,EAA5C,SAAkB;YACY,YAAY,EAA1C,OAAO;YAC0C,IAAI,EAArD,MAAY,OAAO,CAAE,IAAI,CAAC;SACrC;QAA4B,QAAQ,EACpC;YAAsD,MAAM,EAAjD,MAAY,MAAO,IAAI;YACK,GAAG;YACH,MAAM;YACN,SAAS;YACM,IAAI,EAA/C,MAAY,MAAO,IAAI;YACK,GAAG;YACH,MAAM;YACN,SAAS;SAChD;QAA4B,KAAK,EACjC;YAAoC,GAAG;SACvC;QAA4B,SAAS,EACrC;YAAwC,GAAG;YACH,UAAU;SAClD;QAA6B,SAAS,GAA3B,MAAM;QACa,MAAM;QACN,GAAG;QACH,KAAK;QACa,QAAQ,EAA7C,MAAY,OAAO,CAAE,IAAI,CAAC;KACvC;;gCAr+B6D,wBAAwB"}