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

package/linter.ts

@@ -58,16 +58,8 @@ interface LintResponse {
   warnings: LintMessage[];
 }
 
-/**
- * Extracts the `--reporter=json` report from Biome's output.
- *
- * Biome mixes configuration and IO diagnostics into the same stream as the report, so the output is not
- * always JSON alone. Slicing from the first `{` to the last `}` mis-parses as soon as that leading text
- * carries a brace of its own, which is not hypothetical: a config error printed ahead of the report made
- * one unchanged command alternate between 2 and 10 diagnostics. So every `{` is tried as a start, its
- * match is found by depth while string literals are skipped, and the first candidate that both parses and
- * carries a report field wins — a brace in prose parses as nothing, and `{"a":1}` in prose is not a report.
- */
+// Biome mixes config and IO diagnostics into the report stream, and that text can carry braces of its own, so every
+// `{` is tried as a start (string literals skipped) and the first candidate that parses and carries a report field wins.
 export const parseBiomeReport = (output: string): BiomeReport => {
   for (let start = output.indexOf("{"); start !== -1; start = output.indexOf("{", start + 1)) {
     const end = objectEndAt(output, start);
@@ -111,7 +103,19 @@ const asBiomeReport = (candidate: string): BiomeReport | null => {
 /** Biome reads `biome.json` first and `biome.jsonc` second; only the latter may carry comments. */
 const BIOME_CONFIG_FILES = ["biome.json", "biome.jsonc"] as const;
 
+const emptyResult = (filePath: string): LintResult => ({
+  filePath,
+  messages: [],
+  errorCount: 0,
+  warningCount: 0,
+  fixableErrorCount: 0,
+  fixableWarningCount: 0,
+});
+
 export class Linter {
+  //? Bun links a package bin as `<name>.exe` (plus a `.bunx` stub) on Windows, and a bare `<name>` elsewhere.
+  static readonly biomeBinName = process.platform === "win32" ? "biome.exe" : "biome";
+
   lintRoot: string;
   configPath: string;
   #biomeBin: string;
@@ -119,7 +123,7 @@ export class Linter {
   constructor(cwdPath: string) {
     this.lintRoot = this.#findBiomeRootPath(cwdPath);
     this.configPath = Linter.#configPathIn(this.lintRoot) ?? path.join(this.lintRoot, "biome.json");
-    const localBiomeBin = path.join(this.lintRoot, "node_modules/.bin/biome");
+    const localBiomeBin = path.join(this.lintRoot, "node_modules", ".bin", Linter.biomeBinName);
     this.#biomeBin = existsSync(localBiomeBin) ? localBiomeBin : "biome";
   }
 
@@ -199,16 +203,7 @@ export class Linter {
     for (const diagnostic of report.diagnostics ?? []) {
       if (diagnostic.severity !== "error" && diagnostic.severity !== "warning") continue;
       const diagnosticFilePath = this.#diagnosticFilePath(diagnostic, filePath);
-      const result =
-        resultsByPath.get(diagnosticFilePath) ??
-        ({
-          filePath: diagnosticFilePath,
-          messages: [],
-          errorCount: 0,
-          warningCount: 0,
-          fixableErrorCount: 0,
-          fixableWarningCount: 0,
-        } satisfies LintResult);
+      const result = resultsByPath.get(diagnosticFilePath) ?? emptyResult(diagnosticFilePath);
       const message = this.#createLintMessage(diagnostic);
       result.messages.push(message);
       if (message.severity === 2) result.errorCount += 1;
@@ -217,15 +212,7 @@ export class Linter {
     }
 
     return [
-      resultsByPath.get(filePath) ??
-        ({
-          filePath,
-          messages: [],
-          errorCount: 0,
-          warningCount: 0,
-          fixableErrorCount: 0,
-          fixableWarningCount: 0,
-        } satisfies LintResult),
+      resultsByPath.get(filePath) ?? emptyResult(filePath),
       ...[...resultsByPath.entries()].filter(([resultPath]) => resultPath !== filePath).map(([, result]) => result),
     ];
   }
@@ -269,22 +256,12 @@ export class Linter {
     return await this.lintFile(filePath);
   }
 
-  /**
-   * Lint a single file using Biome.
-   * @param filePath - Path to the file to lint
-   * @returns Array of Biome results in the legacy lint result shape
-   */
   async lintFile(filePath: string): Promise<LintResponse> {
     const resolvedFilePath = this.#resolveFilePath(filePath);
     if (!existsSync(resolvedFilePath)) throw new Error(`File not found: ${filePath}`);
     return await this.#checkFile(resolvedFilePath);
   }
 
-  /**
-   * Format lint results for console output
-   * @param results - Array of Biome results
-   * @returns Formatted string
-   */
   formatLintResults(results: LintResult[]): string {
     if (results.length === 0) return "No files to lint";
 
@@ -305,7 +282,7 @@ export class Linter {
             const sourceContent = readFileSync(result.filePath, "utf8");
             sourceLines = sourceContent.split("\n");
           } catch {
-            // Ignore read errors
+            //? An unreadable source only loses its code frame.
           }
         }
 
@@ -318,14 +295,12 @@ export class Linter {
           output.push(`\n  ${icon} ${typeColor(type)}: ${message.message}${ruleInfo}`);
           output.push(`     ${chalk.gray("at")} ${result.filePath}:${chalk.bold(`${message.line}:${message.column}`)}`);
 
-          // Show source line with underline
           if (sourceLines.length > 0 && message.line <= sourceLines.length) {
             const sourceLine = sourceLines[message.line - 1];
             const lineNumber = message.line.toString().padStart(5, " ");
 
             output.push(`\n${chalk.dim(`${lineNumber} |`)} ${sourceLine}`);
 
-            // Create underline
             const underlinePrefix = " ".repeat(message.column - 1);
             const underlineLength = message.endColumn ? message.endColumn - message.column : 1;
             const underline = "^".repeat(Math.max(1, underlineLength));
@@ -345,27 +320,7 @@ export class Linter {
     return summary.concat(output).join("\n");
   }
 
-  /**
-   * Get detailed lint information
-   * @param filePath - Path to the file to lint
-   * @returns Object containing detailed lint information
-   */
-  async getDetailedLintInfo(filePath: string): Promise<{
-    results: LintResult[];
-    details: {
-      line: number;
-      column: number;
-      message: string;
-      ruleId: string | null;
-      severity: "error" | "warning";
-    }[];
-    stats: {
-      errorCount: number;
-      warningCount: number;
-      fixableErrorCount: number;
-      fixableWarningCount: number;
-    };
-  }> {
+  async getDetailedLintInfo(filePath: string) {
     const { results } = await this.lintFile(filePath);
 
     const details = results.flatMap((result) =>
@@ -385,22 +340,13 @@ export class Linter {
         fixableErrorCount: acc.fixableErrorCount + result.fixableErrorCount,
         fixableWarningCount: acc.fixableWarningCount + result.fixableWarningCount,
       }),
-      {
-        errorCount: 0,
-        warningCount: 0,
-        fixableErrorCount: 0,
-        fixableWarningCount: 0,
-      },
+      { errorCount: 0, warningCount: 0, fixableErrorCount: 0, fixableWarningCount: 0 },
     );
 
     return { results, details, stats };
   }
 
-  /**
-   * Check if a file has lint errors
-   * @param filePath - Path to the file to check
-   * @returns true if there are no errors, false otherwise
-   */
+  /** Also false when the file cannot be linted at all. */
   async hasNoLintErrors(filePath: string): Promise<boolean> {
     try {
       const { results } = await this.lintFile(filePath);
@@ -410,32 +356,17 @@ export class Linter {
     }
   }
 
-  /**
-   * Get only error messages (excluding warnings)
-   * @param filePath - Path to the file to lint
-   * @returns Array of error messages
-   */
   async getErrors(filePath: string): Promise<LintMessage[]> {
     const { results } = await this.lintFile(filePath);
     return results.flatMap((result) => result.messages.filter((message) => message.severity === 2));
   }
 
-  /**
-   * Get only warning messages
-   * @param filePath - Path to the file to lint
-   * @returns Array of warning messages
-   */
   async getWarnings(filePath: string): Promise<LintMessage[]> {
     const { results } = await this.lintFile(filePath);
     return results.flatMap((result) => result.messages.filter((message) => message.severity === 1));
   }
 
-  /**
-   * Fix lint errors automatically
-   * @param filePath - Path to the file to fix
-   * @param dryRun - If true, returns the fixed content without writing to file
-   * @returns Fixed content and remaining issues
-   */
+  /** `dryRun` returns the fixed content in `output` without writing the file. */
   async fixFile(filePath: string, dryRun = false): Promise<LintResponse> {
     const resolvedFilePath = this.#resolveFilePath(filePath);
     if (!existsSync(resolvedFilePath)) throw new Error(`File not found: ${filePath}`);
@@ -451,19 +382,8 @@ export class Linter {
     return { ...lintResult, fixed: stdout !== source, output: stdout };
   }
 
-  /**
-   * Get Biome configuration for a file
-   * @param filePath - Path to the file
-   * @returns Biome configuration object
-   */
-  /**
-   * Applies Biome's safe fixes to many files in one process.
-   *
-   * One spawn, not one per file: Biome's startup dominates a small file, so the per-file path turns a
-   * fifteen-file scaffold into three seconds of process launches. Paths that do not exist are dropped
-   * rather than thrown on, because the caller is usually reporting what a template just wrote and a
-   * template is allowed to decline a file.
-   */
+  // One spawn for all files: Biome's startup dominates a small file. Missing paths are dropped (a template may
+  // decline a file).
   async fixFiles(filePaths: string[]): Promise<{ fixed: string[] }> {
     const resolved = filePaths.map((filePath) => this.#resolveFilePath(filePath)).filter(existsSync);
     if (resolved.length === 0) return { fixed: [] };
@@ -489,21 +409,11 @@ export class Linter {
     return JSON.parse(readFileSync(this.configPath, "utf8")) as unknown;
   }
 
-  /**
-   * Get rules that are causing errors in a file
-   * @param filePath - Path to the file to check
-   * @returns Object mapping rule IDs to their error counts
-   */
   async getProblematicRules(filePath: string): Promise<Record<string, number>> {
     const { results } = await this.lintFile(filePath);
     const ruleCounts: Record<string, number> = {};
-
-    results.forEach((result) => {
-      result.messages.forEach((message) => {
-        if (message.ruleId) ruleCounts[message.ruleId] = (ruleCounts[message.ruleId] || 0) + 1;
-      });
-    });
-
+    for (const message of results.flatMap((result) => result.messages))
+      if (message.ruleId) ruleCounts[message.ruleId] = (ruleCounts[message.ruleId] || 0) + 1;
     return ruleCounts;
   }
 }

package/mobile/mobileTarget.ts

@@ -11,6 +11,8 @@ export interface ResolvedMobileTarget {
 
 export const MOBILE_ENVS = ["local", "debug", "develop", "main"] as const satisfies readonly MobileEnv[];
 
+const trimSlashes = (value: string) => value.replace(/^\/+|\/+$/g, "");
+
 export const getMobileTargets = async (app: App): Promise<ResolvedMobileTarget[]> => {
   const config = await app.getConfig();
   return Object.entries(config.mobile.targets).map(([name, target]) => ({ name, config: target }));
@@ -20,26 +22,23 @@ export const getMobileTargetChoices = async (app: App): Promise<string[]> => {
   const config = await app.getConfig();
   const targetNames = Object.keys(config.mobile.targets);
   if (targetNames.length > 0) return targetNames;
-  const basePaths = [...config.basePaths];
-  return basePaths;
+  return [...config.basePaths];
 };
 
 const resolveMobileTargetByBasePath = (
   targets: ResolvedMobileTarget[],
   basePath: string,
 ): ResolvedMobileTarget | undefined => {
-  const normalizedBasePath = basePath.replace(/^\/+|\/+$/g, "");
-  const byBasePath = targets.find((target) => target.config.basePath?.replace(/^\/+|\/+$/g, "") === normalizedBasePath);
+  const normalizedBasePath = trimSlashes(basePath);
+  const byBasePath = targets.find(
+    ({ config }) => config.basePath !== undefined && trimSlashes(config.basePath) === normalizedBasePath,
+  );
   if (byBasePath) return byBasePath;
   const [template] = targets;
   if (!template) return undefined;
   return {
     name: normalizedBasePath,
-    config: {
-      ...template.config,
-      name: normalizedBasePath,
-      basePath: normalizedBasePath,
-    },
+    config: { ...template.config, name: normalizedBasePath, basePath: normalizedBasePath },
   };
 };
 
@@ -70,18 +69,20 @@ export const resolveMobileTargets = async (
   const target = targets.find((candidate) => candidate.name === selection);
   if (target) return [target];
   const basePathTarget = resolveMobileTargetByBasePath(targets, selection);
-  if (basePathTarget && config.basePaths.has(selection.replace(/^\/+|\/+$/g, ""))) return [basePathTarget];
+  if (basePathTarget && config.basePaths.has(trimSlashes(selection))) return [basePathTarget];
   const choices = await getMobileTargetChoices(app);
   throw new Error(`Mobile target '${selection}' was not found. Available: ${choices.join(", ")}`);
 };
 
 export const resolveMobilePath = (target: AkanMobileTargetConfig, pathname: string) => {
-  const basePath = target.basePath?.replace(/^\/+|\/+$/g, "");
+  const basePath = trimSlashes(target.basePath ?? "");
   const normalizedPath = `/${pathname.replace(/^\/+/, "")}`;
   if (!basePath) return normalizedPath;
   if (normalizedPath === `/${basePath}` || normalizedPath.startsWith(`/${basePath}/`)) return normalizedPath;
   return `/${basePath}${normalizedPath === "/" ? "" : normalizedPath}`;
 };
 
-export const targetHtmlFilename = (target: AkanMobileTargetConfig) =>
-  target.basePath?.replace(/^\/+|\/+$/g, "") ? `${target.basePath.replace(/^\/+|\/+$/g, "")}.html` : "index.html";
+export const targetHtmlFilename = (target: AkanMobileTargetConfig) => {
+  const basePath = trimSlashes(target.basePath ?? "");
+  return basePath ? `${basePath}.html` : "index.html";
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-beta.2",
+  "version": "3.0.0-beta.20",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -28,6 +28,7 @@
     "./akanConfig": "./akanConfig/index.ts",
     "./artifact": "./artifact/index.ts",
     "./cloud": "./cloud/index.ts",
+    "./codeAgent": "./codeAgent/index.ts",
     "./commandDecorators": "./commandDecorators/index.ts",
     "./frontendBuild": "./frontendBuild/index.ts",
     "./incrementalBuilder": "./incrementalBuilder/index.ts",
@@ -38,13 +39,16 @@
     "./*": "./*.ts"
   },
   "dependencies": {
+    "@earendil-works/chord": "0.86.1",
+    "@earendil-works/pi-agent-core": "0.86.1",
+    "@earendil-works/pi-ai": "0.86.1",
+    "@earendil-works/pi-coding-agent": "0.86.1",
+    "@earendil-works/pi-telemetry": "0.86.1",
+    "@earendil-works/pi-tui": "0.86.1",
     "@inquirer/prompts": "^8.4.3",
-    "@langchain/core": "^1.1.47",
-    "@langchain/deepseek": "^1.0.26",
-    "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-beta.2",
+    "akanjs": "3.0.0-beta.20",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",
@@ -56,6 +60,7 @@
     "subset-font": "^2.5.0",
     "tailwind-scrollbar": "^4.0.2",
     "tailwindcss": "^4.3.0",
+    "typebox": "1.1.38",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {

package/packageExports.test.ts

@@ -3,30 +3,17 @@ import { existsSync } from "node:fs";
 import path from "node:path";
 import { PackageExportsMap } from "@akanjs/devkit/packageExportsMap";
 
-// Guards the published shape of this package, which the monorepo cannot exercise on its own.
-//
-// Inside the monorepo Bun resolves `@akanjs/devkit/executors` through the root tsconfig `paths`
-// (`@akanjs/devkit/*` -> `pkgs/@akanjs/devkit/*`), and that resolver probes extensions and directory
-// indexes. A published consumer has no such mapping: it goes through this package's `exports` map,
-// whose targets are matched *exactly*. So `"./*": "./*"` type-checked, built, and passed every test
-// here while every subpath import failed at runtime for anyone installing the tarball:
-//
-//   error: Cannot find module '@akanjs/devkit/executors' from
-//     '<consumer>/node_modules/@akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts'
-//
-// `PackageRunner.verifyDistPackage` runs the same check against the built dist tree of every
-// publishable package at release time; these tests keep this package honest on every run.
+//? The monorepo resolves subpaths through tsconfig `paths`, which probe extensions; a published consumer goes through
+//? the exports map, matched exactly — so `"./*": "./*"` passed every test here and broke every installed subpath.
 
 const packageDir = import.meta.dir;
 const exportsMap = await PackageExportsMap.from(packageDir);
 
-/** Every facet the root barrel re-exports, as the subpath a consumer would import. */
 const barrelFacets = async (): Promise<string[]> => {
   const barrel = await Bun.file(path.join(packageDir, "index.ts")).text();
   return [...barrel.matchAll(/^export (?:type )?\* from "\.\/([^"]+)";$/gm)].map((match) => `./${match[1]}`);
 };
 
-/** Every `@akanjs/devkit/<subpath>` specifier written anywhere in the two packages that use them. */
 const importedSubpaths = async (): Promise<string[]> => {
   const repoRoot = path.resolve(packageDir, "../../..");
   const glob = new Bun.Glob("pkgs/@akanjs/{cli,devkit}/**/*.{ts,tsx}");
@@ -53,9 +40,7 @@ describe("published exports map", () => {
   });
 
   test("covers both facet shapes and keeps explicit extensions intact", () => {
-    // A single wildcard cannot serve all three: `./*` -> `./*.ts` reaches bare files, directory
-    // facets need their own literal entry, and `./*.ts` -> `./*.ts` keeps an already-suffixed
-    // specifier from becoming `./cloud/cloudApi.ts.ts`.
+    // One wildcard cannot serve bare files, directory facets and already-suffixed specifiers (no `.ts.ts`) at once.
     expect(exportsMap.resolve("./executors")).toBe("./executors.ts");
     expect(exportsMap.resolve("./frontendBuild")).toBe("./frontendBuild/index.ts");
     expect(exportsMap.resolve("./cloud/cloudApi.ts")).toBe("./cloud/cloudApi.ts");

package/packageExportsMap.ts

@@ -7,17 +7,9 @@ export interface UnreachableSubpath {
   target: string | null;
 }
 
-/**
- * The subset of Node's `exports` resolution that Bun applies to a published package.
- *
- * Exports targets are matched **exactly**: no extension is appended and no `index.ts` is probed. That
- * is invisible inside this monorepo, where `@akanjs/devkit/*` and `akanjs/*` resolve through the root
- * tsconfig `paths` instead — a resolver that *does* probe both. A map of `{"./*": "./*"}` therefore
- * type-checks, builds, and passes every test while every subpath import fails for anyone who installs
- * the tarball. This class exists so that gap can be asserted against before publishing.
- */
+// Bun matches exports targets exactly (no extension, no index.ts), while this monorepo resolves `akanjs/*` through
+// tsconfig paths, which probe both — so a broken map passes every in-repo test and fails for every installer.
 export class PackageExportsMap {
-  /** Reads `<packageDir>/package.json` and builds the map from its `exports` field. */
   static async from(packageDir: string) {
     const manifest = (await Bun.file(path.join(packageDir, "package.json")).json()) as { exports?: unknown };
     return new PackageExportsMap(packageDir, manifest.exports);
@@ -60,7 +52,6 @@ export class PackageExportsMap {
     // wins over `./*`, which is what keeps an already-suffixed specifier from gaining a second `.ts`.
     this.#patterns.sort((a, b) => b.prefix.length - a.prefix.length || b.suffix.length - a.suffix.length);
   }
-  /** Returns the target an `exports` lookup yields, or null when the subpath is unexported. */
   resolve(subpath: string): string | null {
     const literal = this.#literals.get(subpath);
     if (literal) return literal;
@@ -71,20 +62,13 @@ export class PackageExportsMap {
     }
     return null;
   }
-  /**
-   * Resolves a subpath and reports whether the target it yields is a readable file.
-   *
-   * A directory does not count. `{"./*": "./*"}` maps `./commandDecorators` onto the directory of
-   * that name, which exists but is not a module — an `existsSync` check here reports such a subpath
-   * as reachable while the import still fails.
-   */
+  // A directory does not count: `{"./*": "./*"}` maps `./commandDecorators` onto a folder, which is not importable.
   resolveToFile(subpath: string): { target: string | null; exists: boolean } {
     const target = this.resolve(subpath);
     if (!target) return { target: null, exists: false };
     const stat = statSync(path.join(this.#packageDir, target), { throwIfNoEntry: false });
     return { target, exists: !!stat?.isFile() };
   }
-  /** Returns the given subpaths that no consumer could import, in input order. */
   findUnreachable(subpaths: Iterable<string>): UnreachableSubpath[] {
     const unreachable: UnreachableSubpath[] = [];
     for (const subpath of subpaths) {

package/piDependencyPins.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import type { PackageJson } from "@akanjs/devkit/types";
+
+//? A published install reads neither pi's npm-shrinkwrap.json nor our overrides, so PackageRunner re-declares pi's
+//? sibling pins (a floating 0.80.x once broke every global install); this keeps them equal to the shrinkwrap.
+
+const repoRoot = path.resolve(import.meta.dir, "../../..");
+const piName = "@earendil-works/pi-coding-agent";
+const piDir = `${repoRoot}/node_modules/${piName}`;
+const publishedPackages = ["pkgs/@akanjs/devkit/package.json", "pkgs/@akanjs/cli/package.json"];
+
+interface Shrinkwrap {
+  packages: Record<string, { version?: string }>;
+}
+
+const readJson = async <T>(file: string) => (await Bun.file(file).json()) as T;
+
+const shrinkwrappedPins = async () => {
+  const { packages } = await readJson<Shrinkwrap>(`${piDir}/npm-shrinkwrap.json`);
+  // Top-level entries only: a nested `node_modules/` key is another package's placement, not ours to pin.
+  const entries = Object.entries(packages)
+    .filter(([key]) => /^node_modules\/@earendil-works\/[^/]+$/.test(key))
+    .map(([key, entry]) => [key.replace(/^node_modules\//, ""), entry.version ?? ""] as const);
+  return Object.fromEntries(entries);
+};
+
+describe("pi dependency pins", () => {
+  test("the shrinkwrap read here belongs to the coding agent we publish", async () => {
+    const installed = await readJson<PackageJson>(`${piDir}/package.json`);
+    for (const file of publishedPackages) {
+      const { dependencies = {} } = await readJson<PackageJson>(`${repoRoot}/${file}`);
+      expect({ file, [piName]: dependencies[piName] }).toEqual({ file, [piName]: installed.version });
+    }
+  });
+
+  test("every sibling pi package is published at the version the coding agent shrinkwrapped", async () => {
+    const pins = await shrinkwrappedPins();
+    expect(Object.keys(pins).length).toBeGreaterThan(0);
+    for (const file of publishedPackages) {
+      const { dependencies = {} } = await readJson<PackageJson>(`${repoRoot}/${file}`);
+      const declared = Object.fromEntries(Object.keys(pins).map((name) => [name, dependencies[name]]));
+      expect({ file, ...declared }).toEqual({ file, ...pins });
+    }
+  });
+});

package/platformTest/BunTestReport.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import { BunTestReport } from "./BunTestReport";
+
+describe("BunTestReport", () => {
+  test("reads the final summary and attributes each failure to the file header above it", () => {
+    const report = new BunTestReport(
+      [
+        "bun test v1.4.2 (744846f84)",
+        "",
+        "server\\artifact\\routeSeedIndex.test.ts:",
+        "(pass) route seed index > keeps seeds [0.40ms]",
+        "(fail) route seed index > restores relative seed paths [1.20ms]",
+        "",
+        "lib/linter.test.ts:",
+        "\u001b[31m(fail) Linter > finds biome [3.00ms]\u001b[0m",
+        "",
+        "2 tests failed:",
+        "(fail) route seed index > restores relative seed paths [1.20ms]",
+        "(fail) Linter > finds biome [3.00ms]",
+        "",
+        " 1 pass",
+        " 3 skip",
+        " 2 fail",
+        " 1 error",
+        "Ran 6 tests across 2 files. [120.00ms]",
+      ].join("\r\n"),
+    );
+
+    expect(report.hasSummary).toBe(true);
+    expect([report.pass, report.fail, report.skip, report.errors, report.files]).toEqual([1, 2, 3, 1, 2]);
+    expect(report.failures).toEqual([
+      { file: "server/artifact/routeSeedIndex.test.ts", name: "route seed index > restores relative seed paths" },
+      { file: "lib/linter.test.ts", name: "Linter > finds biome" },
+    ]);
+    expect(report.passed).toBe(false);
+  });
+
+  test("a run with no summary is not passed, and counts what it saw before it stopped", () => {
+    const report = new BunTestReport(
+      [
+        "server/akanApp.test.ts:",
+        "(pass) AkanApp > boots [1ms]",
+        "(pass) AkanApp > relays [2ms]",
+        "panic(main thread)",
+      ].join("\n"),
+    );
+
+    expect(report.hasSummary).toBe(false);
+    expect(report.passed).toBe(false);
+    expect(report.pass).toBe(2);
+    expect(report.lastFile).toBe("server/akanApp.test.ts");
+  });
+
+  test("a clean summary passes", () => {
+    const report = new BunTestReport(" 4 pass\n 0 fail\nRan 4 tests across 1 file. [12.00ms]\n");
+
+    expect(report.passed).toBe(true);
+    expect(report.files).toBe(1);
+  });
+});

package/platformTest/BunTestReport.ts

@@ -0,0 +1,65 @@
+import { stripVTControlCharacters } from "node:util";
+
+export interface BunTestFailure {
+  file: string | null;
+  name: string;
+}
+
+export class BunTestReport {
+  static readonly #fileHeaderPattern = /^(\S+\.(?:test|spec)\.[cm]?[jt]sx?):$/;
+  //? After the last file, bun repeats every failure under an "N tests failed:" line — those belong to no header.
+  static readonly #relistPattern = /^\d+ tests? failed:$/;
+  static readonly #durationSuffix = /\s+\[[\d.]+m?s\]$/;
+
+  readonly pass: number;
+  readonly fail: number;
+  readonly skip: number;
+  readonly errors: number;
+  readonly files: number;
+  readonly hasSummary: boolean;
+  readonly failures: BunTestFailure[];
+  readonly lastFile: string | null;
+
+  constructor(output: string) {
+    const lines = stripVTControlCharacters(output).split(/\r?\n/);
+    let currentFile: string | null = null;
+    let lastFile: string | null = null;
+    let relisted = false;
+    const failures = new Map<string, BunTestFailure>();
+    for (const line of lines) {
+      if (BunTestReport.#relistPattern.test(line)) relisted = true;
+      const header = BunTestReport.#fileHeaderPattern.exec(line);
+      if (header?.[1] && !relisted) {
+        currentFile = header[1].replaceAll("\\", "/");
+        lastFile = currentFile;
+        continue;
+      }
+      if (!line.startsWith("(fail) ")) continue;
+      const name = line.slice("(fail) ".length).replace(BunTestReport.#durationSuffix, "");
+      if (!failures.has(name)) failures.set(name, { file: relisted ? null : currentFile, name });
+    }
+    const ran = lines.findLast((line) => /^Ran \d+ tests? across \d+ files?/.test(line));
+    this.hasSummary = !!ran;
+    this.files = ran ? Number(/across (\d+) files?/.exec(ran)?.[1] ?? 0) : 0;
+    this.failures = [...failures.values()];
+    this.lastFile = lastFile;
+    this.pass = ran
+      ? BunTestReport.#lastCount(lines, /^\s*(\d+) pass$/)
+      : lines.filter((line) => line.startsWith("(pass) ")).length;
+    this.fail = ran ? BunTestReport.#lastCount(lines, /^\s*(\d+) fail$/) : this.failures.length;
+    this.skip = ran ? BunTestReport.#lastCount(lines, /^\s*(\d+) skip$/) : 0;
+    this.errors = ran ? BunTestReport.#lastCount(lines, /^\s*(\d+) errors?$/) : 0;
+  }
+
+  get passed() {
+    return this.hasSummary && this.fail === 0 && this.errors === 0;
+  }
+
+  static #lastCount(lines: string[], pattern: RegExp) {
+    for (const line of lines.toReversed()) {
+      const count = pattern.exec(line)?.[1];
+      if (count) return Number(count);
+    }
+    return 0;
+  }
+}