@grupodiariodaregiao/bunstone 0.4.5 → 0.4.7

package/bin/cli.ts

@@ -8,22 +8,464 @@ import {
 } from "node:fs/promises";
 import { join } from "node:path";
 
+// ── Tiny ANSI helpers (no external dep) ──────────────────────────────────────
+const R = "\x1b[0m";
+const bold = (s: string) => `\x1b[1m${s}${R}`;
+const red = (s: string) => `\x1b[31m${s}${R}`;
+const yellow = (s: string) => `\x1b[33m${s}${R}`;
+const green = (s: string) => `\x1b[32m${s}${R}`;
+const cyan = (s: string) => `\x1b[36m${s}${R}`;
+const gray = (s: string) => `\x1b[90m${s}${R}`;
+const BORDER = "━".repeat(64);
+const THIN = "─".repeat(64);
+
+// ── Arg parsing ───────────────────────────────────────────────────────────────
 const args = Bun.argv.slice(2);
-let command = args[0];
-let projectName = args[1];
+const command = args[0];
 
-// Default to "new" command if only project name is provided
-if (command && command !== "new" && !projectName) {
-	projectName = command;
-	command = "new";
+// ── Command dispatch ──────────────────────────────────────────────────────────
+if (command === "run") {
+	await runCommand(args.slice(1));
+} else if (command === "exports") {
+	await exportsCommand();
+} else if (command === "new" || (command && !args[1])) {
+	await scaffold(command === "new" ? args[1] : command);
+} else {
+	printHelp();
+	process.exit(1);
 }
 
-// Default project name if none provided
-if (!projectName && command === "new") {
-	projectName = "my-bunstone-app";
+// ─────────────────────────────────────────────────────────────────────────────
+// bunstone run [bun-flags...] <entrypoint>
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Regexp that matches Bun's raw import error line.
+ * e.g.  SyntaxError: Export named 'RabbitMessage' not found in module '…/bunstone/dist/index.js'.
+ */
+const BUN_EXPORT_RE = /Export named '(.+?)' not found in module '(.+?)'/;
+
+async function runCommand(runArgs: string[]) {
+	if (runArgs.length === 0) {
+		console.error(red("✖  Usage: bunstone run [bun-flags...] <entrypoint.ts>"));
+		process.exit(1);
+	}
+
+	// Separate bun flags (start with -) from the entrypoint
+	const bunFlags: string[] = [];
+	let entrypoint = "";
+	for (const arg of runArgs) {
+		if (arg.startsWith("-") && !entrypoint) bunFlags.push(arg);
+		else entrypoint = arg;
+	}
+
+	if (!entrypoint) {
+		console.error(red("✖  No entrypoint file specified."));
+		console.error(gray("   Usage: bunstone run [--watch] src/main.ts"));
+		process.exit(1);
+	}
+
+	const cmd = ["bun", ...bunFlags, entrypoint];
+
+	const proc = Bun.spawn(cmd, {
+		stdin: "inherit",
+		stdout: "inherit",
+		stderr: "pipe",
+	});
+
+	// Accumulate stderr so we can inspect it for the import error pattern
+	const stderrChunks: Uint8Array[] = [];
+	const stderrReader = proc.stderr.getReader();
+
+	(async () => {
+		const decoder = new TextDecoder();
+		while (true) {
+			const { done, value } = await stderrReader.read();
+			if (done) break;
+			stderrChunks.push(value);
+
+			// Write to real stderr immediately so the developer still sees everything
+			process.stderr.write(decoder.decode(value));
+		}
+	})();
+
+	const exitCode = await proc.exited;
+
+	if (exitCode !== 0) {
+		const decoder = new TextDecoder();
+		const fullStderr = stderrChunks.map((c) => decoder.decode(c)).join("");
+
+		const match = BUN_EXPORT_RE.exec(fullStderr);
+		if (match) {
+			const [, name, modulePath] = match;
+			printImportError(name, modulePath);
+		}
+	}
+
+	process.exit(exitCode);
 }
 
-const projectPath = join(process.cwd(), projectName || "");
+function printImportError(name: string, modulePath: string) {
+	// Lazy-load the utils so the CLI does not depend on the built dist
+	const pkg = modulePath.includes("node_modules/")
+		? modulePath.replace(/.*node_modules\//, "").replace(/\/dist.*/, "")
+		: modulePath;
+
+	// These are inlined here (not imported from dist) so the CLI works even
+	// before the user runs `bun build`.
+	const TYPE_ONLY: ReadonlySet<string> = new Set([
+		"RabbitMessage",
+		"RabbitPublishOptions",
+		"RabbitSubscribeOptions",
+		"DeadLetterMessage",
+		"DeadLetterDeathInfo",
+		"RequeueOptions",
+		"RabbitMQExchangeConfig",
+		"RabbitMQQueueBinding",
+		"RabbitMQQueueConfig",
+		"RabbitMQReconnectConfig",
+		"RabbitMQModuleOptions",
+		"HttpRequest",
+		"ModuleConfig",
+		"Options",
+		"GuardContract",
+	]);
+
+	const ALL_VALUES = [
+		"CacheAdapter",
+		"FormDataAdapter",
+		"UploadAdapter",
+		"EmailModule",
+		"EmailService",
+		"EmailLayout",
+		"AppStartup",
+		"Layout",
+		"Controller",
+		"Get",
+		"Post",
+		"Put",
+		"Patch",
+		"Delete",
+		"Head",
+		"RateLimit",
+		"RateLimitGuard",
+		"RedisStorage",
+		"CommandBus",
+		"CqrsModule",
+		"CommandHandler",
+		"EventHandler",
+		"QueryHandler",
+		"Saga",
+		"EventBus",
+		"QueryBus",
+		"SqlModule",
+		"SqlService",
+		"BullMqModule",
+		"QueueService",
+		"Processor",
+		"Process",
+		"RabbitMQModule",
+		"RabbitMQService",
+		"RabbitMQDeadLetterService",
+		"RabbitMQConnection",
+		"RabbitConsumer",
+		"RabbitSubscribe",
+		"BunstoneError",
+		"DependencyResolutionError",
+		"ModuleInitializationError",
+		"ConfigurationError",
+		"CqrsError",
+		"DatabaseError",
+		"BullMQError",
+		"RabbitMQError",
+		"ScheduleError",
+		"TestingError",
+		"RateLimitError",
+		"UploadError",
+		"EmailError",
+		"HttpParamError",
+		"GuardError",
+		"AdapterError",
+		"ImportError",
+		"ErrorFormatter",
+		"Guard",
+		"UseGuards",
+		"HttpException",
+		"BadRequestException",
+		"UnauthorizedException",
+		"ForbiddenException",
+		"NotFoundException",
+		"ConflictException",
+		"UnprocessableEntityException",
+		"InternalServerErrorException",
+		"OkResponse",
+		"CreatedResponse",
+		"NoContentResponse",
+		"HttpMethod",
+		"Body",
+		"Param",
+		"Query",
+		"Headers",
+		"Req",
+		"Res",
+		"FormData",
+		"Injectable",
+		"Jwt",
+		"JwtModule",
+		"JwtService",
+		"UseJwt",
+		"Module",
+		"OnModuleInit",
+		"OnModuleDestroy",
+		"ApiTags",
+		"ApiOperation",
+		"ApiResponse",
+		"ApiBody",
+		"Render",
+		"Cron",
+		"Timeout",
+		"Test",
+		"TestingModuleBuilder",
+		"TestApp",
+		"Logger",
+	];
+
+	const isTypeOnly = TYPE_ONLY.has(name);
+	const suggestions = closestMatchesCli(
+		name,
+		isTypeOnly ? ALL_VALUES : [...ALL_VALUES, ...TYPE_ONLY],
+	);
+
+	const code = isTypeOnly ? "BNS-IMP-001" : "BNS-IMP-002";
+
+	console.error(`\n${red(BORDER)}`);
+	console.error(red(bold("  💥  Bunstone — Import Error")));
+	console.error(`${red(BORDER)}\n`);
+
+	console.error(
+		`  ${yellow(bold("Code     :"))} ${bold(code)}  ${gray(`(ImportError)`)}`,
+	);
+
+	if (isTypeOnly) {
+		console.error(
+			`  ${yellow(bold("Message  :"))} '${name}' is a ${bold("type-only")} export of '${pkg}' — it does not exist at runtime.`,
+		);
+		console.error(`\n  ${green(bold("💡 How to fix:"))}`);
+		console.error(
+			green(
+				[
+					`    Replace the import with 'import type':`,
+					``,
+					`      ${red("✗")}  import { ${name} } from '${pkg}'`,
+					`      ${green("✓")}  import type { ${name} } from '${pkg}'`,
+				].join("\n"),
+			),
+		);
+		if (suggestions.length > 0) {
+			console.error(
+				`\n  ${cyan("If you were looking for a runtime value with a similar name:")}`,
+			);
+			for (const s of suggestions) {
+				console.error(`    ${gray("→")} ${s}`);
+			}
+		}
+	} else {
+		console.error(
+			`  ${yellow(bold("Message  :"))} '${name}' is not exported by '${pkg}'.`,
+		);
+		console.error(`\n  ${green(bold("💡 How to fix:"))}`);
+		console.error(green(`    Check the spelling of the imported name.`));
+		console.error(
+			green(
+				`    Run ${bold("bunstone exports")} to see all available exports.`,
+			),
+		);
+		if (suggestions.length > 0) {
+			console.error(`\n  ${cyan("Did you mean one of these?")}`);
+			for (const s of suggestions) {
+				console.error(`    ${gray("→")} ${s}`);
+			}
+		}
+	}
+
+	console.error(`\n${red(THIN)}`);
+	console.error(red(bold("  ✖  Fix the import above and restart.")));
+	console.error(`${red(BORDER)}\n`);
+}
+
+/** Minimal inline Levenshtein for the CLI (avoids importing from dist). */
+function closestMatchesCli(
+	name: string,
+	candidates: Iterable<string>,
+	limit = 5,
+	maxDist = 4,
+): string[] {
+	function dist(a: string, b: string) {
+		const s1 = a.toLowerCase();
+		const s2 = b.toLowerCase();
+		const [m, n] = [s1.length, s2.length];
+		const dp = Array.from({ length: m + 1 }, (_, i) =>
+			Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)),
+		);
+		for (let i = 1; i <= m; i++)
+			for (let j = 1; j <= n; j++)
+				dp[i][j] =
+					s1[i - 1] === s2[j - 1]
+						? dp[i - 1][j - 1]
+						: 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+		return dp[m][n];
+	}
+
+	const results: { name: string; d: number }[] = [];
+	for (const c of candidates) {
+		const d = dist(name, c);
+		if (d <= maxDist) results.push({ name: c, d });
+	}
+	return results
+		.sort((a, b) => a.d - b.d)
+		.slice(0, limit)
+		.map((r) => r.name);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// bunstone exports
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function exportsCommand() {
+	const VALUE_EXPORTS = [
+		"CacheAdapter",
+		"FormDataAdapter",
+		"UploadAdapter",
+		"EmailModule",
+		"EmailService",
+		"EmailLayout",
+		"AppStartup",
+		"Layout",
+		"Controller",
+		"Get",
+		"Post",
+		"Put",
+		"Patch",
+		"Delete",
+		"Head",
+		"RateLimit",
+		"RateLimitGuard",
+		"RedisStorage",
+		"CommandBus",
+		"CqrsModule",
+		"CommandHandler",
+		"EventHandler",
+		"QueryHandler",
+		"Saga",
+		"EventBus",
+		"QueryBus",
+		"SqlModule",
+		"SqlService",
+		"BullMqModule",
+		"QueueService",
+		"Processor",
+		"Process",
+		"RabbitMQModule",
+		"RabbitMQService",
+		"RabbitMQDeadLetterService",
+		"RabbitMQConnection",
+		"RabbitConsumer",
+		"RabbitSubscribe",
+		"BunstoneError",
+		"DependencyResolutionError",
+		"ModuleInitializationError",
+		"ConfigurationError",
+		"CqrsError",
+		"DatabaseError",
+		"BullMQError",
+		"RabbitMQError",
+		"ScheduleError",
+		"TestingError",
+		"RateLimitError",
+		"UploadError",
+		"EmailError",
+		"HttpParamError",
+		"GuardError",
+		"AdapterError",
+		"ImportError",
+		"ErrorFormatter",
+		"Guard",
+		"UseGuards",
+		"HttpException",
+		"BadRequestException",
+		"UnauthorizedException",
+		"ForbiddenException",
+		"NotFoundException",
+		"ConflictException",
+		"UnprocessableEntityException",
+		"InternalServerErrorException",
+		"OkResponse",
+		"CreatedResponse",
+		"NoContentResponse",
+		"HttpMethod",
+		"Body",
+		"Param",
+		"Query",
+		"Headers",
+		"Req",
+		"Res",
+		"FormData",
+		"Injectable",
+		"Jwt",
+		"JwtModule",
+		"JwtService",
+		"UseJwt",
+		"Module",
+		"OnModuleInit",
+		"OnModuleDestroy",
+		"ApiTags",
+		"ApiOperation",
+		"ApiResponse",
+		"ApiBody",
+		"Render",
+		"Cron",
+		"Timeout",
+		"Test",
+		"TestingModuleBuilder",
+		"TestApp",
+		"Logger",
+	];
+	const TYPE_ONLY_EXPORTS = [
+		"RabbitMessage",
+		"RabbitPublishOptions",
+		"RabbitSubscribeOptions",
+		"DeadLetterMessage",
+		"DeadLetterDeathInfo",
+		"RequeueOptions",
+		"RabbitMQExchangeConfig",
+		"RabbitMQQueueBinding",
+		"RabbitMQQueueConfig",
+		"RabbitMQReconnectConfig",
+		"RabbitMQModuleOptions",
+		"HttpRequest",
+		"ModuleConfig",
+		"Options",
+		"GuardContract",
+	];
+
+	console.log(`\n${bold("@grupodiariodaregiao/bunstone")} — Public Exports\n`);
+	console.log(cyan(bold("  Value exports  ")) + gray("(import { ... })"));
+	for (const name of VALUE_EXPORTS.sort())
+		console.log(`    ${gray("·")} ${name}`);
+
+	console.log();
+	console.log(
+		yellow(bold("  Type-only exports  ")) + gray("(import type { ... })"),
+	);
+	for (const name of TYPE_ONLY_EXPORTS.sort())
+		console.log(`    ${gray("·")} ${name}`);
+	console.log();
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// bunstone new <project-name>
+// ─────────────────────────────────────────────────────────────────────────────
+
 const starterPath = join(import.meta.dir, "..", "starter");
 
 async function copyDir(src: string, dest: string) {
@@ -34,28 +476,20 @@ async function copyDir(src: string, dest: string) {
 		const srcPath = join(src, entry.name);
 		const destPath = join(dest, entry.name);
 
-		if (entry.isDirectory()) {
-			await copyDir(srcPath, destPath);
-		} else {
-			await copyFile(srcPath, destPath);
-		}
+		if (entry.isDirectory()) await copyDir(srcPath, destPath);
+		else await copyFile(srcPath, destPath);
 	}
 }
 
-async function scaffold() {
-	if (command !== "new" || !projectName) {
-		console.log("Usage: bunstone new <project-name>");
-		console.log("   or: bunstone <project-name>");
-		process.exit(1);
-	}
+async function scaffold(projectName_?: string) {
+	const projectName = projectName_ ?? "my-bunstone-app";
+	const projectPath = join(process.cwd(), projectName);
 
 	console.log(`🚀 Scaffolding new Bunstone project in ${projectPath}...`);
 
 	try {
-		// Copy the entire starter directory
 		await copyDir(starterPath, projectPath);
 
-		// Update package.json name
 		const pkgPath = join(projectPath, "package.json");
 		const pkgContent = await readFile(pkgPath, "utf-8");
 		const pkg = JSON.parse(pkgContent);
@@ -82,4 +516,22 @@ async function scaffold() {
 	}
 }
 
-scaffold();
+// ─────────────────────────────────────────────────────────────────────────────
+// Help
+// ─────────────────────────────────────────────────────────────────────────────
+
+function printHelp() {
+	console.log(`
+${bold("bunstone")} — CLI for the Bunstone framework
+
+${cyan("Usage:")}
+  bunstone new <project-name>          Scaffold a new project
+  bunstone run [bun-flags] <entry>     Run your app with enhanced error messages
+  bunstone exports                     List all public exports
+
+${cyan("Examples:")}
+  bunstone new my-api
+  bunstone run src/main.ts
+  bunstone run --watch src/main.ts
+`);
+}

package/dist/index.js

@@ -32499,6 +32499,41 @@ class AdapterError extends BunstoneError {
   }
 }
 
+class ImportError extends BunstoneError {
+  constructor(message, code = "BNS-IMP-002", suggestion, context, cause) {
+    super(message, code, suggestion, context, cause);
+  }
+  static typeOnlyImport(name, pkg, valueAlternatives) {
+    const altSection = valueAlternatives.length > 0 ? [
+      "",
+      "If you were looking for a runtime value with a similar name, did you mean one of these?",
+      ...valueAlternatives.map((s) => `  - ${s}`)
+    ].join(`
+  `) : "";
+    return new ImportError(`'${name}' is a type-only export of '${pkg}' \u2014 it does not exist at runtime.`, "BNS-IMP-001", [
+      `Replace the import with 'import type':`,
+      `  \u2717  import { ${name} } from '${pkg}'`,
+      `  \u2713  import type { ${name} } from '${pkg}'`,
+      altSection
+    ].filter(Boolean).join(`
+  `), { name, package: pkg });
+  }
+  static unknownExport(name, pkg, suggestions) {
+    const didYouMean = suggestions.length > 0 ? [
+      "",
+      "Did you mean one of these?",
+      ...suggestions.map((s) => `  - ${s}`)
+    ].join(`
+  `) : "";
+    return new ImportError(`'${name}' is not exported by '${pkg}'.`, "BNS-IMP-002", [
+      "Check the spelling of the imported name.",
+      "Run 'bunstone exports' to see all available exports.",
+      didYouMean
+    ].filter(Boolean).join(`
+  `), { name, package: pkg });
+  }
+}
+
 // lib/injectable.ts
 var import_reflect_metadata = __toESM(require_Reflect(), 1);
 function Injectable() {
@@ -43269,7 +43304,156 @@ var colors = {
   strikethrough: "\x1B[9m"
 };
 
+// lib/utils/fuzzy-match.ts
+function editDistance(a, b3) {
+  const s1 = a.toLowerCase();
+  const s2 = b3.toLowerCase();
+  const m = s1.length;
+  const n2 = s2.length;
+  let prev = Array.from({ length: n2 + 1 }, (_3, j3) => j3);
+  let curr = new Array(n2 + 1).fill(0);
+  for (let i = 1;i <= m; i++) {
+    curr[0] = i;
+    for (let j3 = 1;j3 <= n2; j3++) {
+      const cost = s1[i - 1] === s2[j3 - 1] ? 0 : 1;
+      curr[j3] = cost === 0 ? prev[j3 - 1] : 1 + Math.min(prev[j3], curr[j3 - 1], prev[j3 - 1]);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n2];
+}
+function closestMatches(name2, candidates, limit = 5, maxDistance = 4) {
+  const results = [];
+  for (const candidate of candidates) {
+    const dist = editDistance(name2, candidate);
+    if (dist <= maxDistance) {
+      results.push({ name: candidate, dist });
+    }
+  }
+  results.sort((a, b3) => a.dist - b3.dist);
+  return results.slice(0, limit).map((r2) => r2.name);
+}
+
+// lib/utils/known-exports.ts
+var TYPE_ONLY_EXPORTS = new Set([
+  "RabbitMessage",
+  "RabbitPublishOptions",
+  "RabbitSubscribeOptions",
+  "DeadLetterMessage",
+  "DeadLetterDeathInfo",
+  "RequeueOptions",
+  "RabbitMQExchangeConfig",
+  "RabbitMQQueueBinding",
+  "RabbitMQQueueConfig",
+  "RabbitMQReconnectConfig",
+  "RabbitMQModuleOptions",
+  "HttpRequest",
+  "ModuleConfig",
+  "Options",
+  "GuardContract"
+]);
+var VALUE_EXPORTS = [
+  "CacheAdapter",
+  "FormDataAdapter",
+  "UploadAdapter",
+  "EmailModule",
+  "EmailService",
+  "EmailLayout",
+  "AppStartup",
+  "Layout",
+  "Controller",
+  "Get",
+  "Post",
+  "Put",
+  "Patch",
+  "Delete",
+  "Head",
+  "Options",
+  "RateLimit",
+  "RateLimitGuard",
+  "RedisStorage",
+  "CommandBus",
+  "CqrsModule",
+  "CommandHandler",
+  "EventHandler",
+  "QueryHandler",
+  "Saga",
+  "EventBus",
+  "QueryBus",
+  "SqlModule",
+  "SqlService",
+  "BullMqModule",
+  "QueueService",
+  "Processor",
+  "Process",
+  "RabbitMQModule",
+  "RabbitMQService",
+  "RabbitMQDeadLetterService",
+  "RabbitMQConnection",
+  "RabbitConsumer",
+  "RabbitSubscribe",
+  "BunstoneError",
+  "DependencyResolutionError",
+  "ModuleInitializationError",
+  "ConfigurationError",
+  "CqrsError",
+  "DatabaseError",
+  "BullMQError",
+  "RabbitMQError",
+  "ScheduleError",
+  "TestingError",
+  "RateLimitError",
+  "UploadError",
+  "EmailError",
+  "HttpParamError",
+  "GuardError",
+  "AdapterError",
+  "ImportError",
+  "ErrorFormatter",
+  "Guard",
+  "UseGuards",
+  "HttpException",
+  "BadRequestException",
+  "UnauthorizedException",
+  "ForbiddenException",
+  "NotFoundException",
+  "ConflictException",
+  "UnprocessableEntityException",
+  "InternalServerErrorException",
+  "OkResponse",
+  "CreatedResponse",
+  "NoContentResponse",
+  "HttpMethod",
+  "Body",
+  "Param",
+  "Query",
+  "Headers",
+  "Req",
+  "Res",
+  "FormData",
+  "Injectable",
+  "Jwt",
+  "JwtModule",
+  "JwtService",
+  "UseJwt",
+  "Module",
+  "OnModuleInit",
+  "OnModuleDestroy",
+  "ApiTags",
+  "ApiOperation",
+  "ApiResponse",
+  "ApiBody",
+  "Render",
+  "Cron",
+  "Timeout",
+  "Test",
+  "TestingModuleBuilder",
+  "TestApp",
+  "Logger"
+];
+
 // lib/utils/error-formatter.ts
+var BUN_EXPORT_NOT_FOUND = /Export named '(.+?)' not found in module '(.+?)'/;
 var BORDER = "\u2501".repeat(64);
 var THIN = "\u2500".repeat(64);
 function label(text, color) {
@@ -43282,8 +43466,26 @@ function indent(text, spaces = 4) {
 }
 
 class ErrorFormatter {
+  static fromBunSyntaxError(error) {
+    if (!(error instanceof SyntaxError))
+      return null;
+    const match = BUN_EXPORT_NOT_FOUND.exec(error.message);
+    if (!match)
+      return null;
+    const name2 = match[1] ?? "";
+    const modulePath = match[2] ?? "";
+    const pkg = modulePath.includes("node_modules/") ? modulePath.replace(/.*node_modules\//, "").replace(/\/dist.*/, "") : modulePath;
+    if (TYPE_ONLY_EXPORTS.has(name2)) {
+      const valueAlternatives = closestMatches(name2, VALUE_EXPORTS);
+      return ImportError.typeOnlyImport(name2, pkg, valueAlternatives);
+    }
+    const allNames = [...VALUE_EXPORTS, ...TYPE_ONLY_EXPORTS];
+    const suggestions = closestMatches(name2, allNames);
+    return ImportError.unknownExport(name2, pkg, suggestions);
+  }
   static format(error, exit = false) {
-    const e2 = error;
+    const upgraded = ErrorFormatter.fromBunSyntaxError(error);
+    const e2 = upgraded ?? error;
     console.error(`
 ${colors.red}${BORDER}${colors.reset}`);
     console.error(`${colors.red}${colors.bold}  \uD83D\uDCA5  Bunstone \u2014 Error Report${colors.reset}`);
@@ -117981,6 +118183,13 @@ if (document.readyState === 'loading') {
                     return raw.content.toString();
                   }
                 })();
+                const xDeath = raw.properties.headers?.["x-death"];
+                const isDeadLetter = Array.isArray(xDeath) && xDeath.length > 0;
+                const isDlqQueue = queueName.toLowerCase().includes(".dlq");
+                if ((isDlqQueue || descriptor.options.queue?.toLowerCase().includes(".dlq")) && !isDeadLetter) {
+                  channel.ack(raw);
+                  return;
+                }
                 const msg = {
                   data,
                   raw,
@@ -117993,7 +118202,7 @@ if (document.readyState === 'loading') {
                 } catch (err) {
                   AppStartup.logger.error(`Unhandled error in RabbitMQ handler ${providerClass.name}.${descriptor.methodName}() on exchange "${exchange}" routingKey "${routingKey}": ${err.message}`);
                   if (!noAck) {
-                    channel.nack(raw, false, true);
+                    channel.nack(raw, false, false);
                   }
                 }
               }, { noAck });
@@ -118036,6 +118245,13 @@ if (document.readyState === 'loading') {
                 return raw.content.toString();
               }
             })();
+            const xDeath = raw.properties.headers?.["x-death"];
+            const isDeadLetter = Array.isArray(xDeath) && xDeath.length > 0;
+            const isDlqQueue = queue2.toLowerCase().includes(".dlq");
+            if (isDlqQueue && !isDeadLetter) {
+              channel.ack(raw);
+              return;
+            }
             let settled = false;
             const settle = (fn3) => {
               if (!settled) {
@@ -118065,7 +118281,7 @@ if (document.readyState === 'loading') {
               } catch (err) {
                 AppStartup.logger.error(`Unhandled error in RabbitMQ handler ${providerName}.${descriptor.methodName}() on queue "${queue2}": ${err.message}`);
                 if (!handlerNoAck && !settled) {
-                  settle(() => channel.nack(raw, false, true));
+                  settle(() => channel.nack(raw, false, false));
                 }
               }
             }
@@ -120335,6 +120551,7 @@ export {
   Jwt,
   InternalServerErrorException,
   Injectable,
+  ImportError,
   HttpParamError,
   HttpException,
   Header,

package/dist/lib/errors/index.d.ts

@@ -196,3 +196,26 @@ export declare class GuardError extends BunstoneError {
 export declare class AdapterError extends BunstoneError {
     constructor(message: string, code?: "BNS-ADP-001" | "BNS-ADP-002", suggestion?: string, context?: Record<string, unknown>, cause?: Error);
 }
+/**
+ * Represents an import-time error detected by the `bunstone run` CLI.
+ *
+ * Bun raises a raw `SyntaxError: Export named 'X' not found` that gives no
+ * guidance on the problem.  This error carries structured context so the CLI
+ * can print a rich, actionable crash report.
+ *
+ * Codes:
+ * - `BNS-IMP-001` – name is a type-only export (must use `import type`)
+ * - `BNS-IMP-002` – name does not exist at all in the package (typo / wrong name)
+ */
+export declare class ImportError extends BunstoneError {
+    constructor(message: string, code?: "BNS-IMP-001" | "BNS-IMP-002", suggestion?: string, context?: Record<string, unknown>, cause?: Error);
+    /**
+     * The user imported a type-only name as a value.
+     * e.g. `import { RabbitMessage }` instead of `import type { RabbitMessage }`.
+     */
+    static typeOnlyImport(name: string, pkg: string, valueAlternatives: string[]): ImportError;
+    /**
+     * The user imported a name that does not exist in the package at all.
+     */
+    static unknownExport(name: string, pkg: string, suggestions: string[]): ImportError;
+}

package/dist/lib/utils/error-formatter.d.ts

@@ -1,3 +1,4 @@
+import { ImportError } from "../errors";
 /**
  * Formats and prints a structured "Crash Report" whenever a `BunstoneError`
  * (or any unhandled error) aborts initialisation.
@@ -22,6 +23,13 @@
  * ────────────────────────────────────────────────────────────────
  */
 export declare class ErrorFormatter {
+    /**
+     * Attempts to convert a raw Bun `SyntaxError: Export named 'X' not found`
+     * into a structured `ImportError` with actionable hints.
+     *
+     * Returns `null` when the error does not match the pattern.
+     */
+    static fromBunSyntaxError(error: unknown): ImportError | null;
     /**
      * Prints a full crash report and (optionally) exits the process.
      *

package/dist/lib/utils/fuzzy-match.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Lightweight fuzzy-matching utilities used by the `bunstone run` CLI command
+ * to produce "did you mean?" suggestions when an export name is not found.
+ */
+/**
+ * Levenshtein edit distance between two strings (case-insensitive).
+ */
+export declare function editDistance(a: string, b: string): number;
+/**
+ * Returns up to `limit` closest matches for `name` from `candidates`,
+ * ordered by edit distance (closest first).
+ *
+ * Only returns candidates whose distance is ≤ `maxDistance`.
+ */
+export declare function closestMatches(name: string, candidates: Iterable<string>, limit?: number, maxDistance?: number): string[];

package/dist/lib/utils/known-exports.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Catalogue of every public name exported from the bunstone package,
+ * split by whether it is a **value** (present at runtime) or a **type**
+ * (erased at compile-time, absent from the JS bundle).
+ *
+ * Used by the `bunstone run` CLI command to produce "did you mean?" hints
+ * when Bun throws `SyntaxError: Export named 'X' not found`.
+ */
+/** Names that are exported with `export type` – they do NOT exist in the JS bundle. */
+export declare const TYPE_ONLY_EXPORTS: ReadonlySet<string>;
+/**
+ * All value names shipped in the bundle.
+ * Keep in sync with `index.ts`.
+ */
+export declare const VALUE_EXPORTS: ReadonlyArray<string>;

package/lib/app-startup.ts

@@ -1080,6 +1080,24 @@ if (document.readyState === 'loading') {
 										}
 									})();
 
+									const xDeath = raw.properties.headers?.["x-death"];
+									const isDeadLetter =
+										Array.isArray(xDeath) && xDeath.length > 0;
+									const isDlqQueue = queueName.toLowerCase().includes(".dlq");
+
+									// If the handler is on a DLQ or uses DeadLetterMessage type,
+									// only process messages that have x-death headers.
+									if (
+										(isDlqQueue ||
+											descriptor.options.queue
+												?.toLowerCase()
+												.includes(".dlq")) &&
+										!isDeadLetter
+									) {
+										channel.ack(raw);
+										return;
+									}
+
 									const msg: RabbitMessage = {
 										data,
 										raw,
@@ -1095,7 +1113,7 @@ if (document.readyState === 'loading') {
 											`Unhandled error in RabbitMQ handler ${providerClass.name}.${descriptor.methodName}() on exchange "${exchange}" routingKey "${routingKey}": ${err.message}`,
 										);
 										if (!noAck) {
-											channel.nack(raw, false, true);
+											channel.nack(raw, false, false);
 										}
 									}
 								},
@@ -1161,6 +1179,17 @@ if (document.readyState === 'loading') {
 								}
 							})();
 
+							const xDeath = raw.properties.headers?.["x-death"];
+							const isDeadLetter = Array.isArray(xDeath) && xDeath.length > 0;
+							const isDlqQueue = queue.toLowerCase().includes(".dlq");
+
+							// If this is a DLQ, skip messages that don't have x-death headers
+							// (i.e. someone published directly to the DLQ instead of it being a failed message)
+							if (isDlqQueue && !isDeadLetter) {
+								channel.ack(raw);
+								return;
+							}
+
 							// Settle guard: ack/nack/reject may only be called once per
 							// delivery tag regardless of how many handlers invoke it.
 							let settled = false;
@@ -1204,7 +1233,7 @@ if (document.readyState === 'loading') {
 										`Unhandled error in RabbitMQ handler ${providerName}.${descriptor.methodName}() on queue "${queue}": ${err.message}`,
 									);
 									if (!handlerNoAck && !settled) {
-										settle(() => channel.nack(raw, false, true));
+										settle(() => channel.nack(raw, false, false));
 									}
 								}
 							}

package/lib/errors/index.ts

@@ -679,3 +679,92 @@ export class AdapterError extends BunstoneError {
 		super(message, code, suggestion, context, cause);
 	}
 }
+
+// ─── Import ───────────────────────────────────────────────────────────────────
+
+/**
+ * Represents an import-time error detected by the `bunstone run` CLI.
+ *
+ * Bun raises a raw `SyntaxError: Export named 'X' not found` that gives no
+ * guidance on the problem.  This error carries structured context so the CLI
+ * can print a rich, actionable crash report.
+ *
+ * Codes:
+ * - `BNS-IMP-001` – name is a type-only export (must use `import type`)
+ * - `BNS-IMP-002` – name does not exist at all in the package (typo / wrong name)
+ */
+export class ImportError extends BunstoneError {
+	constructor(
+		message: string,
+		code: "BNS-IMP-001" | "BNS-IMP-002" = "BNS-IMP-002",
+		suggestion?: string,
+		context?: Record<string, unknown>,
+		cause?: Error,
+	) {
+		super(message, code, suggestion, context, cause);
+	}
+
+	/**
+	 * The user imported a type-only name as a value.
+	 * e.g. `import { RabbitMessage }` instead of `import type { RabbitMessage }`.
+	 */
+	static typeOnlyImport(
+		name: string,
+		pkg: string,
+		valueAlternatives: string[],
+	): ImportError {
+		const altSection =
+			valueAlternatives.length > 0
+				? [
+						"",
+						"If you were looking for a runtime value with a similar name, did you mean one of these?",
+						...valueAlternatives.map((s) => `  - ${s}`),
+					].join("\n  ")
+				: "";
+
+		return new ImportError(
+			`'${name}' is a type-only export of '${pkg}' — it does not exist at runtime.`,
+			"BNS-IMP-001",
+			[
+				`Replace the import with 'import type':`,
+				`  ✗  import { ${name} } from '${pkg}'`,
+				`  ✓  import type { ${name} } from '${pkg}'`,
+				altSection,
+			]
+				.filter(Boolean)
+				.join("\n  "),
+			{ name, package: pkg },
+		);
+	}
+
+	/**
+	 * The user imported a name that does not exist in the package at all.
+	 */
+	static unknownExport(
+		name: string,
+		pkg: string,
+		suggestions: string[],
+	): ImportError {
+		const didYouMean =
+			suggestions.length > 0
+				? [
+						"",
+						"Did you mean one of these?",
+						...suggestions.map((s) => `  - ${s}`),
+					].join("\n  ")
+				: "";
+
+		return new ImportError(
+			`'${name}' is not exported by '${pkg}'.`,
+			"BNS-IMP-002",
+			[
+				"Check the spelling of the imported name.",
+				"Run 'bunstone exports' to see all available exports.",
+				didYouMean,
+			]
+				.filter(Boolean)
+				.join("\n  "),
+			{ name, package: pkg },
+		);
+	}
+}

package/lib/utils/error-formatter.ts

@@ -1,5 +1,10 @@
-import { BunstoneError } from "../errors";
+import { BunstoneError, ImportError } from "../errors";
 import { colors } from "./colors";
+import { closestMatches } from "./fuzzy-match";
+import { TYPE_ONLY_EXPORTS, VALUE_EXPORTS } from "./known-exports";
+
+/** Regexp that matches Bun's "Export named 'X' not found in module 'Y'." message. */
+const BUN_EXPORT_NOT_FOUND = /Export named '(.+?)' not found in module '(.+?)'/;
 
 const BORDER = "━".repeat(64);
 const THIN = "─".repeat(64);
@@ -39,6 +44,36 @@ function indent(text: string, spaces = 4): string {
  * ────────────────────────────────────────────────────────────────
  */
 export class ErrorFormatter {
+	/**
+	 * Attempts to convert a raw Bun `SyntaxError: Export named 'X' not found`
+	 * into a structured `ImportError` with actionable hints.
+	 *
+	 * Returns `null` when the error does not match the pattern.
+	 */
+	static fromBunSyntaxError(error: unknown): ImportError | null {
+		if (!(error instanceof SyntaxError)) return null;
+
+		const match = BUN_EXPORT_NOT_FOUND.exec(error.message);
+		if (!match) return null;
+
+		const name = match[1] ?? "";
+		const modulePath = match[2] ?? "";
+		const pkg = modulePath.includes("node_modules/")
+			? modulePath.replace(/.*node_modules\//, "").replace(/\/dist.*/, "")
+			: modulePath;
+
+		if (TYPE_ONLY_EXPORTS.has(name)) {
+			// Name exists but is type-only
+			const valueAlternatives = closestMatches(name, VALUE_EXPORTS);
+			return ImportError.typeOnlyImport(name, pkg, valueAlternatives);
+		}
+
+		// Name does not exist at all – fuzzy match against all known names
+		const allNames = [...VALUE_EXPORTS, ...TYPE_ONLY_EXPORTS];
+		const suggestions = closestMatches(name, allNames);
+		return ImportError.unknownExport(name, pkg, suggestions);
+	}
+
 	/**
 	 * Prints a full crash report and (optionally) exits the process.
 	 *
@@ -46,7 +81,9 @@ export class ErrorFormatter {
 	 * @param exit     When `true` (default), calls `process.exit(1)` after printing.
 	 */
 	static format(error: unknown, exit = false): void {
-		const e = error as any;
+		// Upgrade raw Bun import errors before formatting
+		const upgraded = ErrorFormatter.fromBunSyntaxError(error);
+		const e = (upgraded ?? error) as any;
 
 		console.error(`\n${colors.red}${BORDER}${colors.reset}`);
 		console.error(

package/lib/utils/fuzzy-match.ts

@@ -0,0 +1,62 @@
+/**
+ * Lightweight fuzzy-matching utilities used by the `bunstone run` CLI command
+ * to produce "did you mean?" suggestions when an export name is not found.
+ */
+
+/**
+ * Levenshtein edit distance between two strings (case-insensitive).
+ */
+export function editDistance(a: string, b: string): number {
+	const s1 = a.toLowerCase();
+	const s2 = b.toLowerCase();
+	const m = s1.length;
+	const n = s2.length;
+
+	// Two-row rolling DP – avoids 2D-array index safety issues.
+	let prev: number[] = Array.from({ length: n + 1 }, (_, j) => j);
+	let curr: number[] = new Array<number>(n + 1).fill(0);
+
+	for (let i = 1; i <= m; i++) {
+		curr[0] = i;
+		for (let j = 1; j <= n; j++) {
+			const cost = s1[i - 1] === s2[j - 1] ? 0 : 1;
+			curr[j] =
+				cost === 0
+					? (prev[j - 1] as number)
+					: 1 +
+						Math.min(
+							prev[j] as number,
+							curr[j - 1] as number,
+							prev[j - 1] as number,
+						);
+		}
+		[prev, curr] = [curr, prev];
+	}
+
+	return prev[n] as number;
+}
+
+/**
+ * Returns up to `limit` closest matches for `name` from `candidates`,
+ * ordered by edit distance (closest first).
+ *
+ * Only returns candidates whose distance is ≤ `maxDistance`.
+ */
+export function closestMatches(
+	name: string,
+	candidates: Iterable<string>,
+	limit = 5,
+	maxDistance = 4,
+): string[] {
+	const results: { name: string; dist: number }[] = [];
+
+	for (const candidate of candidates) {
+		const dist = editDistance(name, candidate);
+		if (dist <= maxDistance) {
+			results.push({ name: candidate, dist });
+		}
+	}
+
+	results.sort((a, b) => a.dist - b.dist);
+	return results.slice(0, limit).map((r) => r.name);
+}

package/lib/utils/known-exports.ts

@@ -0,0 +1,162 @@
+/**
+ * Catalogue of every public name exported from the bunstone package,
+ * split by whether it is a **value** (present at runtime) or a **type**
+ * (erased at compile-time, absent from the JS bundle).
+ *
+ * Used by the `bunstone run` CLI command to produce "did you mean?" hints
+ * when Bun throws `SyntaxError: Export named 'X' not found`.
+ */
+
+// ── Type-only exports (erased at runtime) ─────────────────────────────────
+
+/** Names that are exported with `export type` – they do NOT exist in the JS bundle. */
+export const TYPE_ONLY_EXPORTS: ReadonlySet<string> = new Set([
+	// rabbitmq-message.interface
+	"RabbitMessage",
+	"RabbitPublishOptions",
+	"RabbitSubscribeOptions",
+	"DeadLetterMessage",
+	"DeadLetterDeathInfo",
+	"RequeueOptions",
+	// rabbitmq-options.interface
+	"RabbitMQExchangeConfig",
+	"RabbitMQQueueBinding",
+	"RabbitMQQueueConfig",
+	"RabbitMQReconnectConfig",
+	"RabbitMQModuleOptions",
+	// general types
+	"HttpRequest",
+	"ModuleConfig",
+	"Options",
+	"GuardContract",
+]);
+
+// ── Value exports (present at runtime) ────────────────────────────────────
+
+/**
+ * All value names shipped in the bundle.
+ * Keep in sync with `index.ts`.
+ */
+export const VALUE_EXPORTS: ReadonlyArray<string> = [
+	// adapters
+	"CacheAdapter",
+	"FormDataAdapter",
+	"UploadAdapter",
+	// email
+	"EmailModule",
+	"EmailService",
+	"EmailLayout",
+	// app
+	"AppStartup",
+	// components
+	"Layout",
+	// controller
+	"Controller",
+	"Get",
+	"Post",
+	"Put",
+	"Patch",
+	"Delete",
+	"Head",
+	"Options",
+	// rate limit
+	"RateLimit",
+	"RateLimitGuard",
+	"RedisStorage",
+	// cqrs
+	"CommandBus",
+	"CqrsModule",
+	"CommandHandler",
+	"EventHandler",
+	"QueryHandler",
+	"Saga",
+	"EventBus",
+	"QueryBus",
+	// database
+	"SqlModule",
+	"SqlService",
+	// bullmq
+	"BullMqModule",
+	"QueueService",
+	"Processor",
+	"Process",
+	// rabbitmq
+	"RabbitMQModule",
+	"RabbitMQService",
+	"RabbitMQDeadLetterService",
+	"RabbitMQConnection",
+	"RabbitConsumer",
+	"RabbitSubscribe",
+	// errors
+	"BunstoneError",
+	"DependencyResolutionError",
+	"ModuleInitializationError",
+	"ConfigurationError",
+	"CqrsError",
+	"DatabaseError",
+	"BullMQError",
+	"RabbitMQError",
+	"ScheduleError",
+	"TestingError",
+	"RateLimitError",
+	"UploadError",
+	"EmailError",
+	"HttpParamError",
+	"GuardError",
+	"AdapterError",
+	"ImportError",
+	"ErrorFormatter",
+	// guard
+	"Guard",
+	"UseGuards",
+	// http-exceptions
+	"HttpException",
+	"BadRequestException",
+	"UnauthorizedException",
+	"ForbiddenException",
+	"NotFoundException",
+	"ConflictException",
+	"UnprocessableEntityException",
+	"InternalServerErrorException",
+	"OkResponse",
+	"CreatedResponse",
+	"NoContentResponse",
+	// http-methods
+	"HttpMethod",
+	// http-params
+	"Body",
+	"Param",
+	"Query",
+	"Headers",
+	"Req",
+	"Res",
+	"FormData",
+	// injectable
+	"Injectable",
+	// jwt
+	"Jwt",
+	"JwtModule",
+	"JwtService",
+	"UseJwt",
+	// module
+	"Module",
+	// on-module
+	"OnModuleInit",
+	"OnModuleDestroy",
+	// openapi
+	"ApiTags",
+	"ApiOperation",
+	"ApiResponse",
+	"ApiBody",
+	// render
+	"Render",
+	// schedule
+	"Cron",
+	"Timeout",
+	// testing
+	"Test",
+	"TestingModuleBuilder",
+	"TestApp",
+	// logger
+	"Logger",
+];

package/package.json

@@ -13,7 +13,7 @@
       "types": "./dist/*.d.ts"
     }
   },
-  "version": "0.4.5",
+  "version": "0.4.7",
   "homepage": "https://bunstone.diario.one/",
   "repository": {
     "url": "https://github.com/diariodaregiao/bunstone.git",