@confect/cli 8.0.0 → 9.0.0-next.0

package/dist/utils.mjs

@@ -2,71 +2,46 @@ import { fromGroupModulePath, getGroupSpec, modulePath } from "./GroupPath.mjs";
 import { logFileAdded, logFileModified, logFileRemoved } from "./log.mjs";
 import { ConvexDirectory } from "./ConvexDirectory.mjs";
 import { ConfectDirectory } from "./ConfectDirectory.mjs";
-import { authConfig, crons, functions, http } from "./templates.mjs";
 import { GroupPaths } from "./GroupPaths.mjs";
 import { groupPaths, make } from "./FunctionPaths.mjs";
-import { createRequire } from "node:module";
-import { Array, Effect, HashSet, Option, Order, Record, String, pipe } from "effect";
+import { authConfig, crons, functions, http } from "./templates.mjs";
+import { Array, Context, Effect, HashSet, Option, Order, Record, Ref, String, pipe } from "effect";
 import { FileSystem, Path } from "@effect/platform";
-import { pathToFileURL } from "node:url";
-import * as esbuild from "esbuild";
 
 //#region src/utils.ts
+/**
+* Tracks whether the current codegen run wrote anything to disk. Set to
+* `true` by every helper that actually overwrites a file (skipping the
+* content-unchanged case). `codegenHandler` provides a fresh `Ref` per
+* run and reads it back to report `anyWritesHappened`; callers outside a
+* codegen pass hit the cached default `Ref` and need not interact with
+* the tracker.
+*/
+var WriteTracker = class extends Context.Reference()("@confect/cli/WriteTracker", { defaultValue: () => Ref.unsafeMake(false) }) {};
+const markWritten = Effect.gen(function* () {
+	const tracker = yield* WriteTracker;
+	yield* Ref.set(tracker, true);
+});
 const removePathExtension = (pathStr) => Effect.gen(function* () {
 	const path = yield* Path.Path;
 	return String.slice(0, -path.extname(pathStr).length)(pathStr);
 });
-const EXTERNAL_PACKAGES = [
-	"@confect/core",
-	"@confect/server",
-	"effect",
-	"@effect/*"
-];
-const isExternalImport = (path) => EXTERNAL_PACKAGES.some((p) => {
-	if (p.endsWith("/*")) return path.startsWith(p.slice(0, -1));
-	return path === p || path.startsWith(p + "/");
-});
-const absoluteExternalsPlugin = {
-	name: "absolute-externals",
-	setup(build) {
-		build.onResolve({ filter: /.*/ }, async (args) => {
-			if (args.kind !== "import-statement" && args.kind !== "dynamic-import") return;
-			if (!isExternalImport(args.path)) return;
-			const parentFile = pathToFileURL(args.resolveDir + "/_").href;
-			return {
-				path: pathToFileURL(createRequire(parentFile).resolve(args.path)).href,
-				external: true
-			};
-		});
-	}
-};
-/**
-* Bundle a TypeScript entry point with esbuild and import the result via a
-* data URL. This handles extensionless `.ts` imports regardless of whether the
-* user's project sets `"type": "module"` in package.json.
-*/
-const bundleAndImport = (entryPoint) => Effect.gen(function* () {
-	const code = (yield* Effect.promise(() => esbuild.build({
-		entryPoints: [entryPoint],
-		bundle: true,
-		write: false,
-		platform: "node",
-		format: "esm",
-		logLevel: "silent",
-		plugins: [absoluteExternalsPlugin]
-	}))).outputFiles[0].text;
-	const dataUrl = "data:text/javascript;base64," + Buffer.from(code).toString("base64");
-	return yield* Effect.promise(() => import(dataUrl));
+/** Ensures a relative path is a valid ESM/TS module specifier (e.g. `spec` → `./spec`). */
+const toModuleImportPath = (relativePath) => Effect.gen(function* () {
+	const withoutExt = yield* removePathExtension(relativePath);
+	return withoutExt.startsWith(".") ? withoutExt : `./${withoutExt}`;
 });
 const writeFileStringAndLog = (filePath, contents) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	if (!(yield* fs.exists(filePath))) {
 		yield* fs.writeFileString(filePath, contents);
+		yield* markWritten;
 		yield* logFileAdded(filePath);
 		return;
 	}
 	if ((yield* fs.readFileString(filePath)) !== contents) {
 		yield* fs.writeFileString(filePath, contents);
+		yield* markWritten;
 		yield* logFileModified(filePath);
 	}
 });
@@ -83,42 +58,58 @@ const writeFileString = (filePath, contents) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	if (!(yield* fs.exists(filePath))) {
 		yield* fs.writeFileString(filePath, contents);
+		yield* markWritten;
 		return "Added";
 	}
 	if ((yield* fs.readFileString(filePath)) !== contents) {
 		yield* fs.writeFileString(filePath, contents);
+		yield* markWritten;
 		return "Modified";
 	}
 	return "Unchanged";
 });
-const generateGroupModule = ({ groupPath, functionNames }) => Effect.gen(function* () {
+const removePathIfExists = (filePath) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	if (!(yield* fs.exists(filePath))) return;
+	yield* fs.remove(filePath).pipe(Effect.catchTag("SystemError", (error) => error.reason === "NotFound" ? Effect.void : Effect.fail(error)));
+});
+/**
+* Bump the mtime of `convex/schema.ts` so the Convex CLI's chokidar watcher
+* emits a `change` event after every successful Confect codegen run. Without
+* this, a codegen that doesn't change any file content (for example,
+* recovering from a transient broken state in `confect/`) leaves Convex
+* stuck on its previous error because nothing it observes has changed.
+*/
+const touchConvexSchema = Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const convexDirectory = yield* ConvexDirectory.get;
+	const schemaPath = path.join(convexDirectory, "schema.ts");
+	if (!(yield* fs.exists(schemaPath))) return;
+	const now = /* @__PURE__ */ new Date();
+	yield* fs.utimes(schemaPath, now, now);
+});
+const generateGroupModule = ({ groupPath, functionNames, registeredFunctionsImportPath, useNode = false }) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	const convexDirectory = yield* ConvexDirectory.get;
-	const confectDirectory = yield* ConfectDirectory.get;
 	const relativeModulePath = yield* modulePath(groupPath);
-	const modulePath$1 = path.join(convexDirectory, relativeModulePath);
-	const directoryPath = path.dirname(modulePath$1);
+	const modulePath$4 = path.join(convexDirectory, relativeModulePath);
+	const directoryPath = path.dirname(modulePath$4);
 	if (!(yield* fs.exists(directoryPath))) yield* fs.makeDirectory(directoryPath, { recursive: true });
-	const isNodeGroup = groupPath.pathSegments[0] === "node";
-	const registeredFunctionsFileName = isNodeGroup ? "nodeRegisteredFunctions.ts" : "registeredFunctions.ts";
-	const registeredFunctionsPath = path.join(confectDirectory, "_generated", registeredFunctionsFileName);
-	const registeredFunctionsImportPath = yield* removePathExtension(path.relative(path.dirname(modulePath$1), registeredFunctionsPath));
-	const registeredFunctionsVariableName = isNodeGroup ? "nodeRegisteredFunctions" : "registeredFunctions";
 	const functionsContentsString = yield* functions({
-		groupPath,
 		functionNames,
 		registeredFunctionsImportPath,
-		registeredFunctionsVariableName,
-		useNode: isNodeGroup,
-		...isNodeGroup ? { registeredFunctionsLookupPath: groupPath.pathSegments.slice(1) } : {}
+		useNode
 	});
-	if (!(yield* fs.exists(modulePath$1))) {
-		yield* fs.writeFileString(modulePath$1, functionsContentsString);
+	if (!(yield* fs.exists(modulePath$4))) {
+		yield* fs.writeFileString(modulePath$4, functionsContentsString);
+		yield* markWritten;
 		return "Added";
 	}
-	if ((yield* fs.readFileString(modulePath$1)) !== functionsContentsString) {
-		yield* fs.writeFileString(modulePath$1, functionsContentsString);
+	if ((yield* fs.readFileString(modulePath$4)) !== functionsContentsString) {
+		yield* fs.writeFileString(modulePath$4, functionsContentsString);
+		yield* markWritten;
 		return "Modified";
 	}
 	return "Unchanged";
@@ -134,18 +125,23 @@ const logGroupPaths = (groupPaths, logFn) => Effect.gen(function* () {
 const generateFunctions = (spec) => Effect.gen(function* () {
 	const path = yield* Path.Path;
 	const convexDirectory = yield* ConvexDirectory.get;
+	const confectDirectory = yield* ConfectDirectory.get;
 	const groupPathsFromFs = yield* getGroupPathsFromFs;
 	const functionPaths = make(spec);
 	const groupPathsFromSpec = groupPaths(functionPaths);
 	const overlappingGroupPaths = GroupPaths.make(HashSet.intersection(groupPathsFromFs, groupPathsFromSpec));
 	yield* Effect.forEach(overlappingGroupPaths, (groupPath) => Effect.gen(function* () {
+		const functionNames = pipe((yield* getGroupSpec(spec, groupPath)).functions, Record.values, Array.sortBy(Order.mapInput(Order.string, (fn) => fn.name)), Array.map((fn) => fn.name));
+		const relativeModulePath = yield* modulePath(groupPath);
+		const modulePath$3 = path.join(convexDirectory, relativeModulePath);
+		const registrySegments = groupPath.pathSegments[0] === "node" ? groupPath.pathSegments.slice(1) : groupPath.pathSegments;
+		const registeredFunctionsPath = path.join(confectDirectory, "_generated", "registeredFunctions", ...registrySegments) + ".ts";
 		if ((yield* generateGroupModule({
 			groupPath,
-			functionNames: pipe((yield* getGroupSpec(spec, groupPath)).functions, Record.values, Array.sortBy(Order.mapInput(Order.string, (fn) => fn.name)), Array.map((fn) => fn.name))
-		})) === "Modified") {
-			const relativeModulePath = yield* modulePath(groupPath);
-			yield* logFileModified(path.join(convexDirectory, relativeModulePath));
-		}
+			functionNames,
+			registeredFunctionsImportPath: yield* toModuleImportPath(path.relative(path.dirname(modulePath$3), registeredFunctionsPath)),
+			useNode: groupPath.pathSegments[0] === "node"
+		})) === "Modified") yield* logFileModified(modulePath$3);
 	}));
 	const extinctGroupPaths = GroupPaths.make(HashSet.difference(groupPathsFromFs, groupPathsFromSpec));
 	yield* removeGroups(extinctGroupPaths);
@@ -169,23 +165,31 @@ const getGroupPathsFromFs = Effect.gen(function* () {
 	return pipe(yield* pipe(yield* fs.readDirectory(convexDirectory, { recursive: true }), Array.filter((convexPath) => path.extname(convexPath) === ".ts" && !RESERVED_CONVEX_TS_FILE_NAMES.has(path.basename(convexPath)) && path.basename(path.dirname(convexPath)) !== "_generated"), Effect.forEach((groupModulePath) => fromGroupModulePath(groupModulePath))), HashSet.fromIterable, GroupPaths.make);
 });
 const removeGroups = (groupPaths) => Effect.gen(function* () {
-	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	const convexDirectory = yield* ConvexDirectory.get;
 	yield* Effect.all(HashSet.map(groupPaths, (groupPath) => Effect.gen(function* () {
 		const relativeModulePath = yield* modulePath(groupPath);
-		const modulePath$2 = path.join(convexDirectory, relativeModulePath);
+		const modulePath$1 = path.join(convexDirectory, relativeModulePath);
 		yield* Effect.logDebug(`Removing group '${relativeModulePath}'...`);
-		yield* fs.remove(modulePath$2);
+		yield* removePathIfExists(modulePath$1);
 		yield* Effect.logDebug(`Group '${relativeModulePath}' removed`);
 	})), { concurrency: "unbounded" });
 });
 const writeGroups = (spec, groupPaths) => Effect.forEach(groupPaths, (groupPath) => Effect.gen(function* () {
+	const path = yield* Path.Path;
+	const convexDirectory = yield* ConvexDirectory.get;
+	const confectDirectory = yield* ConfectDirectory.get;
 	const functionNames = pipe((yield* getGroupSpec(spec, groupPath)).functions, Record.values, Array.sortBy(Order.mapInput(Order.string, (fn) => fn.name)), Array.map((fn) => fn.name));
+	const relativeModulePath = yield* modulePath(groupPath);
+	const modulePath$2 = path.join(convexDirectory, relativeModulePath);
+	const registeredFunctionsPath = path.join(confectDirectory, "_generated", "registeredFunctions", ...groupPath.pathSegments) + ".ts";
+	const registeredFunctionsImportPath = yield* toModuleImportPath(path.relative(path.dirname(modulePath$2), registeredFunctionsPath));
 	yield* Effect.logDebug(`Generating group ${groupPath}...`);
 	yield* generateGroupModule({
 		groupPath,
-		functionNames
+		functionNames,
+		registeredFunctionsImportPath,
+		useNode: groupPath.pathSegments[0] === "node"
 	});
 	yield* Effect.logDebug(`Group ${groupPath} generated`);
 }));
@@ -208,5 +212,5 @@ const generateCrons = generateOptionalFile("crons.ts", "crons.ts", (importPath)
 const generateAuthConfig = generateOptionalFile("auth.ts", "auth.config.ts", (importPath) => authConfig({ authImportPath: importPath }));
 
 //#endregion
-export { EXTERNAL_PACKAGES, bundleAndImport, generateAuthConfig, generateCrons, generateFunctions, generateHttp, removeGroups, removePathExtension, writeFileStringAndLog, writeGroups };
+export { WriteTracker, generateAuthConfig, generateCrons, generateFunctions, generateHttp, removePathExtension, removePathIfExists, toModuleImportPath, touchConvexSchema, writeFileStringAndLog };
 //# sourceMappingURL=utils.mjs.map

package/dist/utils.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"utils.mjs","names":["GroupPath.modulePath","modulePath","templates.functions","FunctionPaths.make","FunctionPaths.groupPaths","GroupPath.getGroupSpec","GroupPath.fromGroupModulePath","templates.http","templates.crons","templates.authConfig"],"sources":["../src/utils.ts"],"sourcesContent":["import type { FunctionSpec, Spec } from \"@confect/core\";\nimport { createRequire } from \"node:module\";\nimport { pathToFileURL } from \"node:url\";\nimport { FileSystem, Path } from \"@effect/platform\";\nimport type { PlatformError } from \"@effect/platform/Error\";\nimport {\n  Array,\n  Effect,\n  HashSet,\n  Option,\n  Order,\n  pipe,\n  Record,\n  String,\n} from \"effect\";\nimport * as esbuild from \"esbuild\";\nimport * as FunctionPaths from \"./FunctionPaths\";\nimport * as GroupPath from \"./GroupPath\";\nimport * as GroupPaths from \"./GroupPaths\";\nimport { logFileAdded, logFileModified, logFileRemoved } from \"./log\";\nimport { ConfectDirectory } from \"./ConfectDirectory\";\nimport { ConvexDirectory } from \"./ConvexDirectory\";\nimport * as templates from \"./templates\";\n\nexport const removePathExtension = (pathStr: string) =>\n  Effect.gen(function* () {\n    const path = yield* Path.Path;\n\n    return String.slice(0, -path.extname(pathStr).length)(pathStr);\n  });\n\nexport const EXTERNAL_PACKAGES = [\n  \"@confect/core\",\n  \"@confect/server\",\n  \"effect\",\n  \"@effect/*\",\n];\n\nconst isExternalImport = (path: string) =>\n  EXTERNAL_PACKAGES.some((p) => {\n    if (p.endsWith(\"/*\")) {\n      return path.startsWith(p.slice(0, -1));\n    }\n    return path === p || path.startsWith(p + \"/\");\n  });\n\nconst absoluteExternalsPlugin: esbuild.Plugin = {\n  name: \"absolute-externals\",\n  setup(build) {\n    build.onResolve({ filter: /.*/ }, async (args) => {\n      if (args.kind !== \"import-statement\" && args.kind !== \"dynamic-import\")\n        return;\n      if (!isExternalImport(args.path)) return;\n      // `import.meta.resolve`'s second argument is silently ignored in modern\n      // Node, so resolution would always walk up from the CLI's bundled file\n      // (`packages/cli/dist/utils.mjs`) instead of from the user's project.\n      // Use `createRequire` keyed on the importing file's directory so we\n      // resolve out of *their* `node_modules`. The synthetic filename is just\n      // a CommonJS resolution anchor; the file does not need to exist.\n      const parentFile = pathToFileURL(args.resolveDir + \"/_\").href;\n      const require_ = createRequire(parentFile);\n      const resolvedPath = require_.resolve(args.path);\n      const resolved = pathToFileURL(resolvedPath).href;\n      return { path: resolved, external: true };\n    });\n  },\n};\n\n/**\n * Bundle a TypeScript entry point with esbuild and import the result via a\n * data URL. This handles extensionless `.ts` imports regardless of whether the\n * user's project sets `\"type\": \"module\"` in package.json.\n */\nexport const bundleAndImport = (entryPoint: string) =>\n  Effect.gen(function* () {\n    const result = yield* Effect.promise(() =>\n      esbuild.build({\n        entryPoints: [entryPoint],\n        bundle: true,\n        write: false,\n        platform: \"node\",\n        format: \"esm\",\n        logLevel: \"silent\",\n        plugins: [absoluteExternalsPlugin],\n      }),\n    );\n    const code = result.outputFiles[0]!.text;\n    const dataUrl =\n      \"data:text/javascript;base64,\" + Buffer.from(code).toString(\"base64\");\n    return yield* Effect.promise(() => import(dataUrl));\n  });\n\nexport const writeFileStringAndLog = (filePath: string, contents: string) =>\n  Effect.gen(function* () {\n    const fs = yield* FileSystem.FileSystem;\n    if (!(yield* fs.exists(filePath))) {\n      yield* fs.writeFileString(filePath, contents);\n      yield* logFileAdded(filePath);\n      return;\n    }\n    const existing = yield* fs.readFileString(filePath);\n    if (existing !== contents) {\n      yield* fs.writeFileString(filePath, contents);\n      yield* logFileModified(filePath);\n    }\n  });\n\nexport const findProjectRoot = Effect.gen(function* () {\n  const fs = yield* FileSystem.FileSystem;\n  const path = yield* Path.Path;\n\n  const startDir = path.resolve(\".\");\n  const root = path.parse(startDir).root;\n\n  const directories = Array.unfold(startDir, (dir) =>\n    dir === root\n      ? Option.none()\n      : Option.some([dir, path.dirname(dir)] as const),\n  );\n\n  const projectRoot = yield* Effect.findFirst(directories, (dir) =>\n    fs.exists(path.join(dir, \"package.json\")),\n  );\n\n  return Option.getOrElse(projectRoot, () => startDir);\n});\n\nexport type WriteChange = \"Added\" | \"Modified\" | \"Unchanged\";\n\nexport const writeFileString = (\n  filePath: string,\n  contents: string,\n): Effect.Effect<WriteChange, PlatformError, FileSystem.FileSystem> =>\n  Effect.gen(function* () {\n    const fs = yield* FileSystem.FileSystem;\n\n    if (!(yield* fs.exists(filePath))) {\n      yield* fs.writeFileString(filePath, contents);\n      return \"Added\";\n    }\n    const existing = yield* fs.readFileString(filePath);\n    if (existing !== contents) {\n      yield* fs.writeFileString(filePath, contents);\n      return \"Modified\";\n    }\n    return \"Unchanged\";\n  });\n\nexport const generateGroupModule = ({\n  groupPath,\n  functionNames,\n}: {\n  groupPath: GroupPath.GroupPath;\n  functionNames: string[];\n}) =>\n  Effect.gen(function* () {\n    const fs = yield* FileSystem.FileSystem;\n    const path = yield* Path.Path;\n    const convexDirectory = yield* ConvexDirectory.get;\n    const confectDirectory = yield* ConfectDirectory.get;\n\n    const relativeModulePath = yield* GroupPath.modulePath(groupPath);\n    const modulePath = path.join(convexDirectory, relativeModulePath);\n\n    const directoryPath = path.dirname(modulePath);\n    if (!(yield* fs.exists(directoryPath))) {\n      yield* fs.makeDirectory(directoryPath, { recursive: true });\n    }\n\n    const isNodeGroup = groupPath.pathSegments[0] === \"node\";\n    const registeredFunctionsFileName = isNodeGroup\n      ? \"nodeRegisteredFunctions.ts\"\n      : \"registeredFunctions.ts\";\n    const registeredFunctionsPath = path.join(\n      confectDirectory,\n      \"_generated\",\n      registeredFunctionsFileName,\n    );\n    const registeredFunctionsImportPath = yield* removePathExtension(\n      path.relative(path.dirname(modulePath), registeredFunctionsPath),\n    );\n    const registeredFunctionsVariableName = isNodeGroup\n      ? \"nodeRegisteredFunctions\"\n      : \"registeredFunctions\";\n\n    const functionsContentsString = yield* templates.functions({\n      groupPath,\n      functionNames,\n      registeredFunctionsImportPath,\n      registeredFunctionsVariableName,\n      useNode: isNodeGroup,\n      ...(isNodeGroup\n        ? {\n            registeredFunctionsLookupPath: groupPath.pathSegments.slice(1),\n          }\n        : {}),\n    });\n\n    if (!(yield* fs.exists(modulePath))) {\n      yield* fs.writeFileString(modulePath, functionsContentsString);\n      return \"Added\" as const;\n    }\n    const existing = yield* fs.readFileString(modulePath);\n    if (existing !== functionsContentsString) {\n      yield* fs.writeFileString(modulePath, functionsContentsString);\n      return \"Modified\" as const;\n    }\n    return \"Unchanged\" as const;\n  });\n\nconst logGroupPaths = <R>(\n  groupPaths: GroupPaths.GroupPaths,\n  logFn: (fullPath: string) => Effect.Effect<void, never, R>,\n) =>\n  Effect.gen(function* () {\n    const path = yield* Path.Path;\n    const convexDirectory = yield* ConvexDirectory.get;\n\n    yield* Effect.forEach(groupPaths, (gp) =>\n      Effect.gen(function* () {\n        const relativeModulePath = yield* GroupPath.modulePath(gp);\n        yield* logFn(path.join(convexDirectory, relativeModulePath));\n      }),\n    );\n  });\n\nexport const generateFunctions = (spec: Spec.AnyWithProps) =>\n  Effect.gen(function* () {\n    const path = yield* Path.Path;\n    const convexDirectory = yield* ConvexDirectory.get;\n\n    const groupPathsFromFs = yield* getGroupPathsFromFs;\n    const functionPaths = FunctionPaths.make(spec);\n    const groupPathsFromSpec = FunctionPaths.groupPaths(functionPaths);\n\n    const overlappingGroupPaths = GroupPaths.GroupPaths.make(\n      HashSet.intersection(groupPathsFromFs, groupPathsFromSpec),\n    );\n    yield* Effect.forEach(overlappingGroupPaths, (groupPath) =>\n      Effect.gen(function* () {\n        const group = yield* GroupPath.getGroupSpec(spec, groupPath);\n        const functionNames = pipe(\n          group.functions,\n          Record.values,\n          Array.sortBy(\n            Order.mapInput(\n              Order.string,\n              (fn: FunctionSpec.AnyWithProps) => fn.name,\n            ),\n          ),\n          Array.map((fn) => fn.name),\n        );\n        const result = yield* generateGroupModule({ groupPath, functionNames });\n        if (result === \"Modified\") {\n          const relativeModulePath = yield* GroupPath.modulePath(groupPath);\n          yield* logFileModified(\n            path.join(convexDirectory, relativeModulePath),\n          );\n        }\n      }),\n    );\n\n    const extinctGroupPaths = GroupPaths.GroupPaths.make(\n      HashSet.difference(groupPathsFromFs, groupPathsFromSpec),\n    );\n    yield* removeGroups(extinctGroupPaths);\n    yield* logGroupPaths(extinctGroupPaths, logFileRemoved);\n\n    const newGroupPaths = GroupPaths.GroupPaths.make(\n      HashSet.difference(groupPathsFromSpec, groupPathsFromFs),\n    );\n    yield* writeGroups(spec, newGroupPaths);\n    yield* logGroupPaths(newGroupPaths, logFileAdded);\n\n    return functionPaths;\n  });\n\nconst getGroupPathsFromFs = Effect.gen(function* () {\n  const fs = yield* FileSystem.FileSystem;\n  const path = yield* Path.Path;\n  const convexDirectory = yield* ConvexDirectory.get;\n\n  const RESERVED_CONVEX_TS_FILE_NAMES = new Set([\n    \"schema.ts\",\n    \"http.ts\",\n    \"crons.ts\",\n    \"auth.config.ts\",\n    \"convex.config.ts\",\n  ]);\n\n  const allConvexPaths = yield* fs.readDirectory(convexDirectory, {\n    recursive: true,\n  });\n  const groupPathArray = yield* pipe(\n    allConvexPaths,\n    Array.filter(\n      (convexPath) =>\n        path.extname(convexPath) === \".ts\" &&\n        !RESERVED_CONVEX_TS_FILE_NAMES.has(path.basename(convexPath)) &&\n        path.basename(path.dirname(convexPath)) !== \"_generated\",\n    ),\n    Effect.forEach((groupModulePath) =>\n      GroupPath.fromGroupModulePath(groupModulePath),\n    ),\n  );\n  return pipe(groupPathArray, HashSet.fromIterable, GroupPaths.GroupPaths.make);\n});\n\nexport const removeGroups = (groupPaths: GroupPaths.GroupPaths) =>\n  Effect.gen(function* () {\n    const fs = yield* FileSystem.FileSystem;\n    const path = yield* Path.Path;\n    const convexDirectory = yield* ConvexDirectory.get;\n\n    yield* Effect.all(\n      HashSet.map(groupPaths, (groupPath) =>\n        Effect.gen(function* () {\n          const relativeModulePath = yield* GroupPath.modulePath(groupPath);\n          const modulePath = path.join(convexDirectory, relativeModulePath);\n\n          yield* Effect.logDebug(`Removing group '${relativeModulePath}'...`);\n\n          yield* fs.remove(modulePath);\n          yield* Effect.logDebug(`Group '${relativeModulePath}' removed`);\n        }),\n      ),\n      { concurrency: \"unbounded\" },\n    );\n  });\n\nexport const writeGroups = (\n  spec: Spec.AnyWithProps,\n  groupPaths: GroupPaths.GroupPaths,\n) =>\n  Effect.forEach(groupPaths, (groupPath) =>\n    Effect.gen(function* () {\n      const group = yield* GroupPath.getGroupSpec(spec, groupPath);\n\n      const functionNames = pipe(\n        group.functions,\n        Record.values,\n        Array.sortBy(\n          Order.mapInput(\n            Order.string,\n            (fn: FunctionSpec.AnyWithProps) => fn.name,\n          ),\n        ),\n        Array.map((fn) => fn.name),\n      );\n\n      yield* Effect.logDebug(`Generating group ${groupPath}...`);\n      yield* generateGroupModule({\n        groupPath,\n        functionNames,\n      });\n      yield* Effect.logDebug(`Group ${groupPath} generated`);\n    }),\n  );\n\nconst generateOptionalFile = (\n  confectFile: string,\n  convexFile: string,\n  generateContents: (importPath: string) => Effect.Effect<string>,\n) =>\n  Effect.gen(function* () {\n    const fs = yield* FileSystem.FileSystem;\n    const path = yield* Path.Path;\n    const confectDirectory = yield* ConfectDirectory.get;\n    const convexDirectory = yield* ConvexDirectory.get;\n\n    const confectFilePath = path.join(confectDirectory, confectFile);\n\n    if (!(yield* fs.exists(confectFilePath))) {\n      return Option.none();\n    }\n\n    const convexFilePath = path.join(convexDirectory, convexFile);\n    const relativeImportPath = path.relative(\n      path.dirname(convexFilePath),\n      confectFilePath,\n    );\n    const importPathWithoutExt = yield* removePathExtension(relativeImportPath);\n    const contents = yield* generateContents(importPathWithoutExt);\n    const change = yield* writeFileString(convexFilePath, contents);\n    return Option.some({ change, convexFilePath });\n  });\n\nexport const generateHttp = generateOptionalFile(\n  \"http.ts\",\n  \"http.ts\",\n  (importPath) => templates.http({ httpImportPath: importPath }),\n);\n\nexport const generateCrons = generateOptionalFile(\n  \"crons.ts\",\n  \"crons.ts\",\n  (importPath) => templates.crons({ cronsImportPath: importPath }),\n);\n\nexport const generateAuthConfig = generateOptionalFile(\n  \"auth.ts\",\n  \"auth.config.ts\",\n  (importPath) => templates.authConfig({ authImportPath: importPath }),\n);\n"],"mappings":"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"}
+{"version":3,"file":"utils.mjs","names":["GroupPath.modulePath","modulePath","templates.functions","FunctionPaths.make","FunctionPaths.groupPaths","GroupPath.getGroupSpec","GroupPath.fromGroupModulePath","templates.http","templates.crons","templates.authConfig"],"sources":["../src/utils.ts"],"sourcesContent":["import type { FunctionSpec, Spec } from \"@confect/core\";\nimport { FileSystem, Path } from \"@effect/platform\";\nimport type { PlatformError } from \"@effect/platform/Error\";\nimport {\n  Array,\n  Context,\n  Effect,\n  HashSet,\n  Option,\n  Order,\n  pipe,\n  Record,\n  Ref,\n  String,\n} from \"effect\";\nimport * as FunctionPaths from \"./FunctionPaths\";\nimport * as GroupPath from \"./GroupPath\";\nimport * as GroupPaths from \"./GroupPaths\";\nimport { logFileAdded, logFileModified, logFileRemoved } from \"./log\";\nimport { ConfectDirectory } from \"./ConfectDirectory\";\nimport { ConvexDirectory } from \"./ConvexDirectory\";\nimport * as templates from \"./templates\";\n\n/**\n * Tracks whether the current codegen run wrote anything to disk. Set to\n * `true` by every helper that actually overwrites a file (skipping the\n * content-unchanged case). `codegenHandler` provides a fresh `Ref` per\n * run and reads it back to report `anyWritesHappened`; callers outside a\n * codegen pass hit the cached default `Ref` and need not interact with\n * the tracker.\n */\nexport class WriteTracker extends Context.Reference<WriteTracker>()(\n  \"@confect/cli/WriteTracker\",\n  { defaultValue: () => Ref.unsafeMake(false) },\n) {}\n\nconst markWritten = Effect.gen(function* () {\n  const tracker = yield* WriteTracker;\n  yield* Ref.set(tracker, true);\n});\n\nexport const removePathExtension = (pathStr: string) =>\n  Effect.gen(function* () {\n    const path = yield* Path.Path;\n\n    return String.slice(0, -path.extname(pathStr).length)(pathStr);\n  });\n\n/** Ensures a relative path is a valid ESM/TS module specifier (e.g. `spec` → `./spec`). */\nexport const toModuleImportPath = (relativePath: string) =>\n  Effect.gen(function* () {\n    const withoutExt = yield* removePathExtension(relativePath);\n    return withoutExt.startsWith(\".\") ? withoutExt : `./${withoutExt}`;\n  });\n\nexport const writeFileStringAndLog = (filePath: string, contents: string) =>\n  Effect.gen(function* () {\n    const fs = yield* FileSystem.FileSystem;\n    if (!(yield* fs.exists(filePath))) {\n      yield* fs.writeFileString(filePath, contents);\n      yield* markWritten;\n      yield* logFileAdded(filePath);\n      return;\n    }\n    const existing = yield* fs.readFileString(filePath);\n    if (existing !== contents) {\n      yield* fs.writeFileString(filePath, contents);\n      yield* markWritten;\n      yield* logFileModified(filePath);\n    }\n  });\n\nexport const findProjectRoot = Effect.gen(function* () {\n  const fs = yield* FileSystem.FileSystem;\n  const path = yield* Path.Path;\n\n  const startDir = path.resolve(\".\");\n  const root = path.parse(startDir).root;\n\n  const directories = Array.unfold(startDir, (dir) =>\n    dir === root\n      ? Option.none()\n      : Option.some([dir, path.dirname(dir)] as const),\n  );\n\n  const projectRoot = yield* Effect.findFirst(directories, (dir) =>\n    fs.exists(path.join(dir, \"package.json\")),\n  );\n\n  return Option.getOrElse(projectRoot, () => startDir);\n});\n\nexport type WriteChange = \"Added\" | \"Modified\" | \"Unchanged\";\n\nexport const writeFileString = (\n  filePath: string,\n  contents: string,\n): Effect.Effect<WriteChange, PlatformError, FileSystem.FileSystem> =>\n  Effect.gen(function* () {\n    const fs = yield* FileSystem.FileSystem;\n\n    if (!(yield* fs.exists(filePath))) {\n      yield* fs.writeFileString(filePath, contents);\n      yield* markWritten;\n      return \"Added\";\n    }\n    const existing = yield* fs.readFileString(filePath);\n    if (existing !== contents) {\n      yield* fs.writeFileString(filePath, contents);\n      yield* markWritten;\n      return \"Modified\";\n    }\n    return \"Unchanged\";\n  });\n\nexport const removePathIfExists = (\n  filePath: string,\n): Effect.Effect<void, PlatformError, FileSystem.FileSystem> =>\n  Effect.gen(function* () {\n    const fs = yield* FileSystem.FileSystem;\n\n    if (!(yield* fs.exists(filePath))) {\n      return;\n    }\n\n    yield* fs\n      .remove(filePath)\n      .pipe(\n        Effect.catchTag(\"SystemError\", (error) =>\n          error.reason === \"NotFound\" ? Effect.void : Effect.fail(error),\n        ),\n      );\n  });\n\n/**\n * Bump the mtime of `convex/schema.ts` so the Convex CLI's chokidar watcher\n * emits a `change` event after every successful Confect codegen run. Without\n * this, a codegen that doesn't change any file content (for example,\n * recovering from a transient broken state in `confect/`) leaves Convex\n * stuck on its previous error because nothing it observes has changed.\n */\nexport const touchConvexSchema = Effect.gen(function* () {\n  const fs = yield* FileSystem.FileSystem;\n  const path = yield* Path.Path;\n  const convexDirectory = yield* ConvexDirectory.get;\n  const schemaPath = path.join(convexDirectory, \"schema.ts\");\n\n  if (!(yield* fs.exists(schemaPath))) {\n    return;\n  }\n\n  const now = new Date();\n  yield* fs.utimes(schemaPath, now, now);\n});\n\nexport const generateGroupModule = ({\n  groupPath,\n  functionNames,\n  registeredFunctionsImportPath,\n  useNode = false,\n}: {\n  groupPath: GroupPath.GroupPath;\n  functionNames: string[];\n  registeredFunctionsImportPath: string;\n  useNode?: boolean;\n}) =>\n  Effect.gen(function* () {\n    const fs = yield* FileSystem.FileSystem;\n    const path = yield* Path.Path;\n    const convexDirectory = yield* ConvexDirectory.get;\n\n    const relativeModulePath = yield* GroupPath.modulePath(groupPath);\n    const modulePath = path.join(convexDirectory, relativeModulePath);\n\n    const directoryPath = path.dirname(modulePath);\n    if (!(yield* fs.exists(directoryPath))) {\n      yield* fs.makeDirectory(directoryPath, { recursive: true });\n    }\n\n    const functionsContentsString = yield* templates.functions({\n      functionNames,\n      registeredFunctionsImportPath,\n      useNode,\n    });\n\n    if (!(yield* fs.exists(modulePath))) {\n      yield* fs.writeFileString(modulePath, functionsContentsString);\n      yield* markWritten;\n      return \"Added\" as const;\n    }\n    const existing = yield* fs.readFileString(modulePath);\n    if (existing !== functionsContentsString) {\n      yield* fs.writeFileString(modulePath, functionsContentsString);\n      yield* markWritten;\n      return \"Modified\" as const;\n    }\n    return \"Unchanged\" as const;\n  });\n\nconst logGroupPaths = <R>(\n  groupPaths: GroupPaths.GroupPaths,\n  logFn: (fullPath: string) => Effect.Effect<void, never, R>,\n) =>\n  Effect.gen(function* () {\n    const path = yield* Path.Path;\n    const convexDirectory = yield* ConvexDirectory.get;\n\n    yield* Effect.forEach(groupPaths, (gp) =>\n      Effect.gen(function* () {\n        const relativeModulePath = yield* GroupPath.modulePath(gp);\n        yield* logFn(path.join(convexDirectory, relativeModulePath));\n      }),\n    );\n  });\n\nexport const generateFunctions = (spec: Spec.AnyWithProps) =>\n  Effect.gen(function* () {\n    const path = yield* Path.Path;\n    const convexDirectory = yield* ConvexDirectory.get;\n    const confectDirectory = yield* ConfectDirectory.get;\n\n    const groupPathsFromFs = yield* getGroupPathsFromFs;\n    const functionPaths = FunctionPaths.make(spec);\n    const groupPathsFromSpec = FunctionPaths.groupPaths(functionPaths);\n\n    const overlappingGroupPaths = GroupPaths.GroupPaths.make(\n      HashSet.intersection(groupPathsFromFs, groupPathsFromSpec),\n    );\n    yield* Effect.forEach(overlappingGroupPaths, (groupPath) =>\n      Effect.gen(function* () {\n        const group = yield* GroupPath.getGroupSpec(spec, groupPath);\n        const functionNames = pipe(\n          group.functions,\n          Record.values,\n          Array.sortBy(\n            Order.mapInput(\n              Order.string,\n              (fn: FunctionSpec.AnyWithProps) => fn.name,\n            ),\n          ),\n          Array.map((fn) => fn.name),\n        );\n        const relativeModulePath = yield* GroupPath.modulePath(groupPath);\n        const modulePath = path.join(convexDirectory, relativeModulePath);\n        const registrySegments =\n          groupPath.pathSegments[0] === \"node\"\n            ? groupPath.pathSegments.slice(1)\n            : groupPath.pathSegments;\n        const registeredFunctionsPath =\n          path.join(\n            confectDirectory,\n            \"_generated\",\n            \"registeredFunctions\",\n            ...registrySegments,\n          ) + \".ts\";\n        const registeredFunctionsImportPath = yield* toModuleImportPath(\n          path.relative(path.dirname(modulePath), registeredFunctionsPath),\n        );\n        const result = yield* generateGroupModule({\n          groupPath,\n          functionNames,\n          registeredFunctionsImportPath,\n          useNode: groupPath.pathSegments[0] === \"node\",\n        });\n        if (result === \"Modified\") {\n          yield* logFileModified(modulePath);\n        }\n      }),\n    );\n\n    const extinctGroupPaths = GroupPaths.GroupPaths.make(\n      HashSet.difference(groupPathsFromFs, groupPathsFromSpec),\n    );\n    yield* removeGroups(extinctGroupPaths);\n    yield* logGroupPaths(extinctGroupPaths, logFileRemoved);\n\n    const newGroupPaths = GroupPaths.GroupPaths.make(\n      HashSet.difference(groupPathsFromSpec, groupPathsFromFs),\n    );\n    yield* writeGroups(spec, newGroupPaths);\n    yield* logGroupPaths(newGroupPaths, logFileAdded);\n\n    return functionPaths;\n  });\n\nconst getGroupPathsFromFs = Effect.gen(function* () {\n  const fs = yield* FileSystem.FileSystem;\n  const path = yield* Path.Path;\n  const convexDirectory = yield* ConvexDirectory.get;\n\n  const RESERVED_CONVEX_TS_FILE_NAMES = new Set([\n    \"schema.ts\",\n    \"http.ts\",\n    \"crons.ts\",\n    \"auth.config.ts\",\n    \"convex.config.ts\",\n  ]);\n\n  const allConvexPaths = yield* fs.readDirectory(convexDirectory, {\n    recursive: true,\n  });\n  const groupPathArray = yield* pipe(\n    allConvexPaths,\n    Array.filter(\n      (convexPath) =>\n        path.extname(convexPath) === \".ts\" &&\n        !RESERVED_CONVEX_TS_FILE_NAMES.has(path.basename(convexPath)) &&\n        path.basename(path.dirname(convexPath)) !== \"_generated\",\n    ),\n    Effect.forEach((groupModulePath) =>\n      GroupPath.fromGroupModulePath(groupModulePath),\n    ),\n  );\n  return pipe(groupPathArray, HashSet.fromIterable, GroupPaths.GroupPaths.make);\n});\n\nexport const removeGroups = (groupPaths: GroupPaths.GroupPaths) =>\n  Effect.gen(function* () {\n    const path = yield* Path.Path;\n    const convexDirectory = yield* ConvexDirectory.get;\n\n    yield* Effect.all(\n      HashSet.map(groupPaths, (groupPath) =>\n        Effect.gen(function* () {\n          const relativeModulePath = yield* GroupPath.modulePath(groupPath);\n          const modulePath = path.join(convexDirectory, relativeModulePath);\n\n          yield* Effect.logDebug(`Removing group '${relativeModulePath}'...`);\n\n          yield* removePathIfExists(modulePath);\n          yield* Effect.logDebug(`Group '${relativeModulePath}' removed`);\n        }),\n      ),\n      { concurrency: \"unbounded\" },\n    );\n  });\n\nexport const writeGroups = (\n  spec: Spec.AnyWithProps,\n  groupPaths: GroupPaths.GroupPaths,\n) =>\n  Effect.forEach(groupPaths, (groupPath) =>\n    Effect.gen(function* () {\n      const path = yield* Path.Path;\n      const convexDirectory = yield* ConvexDirectory.get;\n      const confectDirectory = yield* ConfectDirectory.get;\n      const group = yield* GroupPath.getGroupSpec(spec, groupPath);\n\n      const functionNames = pipe(\n        group.functions,\n        Record.values,\n        Array.sortBy(\n          Order.mapInput(\n            Order.string,\n            (fn: FunctionSpec.AnyWithProps) => fn.name,\n          ),\n        ),\n        Array.map((fn) => fn.name),\n      );\n\n      const relativeModulePath = yield* GroupPath.modulePath(groupPath);\n      const modulePath = path.join(convexDirectory, relativeModulePath);\n      const registeredFunctionsPath =\n        path.join(\n          confectDirectory,\n          \"_generated\",\n          \"registeredFunctions\",\n          ...groupPath.pathSegments,\n        ) + \".ts\";\n      const registeredFunctionsImportPath = yield* toModuleImportPath(\n        path.relative(path.dirname(modulePath), registeredFunctionsPath),\n      );\n\n      yield* Effect.logDebug(`Generating group ${groupPath}...`);\n      yield* generateGroupModule({\n        groupPath,\n        functionNames,\n        registeredFunctionsImportPath,\n        useNode: groupPath.pathSegments[0] === \"node\",\n      });\n      yield* Effect.logDebug(`Group ${groupPath} generated`);\n    }),\n  );\n\nconst generateOptionalFile = (\n  confectFile: string,\n  convexFile: string,\n  generateContents: (importPath: string) => Effect.Effect<string>,\n) =>\n  Effect.gen(function* () {\n    const fs = yield* FileSystem.FileSystem;\n    const path = yield* Path.Path;\n    const confectDirectory = yield* ConfectDirectory.get;\n    const convexDirectory = yield* ConvexDirectory.get;\n\n    const confectFilePath = path.join(confectDirectory, confectFile);\n\n    if (!(yield* fs.exists(confectFilePath))) {\n      return Option.none();\n    }\n\n    const convexFilePath = path.join(convexDirectory, convexFile);\n    const relativeImportPath = path.relative(\n      path.dirname(convexFilePath),\n      confectFilePath,\n    );\n    const importPathWithoutExt = yield* removePathExtension(relativeImportPath);\n    const contents = yield* generateContents(importPathWithoutExt);\n    const change = yield* writeFileString(convexFilePath, contents);\n    return Option.some({ change, convexFilePath });\n  });\n\nexport const generateHttp = generateOptionalFile(\n  \"http.ts\",\n  \"http.ts\",\n  (importPath) => templates.http({ httpImportPath: importPath }),\n);\n\nexport const generateCrons = generateOptionalFile(\n  \"crons.ts\",\n  \"crons.ts\",\n  (importPath) => templates.crons({ cronsImportPath: importPath }),\n);\n\nexport const generateAuthConfig = generateOptionalFile(\n  \"auth.ts\",\n  \"auth.config.ts\",\n  (importPath) => templates.authConfig({ authImportPath: importPath }),\n);\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@confect/cli",
-  "version": "8.0.0",
+  "version": "9.0.0-next.0",
   "description": "Developer tooling for codegen and sync",
   "repository": {
     "type": "git",
@@ -65,7 +65,8 @@
   },
   "peerDependencies": {
     "effect": "^3.21.2",
-    "@confect/core": "^8.0.0"
+    "@confect/core": "^9.0.0-next.0",
+    "@confect/server": "^9.0.0-next.0"
   },
   "engines": {
     "node": ">=22",
@@ -76,7 +77,7 @@
   "types": "./dist/index.d.ts",
   "scripts": {
     "build": "tsdown --config-loader unrun",
-    "dev": "tsdown --watch",
+    "dev": "tsdown --watch --config-loader unrun",
     "test": "vitest run",
     "typecheck": "tsc --noEmit --project tsconfig.json",
     "fix": "prettier --write . && eslint --fix . --max-warnings=0",

package/src/BuildError.ts

@@ -0,0 +1,210 @@
+import { Ansi, AnsiDoc } from "@effect/printer-ansi";
+import { Array, Effect, Match, Option, pipe, Schema, String } from "effect";
+import * as esbuild from "esbuild";
+import { formatPathDoc } from "./log";
+
+// --- Variants ---
+
+export class BundleFailedError extends Schema.TaggedError<BundleFailedError>()(
+  "BundleFailedError",
+  {
+    file: Schema.String,
+    errors: Schema.Array(Schema.Unknown),
+  },
+) {}
+
+export class ImportFailedError extends Schema.TaggedError<ImportFailedError>()(
+  "ImportFailedError",
+  {
+    file: Schema.String,
+    cause: Schema.Unknown,
+  },
+) {}
+
+export const BuildError = Schema.Union(BundleFailedError, ImportFailedError);
+export type BuildError = typeof BuildError.Type;
+
+export const isBuildError = (error: unknown): error is BuildError =>
+  Schema.is(BuildError)(error);
+
+// --- Bundler adapter ---
+
+/**
+ * Internal failure produced by the esbuild bundle/import pipeline. Always
+ * remapped to a {@link BuildError} (which carries enough context for the CLI
+ * to render it) before reaching a user-surface boundary.
+ */
+export class BundlerError extends Schema.TaggedError<BundlerError>()(
+  "BundlerError",
+  {
+    cause: Schema.Unknown,
+  },
+) {}
+
+const isEsbuildBuildFailure = (error: unknown): error is esbuild.BuildFailure =>
+  typeof error === "object" &&
+  error !== null &&
+  "errors" in error &&
+  globalThis.Array.isArray((error as esbuild.BuildFailure).errors);
+
+export const fromBundlerError = (
+  file: string,
+  error: BundlerError,
+): BuildError =>
+  isEsbuildBuildFailure(error.cause)
+    ? new BundleFailedError({ file, errors: error.cause.errors })
+    : new ImportFailedError({ file, cause: error.cause });
+
+// --- Rendering ---
+
+const cross = pipe(AnsiDoc.char("✘"), AnsiDoc.annotate(Ansi.red));
+
+const errorGutter = pipe(
+  AnsiDoc.char("│"),
+  AnsiDoc.annotate(Ansi.red),
+  AnsiDoc.render({ style: "pretty" }),
+);
+
+const withErrorGutterBlock = (output: string): string =>
+  pipe(
+    String.split(output, "\n"),
+    Array.map((line) =>
+      pipe(line, String.trim) === "" ? errorGutter : `${errorGutter} ${line}`,
+    ),
+    Array.join("\n"),
+    (guttered) => `${errorGutter}\n${guttered}\n${errorGutter}`,
+  );
+
+const formatBuildMessage = (
+  error: esbuild.Message | undefined,
+  formattedMessage: string,
+): string => {
+  const lines = String.split(formattedMessage, "\n");
+  const redErrorText = pipe(
+    AnsiDoc.text(error?.text ?? ""),
+    AnsiDoc.annotate(Ansi.red),
+    AnsiDoc.render({ style: "pretty" }),
+  );
+  const replaced = pipe(
+    Array.findFirstIndex(lines, (l) => pipe(l, String.trim, String.isNonEmpty)),
+    Option.match({
+      onNone: () => lines,
+      onSome: (index) => Array.modify(lines, index, () => redErrorText),
+    }),
+  );
+  return pipe(replaced, Array.join("\n"));
+};
+
+/**
+ * Render a list of esbuild messages into a styled, gutter-prefixed block.
+ * Used by both {@link renderBundleFailedError} and the dev-mode esbuild
+ * watcher's `onEnd` hook (where the messages don't flow through the
+ * tagged-error pipeline).
+ */
+export const formatEsbuildMessages = (
+  errors: readonly esbuild.Message[],
+  formattedMessages: readonly string[],
+): string =>
+  pipe(
+    formattedMessages,
+    Array.map((message, i) => formatBuildMessage(errors[i], message)),
+    Array.join(""),
+    String.trimEnd,
+    withErrorGutterBlock,
+  );
+
+const renderImportFailedError = (error: ImportFailedError): AnsiDoc.AnsiDoc => {
+  const causeMessage =
+    error.cause instanceof Error
+      ? error.cause.message
+      : typeof error.cause === "string"
+        ? error.cause
+        : globalThis.String(error.cause);
+  const oneLineCause = pipe(
+    String.split(causeMessage, "\n"),
+    Array.findFirst((line) => pipe(line, String.trim, String.isNonEmpty)),
+    Option.map(String.trim),
+    Option.getOrElse(() => "unknown error"),
+  );
+  return pipe(
+    cross,
+    AnsiDoc.catWithSpace(
+      AnsiDoc.hcat([
+        AnsiDoc.text("Failed to load bundled module "),
+        formatPathDoc(error.file),
+        AnsiDoc.text(
+          `: ${oneLineCause}; check the file's top-level imports and side effects.`,
+        ),
+      ]),
+    ),
+  );
+};
+
+/**
+ * Render a {@link BundleFailedError} as a multi-line, ANSI-styled string:
+ * a one-line `✘ <file>: build errors` header followed by the
+ * gutter-prefixed esbuild diagnostic block. Multi-line is appropriate
+ * here because a single `BundleFailedError` carries an array of distinct
+ * esbuild messages.
+ */
+const renderBundleFailedError = (error: BundleFailedError): string => {
+  const messages = error.errors as readonly esbuild.Message[];
+  const formatted = esbuild.formatMessagesSync(messages as esbuild.Message[], {
+    kind: "error",
+    color: true,
+    terminalWidth: 80,
+  });
+  const header = pipe(
+    cross,
+    AnsiDoc.catWithSpace(
+      AnsiDoc.hcat([formatPathDoc(error.file), AnsiDoc.text(": build errors")]),
+    ),
+    AnsiDoc.render({ style: "pretty" }),
+  );
+  return `${header}\n${formatEsbuildMessages(messages, formatted)}`;
+};
+
+/**
+ * Render any {@link BuildError} into a styled, ready-to-print string.
+ * `ImportFailedError` collapses to a single line; `BundleFailedError`
+ * expands to a header plus one diagnostic block per esbuild message.
+ */
+export const renderBuildError = (error: BuildError): string =>
+  Match.value(error).pipe(
+    Match.tag("BundleFailedError", renderBundleFailedError),
+    Match.tag("ImportFailedError", (e) =>
+      pipe(renderImportFailedError(e), AnsiDoc.render({ style: "pretty" })),
+    ),
+    Match.exhaustive,
+  );
+
+export const logBuildError = (error: BuildError) =>
+  Effect.sync(() => console.error(renderBuildError(error)));
+
+/**
+ * Render a flat list of esbuild messages as a single error block with a
+ * generic `✘ Build errors` header. Used by dev-mode when multiple
+ * watchers surface the same underlying error and we want to log the
+ * coalesced set rather than one block per watcher.
+ */
+const renderCoalescedBuildErrors = (
+  messages: readonly esbuild.Message[],
+): string => {
+  const formatted = esbuild.formatMessagesSync(messages as esbuild.Message[], {
+    kind: "error",
+    color: true,
+    terminalWidth: 80,
+  });
+  const header = pipe(
+    cross,
+    AnsiDoc.catWithSpace(AnsiDoc.text("Build errors")),
+    AnsiDoc.render({ style: "pretty" }),
+  );
+  return `${header}\n${formatEsbuildMessages(messages, formatted)}`;
+};
+
+export const logCoalescedBuildErrors = (messages: readonly esbuild.Message[]) =>
+  Effect.sync(() => {
+    if (messages.length === 0) return;
+    console.error(renderCoalescedBuildErrors(messages));
+  });