@pablozaiden/webapp 0.5.8 → 0.6.0

package/docs/ui-guidelines.md

@@ -11,13 +11,21 @@ The framework intentionally provides a consistent base UI:
 - Main content should prefer panels, toolbars, badges and simple forms over custom one-off layouts.
 - `WebAppRoot` owns the fixed main title bar and `.wapp-main-content`; app routes should not render or style those shell elements directly.
 
+## Mobile breakpoint and viewport synchronization
+
+The framework owns the mobile shell breakpoint. `MOBILE_BREAKPOINT_PX` and `MOBILE_MEDIA_QUERY` are exported from `@pablozaiden/webapp/web` for application JavaScript that needs to coordinate with the shell; do not add an independent `innerWidth` threshold for shell behavior. The generated document initializes the `data-wapp-mobile` marker on the root element before the client and styles load, and `WebAppRoot` keeps it synchronized with media-query changes. Custom CSS that follows the framework mobile mode should use that marker rather than repeating a numeric media query.
+
+`WebAppRoot` follows `visualViewport` resize/scroll, window resize, orientation changes, focus boundaries, and mobile media-query changes. It schedules an immediate animation-frame sync first. Two named, bounded retries remain for mobile Safari/WebKit and Chromium behavior where focus/blur or orientation notifications can arrive before the final `visualViewport` geometry is available while the keyboard, browser chrome, or rotation is settling. The first retry catches the post-event layout pass; the final retry catches the end of that transition when no further geometry event is emitted. These retries are implementation fallbacks, not general synchronization primitives, and are cancelled with the associated animation frame and listeners when the root is unmounted.
+
+The framework mobile mode is separate from the narrower `640px` settings-layout rules. Do not add global touch handlers or arbitrary sleeps to reproduce either behavior; use the framework drawer controls and the existing event-driven viewport lifecycle.
+
 ## Main content primitives
 
 Use these first:
 
 | Component | Use |
 | --- | --- |
-| `Page` | Required top-level wrapper for route content rendered by `WebAppRoot.routes`; provides standard margins/padding and mobile spacing |
+| `Page` | Required top-level wrapper for route content rendered by `WebAppRoot.routes`; uses standard margins/padding and mobile spacing by default, or `layout="full"` for viewport-sized content |
 | `Toolbar` | Page title/actions inside main content |
 | `Panel` | Cards/sections; use `actions` for a top-right menu/action area |
 | `ActionMenu` | Three-line action menu for secondary surfaces; entity-level shell menus should usually come from `SidebarNode.actions` so the framework renders them in the sidebar context menu and fixed title bar |
@@ -36,11 +44,11 @@ Use these first:
 
 For entity actions, prefer the framework title bar: define one `ActionMenuItem[]` builder and attach it to `SidebarNode.actions` for the route-backed node. The framework reuses those actions for both sidebar right-click and the active route title-bar menu. Use `WebAppRoot.header.getActions` only for additional actions not owned by a sidebar node.
 
-Every route component rendered by `WebAppRoot.routes` should return `Page` at the top level, including loading/error/empty states. Do not render a `Panel`, `DataList`, `EmptyState` or custom div directly into `WebAppRoot`; that skips the standard content margins and recreates the visual bug where cards touch the main content edge. Use `EntityHeader` only when the page needs a content-specific heading distinct from the fixed framework title bar; do not duplicate the active route title immediately below the header.
+Every route component rendered by `WebAppRoot.routes` should return `Page` at the top level, including loading/error/empty states. Do not render a `Panel`, `DataList`, `EmptyState` or custom div directly into `WebAppRoot`; that skips the standard content margins and recreates the visual bug where cards touch the main content edge. For a route whose child owns viewport-sized layout and scrolling, use `<Page layout="full">` rather than overriding `.wapp-page` from the application. Use `EntityHeader` only when the page needs a content-specific heading distinct from the fixed framework title bar; do not duplicate the active route title immediately below the header.
 
 ## Visual validation captures
 
-Generated screenshots live in `artifacts/screenshots`:
+Reference screenshots live in `artifacts/screenshots`:
 
 | Capture | Purpose |
 | --- | --- |
@@ -56,7 +64,7 @@ Generated screenshots live in `artifacts/screenshots`:
 | `kitchen-dialog-dark.png` | Confirm dialog overlay |
 | `kitchen-device-light.png` | Device auth approval flow |
 
-Use `bun run screenshots` to regenerate these captures with Playwright. Browser automation and screenshot capture must stay Playwright-based and cross-platform; do not hard-code local Chrome or OS-specific browser paths.
+Use the temporary Playwright harness described in `skills/webapp/SKILL.md` when new visual captures are needed. Its default output is disposable; to intentionally update these checked-in reference captures, run the application-specific temporary harness with `PLAYWRIGHT_OUT_DIR="$PWD/artifacts/screenshots"` and review every changed image before committing it. Browser automation and screenshot capture must stay Playwright-based and cross-platform; do not hard-code local Chrome or OS-specific browser paths. The framework does not ship a screenshot command or Playwright dependency.
 
 Use these captures as the manual visual baseline before changing shell, sidebar, settings or dialog styles. When screenshots are captured to validate a visual change, review them against the specific goal; capturing files without checking the result is not validation.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablozaiden/webapp",
-  "version": "0.5.8",
+  "version": "0.6.0",
   "description": "Opinionated Bun + React webapp framework for single-server apps",
   "license": "MIT",
   "type": "module",
@@ -37,8 +37,7 @@
     "build:kitchen-sink": "bun run --cwd examples/kitchen-sink build",
     "build:notes-todo": "bun run --cwd examples/notes-todo build",
     "test": "bun test",
-    "tsc": "mkdir -p .cache/tsc && bunx tsc --noEmit --pretty false --incremental --tsBuildInfoFile .cache/tsc/build.tsbuildinfo",
-    "screenshots": "bunx playwright install chromium && bun tests/capture-screenshots.ts"
+    "tsc": "mkdir -p .cache/tsc && bunx tsc --noEmit --pretty false --incremental --tsBuildInfoFile .cache/tsc/build.tsbuildinfo"
   },
   "dependencies": {
     "@simplewebauthn/browser": "13.3.0",
@@ -58,7 +57,6 @@
     "@types/bun": "1.3.14",
     "@types/react": "19.2.17",
     "@types/react-dom": "19.2.3",
-    "playwright": "1.61.0",
     "react": "19.2.7",
     "react-dom": "19.2.7",
     "typescript": "7.0.2"

package/src/build/build-binary.ts

@@ -1,14 +1,24 @@
 import type { BunPlugin } from "bun";
 import tailwindPlugin from "bun-plugin-tailwind";
-import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, resolve } from "node:path";
+import { findPackageRoot, resolveReactDomClient } from "../package-resolution";
 
-export type BunCompileTarget =
-  | "bun-linux-x64"
-  | "bun-linux-arm64"
-  | "bun-darwin-x64"
-  | "bun-darwin-arm64"
-  | "bun-windows-x64";
+export const BUN_COMPILE_TARGETS = [
+  "bun-linux-x64",
+  "bun-linux-arm64",
+  "bun-darwin-x64",
+  "bun-darwin-arm64",
+  "bun-windows-x64",
+] as const;
+
+export type BunCompileTarget = (typeof BUN_COMPILE_TARGETS)[number];
+
+const BUN_COMPILE_TARGET_SET = new Set<string>(BUN_COMPILE_TARGETS);
+
+export function isBunCompileTarget(value: unknown): value is BunCompileTarget {
+  return typeof value === "string" && BUN_COMPILE_TARGET_SET.has(value);
+}
 
 export interface BuildWebAppBinaryOptions {
   entrypoint: string;
@@ -25,14 +35,59 @@ export interface BuildWebAppBinaryOptions {
   };
 }
 
+function formatTargetValue(value: unknown): string {
+  if (value === undefined) return "<missing>";
+  if (typeof value === "string") return JSON.stringify(value);
+  return String(value);
+}
+
+function supportedTargetMessage(): string {
+  return `Supported Bun compile targets: ${BUN_COMPILE_TARGETS.join(", ")}.`;
+}
+
+export function assertBunCompileTarget(value: unknown): asserts value is BunCompileTarget {
+  if (!isBunCompileTarget(value)) {
+    throw new Error(`Invalid Bun compile target ${formatTargetValue(value)}. ${supportedTargetMessage()}`);
+  }
+}
+
 export function getBunCompileTargetFromArgs(argv = Bun.argv): BunCompileTarget | undefined {
-  const raw = argv.find((arg) => arg.startsWith("--target="))?.slice("--target=".length);
-  return raw as BunCompileTarget | undefined;
+  const targetArguments: Array<{ argument: string; value: string }> = [];
+  for (const [index, argument] of argv.entries()) {
+    if (argument === undefined) continue;
+    if (argument === "--target" || (argument.startsWith("--target") && !argument.startsWith("--target="))) {
+      const nextArgument = argv[index + 1];
+      const received = argument === "--target" && nextArgument && !nextArgument.startsWith("--")
+        ? `${argument} ${nextArgument}`
+        : argument;
+      throw new Error(`Malformed Bun compile target option ${formatTargetValue(received)}. Expected --target=<target>. ${supportedTargetMessage()}`);
+    }
+    if (argument.startsWith("--target=")) {
+      targetArguments.push({
+        argument,
+        value: argument.slice("--target=".length),
+      });
+    }
+  }
+  if (targetArguments.length === 0) return undefined;
+  if (targetArguments.length > 1) {
+    throw new Error(`Duplicate Bun compile target options are not allowed: ${targetArguments.map(({ argument }) => argument).join(", ")}. ${supportedTargetMessage()}`);
+  }
+  const targetArgument = targetArguments[0];
+  if (targetArgument === undefined) return undefined;
+  const { value } = targetArgument;
+  assertBunCompileTarget(value);
+  return value;
 }
 
 export async function buildWebAppBinary(options: BuildWebAppBinaryOptions): Promise<void> {
+  if (options.target !== undefined) {
+    assertBunCompileTarget(options.target);
+  }
+  const entrypoint = resolve(options.entrypoint);
+  const packageRoot = findPackageRoot(dirname(entrypoint));
+  const reactDomClientPath = resolveReactDomClient(packageRoot, entrypoint);
   mkdirSync(dirname(options.outfile), { recursive: true });
-  const packageRoot = findPackageRoot(dirname(resolve(options.entrypoint)));
   const buildId = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
   const cacheDir = resolve(packageRoot, ".cache", "webapp-build", buildId);
   try {
@@ -41,7 +96,7 @@ export async function buildWebAppBinary(options: BuildWebAppBinaryOptions): Prom
     const rendererEntry = resolve(cacheDir, "webapp-renderer-prelude.ts");
     const clientEntry = resolve(cacheDir, "webapp-client-entry.ts");
     const browserOutDir = resolve(cacheDir, "browser");
-    writeFileSync(rendererEntry, `import { createRoot } from "react-dom/client";
+    writeFileSync(rendererEntry, `import { createRoot } from ${JSON.stringify(reactDomClientPath.replaceAll("\\", "/"))};
 import { configureWebAppRenderer } from "@pablozaiden/webapp/web";
 
 configureWebAppRenderer(createRoot);
@@ -90,7 +145,7 @@ configureWebAppRenderer(createRoot);
 `);
     const compiledEntrypoint = resolve(cacheDir, "entrypoint.ts");
     writeFileSync(compiledEntrypoint, `import "./compiled-webapp-assets";
-import ${JSON.stringify(resolve(options.entrypoint))};
+import ${JSON.stringify(entrypoint)};
 `);
     const result = await Bun.build({
       entrypoints: [compiledEntrypoint],
@@ -114,18 +169,6 @@ import ${JSON.stringify(resolve(options.entrypoint))};
   }
 }
 
-function findPackageRoot(start: string): string {
-  let current = start;
-  while (true) {
-    if (existsSync(resolve(current, "package.json"))) {
-      return current;
-    }
-    const parent = dirname(current);
-    if (parent === current) return start;
-    current = parent;
-  }
-}
-
 function contentTypeForOutput(ext: string): string {
   if (ext === ".js") return "text/javascript; charset=utf-8";
   if (ext === ".css") return "text/css; charset=utf-8";

package/src/cli/api-command.ts

@@ -1,12 +1,12 @@
 import { z } from "zod";
 import { findRouteCatalogEntry, type RouteCatalogEntry } from "../server/route-catalog";
-import { getAuthorizedHeaders, refreshDeviceCredentials, type StoredDeviceCredentials } from "./device-auth";
+import { getAuthorizedHeaders, refreshDeviceCredentials, type DeviceCredentialsStore, type StoredDeviceCredentials } from "./device-auth";
+import { resolveEnvironmentApiKeyAuth, type CliEnvironment } from "./environment-auth";
 import { readOption, type CliCommandResult } from "./runtime";
 
-export interface ApiCliCredentialsStore {
+export type ApiCliCredentialsStore = DeviceCredentialsStore & {
   read(): Promise<StoredDeviceCredentials | undefined>;
-  write(value: StoredDeviceCredentials): Promise<void>;
-}
+};
 
 export interface ApiCliCommandOptions {
   catalog: readonly RouteCatalogEntry[];
@@ -14,6 +14,8 @@ export interface ApiCliCommandOptions {
   mode?: "api" | "schema";
   baseUrl?: string;
   credentials?: ApiCliCredentialsStore;
+  envPrefix?: string;
+  environment?: CliEnvironment;
   fetchFn?: typeof fetch;
   now?: () => Date;
 }
@@ -54,17 +56,51 @@ function endpointArg(args: string[]): string | undefined {
   return args.find((arg) => !arg.startsWith("--"));
 }
 
-async function authHeaders(input: ApiCliCommandOptions): Promise<Headers> {
+type ApiCliAuthSource = "device" | "environment" | "anonymous";
+
+interface ResolvedApiCliAuth {
+  headers: Headers;
+  source: ApiCliAuthSource;
+  baseUrl?: string;
+}
+
+function apiKeyHeaders(apiKey: string, headers: HeadersInit): Headers {
+  const result = new Headers(headers);
+  result.set("authorization", `Bearer ${apiKey}`);
+  return result;
+}
+
+async function resolveAuth(input: ApiCliCommandOptions): Promise<ResolvedApiCliAuth> {
   const headers = new Headers({ accept: "application/json" });
   const stored = await input.credentials?.read();
-  if (!stored) return headers;
-  const refreshed = await refreshDeviceCredentials({
-    credentials: stored,
-    store: input.credentials,
-    fetchFn: input.fetchFn,
-    now: input.now,
-  });
-  return refreshed ? getAuthorizedHeaders(refreshed, headers) : headers;
+  if (stored) {
+    const refreshed = await refreshDeviceCredentials({
+      credentials: stored,
+      store: input.credentials,
+      fetchFn: input.fetchFn,
+      now: input.now,
+    });
+    return {
+      headers: refreshed ? getAuthorizedHeaders(refreshed, headers) : headers,
+      source: "device",
+      baseUrl: (refreshed ?? stored).baseUrl,
+    };
+  }
+  if (input.envPrefix) {
+    const environmentAuth = resolveEnvironmentApiKeyAuth({
+      envPrefix: input.envPrefix,
+      explicitBaseUrl: input.baseUrl,
+      environment: input.environment,
+    });
+    if (environmentAuth) {
+      return {
+        headers: apiKeyHeaders(environmentAuth.apiKey, headers),
+        source: "environment",
+        baseUrl: environmentAuth.baseUrl,
+      };
+    }
+  }
+  return { headers, source: "anonymous" };
 }
 
 export async function runApiCliCommand(input: ApiCliCommandOptions): Promise<CliCommandResult> {
@@ -84,9 +120,10 @@ export async function runApiCliCommand(input: ApiCliCommandOptions): Promise<Cli
     return { exitCode: 1, error: `Method ${method} is not available for ${match.entry.cliPath}` };
   }
   const payload = readOption(input.args, ["--payload", "--data", "-d"]);
-  const baseUrl = (input.baseUrl ?? "http://localhost:3000").replace(/\/+$/, "");
+  const auth = await resolveAuth(input);
+  const baseUrl = (input.baseUrl ?? auth.baseUrl ?? "http://localhost:3000").replace(/\/+$/, "");
   const url = new URL(`${baseUrl}${match.path}`);
-  const headers = await authHeaders(input);
+  const headers = auth.headers;
   let body: string | undefined;
   if (payload !== undefined) {
     JSON.parse(payload) as unknown;
@@ -95,7 +132,7 @@ export async function runApiCliCommand(input: ApiCliCommandOptions): Promise<Cli
   }
   const send = () => (input.fetchFn ?? fetch)(url, { method, headers, body });
   let response = await send();
-  if (response.status === 401 && input.credentials) {
+  if (response.status === 401 && auth.source === "device" && input.credentials) {
     const stored = await input.credentials.read();
     if (stored) {
       const refreshed = await refreshDeviceCredentials({ credentials: { ...stored, accessTokenExpiresAt: new Date(0).toISOString() }, store: input.credentials, fetchFn: input.fetchFn, now: input.now });

package/src/cli/credentials.ts

@@ -1,12 +1,281 @@
 import { chmodSync } from "node:fs";
-import { mkdir, readFile, rename, rm } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { link, mkdir, readFile, rename, rm } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+export interface JsonFileStoreLockOptions {
+  timeoutMs?: number;
+  staleAfterMs?: number;
+  pollIntervalMs?: number;
+}
+
+export type JsonFileStoreLockErrorCode = "timeout" | "release";
+
+export class JsonFileStoreLockError extends Error {
+  constructor(
+    public readonly code: JsonFileStoreLockErrorCode,
+    message: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "JsonFileStoreLockError";
+  }
+}
 
 export interface JsonFileStore<T> {
   path(): string;
   read(): Promise<T | undefined>;
   write(value: T): Promise<void>;
   clear(): Promise<void>;
+  withLock?<R>(callback: () => Promise<R>, options?: JsonFileStoreLockOptions): Promise<R>;
+}
+
+const LOCK_METADATA_VERSION = 1;
+const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
+const DEFAULT_LOCK_STALE_AFTER_MS = 5 * 60_000;
+const DEFAULT_LOCK_POLL_INTERVAL_MS = 25;
+
+interface LockMetadata {
+  version: typeof LOCK_METADATA_VERSION;
+  pid: number;
+  createdAt: number;
+  owner: string;
+}
+
+interface OwnedLock {
+  path: string;
+  metadata: LockMetadata;
+}
+
+type LockState = LockMetadata | "invalid" | undefined;
+
+function errorCode(error: unknown): string | undefined {
+  if (!error || typeof error !== "object" || !("code" in error)) return undefined;
+  return typeof error.code === "string" ? error.code : undefined;
+}
+
+function ensureFiniteOption(name: string, value: number, minimum: number): number {
+  if (!Number.isFinite(value) || value < minimum) {
+    throw new RangeError(`${name} must be a finite number >= ${minimum}`);
+  }
+  return value;
+}
+
+function resolveLockOptions(options?: JsonFileStoreLockOptions): Required<JsonFileStoreLockOptions> {
+  return {
+    timeoutMs: ensureFiniteOption("timeoutMs", options?.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS, 0),
+    staleAfterMs: ensureFiniteOption("staleAfterMs", options?.staleAfterMs ?? DEFAULT_LOCK_STALE_AFTER_MS, 0),
+    pollIntervalMs: ensureFiniteOption("pollIntervalMs", options?.pollIntervalMs ?? DEFAULT_LOCK_POLL_INTERVAL_MS, 1),
+  };
+}
+
+function secureDirectory(path: string): Promise<void> {
+  return mkdir(path, { recursive: true, mode: 0o700 }).then(() => {
+    chmodIfPossible(path, 0o700);
+  });
+}
+
+function lockPathFor(target: string): string {
+  return `${target}.lock`;
+}
+
+function lockCandidatePath(lockPath: string): string {
+  const dir = dirname(lockPath);
+  return join(dir, `.${basename(lockPath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+}
+
+function parseLockMetadata(value: string): LockMetadata | "invalid" {
+  if (value.length > 4096) return "invalid";
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    if (!parsed || typeof parsed !== "object") return "invalid";
+    const record = parsed as Record<string, unknown>;
+    if (
+      record["version"] !== LOCK_METADATA_VERSION ||
+      !Number.isSafeInteger(record["pid"]) ||
+      Number(record["pid"]) <= 0 ||
+      typeof record["createdAt"] !== "number" ||
+      !Number.isFinite(record["createdAt"]) ||
+      typeof record["owner"] !== "string" ||
+      record["owner"].length === 0
+    ) {
+      return "invalid";
+    }
+    return {
+      version: LOCK_METADATA_VERSION,
+      pid: record["pid"] as number,
+      createdAt: record["createdAt"],
+      owner: record["owner"],
+    };
+  } catch {
+    return "invalid";
+  }
+}
+
+async function readLockMetadata(path: string): Promise<LockState> {
+  try {
+    return parseLockMetadata(await readFile(path, "utf8"));
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return errorCode(error) !== "ESRCH";
+  }
+}
+
+function sameOwner(left: LockMetadata, right: LockMetadata): boolean {
+  return left.version === right.version && left.pid === right.pid && left.createdAt === right.createdAt && left.owner === right.owner;
+}
+
+async function removePublishedLock(path: string, metadata: LockMetadata): Promise<void> {
+  const current = await readLockMetadata(path);
+  if (!current || current === "invalid" || !sameOwner(current, metadata)) return;
+  await rm(path, { force: true });
+}
+
+async function publishLock(path: string, metadata: LockMetadata): Promise<boolean> {
+  const candidate = lockCandidatePath(path);
+  let linked = false;
+  let operationError: unknown;
+  try {
+    await Bun.write(candidate, `${JSON.stringify(metadata)}\n`);
+    chmodIfPossible(candidate, 0o600);
+    try {
+      await link(candidate, path);
+      linked = true;
+    } catch (error) {
+      if (errorCode(error) !== "EEXIST") operationError = error;
+    }
+  } catch (error) {
+    operationError = error;
+  }
+  let cleanupError: unknown;
+  try {
+    await rm(candidate, { force: true });
+  } catch (error) {
+    cleanupError = error;
+  }
+  if (cleanupError !== undefined) {
+    const errors: unknown[] = [cleanupError];
+    if (operationError !== undefined) errors.unshift(operationError);
+    if (linked) {
+      try {
+        await removePublishedLock(path, metadata);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    throw new AggregateError(errors, "Unable to create credentials lock");
+  }
+  if (operationError !== undefined) throw operationError;
+  return linked;
+}
+
+async function reclaimStaleLock(path: string, expected: LockMetadata): Promise<void> {
+  const current = await readLockMetadata(path);
+  if (!current || current === "invalid" || !sameOwner(current, expected) || isProcessAlive(current.pid)) return;
+  const confirmed = await readLockMetadata(path);
+  if (!confirmed || confirmed === "invalid" || !sameOwner(confirmed, expected) || isProcessAlive(confirmed.pid)) return;
+  try {
+    await rm(path);
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw error;
+  }
+}
+
+function waitForLock(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function acquireFileLock(target: string, options?: JsonFileStoreLockOptions): Promise<OwnedLock> {
+  const resolved = resolveLockOptions(options);
+  const path = lockPathFor(target);
+  await secureDirectory(dirname(target));
+  const metadata: LockMetadata = {
+    version: LOCK_METADATA_VERSION,
+    pid: process.pid,
+    createdAt: Date.now(),
+    owner: crypto.randomUUID(),
+  };
+  const deadline = Date.now() + resolved.timeoutMs;
+
+  while (true) {
+    if (await publishLock(path, metadata)) return { path, metadata };
+
+    const current = await readLockMetadata(path);
+    const now = Date.now();
+    if (
+      current &&
+      current !== "invalid" &&
+      current.createdAt <= now - resolved.staleAfterMs &&
+      !isProcessAlive(current.pid)
+    ) {
+      await reclaimStaleLock(path, current);
+      continue;
+    }
+    if (now >= deadline) {
+      throw new JsonFileStoreLockError("timeout", "Timed out acquiring credentials lock");
+    }
+    await waitForLock(Math.min(resolved.pollIntervalMs, Math.max(1, deadline - now)));
+  }
+}
+
+async function releaseFileLock(lock: OwnedLock): Promise<void> {
+  let current: LockState;
+  try {
+    current = await readLockMetadata(lock.path);
+  } catch (error) {
+    throw new JsonFileStoreLockError("release", "Unable to verify credentials lock ownership", { cause: error });
+  }
+  if (current === undefined) return;
+  if (current === "invalid" || !sameOwner(current, lock.metadata)) {
+    throw new JsonFileStoreLockError("release", "Unable to verify credentials lock ownership");
+  }
+  try {
+    await rm(lock.path);
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return;
+    throw new JsonFileStoreLockError("release", "Unable to release credentials lock", { cause: error });
+  }
+}
+
+async function withFileLock<T>(
+  target: string,
+  callback: () => Promise<T>,
+  options?: JsonFileStoreLockOptions,
+): Promise<T> {
+  const lock = await acquireFileLock(target, options);
+  let result!: T;
+  let callbackFailed = false;
+  let callbackError: unknown;
+  try {
+    result = await callback();
+  } catch (error) {
+    callbackFailed = true;
+    callbackError = error;
+  }
+
+  let releaseFailed = false;
+  let releaseError: unknown;
+  try {
+    await releaseFileLock(lock);
+  } catch (error) {
+    releaseFailed = true;
+    releaseError = error;
+  }
+
+  if (callbackFailed && releaseFailed) {
+    throw new AggregateError([callbackError, releaseError], "Credentials refresh and lock release failed");
+  }
+  if (callbackFailed) throw callbackError;
+  if (releaseFailed) throw releaseError;
+  return result;
 }
 
 function chmodIfPossible(path: string, mode: number): void {
@@ -47,8 +316,7 @@ export function createJsonFileStore<T>(input: {
     async write(value) {
       const target = filePath();
       const dir = dirname(target);
-      await mkdir(dir, { recursive: true, mode: 0o700 });
-      chmodIfPossible(dir, 0o700);
+      await secureDirectory(dir);
       const temp = join(dir, `.${input.fileName}.${process.pid}.${crypto.randomUUID()}.tmp`);
       try {
         await Bun.write(temp, `${JSON.stringify(value, null, 2)}\n`);
@@ -63,5 +331,8 @@ export function createJsonFileStore<T>(input: {
     async clear() {
       await rm(filePath(), { force: true });
     },
+    async withLock<R>(callback: () => Promise<R>, options?: JsonFileStoreLockOptions) {
+      return withFileLock(filePath(), callback, options);
+    },
   };
 }