@softure-ai/db 0.0.0-stage → 0.1.6

package/src/configured.ts

@@ -0,0 +1,109 @@
+// The handle a config's database resolves to: the app's own (`database.handle`) when it set one, so one
+// process never holds two handles on one database (with `pglite://`, two PGlite instances on one directory
+// corrupt it), otherwise the process-wide handle for `database.url`. Module adapters, the health route and the
+// package commands all resolve through here.
+import type { SoftureDatabaseConfig } from "@softure-ai/core";
+import { createDatabase, isDatabaseHandle, type CreateDatabaseOptions, type DatabaseHandle } from "./client.js";
+import { getSharedDatabase } from "./shared.js";
+
+declare module "@softure-ai/core" {
+  interface SoftureDatabaseHandleTypes {
+    readonly handle: DatabaseHandle;
+  }
+}
+
+type HandleSource = NonNullable<SoftureDatabaseConfig["handle"]>;
+
+const CONFIGURED_KEY = Symbol.for("@softure-ai/db/configured-handles");
+
+interface ConfiguredHandles {
+  /** Keyed by the app's function: `next dev` re-evaluates the config, and a new function is a new entry. */
+  readonly byFunction: WeakMap<HandleSource, Promise<DatabaseHandle>>;
+  /** The same promises, so `closeConfiguredDatabases` can reach them. */
+  readonly open: Set<Promise<DatabaseHandle>>;
+}
+
+type HandleHost = Record<typeof CONFIGURED_KEY, ConfiguredHandles | undefined>;
+
+const host = globalThis as unknown as HandleHost;
+
+function getConfiguredHandles(): ConfiguredHandles {
+  return (host[CONFIGURED_KEY] ??= { byFunction: new WeakMap(), open: new Set() });
+}
+
+/**
+ * The handle for the config's database: the app's `database.handle`, called once per function and checked, or
+ * else `getSharedDatabase(database.url)`. Never closes anything; for a server's whole life. A failed or invalid
+ * `handle` call is not kept, so the next call tries again.
+ */
+export function getConfiguredDatabase(database: SoftureDatabaseConfig): Promise<DatabaseHandle> {
+  const source = database.handle;
+  if (source === undefined) return getSharedDatabase(database.url);
+
+  const handles = getConfiguredHandles();
+  let handle = handles.byFunction.get(source);
+  if (handle === undefined) {
+    handle = resolveHandle(source);
+    const opened = handle;
+    handles.byFunction.set(source, opened);
+    handles.open.add(opened);
+    opened.catch(() => {
+      handles.byFunction.delete(source);
+      handles.open.delete(opened);
+    });
+  }
+  return handle;
+}
+
+async function resolveHandle(source: HandleSource): Promise<DatabaseHandle> {
+  const value: unknown = await source();
+  if (!isDatabaseHandle(value)) {
+    throw new Error(
+      "database.handle: the function must return a database handle; wrap the app's client with createPostgresHandle(pool) or createPgliteHandle(client) from @softure-ai/db",
+    );
+  }
+  return value;
+}
+
+export interface CommandDatabase {
+  readonly handle: DatabaseHandle;
+  /** Closes what the command opened: its own handle, or the app's configured one (and forgets it). */
+  readonly close: () => Promise<void>;
+}
+
+/**
+ * The database for a command's own process (`softure migrate`, a module CLI, an ops script): the app's
+ * configured handle when `database.handle` is set, so the app's hooks and the command share one instance,
+ * otherwise a new handle on `database.url` with `options`. `close` closes either one; a `pglite://` directory is
+ * written back only then. Not for a running server: closing would close the app's handle under it.
+ */
+export async function openCommandDatabase(database: SoftureDatabaseConfig, options: CreateDatabaseOptions = {}): Promise<CommandDatabase> {
+  const source = database.handle;
+  if (source === undefined) {
+    const handle = await createDatabase(database.url, options);
+    return { handle, close: handle.close };
+  }
+  const opened = getConfiguredDatabase(database);
+  const handle = await opened;
+  return {
+    handle,
+    close: async () => {
+      const handles = getConfiguredHandles();
+      handles.byFunction.delete(source);
+      handles.open.delete(opened);
+      await handle.close();
+    },
+  };
+}
+
+/**
+ * Closes and forgets every configured handle this process resolved. For tests; at shutdown the app closes its own
+ * handle, which it owns (`closeSharedDatabases` leaves configured handles alone for that reason).
+ */
+export async function closeConfiguredDatabases(): Promise<void> {
+  const handles = host[CONFIGURED_KEY];
+  if (handles === undefined) return;
+  host[CONFIGURED_KEY] = undefined;
+  const results = await Promise.allSettled([...handles.open]);
+  await Promise.all(results.flatMap((result) => (result.status === "fulfilled" ? [result.value.close()] : [])));
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+// Public API of @softure-ai/db: the database client and the module migrator
+// (docs/02-module-standard.md §4). Test databases: `@softure-ai/db/testing`; CLI: `@softure-ai/db/cli`.
+export {
+  createDatabase,
+  createPgliteHandle,
+  createPostgresHandle,
+  isDatabaseHandle,
+  type CreateDatabaseOptions,
+  type Database,
+  type DatabaseHandle,
+  type DatabaseSchema,
+  type PgliteClientDatabase,
+  type PostgresDatabase,
+  type Queryable,
+} from "./client.js";
+export { closeSharedDatabases, getSharedDatabase } from "./shared.js";
+export { closeConfiguredDatabases, getConfiguredDatabase, openCommandDatabase, type CommandDatabase } from "./configured.js";
+export { computeChecksum, readMigrationFiles, type MigrationFile } from "./migrations/files.js";
+export {
+  describeProblem,
+  type MigrationErrorCode,
+  type MigrationFailure,
+  type MigrationProblem,
+  type MigrationResult,
+} from "./migrations/problems.js";
+export {
+  migrate,
+  planMigrations,
+  runAppMigrations,
+  type AppMigrationHook,
+  type AppMigrationPhase,
+  type AppMigrations,
+  type MigrateOptions,
+  type MigrationPlan,
+  type MigrationReport,
+  type MigrationStep,
+} from "./migrations/migrator.js";
+export { adoptModule, type AdoptionReport, type AdoptOptions } from "./migrations/adopt.js";
+export { exportMigrations } from "./migrations/export.js";
+export {
+  checkExportedMigrations,
+  type ExportedMigration,
+  type ExportedMigrationsCheck,
+} from "./migrations/exported.js";
+export { readJournal, type JournalRow, type MigrationMethod } from "./migrations/ledger.js";
+export type { MigrationSession } from "./migrations/session.js";

package/src/migrations/adopt.ts

@@ -0,0 +1,136 @@
+// Adoption (docs/02-module-standard.md §4, docs/05-adoption-playbook.md step 3): an existing app
+// has moved its own tables into a module's schema with its own migration. `adoptModule` checks
+// that the schema now equals what the module's files 1..through would create, then records those
+// files as `adopted` without running them; the later files stay pending for `migrate`. Any
+// difference refuses: marking a schema as migrated when it is not is the one mistake a later
+// migration cannot recover from. The pending files of the modules it depends on run first.
+import { ok, type AnySoftureModule } from "@softure-ai/core";
+import type { DatabaseHandle } from "../client.js";
+import { applyFile, recordAdoption, withMigrationLock, type MigrationUnit } from "./apply.js";
+import { describeSchema, diffSchemas } from "./introspect.js";
+import { LEDGER_MODULE_ID, readJournal, type JournalRow } from "./ledger.js";
+import { checkThrough, compareJournal, prepareUnits, toStep, type MigrationStep } from "./migrator.js";
+import { failWith, type MigrationProblem, type MigrationResult } from "./problems.js";
+import { buildReferenceSchema, collectWithDependencies, listOwnedSchemas } from "./reference.js";
+import { withSession, type MigrationSession } from "./session.js";
+import { readAppTables } from "./stubs.js";
+
+export interface AdoptOptions {
+  /** The enabled modules, as for `migrate`. */
+  readonly modules: readonly AnySoftureModule[];
+  /** The id of the module to adopt. */
+  readonly module: string;
+  /** Its version; must equal the enabled module's manifest version. */
+  readonly version: string;
+  /**
+   * The last file to adopt (1..n); default every file. The later files stay pending and the next
+   * `migrate` applies them.
+   */
+  readonly through?: number;
+  /** Compare and report only; write nothing (also no ledger). */
+  readonly dryRun?: boolean;
+  readonly migrationsDir?: URL;
+}
+
+export interface AdoptionReport {
+  readonly module: string;
+  readonly version: string;
+  readonly dryRun: boolean;
+  /** Ledger migrations applied first (or that would be, on a dry run). */
+  readonly ledger: readonly MigrationStep[];
+  /** Pending files of the modules it depends on, applied before the comparison (or that would be). */
+  readonly dependencies: readonly MigrationStep[];
+  /** The module's migrations recorded as adopted (or that would be). */
+  readonly adopted: readonly MigrationStep[];
+}
+
+export async function adoptModule(handle: DatabaseHandle, options: AdoptOptions): Promise<MigrationResult<AdoptionReport>> {
+  const target = options.modules.find((module) => module.id === options.module);
+  if (target === undefined) {
+    return failWith([{ code: "db.adopt_unknown_module", module: options.module }]);
+  }
+  if (target.manifest.version !== options.version) {
+    return failWith([{ code: "db.adopt_version_mismatch", module: target.id, requested: options.version, enabled: target.manifest.version }]);
+  }
+  const units = await prepareUnits(options.modules, options.migrationsDir);
+  if (!units.ok) {
+    return units;
+  }
+  const unit = units.value.find((candidate) => candidate.module === target.id);
+  if (unit === undefined) {
+    return failWith([{ code: "db.adopt_no_schema", module: target.id }]);
+  }
+  const through = options.through ?? unit.files.length;
+  const throughProblems = checkThrough(unit, through);
+  if (throughProblems.length > 0) {
+    return failWith(throughProblems);
+  }
+
+  return withSession(handle, (session) =>
+    withMigrationLock(session, async () => {
+      const journal = await readJournal(session);
+      const comparison = compareJournal(units.value, journal);
+      const problems = [...comparison.problems, ...checkAdoptable(unit, journal)];
+      if (problems.length > 0) {
+        return failWith(problems);
+      }
+      const dependencyIds = collectWithDependencies(options.modules, target.id);
+      dependencyIds.delete(target.id);
+      const ledger = comparison.pending.filter((step) => step.module === LEDGER_MODULE_ID);
+      const dependencies = comparison.pending.filter((step) => dependencyIds.has(step.module));
+      const files = unit.files.filter((file) => file.version <= through);
+      const adopted = files.map((file) => toStep(unit, file));
+      const report = { module: unit.module, version: options.version, dryRun: options.dryRun === true, ledger, dependencies, adopted };
+
+      // Built from the live database's app tables (module SQL may reference them, issue #170), so
+      // inside the lock and only once the checks above passed.
+      const appTables = await readAppTables(session, listOwnedSchemas(units.value));
+      const reference = await buildReferenceSchema({ modules: options.modules, units: units.value, target: unit, through, appTables });
+      if (!reference.ok) {
+        return reference;
+      }
+      // The target's own schema only, compared before anything is written: applying a dependency
+      // never changes it.
+      const differences = diffSchemas(reference.value, await describeSchema(session, unit.schema));
+      if (differences.length > 0) {
+        return failWith([{ code: "db.schema_mismatch", module: unit.module, schema: unit.schema, differences }]);
+      }
+      if (options.dryRun === true) {
+        return ok(report);
+      }
+      const ledgerFailure = await applyPending(session, units.value, ledger);
+      if (ledgerFailure !== null) {
+        return failWith([ledgerFailure.problem]);
+      }
+      const dependencyFailure = await applyPending(session, units.value, dependencies);
+      if (dependencyFailure !== null) {
+        return failWith([dependencyFailure.problem, { code: "db.adopt_dependency_pending", module: unit.module, dependency: dependencyFailure.step.module }]);
+      }
+      const failure = await recordAdoption(session, unit, files);
+      return failure === null ? ok(report) : failWith([failure]);
+    }),
+  );
+}
+
+/** The adopted module must be new to the ledger. */
+function checkAdoptable(unit: MigrationUnit, journal: readonly JournalRow[]): MigrationProblem[] {
+  return journal.some((row) => row.module === unit.module) ? [{ code: "db.adopt_already_applied", module: unit.module }] : [];
+}
+
+/** Applies the steps in order, each file in its own transaction; stops at the first failure. */
+async function applyPending(
+  session: MigrationSession,
+  units: readonly MigrationUnit[],
+  steps: readonly MigrationStep[],
+): Promise<{ problem: MigrationProblem; step: MigrationStep } | null> {
+  for (const step of steps) {
+    const unit = units.find((candidate) => candidate.module === step.module);
+    const file = unit?.files.find((candidate) => candidate.version === step.version);
+    if (unit === undefined || file === undefined) {
+      throw new Error(`adoptModule: step ${step.module} ${step.version} has no file; compareJournal is broken`);
+    }
+    const failure = await applyFile(session, { unit, file, method: "applied" });
+    if (failure !== null) return { problem: failure, step };
+  }
+  return null;
+}

package/src/migrations/apply.ts

@@ -0,0 +1,135 @@
+// The primitives every migration path shares (migrate, adoption, the reference schema): one file in
+// one transaction with its ledger row, adoption rows in one transaction, the advisory lock.
+import type { MigrationFile } from "./files.js";
+import { recordMigration, type MigrationMethod } from "./ledger.js";
+import type { MigrationProblem } from "./problems.js";
+import type { MigrationSession } from "./session.js";
+
+/** One migration owner: the ledger itself or an enabled module with a schema. */
+export interface MigrationUnit {
+  readonly module: string;
+  readonly schema: string;
+  readonly moduleVersion: string;
+  readonly files: readonly MigrationFile[];
+}
+
+// Any constant works; it only has to be the same for every runner of every app.
+const MIGRATION_LOCK_KEY = "73012026";
+
+/**
+ * Runs one file and its ledger row in one transaction, inside the unit's schema. Returns the
+ * problem when the SQL fails; the transaction is rolled back first.
+ */
+export async function applyFile(
+  session: MigrationSession,
+  input: { unit: MigrationUnit; file: MigrationFile; method: MigrationMethod },
+): Promise<MigrationProblem | null> {
+  const { unit, file, method } = input;
+  // The schema passed the manifest's lower_snake_case rule and checkModule; quoting is a second line.
+  const schema = quoteIdentifier(unit.schema);
+  try {
+    await session.exec(`BEGIN; CREATE SCHEMA IF NOT EXISTS ${schema}; SET LOCAL search_path TO ${schema}, public;`);
+    const transactionId = await readTransactionId(session);
+    if (method === "applied") {
+      await session.exec(file.sql);
+    }
+    // Second line behind findTransactionControl: a file that still ended the transaction left
+    // part of itself committed, so it must not be reported as cleanly rolled back.
+    if ((await readTransactionId(session)) !== transactionId) {
+      throw new TransactionEndedError();
+    }
+    await recordMigration(session, {
+      module: unit.module,
+      version: file.version,
+      name: file.name,
+      checksum: file.checksum,
+      moduleVersion: unit.moduleVersion,
+      method,
+    });
+    await session.exec("COMMIT");
+    return null;
+  } catch (error) {
+    const reason = await rollBack(session, error);
+    return { code: "db.migration_failed", module: unit.module, version: file.version, name: file.name, reason };
+  }
+}
+
+class TransactionEndedError extends Error {
+  constructor() {
+    super("the file ended the migrator's transaction, so the statements before that point may be committed; check the schema by hand");
+  }
+}
+
+// The transaction id, not now(): two transactions can share a start time (PGlite's clock ticks in
+// milliseconds), but never an id.
+async function readTransactionId(session: MigrationSession): Promise<string> {
+  const [row] = await session.query<{ id: string }>("SELECT pg_current_xact_id()::text AS id");
+  return row?.id ?? "";
+}
+
+/**
+ * Rolls the open transaction back and returns the reason to report. A failing ROLLBACK (a lost
+ * connection) is added to the reason instead of hiding the original error.
+ */
+export async function rollBack(session: MigrationSession, error: unknown): Promise<string> {
+  const reason = describeError(error);
+  try {
+    await session.exec("ROLLBACK");
+    return reason;
+  } catch (rollbackError) {
+    return `${reason} (and ROLLBACK failed: ${describeError(rollbackError)})`;
+  }
+}
+
+/** Holds the session-level advisory lock while `run` runs; a second runner waits for it. */
+export async function withMigrationLock<T>(session: MigrationSession, run: () => Promise<T>): Promise<T> {
+  await session.query("SELECT pg_advisory_lock($1)", [MIGRATION_LOCK_KEY]);
+  let result: T;
+  try {
+    result = await run();
+  } catch (error) {
+    // The run's own error wins; an unlock failure here is secondary (the session is discarded).
+    await session.query("SELECT pg_advisory_unlock($1)", [MIGRATION_LOCK_KEY]).catch((unlockError: unknown) => {
+      throw new Error(`migration run failed (${describeError(error)}) and releasing the lock failed: ${describeError(unlockError)}`, {
+        cause: error,
+      });
+    });
+    throw error;
+  }
+  await session.query("SELECT pg_advisory_unlock($1)", [MIGRATION_LOCK_KEY]);
+  return result;
+}
+
+/**
+ * Records `files` of the unit as adopted, all in one transaction: either every row is written or
+ * none. Returns the problem when a write fails.
+ */
+export async function recordAdoption(session: MigrationSession, unit: MigrationUnit, files: readonly MigrationFile[]): Promise<MigrationProblem | null> {
+  try {
+    await session.exec("BEGIN");
+    for (const file of files) {
+      await recordMigration(session, {
+        module: unit.module,
+        version: file.version,
+        name: file.name,
+        checksum: file.checksum,
+        moduleVersion: unit.moduleVersion,
+        method: "adopted",
+      });
+    }
+    await session.exec("COMMIT");
+    return null;
+  } catch (error) {
+    const reason = await rollBack(session, error);
+    const first = files[0];
+    return { code: "db.migration_failed", module: unit.module, version: first?.version ?? 0, name: first?.name ?? "", reason };
+  }
+}
+
+export function quoteIdentifier(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
+export function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/migrations/export.ts

@@ -0,0 +1,66 @@
+// The container path: a bundled runner cannot find package folders (`import.meta.url` points at
+// the bundle), so the build stage copies every enabled module's files to `<dir>/<module id>/` and
+// the bundled runner reads them with `migrationsDir`. The ledger migration ships as code.
+import type { Dirent } from "node:fs";
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ok, type AnySoftureModule } from "@softure-ai/core";
+import { LEDGER_MODULE_ID } from "./ledger.js";
+import { prepareUnits, type MigrationStep } from "./migrator.js";
+import { failWith, type MigrationProblem, type MigrationResult } from "./problems.js";
+
+/**
+ * Copies each module's migration files to `<targetDir>/<module id>/`, replacing older `.sql`
+ * copies. A module folder holding anything but `.sql` files is refused, never emptied: it is
+ * not an earlier export (e.g. `softure migrate --export-migrations .` in an app with an `auth/`).
+ */
+export async function exportMigrations(
+  modules: readonly AnySoftureModule[],
+  targetDir: string,
+): Promise<MigrationResult<MigrationStep[]>> {
+  const units = await prepareUnits(modules, undefined);
+  if (!units.ok) {
+    return units;
+  }
+  const moduleUnits = units.value.filter((candidate) => candidate.module !== LEDGER_MODULE_ID);
+  const problems: MigrationProblem[] = [];
+  for (const unit of moduleUnits) {
+    const foreign = (await listEntries(join(targetDir, unit.module))).filter((entry) => !entry.isFile() || !entry.name.endsWith(".sql"));
+    if (foreign.length > 0) {
+      problems.push({
+        code: "db.export_target_not_empty",
+        module: unit.module,
+        dir: join(targetDir, unit.module),
+        entries: foreign.map((entry) => entry.name).sort(),
+      });
+    }
+  }
+  if (problems.length > 0) {
+    return failWith(problems);
+  }
+
+  const exported: MigrationStep[] = [];
+  for (const unit of moduleUnits) {
+    const moduleDir = join(targetDir, unit.module);
+    for (const entry of await listEntries(moduleDir)) {
+      await rm(join(moduleDir, entry.name));
+    }
+    await mkdir(moduleDir, { recursive: true });
+    for (const file of unit.files) {
+      await writeFile(join(moduleDir, file.fileName), file.sql, "utf8");
+      exported.push({ module: unit.module, schema: unit.schema, version: file.version, name: file.name, checksum: file.checksum });
+    }
+  }
+  return ok(exported);
+}
+
+async function listEntries(dir: string): Promise<Dirent[]> {
+  try {
+    return await readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}

package/src/migrations/exported.ts

@@ -0,0 +1,82 @@
+// The deploy-time check of an exported migrations folder (the new image's, written by
+// `softure migrate --export-migrations`) against a database's ledger, without the app config. It runs
+// the migrator's own comparison, so a deploy never accepts what `softure migrate` would refuse.
+import type { Dirent } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { ok } from "@softure-ai/core";
+import { readMigrationFiles } from "./files.js";
+import { LEDGER_FILES, LEDGER_MODULE_ID, LEDGER_SCHEMA, LEDGER_VERSION, type JournalRow } from "./ledger.js";
+import { compareJournal, type MigrationUnit } from "./migrator.js";
+import { failWith, type MigrationProblem, type MigrationResult } from "./problems.js";
+
+export interface ExportedMigration {
+  readonly module: string;
+  readonly version: number;
+  readonly name: string;
+  readonly checksum: string;
+}
+
+export interface ExportedMigrationsCheck {
+  /** Files the database has not applied yet, per module in folder order; `softure migrate` applies them. */
+  readonly pending: readonly ExportedMigration[];
+  /** Modules the ledger knows but the folder does not hold: not enabled in the image, so the migrator ignores them. */
+  readonly absent: readonly string[];
+}
+
+/**
+ * Compares `<migrationsDir>/<module id>/*.sql` and the built-in ledger migration with the journal. Fails with every
+ * problem: an applied file edited or missing, a pending file numbered below an applied one, an invalid folder.
+ */
+export async function checkExportedMigrations(
+  migrationsDir: URL,
+  journal: readonly JournalRow[],
+): Promise<MigrationResult<ExportedMigrationsCheck>> {
+  const folders = await listModuleFolders(migrationsDir);
+  if (!folders.ok) {
+    return folders;
+  }
+  const problems: MigrationProblem[] = [];
+  const units: MigrationUnit[] = [
+    { module: LEDGER_MODULE_ID, schema: LEDGER_SCHEMA, moduleVersion: LEDGER_VERSION, files: LEDGER_FILES },
+  ];
+  for (const module of folders.value) {
+    if (module === LEDGER_MODULE_ID) {
+      problems.push({ code: "db.reserved_module", module });
+      continue;
+    }
+    const files = await readMigrationFiles(module, new URL(`${encodeURIComponent(module)}/`, ensureFolderUrl(migrationsDir)));
+    if (files.ok) {
+      // The schema is not part of the export; the comparison does not read it.
+      units.push({ module, schema: "", moduleVersion: "", files: files.value });
+    } else {
+      problems.push(...files.problems);
+    }
+  }
+  const comparison = compareJournal(units, journal);
+  problems.push(...comparison.problems);
+  if (problems.length > 0) {
+    return failWith(problems);
+  }
+  const known = new Set(units.map((unit) => unit.module));
+  const absent = [...new Set(journal.map((row) => row.module))].filter((module) => !known.has(module)).sort();
+  const pending = comparison.pending.map(({ module, version, name, checksum }) => ({ module, version, name, checksum }));
+  return ok({ pending, absent });
+}
+
+/** The module folders, sorted; files beside them (a README) are ignored. */
+async function listModuleFolders(dir: URL): Promise<MigrationResult<string[]>> {
+  let entries: Dirent[];
+  try {
+    entries = await readdir(fileURLToPath(dir), { withFileTypes: true });
+  } catch (error) {
+    const code = error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : "unknown error";
+    const reason = code === "ENOENT" ? "the folder does not exist" : code;
+    return failWith([{ code: "db.migrations_unreadable", module: "(export)", dir: fileURLToPath(dir), reason }]);
+  }
+  return ok(entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort());
+}
+
+function ensureFolderUrl(url: URL): URL {
+  return url.href.endsWith("/") ? url : new URL(`${url.href}/`);
+}