@arkstack/console 0.5.2 → 0.5.3

package/README.md

@@ -1,3 +1,5 @@
 # @arkstack/console
 
+[![@arkstack/console](https://img.shields.io/npm/dt/@arkstack/console?style=flat-square&label=@arkstack/console&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F@arkstack/console)](https://www.npmjs.com/package/@arkstack/console)
+
 Console module for Arkstack, providing the command-line runtime and console integration layer.

package/dist/BuildInterfaces-CPmSl41C.js

@@ -0,0 +1,288 @@
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { Arkstack } from "@arkstack/contract";
+import { Node, Project } from "ts-morph";
+
+//#region src/prepare/TSConfig.ts
+const TSConfig = {
+	compilerOptions: {
+		module: "es2022",
+		target: "es2022",
+		lib: ["es2022", "DOM"],
+		moduleResolution: "bundler",
+		esModuleInterop: true,
+		forceConsistentCasingInFileNames: true,
+		strict: true,
+		skipLibCheck: true,
+		skipDefaultLibCheck: true,
+		strictFunctionTypes: true,
+		strictPropertyInitialization: true,
+		strictBindCallApply: true,
+		noImplicitAny: true,
+		removeComments: true,
+		experimentalDecorators: true,
+		emitDecoratorMetadata: true,
+		paths: {
+			"@": ["../src"],
+			"src/*": ["../src/*"],
+			"@app/*": ["../src/app/*"],
+			"@core/*": ["../src/core/*"],
+			"@controllers/*": ["../src/app/http/controllers/*"],
+			"@models/*": ["../src/app/models/*"]
+		}
+	},
+	include: [
+		"./*.d.ts",
+		"../src",
+		"../tests"
+	]
+};
+const BaseTCConfig = { extends: "./.arkstack/tsconfig.json" };
+
+//#endregion
+//#region src/prepare/BuildInterfaces.ts
+var BuildInterfaces = class BuildInterfaces {
+	static project;
+	static checker;
+	/**
+	* Generate configuration interfaces
+	* 
+	* @param configDir 
+	*/
+	static configs(configDir) {
+		configDir ??= path.join(Arkstack.rootDir(), "src/config");
+		const declaration = this.generateConfig(configDir);
+		writeFileSync(path.join(Arkstack.rootDir(), ".arkstack/ark.d.ts"), declaration, "utf8");
+	}
+	static tsconfig() {
+		const configs = {
+			".arkstack/tsconfig.json": JSON.stringify(TSConfig, void 0, 2),
+			"tsconfig.json": JSON.stringify(BaseTCConfig, void 0, 2)
+		};
+		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"),
+			skipAddingFilesFromTsConfig: true
+		});
+		BuildInterfaces.checker = BuildInterfaces.project.getTypeChecker();
+		const files = readdirSync(configDir).filter((f) => f.endsWith(".ts"));
+		const imports = /* @__PURE__ */ new Map();
+		const properties = [];
+		for (const file of files) {
+			const configName = path.basename(file, ".ts");
+			const sourceFile = BuildInterfaces.project.addSourceFileAtPath(path.join(configDir, file));
+			const exportAssignment = sourceFile.getExportAssignment((e) => !e.isExportEquals());
+			if (!exportAssignment) continue;
+			const expr = exportAssignment.getExpression();
+			const annotatedType = BuildInterfaces.resolveReturnTypeAnnotation(sourceFile, expr, imports);
+			if (annotatedType) {
+				properties.push(`        ${configName}: ${annotatedType}`);
+				continue;
+			}
+			const type = BuildInterfaces.checker.getTypeAtLocation(expr);
+			const callSignatures = type.getCallSignatures();
+			const resolvedType = callSignatures.length ? callSignatures[0].getReturnType() : type;
+			const typeStr = BuildInterfaces.resolveType(resolvedType, 2);
+			properties.push(`        ${configName}: ${typeStr}`);
+		}
+		return [
+			...BuildInterfaces.renderImports(imports),
+			"declare module '@arkstack/common' {",
+			"    interface ConfigRegistry {",
+			...properties,
+			"    }",
+			"}",
+			"",
+			"export {}"
+		].join("\n");
+	}
+	static resolveReturnTypeAnnotation(sourceFile, expr, imports) {
+		if (!Node.isArrowFunction(expr) && !Node.isFunctionExpression(expr)) return;
+		const returnType = expr.getReturnTypeNode();
+		if (!returnType) return;
+		const referencedNames = /* @__PURE__ */ new Set();
+		if (Node.isTypeReference(returnType)) referencedNames.add(returnType.getTypeName().getText());
+		returnType.forEachDescendant((node) => {
+			if (Node.isTypeReference(node)) referencedNames.add(node.getTypeName().getText());
+		});
+		for (const name of referencedNames) {
+			const imported = BuildInterfaces.findNamedTypeImport(sourceFile, name);
+			if (imported) {
+				const specifiers = imports.get(imported.moduleSpecifier) ?? /* @__PURE__ */ new Set();
+				specifiers.add(imported.specifier);
+				imports.set(imported.moduleSpecifier, specifiers);
+			}
+		}
+		return returnType.getText(!!sourceFile);
+	}
+	static findNamedTypeImport(sourceFile, name) {
+		for (const declaration of sourceFile.getImportDeclarations()) for (const namedImport of declaration.getNamedImports()) {
+			const alias = namedImport.getAliasNode()?.getText();
+			const importedName = namedImport.getName();
+			if ((alias ?? importedName) !== name) continue;
+			return {
+				moduleSpecifier: declaration.getModuleSpecifierValue(),
+				specifier: alias ? `${importedName} as ${alias}` : importedName
+			};
+		}
+	}
+	static renderImports(imports) {
+		return [...imports.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([moduleSpecifier, specifiers]) => {
+			return `import type { ${[...specifiers].sort().join(", ")} } from '${moduleSpecifier}'`;
+		});
+	}
+	/**
+	* ts-morph resolves computed keys like path.join(...) as { [x: number]: any }
+	* detect these by checking the type text for an index signature pattern
+	* 
+	* @param type 
+	* @returns 
+	*/
+	static isDynamicMap(type) {
+		return /^\{ \[x: (string|number)\]:/.test(type.getText());
+	}
+	static resolveType(type, indent) {
+		const pad = "    ".repeat(indent);
+		const innerPad = "    ".repeat(indent + 1);
+		if (type.isString()) return "string";
+		if (type.isNumber()) return "number";
+		if (type.isBoolean()) return "boolean";
+		if (type.isNull()) return "null";
+		if (type.isUndefined()) return "undefined";
+		if (type.isAny() || type.isUnknown()) return "any";
+		if (type.isStringLiteral()) return `'${type.getLiteralValue()}'`;
+		if (type.isNumberLiteral()) return String(type.getLiteralValue());
+		if (type.isBooleanLiteral()) return String(type.getLiteralValue());
+		if (type.isUnion()) return type.getUnionTypes().map((t) => BuildInterfaces.resolveType(t, indent)).join(" | ");
+		if (type.isArray()) {
+			const elementType = type.getArrayElementTypeOrThrow();
+			return `${BuildInterfaces.resolveType(elementType, indent)}[]`;
+		}
+		if (type.getCallSignatures().length) return "Function";
+		if (type.isObject()) {
+			if (BuildInterfaces.isDynamicMap(type)) return "Record<string, string>";
+			const props = type.getProperties();
+			if (!props.length) return "Record<string, any>";
+			return `{\n${props.map((prop) => {
+				const decl = prop.getDeclarations()[0];
+				if (!decl) return `${innerPad}${prop.getName()}: any`;
+				const propType = BuildInterfaces.checker.getTypeOfSymbolAtLocation(prop, decl);
+				const optional = prop.isOptional() ? "?" : "";
+				return `${innerPad}${prop.getName()}${optional}: ${BuildInterfaces.resolveType(propType, indent + 1)}`;
+			}).join("\n")}\n${pad}}`;
+		}
+		return type.getText();
+	}
+};
+
+//#endregion
+export { BaseTCConfig as n, TSConfig as r, BuildInterfaces as t };

package/dist/{app-CNmh_S9c.js → app-DnaQWE9q.js}

@@ -1,6 +1,7 @@
+import { existsSync } from "node:fs";
 import path, { isAbsolute, join } from "node:path";
+import { Arkstack } from "@arkstack/contract";
 import { CliApp } from "resora";
-import { existsSync } from "node:fs";
 
 //#region dist/config.js
 const defaultConfig = (app) => {
@@ -22,11 +23,11 @@ const defaultConfig = (app) => {
 //#region dist/app.js
 const resolveStubsDir = (config, options, core) => {
 	const configuredDir = config?.localStubsDir;
-	if (configuredDir) return isAbsolute(configuredDir) ? configuredDir : join(process.cwd(), configuredDir);
+	if (configuredDir) return isAbsolute(configuredDir) ? configuredDir : join(Arkstack.rootDir(), configuredDir);
 	if (!options?.stubsDir) {
 		const driver = core?.getDriver().name ?? "h3";
-		let stubsDir = path.resolve(process.cwd(), `node_modules/@arkstack/driver-${driver}/stubs`);
-		if (!existsSync(stubsDir)) stubsDir = path.resolve(process.cwd(), "stubs");
+		let stubsDir = path.resolve(Arkstack.rootDir(), `node_modules/@arkstack/driver-${driver}/stubs`);
+		if (!existsSync(stubsDir)) stubsDir = path.resolve(Arkstack.rootDir(), "stubs");
 		return stubsDir;
 	}
 	return options?.stubsDir;
@@ -44,7 +45,7 @@ var ArkstackConsoleApp = class extends CliApp {
 		this.mergeConfig();
 		const normalized = name.endsWith("Controller") ? name.replace(/controller/i, "") : name;
 		let controllerName = normalized.endsWith("Controller") ? normalized : `${normalized}Controller`;
-		const outputPath = join(path.resolve(process.cwd(), "src", "app/http/controllers"), `${controllerName}.${opts?.ext ?? "ts"}`);
+		const outputPath = join(path.resolve(Arkstack.rootDir(), "src", "app/http/controllers"), `${controllerName}.${opts?.ext ?? "ts"}`);
 		const stubsDir = resolveStubsDir(this.config, this.options, this.core);
 		if (!stubsDir) {
 			console.error("Error: stubsDir is not configured. Set stubsDir in resora.config.js.");
@@ -72,7 +73,7 @@ var ArkstackConsoleApp = class extends CliApp {
 	* @returns 
 	*/
 	normalizePath = (p) => {
-		return p.replace(process.cwd(), "");
+		return p.replace(Arkstack.rootDir(), "");
 	};
 	/**
 	* Recursively merge defaultConfig with config from resora.config.js, giving 

package/dist/app.d.ts

@@ -21,7 +21,17 @@ declare class ArkstackConsoleApp<TCore extends Core> extends CliApp {
   private readonly options;
   constructor(core: TCore, options: ConsoleAppOptions);
   makeController: (name: string, opts: any) => string;
+  /**
+   * Normalize a file path by removing the current working directory from it.
+   *
+   * @param p
+   * @returns
+   */
   normalizePath: (p: string) => string;
+  /**
+   * Recursively merge defaultConfig with config from resora.config.js, giving
+   * precedence to resora.
+   */
   mergeConfig: () => void;
 }
 //#endregion

package/dist/app.js

@@ -1,3 +1,3 @@
-import { n as resolveStubsDir, t as ArkstackConsoleApp } from "./app-CNmh_S9c.js";
+import { n as resolveStubsDir, t as ArkstackConsoleApp } from "./app-DnaQWE9q.js";
 
 export { ArkstackConsoleApp, resolveStubsDir };

package/dist/index.d.ts

@@ -1,7 +1,119 @@
+//#region src/prepare/BuildInterfaces.d.ts
+declare class BuildInterfaces {
+  private static project;
+  private static checker;
+  /**
+   * Generate configuration interfaces
+   *
+   * @param configDir
+   */
+  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;
+  private static renderImports;
+  /**
+   * ts-morph resolves computed keys like path.join(...) as { [x: number]: any }
+   * detect these by checking the type text for an index signature pattern
+   *
+   * @param type
+   * @returns
+   */
+  private static isDynamicMap;
+  private static resolveType;
+}
+//#endregion
+//#region src/prepare/TSConfig.d.ts
+declare const TSConfig: {
+  compilerOptions: {
+    module: string;
+    target: string;
+    lib: string[];
+    moduleResolution: string;
+    esModuleInterop: boolean;
+    forceConsistentCasingInFileNames: boolean;
+    strict: boolean;
+    skipLibCheck: boolean;
+    skipDefaultLibCheck: boolean;
+    strictFunctionTypes: boolean;
+    strictPropertyInitialization: boolean;
+    strictBindCallApply: boolean;
+    noImplicitAny: boolean;
+    removeComments: boolean;
+    experimentalDecorators: boolean;
+    emitDecoratorMetadata: boolean;
+    paths: {
+      '@': string[];
+      'src/*': string[];
+      '@app/*': string[];
+      '@core/*': string[];
+      '@controllers/*': string[];
+      '@models/*': string[];
+    };
+  };
+  include: string[];
+};
+declare const BaseTCConfig: {
+  extends: string;
+};
+//#endregion
 //#region src/index.d.ts
 interface RunConsoleOptions {
   logo?: string;
 }
+/**
+ * Runs the console kernel, initializing the application and registering commands.
+ *
+ * @param options
+ */
 declare const runConsoleKernel: (options?: RunConsoleOptions) => Promise<void>;
 //#endregion
-export { RunConsoleOptions, runConsoleKernel };
+export { BaseTCConfig, BuildInterfaces, RunConsoleOptions, TSConfig, runConsoleKernel };

package/dist/index.js

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
-import { t as ArkstackConsoleApp } from "./app-CNmh_S9c.js";
-import { config, env, importFile, loadPrototypes, outputDir } from "@arkstack/common";
+import { t as ArkstackConsoleApp } from "./app-DnaQWE9q.js";
+import { n as BaseTCConfig, r as TSConfig, t as BuildInterfaces } from "./BuildInterfaces-CPmSl41C.js";
+import { createRequire } from "node:module";
+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";
-import path, { join } from "node:path";
-import { MakeResource } from "resora";
-import { realpathSync } from "node:fs";
+import path, { dirname, join } from "node:path";
+import { Arkstack } from "@arkstack/contract";
+import { MakeResource, applyRuntimeConfig, getDefaultConfig } from "resora";
 import { Command, Kernel } from "@h3ravel/musket";
 import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { resolve } from "path";
 import { writeFile } from "fs/promises";
 import { CliApp as CliApp$1 } from "arkormx";
@@ -15,14 +19,19 @@ import { str } from "@h3ravel/support";
 
 //#region dist/commands/BuildCommand.js
 var BuildCommand = class extends Command {
-	signature = "build";
+	signature = `build
+    {--d|dev : Run the build in dev mode, the dev server will not be fired}
+    `;
 	description = "Build the application for production";
 	async handle() {
 		await new Promise((resolve, reject) => {
 			const child = spawn(process.platform === "win32" ? "pnpm.cmd" : "pnpm", ["exec", "tsdown"], {
-				cwd: process.cwd(),
+				cwd: Arkstack.rootDir(),
 				stdio: "inherit",
-				env: Object.assign(process.env, { NODE_ENV: "production" })
+				env: Object.assign(process.env, {
+					NODE_ENV: this.option("dev") ? "development" : "production",
+					CLI_BUILD: this.option("dev") ? "true" : void 0
+				})
 			});
 			child.on("error", (error) => {
 				reject(error);
@@ -40,20 +49,32 @@ var BuildCommand = class extends Command {
 
 //#endregion
 //#region dist/commands/DevCommand.js
-var DevCommand = class extends Command {
-	signature = "dev";
+var DevCommand = class DevCommand extends Command {
+	signature = `dev
+        {--t|tunnel : Tunnel the dev server through Ngrok}
+        {--host : Expose the dev server on the local network}
+        {--s|secure : Serve the dev server over HTTPS with a self-signed certificate}
+    `;
 	description = "Run the development server";
 	async handle() {
+		const vars = DevCommand.devServerEnv(this.options());
+		const rootDir = Arkstack.rootDir();
+		const bin = DevCommand.resolveTsdownBin(rootDir);
+		const [command, args] = bin ? [process.execPath, [
+			bin,
+			"--log-level",
+			"silent"
+		]] : [process.platform === "win32" ? "pnpm.cmd" : "pnpm", [
+			"exec",
+			"tsdown",
+			"--log-level",
+			"silent"
+		]];
 		await new Promise((resolve, reject) => {
-			const child = spawn(process.platform === "win32" ? "pnpm.cmd" : "pnpm", [
-				"exec",
-				"tsdown",
-				"--log-level",
-				"silent"
-			], {
-				cwd: process.cwd(),
+			const child = spawn(command, args, {
+				cwd: rootDir,
 				stdio: "inherit",
-				env: Object.assign(process.env, { NODE_ENV: "development" })
+				env: Object.assign(process.env, vars)
 			});
 			child.on("error", (error) => {
 				reject(error);
@@ -67,6 +88,111 @@ var DevCommand = class extends Command {
 			});
 		});
 	}
+	/**
+	* Resolve the absolute path to tsdown's executable so it can be run directly
+	* with `node`, skipping the `pnpm exec` wrapper process. Returns `undefined`
+	* when tsdown cannot be resolved from the app root, letting the caller fall
+	* back to `pnpm exec`.
+	*
+	* @param rootDir  The application root to resolve tsdown from.
+	*/
+	static resolveTsdownBin(rootDir) {
+		try {
+			const pkgPath = createRequire(join(rootDir, "noop.js")).resolve("tsdown/package.json");
+			const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+			const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.tsdown;
+			return bin ? join(dirname(pkgPath), bin) : void 0;
+		} catch {
+			return;
+		}
+	}
+	/**
+	* Map `dev` command flags to the environment variables the running server reads.
+	*
+	* The dev server binds `127.0.0.1` by default so it is local-only; `--host`
+	* switches it to `0.0.0.0` to expose it on the local network. `--secure` flags
+	* the driver to serve HTTPS, and `--tunnel` enables the Ngrok tunnel.
+	* 
+	* @param options 
+	* @returns 
+	*/
+	static devServerEnv(options) {
+		const vars = {
+			NODE_ENV: "development",
+			APP_HOST: options.host ? "0.0.0.0" : "127.0.0.1"
+		};
+		if (options.tunnel) vars.TUNNEL = "true";
+		if (options.secure) vars.APP_SECURE = "true";
+		return vars;
+	}
+};
+
+//#endregion
+//#region dist/commands/KeyGenerateCommand.js
+/**
+* Generate and set the application key (APP_KEY).
+*
+* APP_KEY is the unified secret used for signing JWTs and encrypting values
+* across the framework (exposed as `config('app.key')`).
+*/
+var KeyGenerateCommand = class KeyGenerateCommand extends Command {
+	signature = `key:generate
+        {--show : Display the generated key instead of writing it to the .env file.}
+        {--force : Overwrite the existing APP_KEY without confirmation.}
+    `;
+	description = "Set the application key (APP_KEY).";
+	async handle() {
+		const key = this.generateKey();
+		const ignore = !this.option("interaction");
+		if (this.option("show")) {
+			this.line(key);
+			return;
+		}
+		const envPath = join(Arkstack.rootDir(), ".env");
+		if (!existsSync(envPath)) {
+			this.error("No .env file found. Copy .env.example to .env before running key:generate.");
+			return;
+		}
+		const contents = readFileSync(envPath, "utf-8");
+		if (KeyGenerateCommand.hasEnvValue(contents, "APP_KEY") && !this.option("force") || ignore) {
+			if (!(!ignore ? await this.confirm("An application key already exists. Overwrite it?", false) : false) || ignore) {
+				this.info(`Application key generation ${ignore ? "skipped" : "aborted"}.`);
+				return;
+			}
+		}
+		writeFileSync(envPath, KeyGenerateCommand.upsertEnvKey(contents, "APP_KEY", key));
+		this.success("Application key set successfully.");
+	}
+	generateKey() {
+		return randomBytes(32).toString("base64url");
+	}
+	/**
+	* Whether the env file defines a non-empty value for `name`.
+	*
+	* An empty assignment (`APP_KEY=`), whitespace, or empty quotes (`APP_KEY=""`)
+	* all count as "not set" so a placeholder line is never mistaken for a real key.
+	*
+	* @param contents  The raw `.env` contents.
+	* @param name      The variable name.
+	*/
+	static hasEnvValue = (contents, name) => {
+		const value = contents.match(new RegExp(`^${name}=(.*)$`, "m"))?.[1]?.trim().replace(/^(["'])(.*)\1$/, "$2").trim();
+		return Boolean(value);
+	};
+	/**
+	* Return `contents` with `name` set to `value`, replacing the line in place if
+	* it exists or appending it otherwise.
+	*
+	* @param contents  The raw `.env` contents.
+	* @param name      The variable name.
+	* @param value     The value to set.
+	*/
+	static upsertEnvKey = (contents, name, value) => {
+		const line = `${name}=${value}`;
+		const pattern = new RegExp(`^${name}=.*$`, "m");
+		if (pattern.test(contents)) return contents.replace(pattern, () => line);
+		return `${contents.replace(/\s*$/, "")}\n${line}\n`;
+	};
 };
 
 //#endregion
@@ -80,7 +206,7 @@ var MakeCommand = class extends Command {
 		const name = String(this.argument("name")).replace(/\s+/g, "").replace(/\.js$/, "").trim();
 		if (!name) return void this.error("Command name is required");
 		const stubContent = this.stub(name);
-		const filePath = resolve(process.cwd(), "src", `app/console/commands/${name}.js`);
+		const filePath = resolve(Arkstack.rootDir(), "src", `app/console/commands/${name}.js`);
 		await writeFile(filePath, stubContent, { flag: "wx" });
 		this.success(`Command ${name} created successfully at ${filePath}`);
 	}
@@ -179,7 +305,129 @@ var MakeFullResource = class extends Command {
 
 //#endregion
 //#region dist/commands/MakeResource.js
-var MakeResource$1 = class extends MakeResource {};
+var MakeResource$1 = class extends MakeResource {
+	async handle() {
+		try {
+			applyRuntimeConfig({
+				...getDefaultConfig(),
+				...config("resources", {})
+			});
+		} catch {}
+		return super.handle();
+	}
+};
+
+//#endregion
+//#region dist/commands/PublishCommand.js
+/** Suffix that marks a file as a publishable stub; stripped on publish. */
+const STUB_SUFFIX = ".stub";
+/**
+* Strip a trailing `.stub` suffix from a path.
+*
+* Stubs are shipped as `<name>.<ext>.stub` so they are ignored by linting,
+* type-checking and test discovery in the source repo, then restored to their
+* real extension when published into an application.
+*
+* @param path
+*/
+const stripStubSuffix = (path) => path.endsWith(STUB_SUFFIX) ? path.slice(0, -5) : path;
+/**
+* Publish artifacts (migrations, stubs, assets, …) that installed packages
+* register via `publishes()` into the consuming application.
+*/
+var PublishCommand = class extends Command {
+	signature = `publish
+        {--package= : Only publish artifacts registered by this package (e.g. @arkstack/cache).}
+        {--tag= : Only publish artifacts registered under this tag.}
+        {--force : Overwrite files that already exist at the destination.}
+        {--list : List the publishable artifacts without copying anything.}
+    `;
+	description = "Publish package artifacts into your application.";
+	async handle() {
+		await this.loadPackageSetups();
+		const filter = {
+			package: this.option("package"),
+			tag: this.option("tag")
+		};
+		const groups = Publisher.publishables(filter);
+		if (groups.length < 1) {
+			this.warn(`No publishable artifacts found${this.describeFilter(filter)}.`);
+			return;
+		}
+		if (this.option("list")) {
+			this.listGroups(groups);
+			return;
+		}
+		let published = 0;
+		let skipped = 0;
+		for (const group of groups) for (const entry of group.entries) {
+			if (!existsSync(entry.from)) {
+				this.warn(`[${group.package}] Source not found, skipping: ${entry.from}`);
+				continue;
+			}
+			const to = stripStubSuffix(entry.to);
+			const dest = join(Arkstack.rootDir(), to);
+			if (existsSync(dest) && !this.option("force")) {
+				this.warn(`Exists, skipped (use --force): ${to}`);
+				skipped++;
+				continue;
+			}
+			mkdirSync(dirname(dest), { recursive: true });
+			cpSync(entry.from, dest, { recursive: true });
+			if (statSync(dest).isDirectory()) this.stripStubsInTree(dest);
+			this.success(`Published [${group.package}] -> ${to}`);
+			published++;
+		}
+		this.info(`Done. ${published} published, ${skipped} skipped.`);
+	}
+	/**
+	* Recursively rename `*.stub` files within a published directory to their
+	* real extension.
+	*
+	* @param dir
+	*/
+	stripStubsInTree(dir) {
+		for (const item of readdirSync(dir, {
+			recursive: true,
+			withFileTypes: true
+		})) if (item.isFile() && item.name.endsWith(STUB_SUFFIX)) {
+			const current = join(item.parentPath, item.name);
+			renameSync(current, stripStubSuffix(current));
+		}
+	}
+	/**
+	* Print the publishable artifacts grouped by package without copying.
+	*
+	* @param groups
+	*/
+	listGroups(groups) {
+		this.info("Publishable artifacts:");
+		for (const group of groups) {
+			this.line(`  ${group.package}${group.tag ? ` (tag: ${group.tag})` : ""}`);
+			for (const entry of group.entries) this.line(`    - ${stripStubSuffix(entry.to)}`);
+		}
+	}
+	/**
+	* Import the `setup` module of every installed `@arkstack/*` package so its
+	* `publishes()` registrations run. Errors (missing build, side effects) are
+	* ignored so one bad package cannot break publishing.
+	*/
+	async loadPackageSetups() {
+		const scope = join(Arkstack.rootDir(), "node_modules", "@arkstack");
+		if (!existsSync(scope)) return;
+		for (const pkg of readdirSync(scope)) {
+			const setup = join(scope, pkg, "dist", "setup.js");
+			if (!existsSync(setup)) continue;
+			try {
+				await import(pathToFileURL(setup).href);
+			} catch {}
+		}
+	}
+	describeFilter(filter) {
+		const parts = [filter.package ? `package "${filter.package}"` : "", filter.tag ? `tag "${filter.tag}"` : ""].filter(Boolean);
+		return parts.length ? ` for ${parts.join(" and ")}` : "";
+	}
+};
 
 //#endregion
 //#region dist/commands/RouteList.js
@@ -253,14 +501,37 @@ var logo_default = String.raw`
 
 //#endregion
 //#region dist/index.js
-/**
-* Loads the core application instance by importing the bootstrap file.
+/** 
+* A missing-module error from importing a stale/incomplete build artifact. 
 * 
+* @param error 
 * @returns 
 */
+const isMissingModuleError = (error) => {
+	const code = error?.code;
+	return code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND";
+};
+/**
+* Loads the core application instance by importing the built bootstrap file.
+*
+* The kernel boots this for every command — including `build` — before the build
+* can run, so a stale or incomplete build artifact (source changed since the last
+* build: a module moved, renamed, or added) would otherwise wedge startup with
+* `Cannot find module '<outDir>/...'` and the build could never self-heal. When
+* that happens and source is present, regenerate the output once and retry.
+*
+* @returns
+*/
 const loadCoreApp = async () => {
-	const dist = path.relative(process.cwd(), outputDir());
-	return (await importFile(join(process.cwd(), `${dist}/core/bootstrap.js`))).app;
+	const dist = path.relative(Arkstack.rootDir(), outputDir());
+	const bootstrapPath = join(Arkstack.rootDir(), `${dist}/core/bootstrap.js`);
+	try {
+		return (await importFile(bootstrapPath)).app;
+	} catch (error) {
+		if (!isMissingModuleError(error) || !existsSync(join(Arkstack.rootDir(), "src"))) throw error;
+		await rebuildOutput();
+		return (await importFile(bootstrapPath)).app;
+	}
 };
 /**
 * Runs the console kernel, initializing the application and registering commands.
@@ -270,13 +541,17 @@ const loadCoreApp = async () => {
 const runConsoleKernel = async (options = {}) => {
 	loadPrototypes();
 	const app = await loadCoreApp();
-	const dist = path.relative(process.cwd(), outputDir());
 	const stubsDir = process.env.ARKSTACK_STUBS_DIR;
 	globalThis.app = () => app;
 	globalThis.env = env;
 	globalThis.config = config;
 	globalThis.str = str;
+	globalThis.abort = abort;
+	globalThis.abortIf = abortIf;
+	globalThis.assertFound = assertFound;
 	globalThis.arkctx = { runtime: "CLI" };
+	await initializeGlobalContext();
+	const userCommands = await discoverCommands();
 	await Kernel.init(await new ArkstackConsoleApp(app, { stubsDir }).loadConfig(), {
 		logo: options.logo ?? logo_default,
 		name: "Cmd",
@@ -287,16 +562,12 @@ const runConsoleKernel = async (options = {}) => {
 			MakeFullResource,
 			DevCommand,
 			BuildCommand,
-			MakeCommand
-		],
-		discoveryPaths: [
-			join(process.cwd(), "src", "app", "console", "commands/*.js"),
-			join(process.cwd(), "src", "app/console/commands/*.js"),
-			join(process.cwd(), "src", "app/console/commands/*.mjs"),
-			join(process.cwd(), dist, "app/console/commands/*.js"),
-			join(process.cwd(), dist, "app/console/commands/*.mjs"),
-			join(process.cwd(), "node_modules", "@arkstack/*", "dist", "commands", "*.js")
+			MakeCommand,
+			KeyGenerateCommand,
+			PublishCommand,
+			...userCommands
 		],
+		discoveryPaths: [join(Arkstack.rootDir(), "node_modules", "@arkstack/*", "dist", "commands", "*.js")],
 		exceptionHandler(exception) {
 			throw exception;
 		}
@@ -320,4 +591,4 @@ const isEntrypointExecution = () => {
 if (isEntrypointExecution()) await runConsoleKernel();
 
 //#endregion
-export { runConsoleKernel };
+export { BaseTCConfig, BuildInterfaces, TSConfig, runConsoleKernel };

package/dist/prepare.js

@@ -1,14 +1,26 @@
+#!/usr/bin/env node
+import { t as BuildInterfaces } from "./BuildInterfaces-CPmSl41C.js";
+import { existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { Arkstack } from "@arkstack/contract";
 import { spawn } from "node:child_process";
 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();
+	BuildInterfaces.env();
+}
+BuildInterfaces.tsconfig();
+const LOG_LEVEL = parseInt(process.env.VERBOSITY ?? "0") > 0 ? [] : ["--log-level=silent"];
 const NODE_ENV = process.env.NODE_ENV || "development";
 const child = spawn(process.platform === "win32" ? "pnpm.cmd" : "pnpm", [
 	"exec",
 	"tsdown",
-	"--log-level=silent"
+	...LOG_LEVEL
 ], {
-	cwd: process.cwd(),
+	cwd: Arkstack.rootDir(),
 	stdio: "inherit",
 	env: Object.assign({}, process.env, {
 		NODE_ENV,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/console",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "type": "module",
   "description": "Console module for Arkstack, providing the command-line runtime and console integration layer.",
   "homepage": "https://arkstack.toneflix.net/guide/cli",
@@ -42,16 +42,17 @@
     }
   },
   "peerDependencies": {
-    "clear-router": "^2.6.4",
-    "arkormx": "^2.0.11"
+    "arkormx": "^2.10.1",
+    "clear-router": "^2.9.0"
   },
   "dependencies": {
-    "@h3ravel/musket": "^0.10.1",
-    "@h3ravel/support": "^0.15.11",
+    "@h3ravel/musket": "^2.2.1",
+    "@h3ravel/support": "^2.2.0",
     "chalk": "^5.6.2",
-    "resora": "^1.2.4",
-    "@arkstack/contract": "^0.5.2",
-    "@arkstack/common": "^0.5.2"
+    "resora": "^1.3.27",
+    "ts-morph": "^28.0.0",
+    "@arkstack/common": "^0.5.3",
+    "@arkstack/contract": "^0.5.3"
   },
   "scripts": {
     "build": "tsdown",