@arkstack/console 0.14.18 → 0.14.19

package/dist/{BuildInterfaces-CsZ3Uerb.js → BuildInterfaces-CPmSl41C.js}

@@ -1,4 +1,4 @@
-import { readdirSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { Arkstack } from "@arkstack/contract";
 import { Node, Project } from "ts-morph";
@@ -61,6 +61,113 @@ var BuildInterfaces = class BuildInterfaces {
 		};
 		for (const [file, config] of Object.entries(configs)) writeFileSync(path.join(Arkstack.rootDir(), file), config, "utf8");
 	}
+	/**
+	* Generate an `EnvRegistry` augmentation from the application's `.env`
+	* schema, giving `env()` precise return types for app-specific variables.
+	*
+	* Mirrors {@link configs}: the declaration is appended to
+	* `.arkstack/ark.d.ts`. Keys already typed by the framework's own
+	* `EnvRegistry` are skipped so declaration merging never conflicts.
+	*
+	* @param envFile  Explicit `.env` path; defaults to `.env.example` then `.env`.
+	*/
+	static env(envFile) {
+		const root = Arkstack.rootDir();
+		const file = envFile ?? BuildInterfaces.resolveEnvFile(root);
+		if (!file) return;
+		const declaration = BuildInterfaces.envRegistryFromEnv(readFileSync(file, "utf8"), [...BuildInterfaces.frameworkEnvKeys()]);
+		if (!declaration) return;
+		const target = path.join(root, ".arkstack/ark.d.ts");
+		let content = `${existsSync(target) ? readFileSync(target, "utf8") : ""}\n${declaration}\n`;
+		if (!/^\s*export\s|\bimport\s/m.test(content)) content += "\nexport {}\n";
+		writeFileSync(target, content, "utf8");
+	}
+	/**
+	* Render an `EnvRegistry` augmentation for the variables declared in the
+	* given `.env` contents. Pure (no filesystem) for testability.
+	*
+	* @param contents  Raw `.env` file contents.
+	* @param skip      Variable names to omit (e.g. framework-owned keys).
+	* @returns         The `declare module` block, or `''` when nothing to emit.
+	*/
+	static envRegistryFromEnv(contents, skip = []) {
+		const skipped = new Set(skip);
+		const properties = Object.entries(BuildInterfaces.parseEnvFile(contents)).filter(([key]) => !skipped.has(key)).map(([key, value]) => `        ${key}: ${BuildInterfaces.inferEnvType(value)}`);
+		if (!properties.length) return "";
+		return [
+			"declare module '@arkstack/common' {",
+			"    interface EnvRegistry {",
+			...properties,
+			"    }",
+			"}"
+		].join("\n");
+	}
+	/** 
+	* Prefer `.env.example` (the documented schema), then `.env`. 
+	* 
+	* @param root 
+	* @returns 
+	*/
+	static resolveEnvFile(root) {
+		for (const name of [".env.example", ".env"]) {
+			const file = path.join(root, name);
+			if (existsSync(file)) return file;
+		}
+	}
+	/** 
+	* Parse `KEY=VALUE` lines, skipping blanks, comments and invalid names. 
+	* 
+	* @param contents 
+	* @returns 
+	*/
+	static parseEnvFile(contents) {
+		const entries = {};
+		for (const raw of contents.split(/\r?\n/)) {
+			const line = raw.trim();
+			if (!line || line.startsWith("#")) continue;
+			const eq = line.indexOf("=");
+			if (eq === -1) continue;
+			const key = line.slice(0, eq).trim();
+			if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+			let value = line.slice(eq + 1).trim();
+			if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
+			entries[key] = value;
+		}
+		return entries;
+	}
+	/** 
+	* Infer a TS type from a value, mirroring env()'s runtime coercion.      
+	*  
+	* @param value 
+	* @returns 
+	*/
+	static inferEnvType(value) {
+		if (value === "") return "string";
+		if ([
+			"true",
+			"false",
+			"on",
+			"off"
+		].includes(value)) return "boolean";
+		if (!Number.isNaN(Number(value))) return "number";
+		return "string";
+	}
+	/** 
+	* Resolve the framework's own `EnvRegistry` keys to skip during generation.  
+	* 
+	* @returns 
+	*/
+	static frameworkEnvKeys() {
+		try {
+			const keys = new Project({
+				tsConfigFilePath: path.join(Arkstack.rootDir(), "tsconfig.json"),
+				skipAddingFilesFromTsConfig: true
+			}).createSourceFile("__ark_env_probe__.ts", "import type { EnvRegistry } from '@arkstack/common'\ndeclare const value: EnvRegistry\n", { overwrite: true }).getVariableDeclarationOrThrow("value").getType().getProperties().map((prop) => prop.getName());
+			return new Set(keys);
+		} catch {
+			return /* @__PURE__ */ new Set();
+		}
+	}
 	static generateConfig(configDir = path.join(process.cwd(), "src/config")) {
 		BuildInterfaces.project = new Project({
 			tsConfigFilePath: path.join(process.cwd(), "tsconfig.json"),

package/dist/index.d.ts

@@ -9,6 +9,53 @@ declare class BuildInterfaces {
    */
   static configs(configDir?: string): void;
   static tsconfig(): void;
+  /**
+   * Generate an `EnvRegistry` augmentation from the application's `.env`
+   * schema, giving `env()` precise return types for app-specific variables.
+   *
+   * Mirrors {@link configs}: the declaration is appended to
+   * `.arkstack/ark.d.ts`. Keys already typed by the framework's own
+   * `EnvRegistry` are skipped so declaration merging never conflicts.
+   *
+   * @param envFile  Explicit `.env` path; defaults to `.env.example` then `.env`.
+   */
+  static env(envFile?: string): void;
+  /**
+   * Render an `EnvRegistry` augmentation for the variables declared in the
+   * given `.env` contents. Pure (no filesystem) for testability.
+   *
+   * @param contents  Raw `.env` file contents.
+   * @param skip      Variable names to omit (e.g. framework-owned keys).
+   * @returns         The `declare module` block, or `''` when nothing to emit.
+   */
+  static envRegistryFromEnv(contents: string, skip?: string[]): string;
+  /**
+   * Prefer `.env.example` (the documented schema), then `.env`.
+   *
+   * @param root
+   * @returns
+   */
+  private static resolveEnvFile;
+  /**
+   * Parse `KEY=VALUE` lines, skipping blanks, comments and invalid names.
+  *
+  * @param contents
+  * @returns
+  */
+  private static parseEnvFile;
+  /**
+   * Infer a TS type from a value, mirroring env()'s runtime coercion.
+   *
+   * @param value
+   * @returns
+   */
+  private static inferEnvType;
+  /**
+   * Resolve the framework's own `EnvRegistry` keys to skip during generation.
+   *
+   * @returns
+   */
+  private static frameworkEnvKeys;
   private static generateConfig;
   private static resolveReturnTypeAnnotation;
   private static findNamedTypeImport;

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { t as ArkstackConsoleApp } from "./app-DnaQWE9q.js";
-import { n as BaseTCConfig, r as TSConfig, t as BuildInterfaces } from "./BuildInterfaces-CsZ3Uerb.js";
+import { n as BaseTCConfig, r as TSConfig, t as BuildInterfaces } from "./BuildInterfaces-CPmSl41C.js";
 import { Publisher, abort, abortIf, assertFound, config, discoverCommands, env, importFile, initializeGlobalContext, loadPrototypes, outputDir, rebuildOutput } from "@arkstack/common";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";

package/dist/prepare.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as BuildInterfaces } from "./BuildInterfaces-CsZ3Uerb.js";
+import { t as BuildInterfaces } from "./BuildInterfaces-CPmSl41C.js";
 import { existsSync, mkdirSync } from "node:fs";
 import path from "node:path";
 import { Arkstack } from "@arkstack/contract";
@@ -8,7 +8,10 @@ import chalk from "chalk";
 
 //#region dist/prepare.js
 if (!existsSync(path.join(Arkstack.rootDir(), ".arkstack/build"))) mkdirSync(path.join(Arkstack.rootDir(), ".arkstack/build"), { recursive: true });
-if (!process.env.NODE_CI) BuildInterfaces.configs();
+if (!process.env.NODE_CI) {
+	BuildInterfaces.configs();
+	BuildInterfaces.env();
+}
 BuildInterfaces.tsconfig();
 const LOG_LEVEL = parseInt(process.env.VERBOSITY ?? "0") > 0 ? [] : ["--log-level=silent"];
 const NODE_ENV = process.env.NODE_ENV || "development";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/console",
-  "version": "0.14.18",
+  "version": "0.14.19",
   "type": "module",
   "description": "Console module for Arkstack, providing the command-line runtime and console integration layer.",
   "homepage": "https://arkstack.toneflix.net/guide/cli",
@@ -51,8 +51,8 @@
     "chalk": "^5.6.2",
     "resora": "^1.3.27",
     "ts-morph": "^28.0.0",
-    "@arkstack/common": "^0.14.18",
-    "@arkstack/contract": "^0.14.18"
+    "@arkstack/contract": "^0.14.19",
+    "@arkstack/common": "^0.14.19"
   },
   "scripts": {
     "build": "tsdown",