@podosoft/podokit 1.4.2 → 1.6.0

package/dist/update.d.ts

@@ -1,5 +1,5 @@
-import { type TemplateVars } from "@podosoft/podokit-template-engine";
-import { type Tier } from "./lockfile";
+import { type TemplateVars, type VfsTree } from "@podosoft/podokit-template-engine";
+import { type Tier, type FilesLock, type ManifestModule, type PodokitManifest } from "./lockfile";
 import type { ProviderCapability } from "@podosoft/podokit-runtime";
 import type { Toolchain } from "./toolchain";
 import { type ApiPathResult } from "./module-api-paths";
@@ -9,7 +9,7 @@ import { type ApiPathResult } from "./module-api-paths";
  * working copy, classifying each file. Applying the plan (writing files, 3-way
  * merging) is a later step (see ADR-0009).
  */
-export type Action = "update" | "merge" | "conflict" | "add" | "move" | "remove" | "skip" | "up-to-date";
+export type Action = "review" | "update" | "merge" | "conflict" | "add" | "move" | "remove" | "skip" | "up-to-date";
 export interface FileChange {
     path: string;
     /** Previous path when this change is an update migration move. */
@@ -36,10 +36,38 @@ export interface UpdatePlan {
     modules: string[];
     /** Modules the update adds, ordered ahead of the modules that need them. */
     addedModules: AddedModule[];
+    /**
+     * External modules whose installed package is older than the version the
+     * project last applied. Applying would write the older module's files, so
+     * `applyUpdate` refuses while this is not empty.
+     */
+    moduleDowngrades: ModuleDowngrade[];
     changes: FileChange[];
     /** Direct API paths that modules newly declare, per configuration file. */
     apiPaths: ApiPathResult;
+    /**
+     * Owned files that differ from this version's template while the lock has no
+     * record of the template they came from, so PodoKit cannot tell whether the
+     * template changed. Applying the update records it for the next one.
+     */
+    ownedWithoutTemplate: string[];
 }
+/** An external module installed at an older version than the project last applied. */
+export interface ModuleDowngrade {
+    name: string;
+    packageName: string;
+    /** Version recorded in the manifest. */
+    recorded: string;
+    /** Version installed in node_modules. */
+    installed: string;
+}
+/** Semantic version order of two exact versions: negative when `a` is older. */
+export declare function compareVersions(a: string, b: string): number;
+/** Owned paths the template and the installed modules declare, without the app's own. */
+export declare function declaredOwnedGlobs(projectRoot: string, templatesDir: string, modules: {
+    name: string;
+    packageName?: string;
+}[]): string[];
 /**
  * Build the update plan. `templatesDir` is the installed CLI's template set (the
  * new version); the lock records what PodoKit last wrote (to detect user edits).
@@ -52,6 +80,20 @@ export interface PlanOptions {
     /** Restrict planning to selected paths, used by focused conversions. */
     onlyPaths?: string[];
 }
+/** The project as the installed CLI's templates would generate it. */
+export interface TargetProject {
+    manifest: PodokitManifest;
+    lock: FilesLock;
+    /** Recorded modules plus any the target version requires, in configure order. */
+    modules: ManifestModule[];
+    addedModules: AddedModule[];
+    /** External modules installed at an older version than the project applied. */
+    moduleDowngrades: ModuleDowngrade[];
+    tree: VfsTree;
+    ownedGlobs: string[];
+    managedOverrides: string[];
+}
+export declare function targetProject(projectRoot: string, templatesDir: string, targetAnswers?: TemplateVars): TargetProject;
 export declare function planUpdate(projectRoot: string, templatesDir: string, options?: PlanOptions): UpdatePlan;
 export interface ApplyOptions {
     /** Templates for the version the project is currently on, for 3-way merges. */
@@ -80,9 +122,23 @@ export interface ApplyResult {
     merged: string[];
     /** Files written with conflict markers for manual resolution. */
     conflicts: string[];
+    /** Owned files whose template changed; they are left as they are. */
+    review: string[];
     /** Direct API paths added to `.podokit/dev.json` and deployment profiles. */
     apiPaths: ApiPathResult;
 }
+export interface UpstreamChange {
+    path: string;
+    /** Unified diff from the previous template to the new one; empty when the
+     *  previous templates did not generate the file. */
+    diff: string;
+}
+/**
+ * What the template changed between the project's version and this one for
+ * each owned file the plan marks for review, given the previous version's
+ * templates.
+ */
+export declare function upstreamChanges(projectRoot: string, templatesDir: string, plan: UpdatePlan, oldTemplatesDir: string, oldExternalModulesRoot?: string): UpstreamChange[];
 /**
  * Apply an update to the working copy. Clean updates and additions are written,
  * upstream removals deleted, and user-edited files 3-way merged against the old
@@ -91,6 +147,8 @@ export interface ApplyResult {
  * stamps the new version.
  */
 export declare function applyUpdate(projectRoot: string, templatesDir: string, options?: ApplyOptions): ApplyResult;
+/** One line per external module installed at an older version than recorded. */
+export declare function describeDowngrades(downgrades: ModuleDowngrade[]): string;
 /** Why an update adds a module, for the plan report. */
 export declare function addedModuleReason(module: AddedModule): string;
 /** Count actions for a one-line summary. */

package/dist/update.js

@@ -1,7 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareVersions = compareVersions;
+exports.declaredOwnedGlobs = declaredOwnedGlobs;
+exports.targetProject = targetProject;
 exports.planUpdate = planUpdate;
+exports.upstreamChanges = upstreamChanges;
 exports.applyUpdate = applyUpdate;
+exports.describeDowngrades = describeDowngrades;
 exports.addedModuleReason = addedModuleReason;
 exports.summarize = summarize;
 const node_child_process_1 = require("node:child_process");
@@ -10,6 +15,7 @@ const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
 const assemble_1 = require("./assemble");
+const text_diff_1 = require("./text-diff");
 const lockfile_1 = require("./lockfile");
 const inspect_1 = require("./inspect");
 const add_1 = require("./add");
@@ -25,6 +31,31 @@ function diskContent(projectRoot, path) {
     const abs = (0, node_path_1.join)(projectRoot, path);
     return (0, node_fs_1.existsSync)(abs) ? (0, node_fs_1.readFileSync)(abs) : null;
 }
+function versionParts(version) {
+    const [withoutBuild = ""] = version.split("+");
+    const dash = withoutBuild.indexOf("-");
+    const core = (dash === -1 ? withoutBuild : withoutBuild.slice(0, dash))
+        .split(".")
+        .map((part) => Number.parseInt(part, 10) || 0);
+    return { core, prerelease: dash === -1 ? null : withoutBuild.slice(dash + 1) };
+}
+/** Semantic version order of two exact versions: negative when `a` is older. */
+function compareVersions(a, b) {
+    const left = versionParts(a);
+    const right = versionParts(b);
+    for (let index = 0; index < Math.max(left.core.length, right.core.length); index += 1) {
+        const difference = (left.core[index] ?? 0) - (right.core[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    if (left.prerelease === right.prerelease)
+        return 0;
+    if (left.prerelease === null)
+        return 1;
+    if (right.prerelease === null)
+        return -1;
+    return left.prerelease.localeCompare(right.prerelease, "en", { numeric: true });
+}
 /**
  * Expand the recorded module list against the target manifests. A module may
  * gain a new requirement after it was first added to a project, either another
@@ -39,6 +70,7 @@ function targetModules(projectRoot, templatesDir, modules, providers) {
     const recorded = new Map(modules.map((module) => [module.name, module]));
     const ordered = [];
     const added = [];
+    const downgrades = [];
     const visiting = new Set();
     const visited = new Set();
     const visit = (name, requiredBy, capability) => {
@@ -54,6 +86,17 @@ function targetModules(projectRoot, templatesDir, modules, providers) {
                 ? `Module "${requiredBy}" requires unknown module "${name}".`
                 : `Cannot resolve module "${name}" while updating the project.`);
         }
+        if (existing?.moduleVersion &&
+            resolved.packageName &&
+            resolved.moduleVersion &&
+            compareVersions(resolved.moduleVersion, existing.moduleVersion) < 0) {
+            downgrades.push({
+                name: resolved.name,
+                packageName: resolved.packageName,
+                recorded: existing.moduleVersion,
+                installed: resolved.moduleVersion,
+            });
+        }
         visiting.add(name);
         const moduleManifest = (0, add_1.readModuleManifest)(resolved.dir);
         for (const required of moduleManifest.requires ?? [])
@@ -89,7 +132,7 @@ function targetModules(projectRoot, templatesDir, modules, providers) {
     for (const module of [...modules].sort((a, b) => a.order - b.order)) {
         visit(module.name);
     }
-    return { modules: ordered, added };
+    return { modules: ordered, added, downgrades };
 }
 function targetApiPaths(projectRoot, templatesDir, modules) {
     const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
@@ -104,7 +147,7 @@ function targetApiPaths(projectRoot, templatesDir, modules) {
     return { declared, pending };
 }
 function targetManagedOverrides(projectRoot, templatesDir, modules, current = []) {
-    const overrides = new Set(current);
+    const overrides = new Set([...lockfile_1.DEFAULT_MANAGED_OVERRIDES, ...current]);
     const modulesDir = (0, node_path_1.join)(templatesDir, "modules");
     for (const module of modules) {
         const resolved = (0, add_1.resolveModule)(module.packageName ?? module.name, modulesDir, projectRoot);
@@ -127,21 +170,36 @@ function targetOwnedGlobs(projectRoot, templatesDir, modules, current) {
     }
     return [...owned];
 }
-function planUpdate(projectRoot, templatesDir, options = {}) {
+/** Owned paths the template and the installed modules declare, without the app's own. */
+function declaredOwnedGlobs(projectRoot, templatesDir, modules) {
+    return targetOwnedGlobs(projectRoot, templatesDir, modules, []);
+}
+function targetProject(projectRoot, templatesDir, targetAnswers) {
     const manifest = (0, lockfile_1.readManifest)(projectRoot);
     const lock = (0, lockfile_1.readFilesLock)(projectRoot);
     if (!manifest || !lock)
         throw new inspect_1.NotAProjectError();
-    const { modules, added } = targetModules(projectRoot, templatesDir, manifest.modules, manifest.providers);
-    const newTree = (0, assemble_1.assembleProject)({
+    const { modules, added, downgrades } = targetModules(projectRoot, templatesDir, manifest.modules, manifest.providers);
+    const tree = (0, assemble_1.assembleProject)({
         templatesDir,
         template: manifest.template,
-        answers: options.targetAnswers ?? (0, lockfile_1.manifestTemplateVars)(manifest),
+        answers: targetAnswers ?? (0, lockfile_1.manifestTemplateVars)(manifest),
         modules,
         projectRoot,
     });
-    const managedOverrides = targetManagedOverrides(projectRoot, templatesDir, modules, manifest.managedOverrides);
-    const ownedGlobs = targetOwnedGlobs(projectRoot, templatesDir, modules, manifest.ownedGlobs);
+    return {
+        manifest,
+        lock,
+        modules,
+        addedModules: added,
+        moduleDowngrades: downgrades,
+        tree,
+        ownedGlobs: targetOwnedGlobs(projectRoot, templatesDir, modules, manifest.ownedGlobs),
+        managedOverrides: targetManagedOverrides(projectRoot, templatesDir, modules, manifest.managedOverrides),
+    };
+}
+function planUpdate(projectRoot, templatesDir, options = {}) {
+    const { manifest, lock, modules, addedModules: added, moduleDowngrades, tree: newTree, ownedGlobs, managedOverrides, } = targetProject(projectRoot, templatesDir, options.targetAnswers);
     const pendingMigrations = (0, module_migrations_1.collectPendingMigrations)(projectRoot, templatesDir, modules);
     const migrationPlan = (0, module_migrations_1.planModuleMigrations)(projectRoot, newTree, lock, pendingMigrations);
     const changes = migrationPlan.moves.map((move) => ({
@@ -159,6 +217,7 @@ function planUpdate(projectRoot, templatesDir, options = {}) {
             note: conflict,
         });
     }
+    const ownedWithoutTemplate = [];
     const movedSources = new Set(migrationPlan.moves.map((move) => move.from));
     const movedTargets = new Set(migrationPlan.moves.map((move) => move.to));
     const paths = new Set([...newTree.keys(), ...Object.keys(lock.files)]);
@@ -192,6 +251,24 @@ function planUpdate(projectRoot, templatesDir, options = {}) {
                 changes.push({ path, tier, action: "add", note: "new owned seed in this version" });
                 continue;
             }
+            if (newText !== null && disk !== null) {
+                const newHash = (0, podokit_template_engine_1.hashContent)(newText);
+                const recorded = (0, lockfile_1.recordedTemplateHash)(locked);
+                if ((0, podokit_template_engine_1.hashContent)(disk) !== newHash) {
+                    if (recorded && recorded !== newHash) {
+                        changes.push({
+                            path,
+                            tier,
+                            action: "review",
+                            note: `owned; the template changed, see podo diff ${path}`,
+                        });
+                        continue;
+                    }
+                    // The lock never records files under .podokit/, so only judge tracked files.
+                    if (!recorded && locked)
+                        ownedWithoutTemplate.push(path);
+                }
+            }
             const explicitlyOwned = ownedGlobs.some((glob) => !glob.includes("*") && (0, lockfile_1.matchGlob)(path, glob));
             changes.push({
                 path,
@@ -251,8 +328,10 @@ function planUpdate(projectRoot, templatesDir, options = {}) {
         template: manifest.template,
         modules: modules.map((module) => module.name),
         addedModules: added,
+        moduleDowngrades,
         changes,
         apiPaths,
+        ownedWithoutTemplate,
     };
 }
 function assertRecordedExternalModules(moduleRoot, templatesDir, modules) {
@@ -297,6 +376,48 @@ function previousExternalModules(projectRoot, templatesDir, modules, providedRoo
     }
     return { root, cleanup: true };
 }
+/** The project as the templates of the version it is on generated it. */
+function previousTree(projectRoot, manifest, oldTemplatesDir, oldExternalModulesRoot) {
+    const previousModules = previousExternalModules(projectRoot, oldTemplatesDir, manifest.modules, oldExternalModulesRoot);
+    try {
+        return (0, assemble_1.assembleProject)({
+            templatesDir: oldTemplatesDir,
+            template: manifest.template,
+            answers: (0, lockfile_1.manifestTemplateVars)(manifest),
+            modules: manifest.modules,
+            projectRoot: previousModules.root,
+        });
+    }
+    finally {
+        if (previousModules.cleanup)
+            (0, node_fs_1.rmSync)(previousModules.root, { recursive: true, force: true });
+    }
+}
+/**
+ * What the template changed between the project's version and this one for
+ * each owned file the plan marks for review, given the previous version's
+ * templates.
+ */
+function upstreamChanges(projectRoot, templatesDir, plan, oldTemplatesDir, oldExternalModulesRoot) {
+    const review = plan.changes.filter((change) => change.action === "review");
+    if (!review.length)
+        return [];
+    const target = targetProject(projectRoot, templatesDir);
+    const oldTree = previousTree(projectRoot, target.manifest, oldTemplatesDir, oldExternalModulesRoot);
+    return review.map((change) => {
+        const before = treeText(oldTree, change.path);
+        const after = treeText(target.tree, change.path) ?? "";
+        return {
+            path: change.path,
+            diff: before === null
+                ? ""
+                : (0, text_diff_1.unifiedDiff)(before, after, {
+                    fromLabel: `podokit-${plan.fromVersion}/${change.path}`,
+                    toLabel: `podokit-${plan.toVersion}/${change.path}`,
+                }),
+        };
+    });
+}
 function writeFile(projectRoot, path, content) {
     const abs = (0, node_path_1.join)(projectRoot, path);
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(abs), { recursive: true });
@@ -328,6 +449,8 @@ function updatedFilesLock(projectRoot, newTree, previous, ownedGlobs, managedOve
                 }
                 entry.outHash = (0, podokit_template_engine_1.hashContent)(newText);
             }
+            if (entry.tier === "owned")
+                entry.templateHash = (0, podokit_template_engine_1.hashContent)(newText);
             continue;
         }
         if (entry.tier === "owned")
@@ -344,16 +467,19 @@ function updatedFilesLock(projectRoot, newTree, previous, ownedGlobs, managedOve
             delete next.files[path];
         }
     }
-    // Keep a tombstone for an owned seed that the application deleted or moved.
-    // Without the previous entry, the next update would mistake the missing path
-    // for a newly introduced seed and recreate it.
+    // Keep a tombstone for an owned seed that the application deleted or moved,
+    // including a file this update turns from managed into owned. Without the
+    // entry, the next update would mistake the missing path for a newly
+    // introduced seed and recreate it.
     for (const [path, entry] of Object.entries(previous.files)) {
-        if (entry.tier !== "owned" || next.files[path])
+        if (next.files[path])
             continue;
         const newText = treeText(newTree, path);
         if (newText !== null &&
             (0, lockfile_1.classifyTier)(path, newText, ownedGlobs, managedOverrides) === "owned") {
-            next.files[path] = entry;
+            next.files[path] = entry.tier === "owned"
+                ? entry
+                : { tier: "owned", outHash: entry.outHash, templateHash: (0, podokit_template_engine_1.hashContent)(newText) };
         }
     }
     return next;
@@ -375,6 +501,10 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
         forceManagedPaths: options.forceManagedPaths,
         onlyPaths: options.onlyPaths,
     });
+    if (plan.moduleDowngrades.length) {
+        throw new Error(`Refusing to downgrade external modules:\n${describeDowngrades(plan.moduleDowngrades)}\n` +
+            "Install at least the recorded version (for example bun install), then run podo update again.");
+    }
     const { modules } = targetModules(projectRoot, templatesDir, manifest.modules, manifest.providers);
     const newTree = (0, assemble_1.assembleProject)({
         templatesDir,
@@ -401,20 +531,7 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
     const needsMergeBase = plan.changes.some((change) => change.action === "conflict");
     let oldTree = null;
     if (options.oldTemplatesDir && needsMergeBase) {
-        const previousModules = previousExternalModules(projectRoot, options.oldTemplatesDir, manifest.modules, options.oldExternalModulesRoot);
-        try {
-            oldTree = (0, assemble_1.assembleProject)({
-                templatesDir: options.oldTemplatesDir,
-                template: manifest.template,
-                answers: (0, lockfile_1.manifestTemplateVars)(manifest),
-                modules: manifest.modules,
-                projectRoot: previousModules.root,
-            });
-        }
-        finally {
-            if (previousModules.cleanup)
-                (0, node_fs_1.rmSync)(previousModules.root, { recursive: true, force: true });
-        }
+        oldTree = previousTree(projectRoot, manifest, options.oldTemplatesDir, options.oldExternalModulesRoot);
     }
     if (options.abortOnConflict) {
         const unresolved = [];
@@ -444,6 +561,7 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
         removed: [],
         merged: [],
         conflicts: [],
+        review: plan.changes.filter((change) => change.action === "review").map((change) => change.path),
         apiPaths: { changed: [], skipped: [] },
     };
     for (const change of plan.changes) {
@@ -523,6 +641,12 @@ function applyUpdate(projectRoot, templatesDir, options = {}) {
     });
     return result;
 }
+/** One line per external module installed at an older version than recorded. */
+function describeDowngrades(downgrades) {
+    return downgrades
+        .map((entry) => `  ${entry.packageName} ${entry.installed} is installed; the project applied ${entry.recorded}`)
+        .join("\n");
+}
 /** Why an update adds a module, for the plan report. */
 function addedModuleReason(module) {
     return module.capability
@@ -532,6 +656,7 @@ function addedModuleReason(module) {
 /** Count actions for a one-line summary. */
 function summarize(plan) {
     const counts = {
+        review: 0,
         update: 0,
         merge: 0,
         conflict: 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podosoft/podokit",
-  "version": "1.4.2",
+  "version": "1.6.0",
   "description": "An opinionated Bun and Elysia full-stack TypeScript starter toolkit and CLI with SvelteKit, TailwindCSS, shadcn-svelte, Docker, and k3s.",
   "license": "Apache-2.0",
   "repository": {
@@ -45,7 +45,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@podosoft/podokit-runtime": "^0.4.0",
+    "@podosoft/podokit-runtime": "^0.5.0",
     "@podosoft/podokit-template-engine": "^0.4.2"
   }
 }

package/dist/templates/modules/admin-dashboard/files/tests/api/exclusive.api.spec.ts

@@ -1,75 +0,0 @@
-import { expect, test } from "@playwright/test";
-import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, utimesSync, writeFileSync } from "node:fs";
-import { rm } from "node:fs/promises";
-import { join } from "node:path";
-import { exclusive, lockPath } from "../helpers/exclusive";
-
-// Checks the lock that specs changing shared settings hold. Names are unique per
-// run so these never wait on, or release, a lock a real spec holds.
-const unique = (label: string): string => `self-test-${label}-${process.pid}-${Date.now()}`;
-
-test("exclusive releases its locks when the body fails", async () => {
-  const first = unique("first");
-  const second = unique("second");
-  await expect(
-    exclusive([second, first], async () => {
-      expect(existsSync(lockPath(first))).toBe(true);
-      expect(existsSync(lockPath(second))).toBe(true);
-      throw new Error("body failed");
-    }),
-  ).rejects.toThrow("body failed");
-  expect(existsSync(lockPath(first))).toBe(false);
-  expect(existsSync(lockPath(second))).toBe(false);
-
-  // The next holder gets the lock without waiting.
-  const started = Date.now();
-  await exclusive(first, async () => undefined);
-  expect(Date.now() - started).toBeLessThan(1_000);
-});
-
-test("exclusive runs holders of one lock one at a time", async () => {
-  const name = unique("serial");
-  const events: string[] = [];
-  const hold = (id: string): Promise<void> =>
-    exclusive(name, async () => {
-      events.push(`${id} start`);
-      await new Promise((resolve) => setTimeout(resolve, 100));
-      events.push(`${id} end`);
-    });
-  await Promise.all([hold("a"), hold("b")]);
-  expect(events.map((event) => event.split(" ")[1])).toEqual(["start", "end", "start", "end"]);
-  expect(existsSync(lockPath(name))).toBe(false);
-});
-
-test("exclusive takes over a lock left by a run that was killed", async () => {
-  const name = unique("stale");
-  mkdirSync(lockPath(name));
-  const longAgo = new Date(Date.now() - 10 * 60_000);
-  utimesSync(lockPath(name), longAgo, longAgo);
-  await expect(exclusive(name, async () => "acquired")).resolves.toBe("acquired");
-  expect(existsSync(lockPath(name))).toBe(false);
-});
-
-test("exclusive takes over a lock whose holder exited, such as after Ctrl-C", async () => {
-  const name = unique("exited");
-  const exited = spawnSync(process.execPath, ["-e", ""]).pid;
-  mkdirSync(lockPath(name));
-  writeFileSync(join(lockPath(name), "owner"), String(exited));
-  const started = Date.now();
-  await expect(exclusive(name, async () => "acquired")).resolves.toBe("acquired");
-  expect(Date.now() - started).toBeLessThan(1_000);
-  expect(existsSync(lockPath(name))).toBe(false);
-});
-
-test("exclusive waits for a lock whose holder is still running", async () => {
-  const name = unique("alive");
-  mkdirSync(lockPath(name));
-  writeFileSync(join(lockPath(name), "owner"), String(process.pid));
-  const waiting = exclusive(name, async () => "acquired");
-  await new Promise((resolve) => setTimeout(resolve, 500));
-  expect(existsSync(lockPath(name))).toBe(true);
-  // The holder finishes; the waiter then gets the lock.
-  await rm(lockPath(name), { recursive: true, force: true });
-  await expect(waiting).resolves.toBe("acquired");
-});

package/dist/templates/modules/admin-dashboard/files/tests/helpers/exclusive.ts

@@ -1,80 +0,0 @@
-import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-// Locks for server-wide settings that specs in more than one file change. The
-// suite runs on one worker by default; with --workers above 1, specs of the api
-// and ui projects run at the same time, and two that flip the same setting
-// would undo each other mid-test:
-//
-// - `require2fa`, `magic-link`, `oidc-provider`: feature flags
-// - `session-idle-timeout`: automatic logout in the auth configuration
-// - `social-providers`: any social sign-in provider in the auth configuration
-// - `site-general`: the General settings form, which saves all of its fields
-//   (name, footer, locale, maintenance mode, public sign-up, ...) at once
-// - `site-theme`: the Appearance settings
-//
-// A spec that holds a lock calls `test.slow()`, since waiting for another
-// holder counts against its timeout.
-
-// Longer than any spec holds a lock. A lock whose holder process has exited is
-// taken over at once; this bounds the wait when the holder cannot be checked.
-const STALE_MS = 120_000;
-const OWNER_FILE = "owner";
-
-/** The lock directory for `name`, shared by every worker on this machine. */
-export function lockPath(name: string): string {
-  return join(tmpdir(), `podokit-e2e-${name}.lock`);
-}
-
-/** Whether the worker that holds `lock` has exited, such as after Ctrl-C. */
-async function holderExited(lock: string): Promise<boolean> {
-  const pid = Number(await readFile(join(lock, OWNER_FILE), "utf8").catch(() => ""));
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return false;
-  } catch (error) {
-    return (error as NodeJS.ErrnoException).code === "ESRCH";
-  }
-}
-
-async function acquire(lock: string): Promise<void> {
-  for (;;) {
-    const created = await mkdir(lock).then(
-      () => true,
-      (error: NodeJS.ErrnoException) => {
-        if (error.code === "EEXIST") return false;
-        throw error;
-      },
-    );
-    if (created) {
-      await writeFile(join(lock, OWNER_FILE), String(process.pid)).catch(async (error: unknown) => {
-        await rm(lock, { recursive: true, force: true });
-        throw error;
-      });
-      return;
-    }
-    const age = await stat(lock).then((info) => Date.now() - info.mtimeMs, () => 0);
-    if (age > STALE_MS || (await holderExited(lock))) await rm(lock, { recursive: true, force: true });
-    else await new Promise((resolve) => setTimeout(resolve, 200));
-  }
-}
-
-/** Runs `body` while no other Playwright worker on this machine holds any of
- *  the named locks, and releases them however `body` ends. */
-export async function exclusive<T>(names: string | string[], body: () => Promise<T>): Promise<T> {
-  // One acquisition order for every caller, so two specs that each need
-  // several locks cannot wait on each other.
-  const locks = [...new Set([names].flat())].sort().map(lockPath);
-  const held: string[] = [];
-  try {
-    for (const lock of locks) {
-      await acquire(lock);
-      held.push(lock);
-    }
-    return await body();
-  } finally {
-    for (const lock of held.reverse()) await rm(lock, { recursive: true, force: true });
-  }
-}