@akanjs/devkit 3.0.0-beta.19 → 3.0.0-beta.20

package/commandDecorators/helpFormatter.ts

@@ -1,191 +1,119 @@
 import chalk from "chalk";
 
 import { type EnumChoice, getArgMetas } from "./argMeta";
+import { camelToKebabCase } from "./camelToKebabCase";
 import { type CommandCls, getTargetMetas } from "./targetMeta";
 
-const camelToKebabCase = (str: string) => str.replace(/([A-Z])/g, "-$1").toLowerCase();
 const formatChoice = (choice: EnumChoice) => (typeof choice === "object" ? choice.label : choice.toString());
 
 const groupCommands = (commands: CommandCls[]) => {
-  const groups = new Map<string, { name: string; commands: { key: string; args: string[]; desc?: string }[] }>();
-
+  const groups = new Map<string, { key: string; args: string[]; desc?: string }[]>();
   for (const command of commands) {
-    const className = command.name.replace("Command", "");
-    const groupName = className;
-
-    if (!groups.has(groupName)) {
-      groups.set(groupName, { name: groupName, commands: [] });
-    }
-
-    const targetMetas = getTargetMetas(command);
-    for (const targetMeta of targetMetas) {
-      // Skip devOnly commands in help
+    const group = groups.getOrInsert(command.name.replace("Command", ""), []);
+    for (const targetMeta of getTargetMetas(command)) {
       if (targetMeta.targetOption.devOnly) continue;
-
       const [allArgMetas] = getArgMetas(command, targetMeta.key);
       const args = allArgMetas
         .filter((arg) => arg.type !== "Option")
         .map((arg) => {
           if (arg.type === "Workspace") return "";
           if (arg.type === "Module") return "[sys:module]";
-          if (arg.type === "Argument") {
-            return `[${arg.name}]`;
-          }
+          if (arg.type === "Argument") return `[${arg.name}]`;
           return `[${arg.type.toLowerCase()}]`;
         })
         .filter(Boolean);
-
-      const group = groups.get(groupName);
-      if (group) {
-        group.commands.push({
-          key: camelToKebabCase(targetMeta.key),
-          args,
-          desc: targetMeta.targetOption.desc,
-        });
-      }
+      group.push({ key: camelToKebabCase(targetMeta.key), args, desc: targetMeta.targetOption.desc });
     }
   }
-
   return groups;
 };
 
 export const formatHelp = (commands: CommandCls[], version: string) => {
-  const groups = groupCommands(commands);
-  const lines: string[] = [];
-
-  // Header
-  lines.push("");
-  lines.push(chalk.bold.cyan("  ╔═══════════════════════════════════════════════════╗"));
-  lines.push(
+  const lines = [
+    "",
+    chalk.bold.cyan("  ╔═══════════════════════════════════════════════════╗"),
     chalk.bold.cyan("  ║") +
       chalk.bold.white("              Akan.js Framework CLI            ") +
       chalk.bold.cyan("    ║"),
-  );
-  lines.push(chalk.bold.cyan("  ╚═══════════════════════════════════════════════════╝"));
-  lines.push("");
-  lines.push(chalk.gray(`  Version: ${version}`));
-  lines.push("");
-
-  // Usage
-  lines.push(chalk.bold.yellow("  USAGE"));
-  lines.push("");
-  lines.push(chalk.gray("    $ ") + chalk.white("akan") + chalk.gray(" <command> [options]"));
-  lines.push("");
-
-  // Commands by category
-  lines.push(chalk.bold.yellow("  COMMANDS"));
-  lines.push("");
-
-  for (const [groupName, group] of groups) {
-    // Skip empty groups (all commands are devOnly)
-    if (group.commands.length === 0) continue;
-
-    lines.push(chalk.bold.magenta(`    ${groupName}`));
-    lines.push("");
-
-    for (const cmd of group.commands) {
-      const cmdName = chalk.green(cmd.key);
-      const cmdArgs = cmd.args.length > 0 ? chalk.gray(` ${cmd.args.join(" ")}`) : "";
-
-      // Format description: wrap if too long
-      if (cmd.desc) {
-        const maxLineLength = 70;
-        const cmdPrefix = `      ${cmdName}${cmdArgs}`;
-        const indent = "        ";
-
-        if (cmdPrefix.length + cmd.desc.length + 3 < maxLineLength) {
-          // Single line
-          lines.push(`${cmdPrefix}  ${chalk.gray(cmd.desc)}`);
-        } else {
-          // Multi-line
-          lines.push(cmdPrefix);
-          lines.push(`${indent}${chalk.gray(cmd.desc)}`);
-        }
-      } else {
-        lines.push(`      ${cmdName}${cmdArgs}`);
-      }
+    chalk.bold.cyan("  ╚═══════════════════════════════════════════════════╝"),
+    "",
+    chalk.gray(`  Version: ${version}`),
+    "",
+    chalk.bold.yellow("  USAGE"),
+    "",
+    chalk.gray("    $ ") + chalk.white("akan") + chalk.gray(" <command> [options]"),
+    "",
+    chalk.bold.yellow("  COMMANDS"),
+    "",
+  ];
+  for (const [groupName, cmds] of groupCommands(commands)) {
+    if (cmds.length === 0) continue;
+    lines.push(chalk.bold.magenta(`    ${groupName}`), "");
+    for (const cmd of cmds) {
+      const cmdPrefix = `      ${chalk.green(cmd.key)}${cmd.args.length > 0 ? chalk.gray(` ${cmd.args.join(" ")}`) : ""}`;
+      if (!cmd.desc) lines.push(cmdPrefix);
+      else if (cmdPrefix.length + cmd.desc.length + 3 < 70) lines.push(`${cmdPrefix}  ${chalk.gray(cmd.desc)}`);
+      else lines.push(cmdPrefix, `        ${chalk.gray(cmd.desc)}`);
     }
     lines.push("");
   }
-
-  // Global Options
-  lines.push(chalk.bold.yellow("  OPTIONS"));
-  lines.push("");
-  lines.push(`      ${chalk.green("-v, --verbose")}      ${chalk.gray("Enable verbose output")}`);
-  lines.push(`      ${chalk.green("-h, --help")}         ${chalk.gray("Display this help message")}`);
-  lines.push(`      ${chalk.green("-V, --version")}      ${chalk.gray("Output version number")}`);
-  lines.push("");
-
-  // Examples
-  lines.push(chalk.bold.yellow("  EXAMPLES"));
-  lines.push("");
-  lines.push(chalk.gray("    # Create a new workspace"));
-  lines.push(chalk.white("    $ akan create-workspace myproject"));
-  lines.push("");
-  lines.push(chalk.gray("    # Start development server"));
-  lines.push(chalk.white("    $ akan start myapp"));
-  lines.push("");
-  lines.push(chalk.gray("    # Create a new module"));
-  lines.push(chalk.white("    $ akan create-module userProfile"));
-  lines.push("");
-
-  // Footer
-  lines.push(chalk.gray("  Documentation: ") + chalk.cyan("https://akanjs.com/docs"));
-  lines.push(chalk.gray("  Report issues: ") + chalk.cyan("https://github.com/akan-team/akanjs/issues"));
-  lines.push("");
-
+  lines.push(
+    chalk.bold.yellow("  OPTIONS"),
+    "",
+    `      ${chalk.green("-v, --verbose")}      ${chalk.gray("Enable verbose output")}`,
+    `      ${chalk.green("-h, --help")}         ${chalk.gray("Display this help message")}`,
+    `      ${chalk.green("-V, --version")}      ${chalk.gray("Output version number")}`,
+    "",
+    chalk.bold.yellow("  EXAMPLES"),
+    "",
+    chalk.gray("    # Create a new workspace"),
+    chalk.white("    $ akan create-workspace myproject"),
+    "",
+    chalk.gray("    # Start development server"),
+    chalk.white("    $ akan start myapp"),
+    "",
+    chalk.gray("    # Create a new module"),
+    chalk.white("    $ akan create-module userProfile"),
+    "",
+    chalk.gray("  Documentation: ") + chalk.cyan("https://akanjs.com/docs"),
+    chalk.gray("  Report issues: ") + chalk.cyan("https://github.com/akan-team/akanjs/issues"),
+    "",
+  );
   return lines.join("\n");
 };
 
 export const formatCommandHelp = (command: CommandCls, key: string) => {
-  const [allArgMetas, argMetas] = getArgMetas(command, key);
+  const [allArgMetas, optionArgs] = getArgMetas(command, key);
   const kebabKey = camelToKebabCase(key);
-  const lines: string[] = [];
-
-  const targetMetas = getTargetMetas(command);
-  const targetMeta = targetMetas.find((t) => t.key === key);
-  const commandDesc = targetMeta?.targetOption.desc;
-
-  lines.push("");
-  lines.push(chalk.bold.cyan(`  Command: ${kebabKey}`));
-  if (commandDesc) {
-    lines.push(chalk.gray(`  ${commandDesc}`));
-  }
-  lines.push("");
-
-  // Usage
-  const args = allArgMetas
-    .filter((arg) => arg.type !== "Option")
+  const commandDesc = getTargetMetas(command).find((t) => t.key === key)?.targetOption.desc;
+  const nonOptionArgs = allArgMetas.filter((arg) => arg.type !== "Option");
+  const args = nonOptionArgs
     .map((arg) => {
       if (arg.type === "Workspace") return "";
       if (arg.type === "Module") return "[sys:module]";
       if (arg.type === "Apps") return "[apps...]";
-      if (arg.type === "Argument") {
-        return `[${camelToKebabCase(arg.name)}]`;
-      }
+      if (arg.type === "Argument") return `[${camelToKebabCase(arg.name)}]`;
       return `[${arg.type.toLowerCase()}]`;
     })
     .filter(Boolean)
     .join(" ");
 
-  lines.push(chalk.bold.yellow("  USAGE"));
-  lines.push("");
-  lines.push(chalk.gray("    $ ") + chalk.white(`akan ${kebabKey}`) + (args ? chalk.gray(` ${args}`) : ""));
-  lines.push("");
-
-  // Arguments
-  const nonOptionArgs = allArgMetas.filter((arg) => arg.type !== "Option");
+  const lines = ["", chalk.bold.cyan(`  Command: ${kebabKey}`)];
+  if (commandDesc) lines.push(chalk.gray(`  ${commandDesc}`));
+  lines.push(
+    "",
+    chalk.bold.yellow("  USAGE"),
+    "",
+    chalk.gray("    $ ") + chalk.white(`akan ${kebabKey}`) + (args ? chalk.gray(` ${args}`) : ""),
+    "",
+  );
   if (nonOptionArgs.length > 0) {
-    lines.push(chalk.bold.yellow("  ARGUMENTS"));
-    lines.push("");
-
+    lines.push(chalk.bold.yellow("  ARGUMENTS"), "");
     for (const arg of nonOptionArgs) {
       if (arg.type === "Workspace") continue;
-
       let argName: string;
       let argDesc: string;
       let example = "";
-
       if (arg.type === "Argument") {
         argName = camelToKebabCase(arg.name);
         argDesc = arg.argsOption.desc ?? "";
@@ -200,19 +128,13 @@ export const formatCommandHelp = (command: CommandCls, key: string) => {
         argName = arg.type.toLowerCase();
         argDesc = `${arg.type} name in this workspace`;
       }
-
       lines.push(`      ${chalk.green(argName)}      ${chalk.gray(argDesc)}${example}`);
     }
-
     lines.push("");
   }
 
-  // Options
-  const optionArgs = argMetas.filter((a) => a.type === "Option");
   if (optionArgs.length > 0) {
-    lines.push(chalk.bold.yellow("  OPTIONS"));
-    lines.push("");
-
+    lines.push(chalk.bold.yellow("  OPTIONS"), "");
     for (const arg of optionArgs) {
       const opt = arg.argsOption;
       const flag = opt.flag ? `-${opt.flag}, ` : "";

package/commandDecorators/index.ts

@@ -1,8 +1,6 @@
 export * from "./argMeta";
 export * from "./command";
 export * from "./commandBuilder";
-export * from "./commandMeta";
 export * from "./dependencyBuilder";
 export * from "./helpFormatter";
 export * from "./targetMeta";
-export * from "./types";

package/commandDecorators/targetMeta.ts

@@ -1,5 +1,6 @@
 import type { ArgMeta, InternalArgMeta } from "./argMeta";
-import type { DependencyCls } from "./types";
+import { camelToKebabCase } from "./camelToKebabCase";
+import type { Cls, DependencyCls } from "./dependencyBuilder";
 
 export const COMMAND_META: unique symbol = Symbol("akan.command.meta");
 
@@ -22,12 +23,7 @@ export const getTargetMetas = (command: CommandCls): TargetMeta[] => {
   return [...targetMetaMap.values()];
 };
 
-const camelToKebabCase = (str: string) => str.replace(/([A-Z])/g, "-$1").toLowerCase();
-
-/**
- * CLI names a target answers to. Shared with the command-manifest generator so a lazily-loaded CLI
- * resolves `argv[2]` to the same module that `runCommands` would have registered it under.
- */
+/** Shared with the command-manifest generator, so a lazily loaded CLI maps argv[2] to the module runCommands would. */
 export const getTargetCommandNames = (targetMeta: TargetMeta): string[] => {
   const kebabKey = camelToKebabCase(targetMeta.key);
   if (targetMeta.targetOption.short !== true) return [kebabKey];
@@ -48,3 +44,9 @@ export interface TargetOption {
   runsOnWorkspaceRoot?: boolean;
   stdio?: boolean;
 }
+
+export const Commands = () => {
+  return (target: Cls) => {
+    // not implemented yet
+  };
+};

package/createTunnel.ts

@@ -1,18 +1,6 @@
-import type { SshOptions } from "akanjs/base";
-
 import { type AppExecutor, WorkspaceExecutor } from "./executors";
 import { createSshTunnel } from "./sshTunnel";
 
-const getSshTunnelOptions = (app: AppExecutor, environment: string): SshOptions => {
-  const { serveDomain, repoName } = WorkspaceExecutor.getBaseDevEnv();
-  return {
-    host: `${app.name}-${environment}.${serveDomain}`,
-    port: process.env.SSH_TUNNEL_PORT ? parseInt(process.env.SSH_TUNNEL_PORT) : 32767,
-    username: process.env.SSH_TUNNEL_USERNAME ?? "root",
-    password: process.env.SSH_TUNNEL_PASSWORD ?? repoName,
-  };
-};
-
 interface TunnelOption {
   app: AppExecutor;
   environment: string;
@@ -22,7 +10,7 @@ export const createTunnel = async (
   service: "redis" | "postgres",
   { app, environment, port = service === "postgres" ? 5432 : 6379 }: TunnelOption,
 ) => {
-  const sshOptions: SshOptions = getSshTunnelOptions(app, environment);
+  const { serveDomain, repoName } = WorkspaceExecutor.getBaseDevEnv();
   await createSshTunnel({
     localHost: "0.0.0.0",
     localPort: port,
@@ -30,7 +18,12 @@ export const createTunnel = async (
     srcPort: port,
     dstHost: `${service}-0.${service}-svc.${app.name}-${environment}.svc.cluster.local`,
     dstPort: service === "postgres" ? 5432 : 6379,
-    sshOptions,
+    sshOptions: {
+      host: `${app.name}-${environment}.${serveDomain}`,
+      port: process.env.SSH_TUNNEL_PORT ? parseInt(process.env.SSH_TUNNEL_PORT) : 32767,
+      username: process.env.SSH_TUNNEL_USERNAME ?? "root",
+      password: process.env.SSH_TUNNEL_PASSWORD ?? repoName,
+    },
   });
   return `localhost:${port}`;
 };

package/dependencyScanner.test.ts

@@ -1,22 +1,14 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
 import path from "node:path";
 import { TypeScriptDependencyScanner } from "./dependencyScanner";
+import { tempDirs, writeText } from "./testHelpers";
 import type { PackageJson } from "./types";
 
-const tempRoots: string[] = [];
-
-const makeTempRoot = async () => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-devkit-depscan-"));
-  tempRoots.push(root);
-  return root;
-};
+const makeTempRoot = tempDirs("akan-devkit-depscan-");
 
 const write = async (root: string, relPath: string, content: string) => {
   const filePath = path.join(root, relPath);
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, content);
+  await writeText(filePath, content);
   return filePath;
 };
 
@@ -27,10 +19,6 @@ const scannerFor = async (root: string, dependencies: Record<string, string> = {
     rootPackageJson: { dependencies } as unknown as PackageJson,
   });
 
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
-
 describe("TypeScriptDependencyScanner — getPackageBuildDependencies", () => {
   test("collects imports from ordinary source files", async () => {
     const root = await makeTempRoot();

package/dependencyScanner.ts

@@ -7,8 +7,7 @@ import { FileSys } from "./fileSys";
 import type { PackageJson, TsConfigJson } from "./types";
 
 const testFileRegex = /\.(?:test|spec)\.[cm]?[tj]sx?$/;
-// `__fixtures__` holds deliberately invalid sample sources for the lint-rule suites; tsconfig `exclude` and
-// biome's `!` override already skip them, and their imports are violations rather than real dependencies.
+// `__fixtures__` holds deliberately invalid lint-rule samples, whose imports are violations, not dependencies.
 const skipDirs = ["node_modules", "dist", "build", ".git", ".next", "public", "ios", "android", "__fixtures__"];
 const isSkippedPath = (filePath: string) => {
   const posixPath = filePath.split(path.sep).join("/");
@@ -75,11 +74,8 @@ export class TypeScriptDependencyScanner {
   ): Promise<{ npmDeps: string[]; npmDevDeps: string[]; missingDeps: string[] }> {
     const runtimeDeps = new Set<string>();
     const devDeps = new Set<string>();
-    const sourceFiles = await this.#findTypeScriptFiles(this.#directory, {
-      excludeBuildFiles: true,
-      excludeTestFiles: true,
-    });
-    const cssFiles = await this.#findCssFiles(this.#directory);
+    const sourceFiles = await this.#findFiles("**/*.{ts,tsx}", { excludeBuildFiles: true, excludeTestFiles: true });
+    const cssFiles = await this.#findFiles("**/*.css");
 
     for (const filePath of sourceFiles) {
       const fileContent = await FileSys.readText(filePath);
@@ -135,25 +131,19 @@ export class TypeScriptDependencyScanner {
     depSets: DepSets,
     fileDependencies: Map<string, string[]>,
   ): DepSets {
-    const importedDepSets = new Array<Set<string>>(depSets.length);
-    for (let i = 0; i < depSets.length; i++) importedDepSets[i] = new Set<string>();
-    fileDependencies.forEach((imps) => {
-      imps.forEach((imp) => {
-        if (imp.startsWith(".")) return;
-        const moduleName = imp;
-        const moduleNameParts = moduleName.split("/");
-        const subModuleLength = moduleNameParts.length;
-        for (let i = 0; i < subModuleLength; i++) {
-          const importName = moduleNameParts.slice(0, i + 1).join("/");
-          for (let j = 0; j < depSets.length; j++) {
-            if (depSets[j]?.has(importName)) {
-              importedDepSets[j]?.add(importName);
-              return;
-            }
-          }
+    const importedDepSets = depSets.map(() => new Set<string>());
+    for (const imps of fileDependencies.values())
+      for (const imp of imps) {
+        if (imp.startsWith(".")) continue;
+        const parts = imp.split("/");
+        for (let length = 1; length <= parts.length; length++) {
+          const importName = parts.slice(0, length).join("/");
+          const setIndex = depSets.findIndex((depSet) => depSet.has(importName));
+          if (setIndex === -1) continue;
+          importedDepSets[setIndex]?.add(importName);
+          break;
         }
-      });
-    });
+      }
     return importedDepSets as DepSets;
   }
 
@@ -163,48 +153,24 @@ export class TypeScriptDependencyScanner {
     this.#fileTypeDependencies.clear();
     this.#visitedFiles.clear();
 
-    const files = await this.#findTypeScriptFiles(this.#directory);
-
-    for (const file of files) await this.#analyzeFile(file, this.#directory);
-
+    for (const file of await this.#findFiles("**/*.{ts,tsx}")) await this.#analyzeFile(file, this.#directory);
     return this.#fileDependencies;
   }
 
-  async #findTypeScriptFiles(
-    directory: string,
+  async #findFiles(
+    pattern: string,
     {
       excludeBuildFiles = false,
       excludeTestFiles = false,
     }: { excludeBuildFiles?: boolean; excludeTestFiles?: boolean } = {},
   ): Promise<string[]> {
     const files: string[] = [];
-
-    const glob = new Bun.Glob("**/*.{ts,tsx}");
-    for await (const filePath of glob.scan({ cwd: directory, onlyFiles: true })) {
+    for await (const filePath of new Bun.Glob(pattern).scan({ cwd: this.#directory, onlyFiles: true })) {
       if (isSkippedPath(filePath)) continue;
       if (excludeBuildFiles && filePath === "build.ts") continue;
       if (excludeTestFiles && testFileRegex.test(filePath)) continue;
-
-      const fullPath = path.join(directory, filePath);
-      const relativePath = path.relative(this.#workspaceRoot, fullPath);
-      if (this.#ig.ignores(relativePath)) continue;
-
-      files.push(fullPath);
-    }
-    return files;
-  }
-
-  async #findCssFiles(directory: string): Promise<string[]> {
-    const files: string[] = [];
-    const glob = new Bun.Glob("**/*.css");
-    for await (const filePath of glob.scan({ cwd: directory, onlyFiles: true })) {
-      if (isSkippedPath(filePath)) continue;
-
-      const fullPath = path.join(directory, filePath);
-      const relativePath = path.relative(this.#workspaceRoot, fullPath);
-      if (this.#ig.ignores(relativePath)) continue;
-
-      files.push(fullPath);
+      const fullPath = path.join(this.#directory, filePath);
+      if (!this.#ig.ignores(path.relative(this.#workspaceRoot, fullPath))) files.push(fullPath);
     }
     return files;
   }
@@ -217,12 +183,8 @@ export class TypeScriptDependencyScanner {
     try {
       const fileContent = await FileSys.readText(filePath);
       const { imports, typeImports } = this.#extractImports(fileContent, filePath);
-
-      // Convert imports to absolute or relative paths
       const resolvedImports = await this.#resolveImports(imports, filePath, baseDir);
       const resolvedTypeImports = await this.#resolveImports(typeImports, filePath, baseDir);
-
-      // Store the dependencies
       const relativePath = path.relative(baseDir, filePath);
       this.#fileDependencies.set(relativePath, [...new Set([...resolvedImports, ...resolvedTypeImports])]);
       this.#fileRuntimeDependencies.set(relativePath, resolvedImports);
@@ -235,12 +197,8 @@ export class TypeScriptDependencyScanner {
   async #resolveImports(imports: string[], filePath: string, baseDir: string): Promise<string[]> {
     return await Promise.all(
       imports.map(async (importPath) => {
-        if (importPath.startsWith(".")) {
-          // Handle relative imports
-          const resolvedPath = `./${path.join(path.relative(baseDir, filePath), importPath)}`;
-          return await this.#ensureExtension(resolvedPath);
-        }
-        return importPath; // Keep package imports as is
+        if (!importPath.startsWith(".")) return importPath;
+        return await this.#ensureExtension(`./${path.join(path.relative(baseDir, filePath), importPath)}`);
       }),
     );
   }
@@ -326,19 +284,10 @@ export class TypeScriptDependencyScanner {
       const projectImports = imports.filter((i) => !i.startsWith("react") && !i.startsWith("@"));
       const externalImports = imports.filter((i) => i.startsWith("react") || i.startsWith("@"));
 
-      if (projectImports.length > 0) {
-        graph += "  Project dependencies:\n";
-        projectImports.forEach((imp) => {
-          graph += `    → ${imp}\n`;
-        });
-      }
-
-      if (externalImports.length > 0) {
-        graph += "  External dependencies:\n";
-        externalImports.forEach((imp) => {
-          graph += `    → ${imp}\n`;
-        });
-      }
+      if (projectImports.length > 0)
+        graph += `  Project dependencies:\n${projectImports.map((imp) => `    → ${imp}\n`).join("")}`;
+      if (externalImports.length > 0)
+        graph += `  External dependencies:\n${externalImports.map((imp) => `    → ${imp}\n`).join("")}`;
 
       graph += "\n";
     }

package/devkitUtils.test.ts

@@ -1,29 +1,14 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
+import { realpath } from "node:fs/promises";
 import path from "node:path";
 import { ApplicationBuildReporter } from "./applicationBuildReporter";
 import { resolveSignalTestPreloadPath } from "./applicationTestPreload";
 import { TypeScriptDependencyScanner } from "./dependencyScanner";
 import { AppExecutor, WorkspaceExecutor } from "./executors";
+import { tempDirs, writeText as write } from "./testHelpers";
 import type { PackageJson, TsConfigJson } from "./types";
 
-const tempRoots: string[] = [];
-
-const makeTempRoot = async () => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-devkit-utils-"));
-  tempRoots.push(root);
-  return root;
-};
-
-const write = async (filePath: string, content: string) => {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, content);
-};
-
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
+const makeTempRoot = tempDirs("akan-devkit-utils-");
 
 describe("resolveSignalTestPreloadPath", () => {
   test("resolves the preload file from an installed akanjs package", async () => {
@@ -213,4 +198,47 @@ describe("ApplicationBuildReporter", () => {
       ["failed", "  first", "  second", "  third"].join("\n"),
     );
   });
+
+  test("says where the bundler placed each reason, relative to the workspace root", async () => {
+    const root = await makeTempRoot();
+    const refuseWith = (message: string) => ({
+      name: "refuse",
+      setup: (build: Bun.PluginBuilder) => {
+        build.onLoad({ filter: /plugged\.ts$/ }, () => {
+          throw new Error(message);
+        });
+      },
+    });
+    const failureOf = (entry: string, plugins: Bun.BunPlugin[] = []) =>
+      Bun.build({ entrypoints: [path.join(root, entry)], plugins }).then(
+        () => null,
+        (error: unknown) => error,
+      );
+    await write(
+      path.join(root, "src/entry.ts"),
+      'export const a = 1;\nimport { gone } from "./not-there";\nexport const b = gone;\n',
+    );
+    await write(path.join(root, "src/plugged.ts"), "export const b = 1;\n");
+
+    const unresolved = await failureOf("src/entry.ts");
+    expect(ApplicationBuildReporter.formatError(unresolved, root)).toBe(
+      ["Bundle failed", '  Could not resolve: "./not-there" (src/entry.ts:2:22)'].join("\n"),
+    );
+    const outside = path.join(await realpath(root), "src/entry.ts");
+    expect(ApplicationBuildReporter.formatError(unresolved, path.join(root, "elsewhere"))).toBe(
+      ["Bundle failed", `  Could not resolve: "./not-there" (${outside}:2:22)`].join("\n"),
+    );
+    expect(
+      ApplicationBuildReporter.formatError(
+        await failureOf("src/plugged.ts", [refuseWith("refused\nsecond line")]),
+        root,
+      ),
+    ).toBe(["Bundle failed", "  refused (src/plugged.ts)", "  second line"].join("\n"));
+    expect(
+      ApplicationBuildReporter.formatError(
+        await failureOf("src/plugged.ts", [refuseWith("src/plugged.ts is refused")]),
+        root,
+      ),
+    ).toBe(["Bundle failed", "  src/plugged.ts is refused"].join("\n"));
+  });
 });