bazis 0.96.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Alenin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# bazis
+
+A modular backend framework for [Bun](https://bun.com), written in TypeScript:
+constructor dependency injection wired by code generation, HTTP controllers
+with validated request models, an ORM for PostgreSQL, configuration with
+per-environment defaults, JWT, WebSocket, gRPC, background services, AI agents
+and a CLI that scaffolds, runs, tests and compiles your app into a single
+executable.
+
+The package ships TypeScript sources and runs on Bun only (≥ 1.4.0). There is
+no build step and no separate type package.
+
+## Quick start
+
+```sh
+bunx bazis new MyApp
+cd my-app
+bun install
+bunx bazis dev            # GET http://127.0.0.1:3000/health
+```
+
+`bazis new` creates a project with `src/index.ts`, a root `AppModule`,
+`bazis.config.json`, scripts, a `/health` test and an `.env.example`.
+
+## CLI
+
+| Command | What it does |
+| --- | --- |
+| `bazis new <Name>` | Create a project in `./<name>` |
+| `bazis g module <Name> --empty\|--minimal\|--full` | Add a module: empty; CRUD with ORM, validation and paging; or the same with auth guards |
+| `bazis g pack <Name> --parts a,b` | Add a composite module made of several atomic ones |
+| `bazis codegen` | Regenerate dependency wiring into `src/generated/bazis` |
+| `bazis dev [--watch]` | Codegen, then run the app from source with `BAZIS_ENV=development` (unless set); `--watch` restarts on changes in `src/` |
+| `bazis test [args]` | Codegen, then `bun test` |
+| `bazis build` | Codegen and typecheck |
+| `bazis build --bin` | Also compile `bin/<name>`, a standalone executable |
+
+`dev`, `test` and `build` run codegen themselves. If you start the app some
+other way after changing code, it warns at startup that the generated code is
+out of date. A compiled binary carries everything it needs and skips that
+check.
+
+## A module
+
+```ts
+// src/app/modules/greeting/Greeting.module.ts
+import { Module, scoped } from "bazis/core/di";
+import { Controller, Get } from "bazis/core/http";
+
+export class GreetingService {
+  hello(name: string) {
+    return { message: `Hello, ${name}` };
+  }
+}
+
+@Controller("greetings")
+export class GreetingController {
+  // No registration code: `bazis codegen` reads the constructor.
+  constructor(private readonly greetings: GreetingService) {}
+
+  @Get(":name")
+  get(name: string) {
+    return this.greetings.hello(name);
+  }
+}
+
+@Module({
+  controllers: [GreetingController],
+  providers: [scoped(GreetingService)],
+  exports: [GreetingService],
+})
+export class GreetingModule {}
+```
+
+`bunx bazis g module Greeting --empty` creates this file with an empty module
+and adds `GreetingModule` to the `imports` of `AppModule`. With the code above,
+`GET /greetings/world` answers `{"message":"Hello, world"}`. Another module
+that imports `GreetingModule` can take `GreetingService` in its own
+constructor.
+
+## Database
+
+```ts
+// src/app/infra/App.infra.ts
+import { Infra } from "bazis/core/infra";
+import { ormBazisConnect } from "bazis/core/orm";
+import { dbConfig } from "../config/db.config"; // defineConfig("db", { default: { host, port, ... } })
+
+@Infra({ db: ormBazisConnect(dbConfig) })
+export class AppInfra {}
+
+// src/index.ts
+await runApp(AppModule, { infra: AppInfra, http: { port: 3000, health: true } });
+```
+
+A feature module attaches its own `DbContext` and entities with
+`ormBazis: { context, entities }`; its services take that context in their
+constructors. `bunx bazis g module Task --minimal` generates such a module.
+Configuration values can be overridden from the environment
+(`BAZIS_DB__HOST`, `BAZIS_DB__PASSWORD`, ...). Invalid configuration or a
+missing production secret stops startup with an error that names the key.
+
+A unique index violation in `saveChanges()` rejects with
+`UniqueViolationError` (with `constraint` and `table`); catch it to answer 409.
+Request-body fields declared as `string`, `number` or `boolean` are checked
+against the JSON type automatically (400 on mismatch); other rules come from
+`@Validator`.
+
+## Example
+
+The source repository contains `examples/todo`: three modules (projects,
+tasks and a report), PostgreSQL, cross-module injection, validation, JSON:API
+lists, an end-to-end test and a binary build.
+
+## Entry points
+
+Import from the subpaths listed in `exports` of `package.json`:
+`bazis/core/app`, `bazis/core/di`, `bazis/core/http`, `bazis/core/orm`,
+`bazis/core/infra`, `bazis/core/kernel`, `bazis/library/validation`,
+`bazis/library/jsonapi` and others. Anything not listed there is internal.
+
+## Language of built-in texts
+
+Built-in texts are English. Russian sets ship with the package; apply them
+once at startup:
+
+```ts
+import { MessageRegistry, RU_VALIDATION_MESSAGES } from "bazis/library/validation";
+import { CodexError, RU_CODEX_MESSAGES } from "bazis/core/infra";
+import { RU_UI_LABELS } from "bazis/core/app";
+
+MessageRegistry.setDefaults(RU_VALIDATION_MESSAGES); // validation errors
+CodexError.useMessages(RU_CODEX_MESSAGES);           // Codex connector errors
+await runApp(AppModule, { ui: { labels: RU_UI_LABELS, surfaces: [/* ... */] } }); // generated UI texts
+```
+
+Either call also accepts your own texts for some codes.
+
+## Status
+
+Pre-1.0: a minor version (0.x) can contain breaking changes; a patch version
+does not.
+
+## License
+
+MIT

package/cli/build.ts

@@ -0,0 +1,147 @@
+import { existsSync, mkdtempSync, rmSync, watch } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { resolveBun } from "./codegen";
+
+type Codegen = (cwd: string, target?: string) => Promise<number>;
+
+export interface BuildOptions {
+  /** Also compile the entrypoint into a standalone executable. */
+  readonly bin: boolean;
+  /** Executable path relative to the project; default `bin/<package name>`. */
+  readonly outfile?: string;
+}
+
+/**
+ * `bazis dev`: codegen, then run the default target's entrypoint from source.
+ * With `watch`, a change under src/ (except src/generated) stops the app,
+ * reruns codegen and starts it again; a failed codegen waits for the next change.
+ * The app runs as `development` unless BAZIS_ENV is set in the shell.
+ */
+/** `bazis dev` means development; an BAZIS_ENV from the shell still wins. */
+export function devEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  return { ...env, BAZIS_ENV: env.BAZIS_ENV || "development" };
+}
+
+export async function runDev(cwd: string, codegen: Codegen, log: (message: string) => void, options: { readonly watch?: boolean } = {}): Promise<number> {
+  const bun = await resolveBun(cwd);
+  const entry = await projectEntry(cwd);
+  const env = devEnvironment(process.env);
+  if (!options.watch) {
+    const generated = await codegen(cwd);
+    if (generated !== 0) return generated;
+    const child = Bun.spawn([bun, "run", entry], { cwd, env, stdin: "inherit", stdout: "inherit", stderr: "inherit" });
+    // The app owns graceful shutdown; forward the signal instead of dying first.
+    const forward = (signal: NodeJS.Signals) => () => child.kill(signal);
+    const onInterrupt = forward("SIGINT"), onTerminate = forward("SIGTERM");
+    process.on("SIGINT", onInterrupt);
+    process.on("SIGTERM", onTerminate);
+    try {
+      return await child.exited;
+    } finally {
+      process.off("SIGINT", onInterrupt);
+      process.off("SIGTERM", onTerminate);
+    }
+  }
+
+  let child: ReturnType<typeof Bun.spawn> | undefined;
+  let queue = Promise.resolve();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const stop = async () => {
+    if (!child) return;
+    const running = child;
+    child = undefined;
+    running.kill("SIGTERM");
+    await running.exited;
+  };
+  const start = async () => {
+    if (await codegen(cwd) !== 0) { log("[bazis] codegen failed; waiting for changes..."); return; }
+    child = Bun.spawn([bun, "run", entry], { cwd, env, stdin: "inherit", stdout: "inherit", stderr: "inherit" });
+  };
+  const watcher = watch(path.join(cwd, "src"), { recursive: true }, (_event, file) => {
+    // codegen writes src/generated: watching it would restart forever.
+    if (!file || /^generated([\\/]|$)/.test(String(file))) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      queue = queue.then(async () => { log(`[bazis] ${file} changed, restarting...`); await stop(); await start(); });
+    }, 150);
+  });
+  const finished = Promise.withResolvers<number>();
+  const shutdown = () => {
+    watcher.close();
+    clearTimeout(timer);
+    queue = queue.then(stop).then(() => finished.resolve(0), () => finished.resolve(1));
+  };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+  log("[bazis] watching src/ for changes (Ctrl+C to stop)");
+  queue = queue.then(start);
+  try {
+    return await finished.promise;
+  } finally {
+    process.off("SIGINT", shutdown);
+    process.off("SIGTERM", shutdown);
+  }
+}
+
+/** `bazis test [args]`: codegen, then `bun test` with the given arguments. */
+export async function runTest(cwd: string, args: readonly string[], codegen: Codegen): Promise<number> {
+  const generated = await codegen(cwd);
+  if (generated !== 0) return generated;
+  return await Bun.spawn([await resolveBun(cwd), "test", ...args], { cwd, stdin: "inherit", stdout: "inherit", stderr: "inherit" }).exited;
+}
+
+/** `bazis build [--bin]`: codegen and typecheck; with `bin`, also compile. */
+export async function runBuild(cwd: string, options: BuildOptions, codegen: Codegen, log: (message: string) => void): Promise<number> {
+  const generated = await codegen(cwd);
+  if (generated !== 0) return generated;
+  const bun = await resolveBun(cwd);
+  const tsc = path.join(cwd, "node_modules/typescript/bin/tsc");
+  if (!existsSync(tsc)) throw new Error("TypeScript is not installed in this project. Run: bun add -d typescript");
+  log("[bazis] typecheck...");
+  const typecheck = await Bun.spawn([bun, tsc, "--noEmit"], { cwd, stdout: "inherit", stderr: "inherit" }).exited;
+  if (typecheck !== 0 || !options.bin) return typecheck;
+  const outfile = path.resolve(cwd, options.outfile ?? path.join("bin", await binaryName(cwd)));
+  log(`[bazis] compile ${path.relative(cwd, outfile)}...`);
+  return compileBinary(bun, await projectEntry(cwd), outfile);
+}
+
+/**
+ * `bun build --compile` clones the running Bun executable into a temporary
+ * `.<hash>.bun-build` file in its working directory and cannot remove it when
+ * that executable is read-only or carries `uchg` (scripts/bazis-bun). Compile
+ * from a private directory and remove it afterwards.
+ */
+export function compileBinary(bun: string, entry: string, outfile: string): number {
+  const workDir = mkdtempSync(path.join(tmpdir(), "bazis-compile-"));
+  try {
+    const result = Bun.spawnSync([bun, "build", "--compile", path.resolve(entry), "--outfile", path.resolve(outfile)],
+      { cwd: workDir, stdout: "inherit", stderr: "inherit" });
+    return result.exitCode ?? 1;
+  } finally {
+    if (existsSync("/usr/bin/chflags")) Bun.spawnSync(["/usr/bin/chflags", "-R", "nouchg", workDir]);
+    try {
+      rmSync(workDir, { recursive: true, force: true });
+    } catch (error) {
+      // The binary itself is complete; report the leftover without failing the build.
+      console.error(`[bazis] temporary directory was not removed: ${workDir}`, error);
+    }
+  }
+}
+
+async function projectEntry(cwd: string): Promise<string> {
+  const configFile = Bun.file(path.join(cwd, "bazis.config.json"));
+  if (!await configFile.exists()) throw new Error("bazis.config.json not found in the current directory.");
+  const config = await configFile.json() as { defaultTarget?: string; targets?: Record<string, { entrypoints?: unknown }> };
+  const entry = (config.targets?.[config.defaultTarget ?? ""]?.entrypoints as unknown[] | undefined)?.[0];
+  if (typeof entry !== "string" || !entry) throw new Error("bazis.config.json has no entrypoint for its default target.");
+  return path.resolve(cwd, entry);
+}
+
+async function binaryName(cwd: string): Promise<string> {
+  const manifest = Bun.file(path.join(cwd, "package.json"));
+  const name = await manifest.exists() ? (await manifest.json() as { name?: unknown }).name : undefined;
+  const base = typeof name === "string" ? name.replace(/^@[^/]+\//, "").replace(/[^a-z0-9._-]+/gi, "-") : "";
+  if (!base) throw new Error("package.json needs a name for the default binary path; pass --outfile.");
+  return base;
+}

package/cli/codegen.ts

@@ -0,0 +1,40 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+const GENERATOR = "core/scripts/di-generate.ts";
+
+/** Run the framework generator for the project in `cwd`; returns its exit code. */
+export async function runCodegen(cwd: string, target?: string): Promise<number> {
+  if (target !== undefined) {
+    const configFile = Bun.file(path.join(cwd, "bazis.config.json"));
+    if (!await configFile.exists()) throw new Error("--target requires bazis.config.json in the current directory.");
+    const config = await configFile.json();
+    if (target !== "all" && !Object.hasOwn(config.targets ?? {}, target)) throw new Error(`Unknown codegen target: ${target}`);
+  }
+  const args = [await resolveBun(cwd), resolveGenerator(cwd), ...(target === undefined ? [] : ["--target", target])];
+  return await Bun.spawn(args, { cwd, stdout: "inherit", stderr: "inherit" }).exited;
+}
+
+/**
+ * The generator of the framework this project uses: the installed package,
+ * the framework source checkout, or the package this CLI runs from.
+ */
+export function resolveGenerator(cwd: string): string {
+  const candidates = [
+    path.join(cwd, "node_modules/bazis", GENERATOR),
+    path.join(cwd, "src/bazis", GENERATOR),
+    path.resolve(import.meta.dir, "..", GENERATOR),
+  ];
+  const generator = candidates.find((candidate) => existsSync(candidate));
+  if (!generator) throw new Error("bazis code generator not found. Install the framework in this project: bun add bazis");
+  return generator;
+}
+
+/** Bun for child processes: the project's qualified launcher when present. */
+export async function resolveBun(cwd: string): Promise<string> {
+  const wrapper = path.join(cwd, "scripts/bazis-bun");
+  // process.execPath can be the compiled CLI itself. Never invoke it as Bun.
+  const executable = await Bun.file(wrapper).exists() ? wrapper : (process.env.BAZIS_BUN_BIN || Bun.which("bun"));
+  if (!executable) throw new Error("Bun was not found. Set BAZIS_BUN_BIN or put Bun on PATH.");
+  return executable;
+}

package/cli/generateModule.ts

@@ -0,0 +1,187 @@
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, realpath, rename, rm, rmdir, writeFile } from "node:fs/promises";
+import { buildModuleTemplates, type ModuleTemplateFiles, type ModuleTemplateProfile } from "./templates/module";
+import { buildPackTemplates } from "./templates/pack";
+import { parseModuleName, type ModuleNaming } from "./naming";
+import { moduleImportPath, registerModuleInSource } from "./moduleRegistration";
+
+export interface GenerateModuleOptions {
+  /** User, users, order-item. */
+  readonly name: string;
+  /** Default: src/app/modules, relative to cwd. */
+  readonly modulesRoot?: string;
+  /** Default: {modulesRoot}/App.module.ts, relative to cwd. */
+  readonly appModulePath?: string;
+  readonly register?: boolean;
+  readonly force?: boolean;
+  readonly profile?: ModuleTemplateProfile;
+  /** Validate and return the plan without writing files. */
+  readonly dryRun?: boolean;
+}
+
+export interface GenerateModulePackOptions extends Omit<GenerateModuleOptions, "profile"> {
+  readonly parts: readonly string[];
+}
+
+export interface GenerateModuleResult {
+  readonly moduleDir: string;
+  readonly files: readonly string[];
+  /** In dry-run, whether the resulting plan connects the module. */
+  readonly registered: boolean;
+  readonly dryRun: boolean;
+  readonly changes: readonly { readonly path: string; readonly action: "create" | "update" }[];
+  readonly warnings: readonly string[];
+}
+
+interface PlannedWrite {
+  readonly absolute: string;
+  readonly content: string;
+  readonly original: string | undefined;
+}
+
+export async function generateModule(options: GenerateModuleOptions): Promise<GenerateModuleResult> {
+  const naming = parseModuleName(options.name);
+  const profile = options.profile ?? "minimal";
+  if (!["empty", "minimal", "full"].includes(profile)) throw new Error(`Unknown profile: ${profile}`);
+  const modulesRoot = await canonicalDirectory(path.resolve(options.modulesRoot ?? "src/app/modules"));
+  let authImportPath: string | null | undefined;
+  if (profile === "full") {
+    // The host's auth helpers are optional: without them the controller is
+    // generated without @Authorize and the command says so.
+    const authDir = path.resolve("src/app/modules/auth");
+    const helpers = await Promise.all(["tokenKinds.ts", "jwtAuth.ts"].map(async (helper) => (await fileInfo(path.join(authDir, helper)))?.isFile() === true));
+    authImportPath = helpers.every(Boolean)
+      ? moduleImportPath(path.join(modulesRoot, naming.folder, "http", `${naming.module}.controller.ts`), await canonicalDirectory(authDir))
+      : null;
+  }
+  const result = await generateFiles(options, naming, naming.folder, buildModuleTemplates(naming, profile, authImportPath));
+  return authImportPath === null
+    ? { ...result, warnings: [...result.warnings, "No auth helpers in src/app/modules/auth: the full profile controller has no @Authorize. Protect its routes before exposing them."] }
+    : result;
+}
+
+export async function generateModulePack(options: GenerateModulePackOptions): Promise<GenerateModuleResult> {
+  const naming = parseModuleName(options.name);
+  return generateFiles(options, naming, `${naming.folder}_modules`, buildPackTemplates(naming, options.parts));
+}
+
+async function generateFiles(options: GenerateModuleOptions, naming: ModuleNaming, folder: string, templates: readonly ModuleTemplateFiles[]): Promise<GenerateModuleResult> {
+  const modulesRoot = await canonicalDirectory(path.resolve(options.modulesRoot ?? "src/app/modules"));
+  const moduleDir = path.join(modulesRoot, folder);
+  const requestedAppPath = path.resolve(options.appModulePath ?? path.join(modulesRoot, "App.module.ts"));
+  const appModulePath = path.join(await canonicalDirectory(path.dirname(requestedAppPath)), path.basename(requestedAppPath));
+  const moduleInfo = await fileInfo(moduleDir);
+  if (moduleInfo && !options.force) throw new Error(`Module folder already exists: ${moduleDir}. Use --force to overwrite.`);
+  if (moduleInfo && !moduleInfo.isDirectory()) throw new Error(`Module path is not a directory: ${moduleDir}.`);
+
+  const featureWrites: PlannedWrite[] = [];
+  for (const file of templates) {
+    const absolute = path.join(moduleDir, file.relativePath);
+    const info = await fileInfo(absolute);
+    if (info && !options.force) throw new Error(`File already exists: ${absolute}. Use --force to overwrite.`);
+    if (info && !info.isFile()) throw new Error(`Refusing to overwrite a non-regular file: ${absolute}`);
+    featureWrites.push({ absolute, content: file.content, original: info ? await readFile(absolute, "utf8") : undefined });
+  }
+
+  // Complete host preflight before the first write, including on --force.
+  const writes = [...featureWrites];
+  const warnings: string[] = [];
+  let registered = false;
+  if (options.register !== false) {
+    const appInfo = await fileInfo(appModulePath);
+    if (!appInfo) {
+      warnings.push(`App module not found, skipped registration: ${appModulePath}`);
+    } else {
+      if (!appInfo.isFile()) throw new Error(`App module must be a regular file: ${appModulePath}`);
+      const original = await readFile(appModulePath, "utf8");
+      const content = registerModuleInSource(original, appModulePath, path.join(moduleDir, `${naming.module}.module.ts`), naming.moduleClass);
+      if (content !== original) writes.push({ absolute: appModulePath, content, original });
+      registered = true;
+    }
+  }
+  const changed = writes.filter((write) => write.content !== write.original);
+  if (!options.dryRun) await commitWrites(changed);
+  return {
+    moduleDir,
+    files: featureWrites.map((write) => path.relative(process.cwd(), write.absolute)),
+    registered, dryRun: options.dryRun === true, warnings,
+    changes: changed.map((write) => ({ path: path.relative(process.cwd(), write.absolute), action: write.original === undefined ? "create" : "update" })),
+  };
+}
+
+async function fileInfo(absolute: string) {
+  try {
+    return await lstat(absolute);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") return undefined;
+    throw error;
+  }
+}
+
+/** Relative imports must survive runtime realpath resolution (e.g. /var -> /private/var). */
+async function canonicalDirectory(directory: string): Promise<string> {
+  try {
+    return await realpath(directory);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    const parent = path.dirname(directory);
+    if (parent === directory) throw error;
+    return path.join(await canonicalDirectory(parent), path.basename(directory));
+  }
+}
+
+async function commitWrites(writes: readonly PlannedWrite[]): Promise<void> {
+  const completed: PlannedWrite[] = [];
+  const createdDirectories = new Set<string>();
+  try {
+    for (const write of writes) {
+      const current = await fileInfo(write.absolute);
+      if ((current ? await readFile(write.absolute, "utf8") : undefined) !== write.original) {
+        throw new Error(`File changed after generation was planned: ${write.absolute}`);
+      }
+      await writeAtomically(write.absolute, write.content, createdDirectories);
+      completed.push(write);
+    }
+  } catch (error) {
+    const rollbackErrors: unknown[] = [];
+    for (const write of completed.reverse()) {
+      try {
+        if (write.original === undefined) await rm(write.absolute, { force: true });
+        else await writeAtomically(write.absolute, write.original, createdDirectories);
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError);
+      }
+    }
+    for (const directory of [...createdDirectories].sort((a, b) => b.length - a.length)) {
+      try {
+        await rmdir(directory);
+      } catch (cleanupError) {
+        const code = (cleanupError as NodeJS.ErrnoException).code;
+        // Preserve files another writer may have added to a new directory.
+        if (code !== "ENOTEMPTY" && code !== "ENOENT") rollbackErrors.push(cleanupError);
+      }
+    }
+    if (rollbackErrors.length) throw new AggregateError([error, ...rollbackErrors], "Module generation failed and rollback was incomplete.");
+    throw error;
+  }
+}
+
+async function writeAtomically(absolute: string, content: string, createdDirectories: Set<string>): Promise<void> {
+  const parent = path.dirname(absolute);
+  const firstCreated = await mkdir(parent, { recursive: true });
+  if (firstCreated) {
+    for (let directory = parent; ; directory = path.dirname(directory)) {
+      createdDirectories.add(directory);
+      if (directory === firstCreated) break;
+    }
+  }
+  const temporary = path.join(parent, `.${path.basename(absolute)}.bazis-${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, content, { encoding: "utf8", flag: "wx" });
+    await rename(temporary, absolute);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}