@verbatra/sdk 0.8.0 → 0.9.0

package/dist/index.cjs

@@ -2,11 +2,11 @@
 
 var path = require('path');
 var zod = require('zod');
+var crypto = require('crypto');
+var promises = require('fs/promises');
 var fs = require('fs');
 var cosmiconfig = require('cosmiconfig');
 var cosmiconfigTypescriptLoader = require('cosmiconfig-typescript-loader');
-var crypto = require('crypto');
-var promises = require('fs/promises');
 var Anthropic = require('@anthropic-ai/sdk');
 var deepl = require('deepl-node');
 var module$1 = require('module');
@@ -297,52 +297,238 @@ var defaultFs = {
     await promises.mkdir(path, { recursive: true });
   }
 };
+var LOCAL_DIR_NAME = ".verbatra-local";
+var LOCK_FILE_GUARD_STEM = "_lockfile";
+var GLOSSARY_GUARD_STEM = "_glossary";
+var DEFAULT_POLL_INTERVAL_MS = 100;
+var DEFAULT_ACQUIRE_TIMEOUT_MS = 10 * 6e4;
+var WAIT_NOTICE_INTERVAL_MS = 1e3;
+var MAX_LOCK_PAYLOAD_BYTES = 64 * 1024;
+function lockPath(cwd, stem) {
+  return path.resolve(cwd, LOCAL_DIR_NAME, "locks", `${stem}.lock`);
+}
+function localeLockPath(cwd, locale) {
+  return lockPath(cwd, locale);
+}
+function lockFileGuardPath(cwd) {
+  return lockPath(cwd, LOCK_FILE_GUARD_STEM);
+}
+function glossaryGuardPath(cwd) {
+  return lockPath(cwd, GLOSSARY_GUARD_STEM);
+}
+function sleep(ms) {
+  return new Promise((res) => {
+    setTimeout(res, ms);
+  });
+}
+function lockPayload() {
+  return JSON.stringify({ pid: process.pid, acquiredAt: (/* @__PURE__ */ new Date()).toISOString() });
+}
+function parseHolder(read) {
+  if (read.kind !== "ok") {
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(read.content);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return void 0;
+  }
+  const record = parsed;
+  const holder = {};
+  if (typeof record.pid === "number") {
+    holder.pid = record.pid;
+  }
+  if (typeof record.acquiredAt === "string") {
+    holder.acquiredAt = record.acquiredAt;
+  }
+  return holder;
+}
+function makeWaitNotifier(path, fs, onWait, start) {
+  let holder;
+  let holderRead = false;
+  let lastEmit;
+  return async () => {
+    if (!holderRead) {
+      holderRead = true;
+      holder = parseHolder(await fs.readFileBounded(path, MAX_LOCK_PAYLOAD_BYTES));
+    }
+    const elapsedMs = Date.now() - start;
+    if (lastEmit !== void 0 && elapsedMs - lastEmit < WAIT_NOTICE_INTERVAL_MS) {
+      return;
+    }
+    lastEmit = elapsedMs;
+    onWait({ lockPath: path, elapsedMs, ...holder !== void 0 ? { holder } : {} });
+  };
+}
+async function acquireLock(path, fs, pollIntervalMs, deadline, notify) {
+  for (; ; ) {
+    if (await fs.createExclusive(path, lockPayload())) {
+      return;
+    }
+    if (notify !== void 0) {
+      await notify();
+    }
+    if (Date.now() >= deadline) {
+      throw new SdkError(
+        "LOCK_CONTENDED",
+        `Could not acquire the write lock at ${path}: another process may be holding it. If no verbatra process is currently running, this lock file was likely left behind by one that was killed; delete it and retry.`
+      );
+    }
+    const jitter = Math.random() * pollIntervalMs;
+    await sleep(pollIntervalMs + jitter);
+  }
+}
+async function withFileLock(path, fs, fn, options) {
+  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const acquireTimeoutMs = options.acquireTimeoutMs ?? DEFAULT_ACQUIRE_TIMEOUT_MS;
+  const start = Date.now();
+  const notify = options.onWait !== void 0 ? makeWaitNotifier(path, fs, options.onWait, start) : void 0;
+  await acquireLock(path, fs, pollIntervalMs, start + acquireTimeoutMs, notify);
+  try {
+    return await fn();
+  } finally {
+    await fs.deleteFile(path);
+  }
+}
+async function withLocaleWriteLock(cwd, locale, fs, fn, options = {}) {
+  return withFileLock(localeLockPath(cwd, locale), fs, fn, options);
+}
+async function withLockFileGuard(cwd, fs, fn, options = {}) {
+  return withFileLock(lockFileGuardPath(cwd), fs, fn, options);
+}
+async function withGlossaryGuard(cwd, fs, fn, options = {}) {
+  return withFileLock(glossaryGuardPath(cwd), fs, fn, options);
+}
+
+// src/config/glossary-file.ts
 var MAX_GLOSSARY_FILE_BYTES = 1024 * 1024;
-var glossaryRecordSchema = zod.z.record(zod.z.string(), zod.z.string());
+var DEFAULT_INDENT = "  ";
+var INDENT_PATTERN = /^([ \t]+)"/m;
 var BOM = "\uFEFF";
 var REPLACEMENT_CHARACTER = "\uFFFD";
 var NUL = "\0";
+var glossaryRecordSchema = zod.z.record(zod.z.string(), zod.z.string());
 function stripBom(content) {
   return content.startsWith(BOM) ? content.slice(BOM.length) : content;
 }
 function looksLikeInvalidEncoding(content) {
   return content.startsWith(REPLACEMENT_CHARACTER) || content.includes(NUL);
 }
-async function readGlossaryFile(resolvedPath, fs) {
-  const read = await fs.readFileBounded(resolvedPath, MAX_GLOSSARY_FILE_BYTES);
+function detectIndent(content) {
+  return INDENT_PATTERN.exec(content)?.[1] ?? DEFAULT_INDENT;
+}
+async function readGlossaryDocument(path, fs) {
+  const read = await fs.readFileBounded(path, MAX_GLOSSARY_FILE_BYTES);
   if (read.kind === "missing") {
     throw new SdkError(
       "CONFIG_INVALID",
-      `The glossary file at ${resolvedPath} was not found or could not be read.`
+      `The glossary file at ${path} was not found or could not be read.`
     );
   }
   if (read.kind === "too-large") {
     throw new SdkError(
       "CONFIG_INVALID",
-      `The glossary file at ${resolvedPath} exceeds the maximum allowed size of ${MAX_GLOSSARY_FILE_BYTES} bytes.`
+      `The glossary file at ${path} exceeds the maximum allowed size of ${MAX_GLOSSARY_FILE_BYTES} bytes.`
     );
   }
   const content = stripBom(read.content);
   if (looksLikeInvalidEncoding(content)) {
-    throw new SdkError(
-      "CONFIG_INVALID",
-      `The glossary file at ${resolvedPath} must be UTF-8 encoded.`
-    );
+    throw new SdkError("CONFIG_INVALID", `The glossary file at ${path} must be UTF-8 encoded.`);
   }
   let parsed;
   try {
     parsed = JSON.parse(content);
   } catch {
-    throw new SdkError("CONFIG_INVALID", `The glossary file at ${resolvedPath} is not valid JSON.`);
+    throw new SdkError("CONFIG_INVALID", `The glossary file at ${path} is not valid JSON.`);
   }
   const result = glossaryRecordSchema.safeParse(parsed);
   if (!result.success) {
     throw new SdkError(
       "CONFIG_INVALID",
-      `The glossary file at ${resolvedPath} must contain a flat object of string keys to string values.`
+      `The glossary file at ${path} must contain a flat object of string keys to string values.`
+    );
+  }
+  return {
+    entries: result.data,
+    indent: detectIndent(content),
+    trailingNewline: content.endsWith("\n") ? "\n" : ""
+  };
+}
+async function readGlossaryRecord(path, fs) {
+  return (await readGlossaryDocument(path, fs)).entries;
+}
+function glossaryFilePath(glossary) {
+  if (glossary.source !== "file") {
+    throw new SdkError(
+      "GLOSSARY_NOT_FILE_BACKED",
+      `The glossary is ${glossary.source === "inline" ? "written inline in the config" : "not configured"}, so there is no glossary file to work with. Point the config's glossary at a JSON file first.`
+    );
+  }
+  return glossary.path;
+}
+function assertWritableTerm(term, translation) {
+  if (term.trim().length === 0) {
+    throw new SdkError("CONFIG_INVALID", "A glossary term must not be blank.");
+  }
+  if (translation !== null && translation.trim().length === 0) {
+    throw new SdkError(
+      "CONFIG_INVALID",
+      `The translation for the glossary term "${term}" must not be blank. Remove the term instead.`
+    );
+  }
+}
+function applyTerm(current, term, translation) {
+  const pairs = Object.entries(current);
+  const index = pairs.findIndex(([existing]) => existing === term);
+  if (translation === null) {
+    if (index >= 0) {
+      pairs.splice(index, 1);
+    }
+  } else if (index >= 0) {
+    pairs[index] = [term, translation];
+  } else {
+    pairs.push([term, translation]);
+  }
+  return Object.fromEntries(pairs);
+}
+function serializeGlossary(entries, document, path) {
+  const serialized = `${JSON.stringify(entries, null, document.indent)}${document.trailingNewline}`;
+  if (Buffer.byteLength(serialized, "utf8") > MAX_GLOSSARY_FILE_BYTES) {
+    throw new SdkError(
+      "CONFIG_INVALID",
+      `The updated glossary file at ${path} would exceed the maximum allowed size of ${MAX_GLOSSARY_FILE_BYTES} bytes.`
+    );
+  }
+  return serialized;
+}
+async function writeGlossary(path, serialized, fs) {
+  try {
+    await fs.writeFile(path, serialized);
+  } catch (error) {
+    throw new SdkError(
+      "GLOSSARY_UNWRITABLE",
+      `The glossary file at ${path} could not be written: ${error instanceof Error ? error.message : String(error)}`
     );
   }
-  return result.data;
+}
+async function readGlossaryFile(input, deps = {}) {
+  return readGlossaryRecord(glossaryFilePath(input.glossary), deps.fs ?? defaultFs);
+}
+async function updateGlossaryTerm(input, deps = {}) {
+  const path = glossaryFilePath(input.glossary);
+  assertWritableTerm(input.term, input.translation);
+  const fs = deps.fs ?? defaultFs;
+  const cwd = input.cwd ?? process.cwd();
+  return withGlossaryGuard(cwd, fs, async () => {
+    const document = await readGlossaryDocument(path, fs);
+    const entries = applyTerm(document.entries, input.term, input.translation);
+    await writeGlossary(path, serializeGlossary(entries, document, path), fs);
+    return entries;
+  });
 }
 async function resolveGlossary(glossary, baseDir, fs) {
   if (glossary === void 0) {
@@ -350,7 +536,7 @@ async function resolveGlossary(glossary, baseDir, fs) {
   }
   if (typeof glossary === "string") {
     const resolvedPath = path.resolve(baseDir, glossary);
-    const record = await readGlossaryFile(resolvedPath, fs);
+    const record = await readGlossaryRecord(resolvedPath, fs);
     return { glossary: record, provenance: { source: "file", path: resolvedPath } };
   }
   return { glossary, provenance: { source: "inline" } };
@@ -1001,6 +1187,66 @@ function isAbortError(error, signal) {
   }
   return isAbortShapedError(error);
 }
+var REFUSED = {
+  cause: "the connection was refused",
+  remedy: "Check that the endpoint is running and that the configured host and port are right, then run again."
+};
+var UNRESOLVED = {
+  cause: "the host name could not be resolved",
+  remedy: "Check the spelling of the configured endpoint and your DNS or network access."
+};
+var CLOSED = {
+  cause: "the connection was closed before a reply arrived",
+  remedy: "Retry, and check any proxy or firewall between you and the endpoint."
+};
+var UNREACHABLE = {
+  cause: "the host could not be reached",
+  remedy: "Check your network access and any proxy or firewall between you and the endpoint."
+};
+var UNTRUSTED_CERTIFICATE = {
+  cause: "the endpoint's TLS certificate could not be verified",
+  remedy: "Check the certificate the endpoint serves, or point at a host your system already trusts."
+};
+var NETWORK_CAUSE_BY_CODE = {
+  ECONNREFUSED: REFUSED,
+  ENOTFOUND: UNRESOLVED,
+  EAI_AGAIN: UNRESOLVED,
+  ECONNRESET: CLOSED,
+  ECONNABORTED: CLOSED,
+  EPIPE: CLOSED,
+  ETIMEDOUT: UNREACHABLE,
+  EHOSTUNREACH: UNREACHABLE,
+  ENETUNREACH: UNREACHABLE,
+  CERT_HAS_EXPIRED: UNTRUSTED_CERTIFICATE,
+  DEPTH_ZERO_SELF_SIGNED_CERT: UNTRUSTED_CERTIFICATE,
+  UNABLE_TO_VERIFY_LEAF_SIGNATURE: UNTRUSTED_CERTIFICATE,
+  SELF_SIGNED_CERT_IN_CHAIN: UNTRUSTED_CERTIFICATE
+};
+var MAX_CAUSE_DEPTH = 4;
+function ownCode(error) {
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return void 0;
+  }
+  const code = error.code;
+  return typeof code === "string" ? code : void 0;
+}
+function nextCause(error) {
+  return typeof error === "object" && error !== null && "cause" in error ? error.cause : void 0;
+}
+function findNetworkCause(error) {
+  let current = error;
+  for (let depth = 0; depth < MAX_CAUSE_DEPTH && current !== void 0; depth += 1) {
+    const code = ownCode(current);
+    if (code !== void 0 && Object.hasOwn(NETWORK_CAUSE_BY_CODE, code)) {
+      return NETWORK_CAUSE_BY_CODE[code];
+    }
+    current = nextCause(current);
+  }
+  return void 0;
+}
+function describeNetworkCause(cause) {
+  return `${cause.cause}. ${cause.remedy}`;
+}
 var PROVIDER_CALL_FAILED_MESSAGE = "The translation provider request failed.";
 var RATE_LIMITED_MESSAGE = "The translation provider rate-limited this request.";
 var TIMEOUT_MESSAGE = "The translation provider request timed out.";
@@ -1013,7 +1259,19 @@ var MESSAGE_BY_CODE = {
   PROVIDER_UNAVAILABLE: PROVIDER_UNAVAILABLE_MESSAGE,
   PROVIDER_ERROR: PROVIDER_CALL_FAILED_MESSAGE
 };
-async function guardProviderCall(call, signal) {
+function providerErrorMessage(error, endpointHost) {
+  const cause = findNetworkCause(error);
+  if (cause === void 0 && endpointHost === void 0) {
+    return PROVIDER_CALL_FAILED_MESSAGE;
+  }
+  const where = endpointHost === void 0 ? "" : ` to ${endpointHost}`;
+  const why = cause === void 0 ? "" : `: ${describeNetworkCause(cause)}`;
+  return `The translation provider request${where} failed${why === "" ? "." : why}`;
+}
+function messageFor(code, error, context) {
+  return code === "PROVIDER_ERROR" ? providerErrorMessage(error, context?.endpointHost) : MESSAGE_BY_CODE[code];
+}
+async function guardProviderCall(call, signal, context) {
   signal?.throwIfAborted();
   try {
     return await call();
@@ -1022,7 +1280,7 @@ async function guardProviderCall(call, signal) {
       throw error;
     }
     const code = classifyProviderError(error);
-    throw new ProviderError(code, MESSAGE_BY_CODE[code]);
+    throw new ProviderError(code, messageFor(code, error, context));
   }
 }
 var DEFAULT_REQUEST_TIMEOUT_MS = 12e4;
@@ -1032,7 +1290,7 @@ function requestTimedOutMessage(timeoutMs) {
 function combineSignals(caller, timeout) {
   return caller === void 0 ? timeout : AbortSignal.any([caller, timeout]);
 }
-async function withRequestTimeout(timeoutMs, callerSignal, call) {
+async function withRequestTimeout(timeoutMs, callerSignal, call, context) {
   const timeoutController = new AbortController();
   const signal = combineSignals(callerSignal, timeoutController.signal);
   let timer;
@@ -1043,7 +1301,7 @@ async function withRequestTimeout(timeoutMs, callerSignal, call) {
     }, timeoutMs);
   });
   try {
-    return await Promise.race([guardProviderCall(() => call(signal), signal), timedOut]);
+    return await Promise.race([guardProviderCall(() => call(signal), signal, context), timedOut]);
   } finally {
     if (timer !== void 0) {
       clearTimeout(timer);
@@ -1777,22 +2035,22 @@ var HOSTED_PROVIDER_ENV_VARS = new Set(
 function isNotHostedProviderEnvVar(value) {
   return !HOSTED_PROVIDER_ENV_VARS.has(value.toUpperCase());
 }
-function isHttpOrHttpsUrl(value) {
-  try {
-    const { protocol } = new URL(value);
-    return protocol === "http:" || protocol === "https:";
-  } catch {
-    return false;
-  }
-}
+var HTTP_OR_HTTPS_SCHEME = /^https?:\/\//i;
 var openAiCompatibleConfigSchema = zod.z.object({
-  baseUrl: zod.z.url({ message: "baseUrl must be a valid absolute URL." }).refine(isHttpOrHttpsUrl, { message: "baseUrl must use the http or https scheme." }),
+  baseUrl: zod.z.url({ message: "baseUrl must be a valid absolute URL." }).regex(HTTP_OR_HTTPS_SCHEME, { message: "baseUrl must use the http or https scheme." }),
   model: zod.z.string().min(1),
   maxOutputTokens: zod.z.number().int().positive(),
   apiKeyEnvVar: zod.z.string().min(1).refine(isNotHostedProviderEnvVar, {
     message: "apiKeyEnvVar must not name a hosted provider's environment variable."
   }).optional()
 }).extend(requestTimeoutConfigSchema.shape);
+function endpointContextOf(baseUrl) {
+  try {
+    return { endpointHost: new URL(baseUrl).host };
+  } catch {
+    return void 0;
+  }
+}
 function createDefaultClient5(config) {
   const sdk = new OpenAI__default.default({
     apiKey: resolveOpenAiCompatibleKey(config.apiKeyEnvVar),
@@ -1824,19 +2082,21 @@ function createOpenAiCompatibleProvider(config, deps = {}) {
 }
 function createMechanism4(client, config) {
   const timeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  const endpoint = endpointContextOf(config.baseUrl);
   return {
     translate: async ({ payloadJson, signal }) => {
       const body = buildOpenAiRequest(config, payloadJson, "strict-schema", "max_tokens");
-      const completion = await callClient4(client, body, timeoutMs, signal);
+      const completion = await callClient4(client, body, timeoutMs, signal, endpoint);
       return extractOpenAiResult(completion, true);
     }
   };
 }
-function callClient4(client, body, timeoutMs, signal) {
+function callClient4(client, body, timeoutMs, signal, endpoint) {
   return withRequestTimeout(
     timeoutMs,
     signal,
-    (requestSignal) => client.chat.completions.create(body, { signal: requestSignal })
+    (requestSignal) => client.chat.completions.create(body, { signal: requestSignal }),
+    endpoint
   );
 }
 var SCAFFOLD_MODELS = {
@@ -1866,6 +2126,10 @@ var providerFactories = {
   deepl: (options) => createDeepLProvider(options),
   "openai-compatible": (options) => createOpenAiCompatibleProvider(options)
 };
+var PROVIDER_IDS = Object.keys(providerFactories);
+function hasProviderFactory(id) {
+  return Object.hasOwn(providerFactories, id);
+}
 function buildProvider(config) {
   const create = providerFactories[config.id];
   return create(config.options);
@@ -1886,11 +2150,12 @@ function findCaseInsensitiveDuplicate(locales) {
   return void 0;
 }
 var verbatraConfigSchema = zod.z.strictObject({
+  $schema: zod.z.string().optional(),
   sourceLocale: zod.z.string().min(1),
   targetLocales: zod.z.array(zod.z.string().min(1)).min(1),
   format: supportedFormatSchema,
   files: zod.z.strictObject({
-    pattern: zod.z.string().min(1),
+    pattern: zod.z.string().min(1).regex(/\{locale\}/, { message: `files.pattern must contain the ${LOCALE_TOKEN} token` }),
     localeStyle: zod.z.enum(LOCALE_STYLES).optional()
   }),
   provider: providerConfigSchema,
@@ -1912,9 +2177,6 @@ var verbatraConfigSchema = zod.z.strictObject({
     return `targetLocales must not contain case-insensitively duplicate locales: "${duplicate}"`;
   },
   path: ["targetLocales"]
-}).refine((config) => config.files.pattern.includes(LOCALE_TOKEN), {
-  message: `files.pattern must contain the ${LOCALE_TOKEN} token`,
-  path: ["files", "pattern"]
 });
 
 // src/config/load-config.ts
@@ -2059,114 +2321,13 @@ function createLocalePathResolver(cwd, config) {
   const style = config.files.localeStyle ?? DEFAULT_LOCALE_STYLE;
   const pattern = config.files.pattern;
   validatePattern(pattern, style);
-  const pathFor = (locale) => path.resolve(cwd, expandPattern(pattern, safeSpelling(locale, style, config.sourceLocale)));
-  const forward = buildForwardMap(config, pathFor);
-  return {
-    pathFor,
-    localeFor: (absolutePath) => forward.get(path.resolve(cwd, absolutePath))
-  };
-}
-var LOCAL_DIR_NAME = ".verbatra-local";
-var LOCK_FILE_GUARD_STEM = "_lockfile";
-var DEFAULT_POLL_INTERVAL_MS = 100;
-var DEFAULT_ACQUIRE_TIMEOUT_MS = 10 * 6e4;
-var WAIT_NOTICE_INTERVAL_MS = 1e3;
-var MAX_LOCK_PAYLOAD_BYTES = 64 * 1024;
-function lockPath(cwd, stem) {
-  return path.resolve(cwd, LOCAL_DIR_NAME, "locks", `${stem}.lock`);
-}
-function localeLockPath(cwd, locale) {
-  return lockPath(cwd, locale);
-}
-function lockFileGuardPath(cwd) {
-  return lockPath(cwd, LOCK_FILE_GUARD_STEM);
-}
-function sleep(ms) {
-  return new Promise((res) => {
-    setTimeout(res, ms);
-  });
-}
-function lockPayload() {
-  return JSON.stringify({ pid: process.pid, acquiredAt: (/* @__PURE__ */ new Date()).toISOString() });
-}
-function parseHolder(read) {
-  if (read.kind !== "ok") {
-    return void 0;
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(read.content);
-  } catch {
-    return void 0;
-  }
-  if (typeof parsed !== "object" || parsed === null) {
-    return void 0;
-  }
-  const record = parsed;
-  const holder = {};
-  if (typeof record.pid === "number") {
-    holder.pid = record.pid;
-  }
-  if (typeof record.acquiredAt === "string") {
-    holder.acquiredAt = record.acquiredAt;
-  }
-  return holder;
-}
-function makeWaitNotifier(path, fs, onWait, start) {
-  let holder;
-  let holderRead = false;
-  let lastEmit;
-  return async () => {
-    if (!holderRead) {
-      holderRead = true;
-      holder = parseHolder(await fs.readFileBounded(path, MAX_LOCK_PAYLOAD_BYTES));
-    }
-    const elapsedMs = Date.now() - start;
-    if (lastEmit !== void 0 && elapsedMs - lastEmit < WAIT_NOTICE_INTERVAL_MS) {
-      return;
-    }
-    lastEmit = elapsedMs;
-    onWait({ lockPath: path, elapsedMs, ...holder !== void 0 ? { holder } : {} });
-  };
-}
-async function acquireLock(path, fs, pollIntervalMs, deadline, notify) {
-  for (; ; ) {
-    if (await fs.createExclusive(path, lockPayload())) {
-      return;
-    }
-    if (notify !== void 0) {
-      await notify();
-    }
-    if (Date.now() >= deadline) {
-      throw new SdkError(
-        "LOCK_CONTENDED",
-        `Could not acquire the write lock at ${path}: another process may be holding it. If no verbatra process is currently running, this lock file was likely left behind by one that was killed; delete it and retry.`
-      );
-    }
-    const jitter = Math.random() * pollIntervalMs;
-    await sleep(pollIntervalMs + jitter);
-  }
-}
-async function withFileLock(path, fs, fn, options) {
-  const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-  const acquireTimeoutMs = options.acquireTimeoutMs ?? DEFAULT_ACQUIRE_TIMEOUT_MS;
-  const start = Date.now();
-  const notify = options.onWait !== void 0 ? makeWaitNotifier(path, fs, options.onWait, start) : void 0;
-  await acquireLock(path, fs, pollIntervalMs, start + acquireTimeoutMs, notify);
-  try {
-    return await fn();
-  } finally {
-    await fs.deleteFile(path);
-  }
-}
-async function withLocaleWriteLock(cwd, locale, fs, fn, options = {}) {
-  return withFileLock(localeLockPath(cwd, locale), fs, fn, options);
-}
-async function withLockFileGuard(cwd, fs, fn, options = {}) {
-  return withFileLock(lockFileGuardPath(cwd), fs, fn, options);
+  const pathFor = (locale) => path.resolve(cwd, expandPattern(pattern, safeSpelling(locale, style, config.sourceLocale)));
+  const forward = buildForwardMap(config, pathFor);
+  return {
+    pathFor,
+    localeFor: (absolutePath) => forward.get(path.resolve(cwd, absolutePath))
+  };
 }
-
-// src/lock/lock-file.ts
 var LOCK_FILE_NAME = "verbatra.lock.json";
 var CURRENT_VERSION2 = 1;
 var EMPTY_LOCK = { version: CURRENT_VERSION2, locales: {} };
@@ -2249,6 +2410,87 @@ async function updateLockFileLocale(cwd, fs, locale, patch) {
     return next;
   });
 }
+async function cleanup(ops, tmp) {
+  try {
+    await ops.rm(tmp);
+  } catch {
+  }
+}
+function tempFileName2(path$1) {
+  return path.join(path.dirname(path$1), `.${path.basename(path$1)}.tmp-${process.pid}-${Date.now()}-${crypto.randomUUID()}`);
+}
+async function atomicWriteFile(path$1, data, ops) {
+  const directory = path.dirname(path$1);
+  const tmp = tempFileName2(path$1);
+  try {
+    await ops.mkdir(directory);
+    await ops.writeFile(tmp, data);
+    await ops.fsyncFile(tmp);
+    await ops.rename(tmp, path$1);
+  } catch (error) {
+    await cleanup(ops, tmp);
+    throw error;
+  }
+  try {
+    await ops.fsyncDir(directory);
+  } catch {
+  }
+}
+async function readUtf8(handle, size) {
+  const buffer = Buffer.allocUnsafe(size);
+  let offset = 0;
+  while (offset < size) {
+    const { bytesRead } = await handle.read(buffer, offset, size - offset, offset);
+    if (bytesRead === 0) {
+      break;
+    }
+    offset += bytesRead;
+  }
+  return buffer.toString("utf8", 0, offset);
+}
+async function nodeReadBounded(path, maxBytes) {
+  const handle = await promises.open(path, "r");
+  try {
+    const info = await handle.stat();
+    if (!info.isFile()) {
+      return { kind: "not-a-file" };
+    }
+    if (info.size > maxBytes) {
+      return { kind: "too-large" };
+    }
+    return { kind: "ok", content: await readUtf8(handle, info.size) };
+  } finally {
+    await handle.close();
+  }
+}
+async function fsyncPath(path) {
+  const handle = await promises.open(path, "r");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+async function fsyncDirBestEffort(path) {
+  try {
+    await fsyncPath(path);
+  } catch {
+  }
+}
+var nodeOps = {
+  mkdir: async (path) => {
+    await promises.mkdir(path, { recursive: true });
+  },
+  writeFile: (path, data) => promises.writeFile(path, data, "utf8"),
+  fsyncFile: (path) => fsyncPath(path),
+  rename: (from, to) => promises.rename(from, to),
+  fsyncDir: (path) => fsyncDirBestEffort(path),
+  rm: (path) => promises.rm(path, { force: true })
+};
+var nodeAdapterFs = {
+  readBounded: nodeReadBounded,
+  writeFileAtomic: (path, data) => atomicWriteFile(path, data, nodeOps)
+};
 var VALID_EMPTY = { placeholders: [], isPlural: false, valid: true };
 var INVALID = { placeholders: [], isPlural: false, valid: false };
 function tokenOf(element) {
@@ -2718,85 +2960,12 @@ function buildCanHandle(extensions, sniff) {
     return sample === void 0 || sniff === void 0 || sniff(sample);
   };
 }
-async function fsyncPath(path) {
-  const handle = await promises.open(path, "r");
-  try {
-    await handle.sync();
-  } finally {
-    await handle.close();
-  }
-}
-async function fsyncDirBestEffort(path) {
-  try {
-    await fsyncPath(path);
-  } catch {
-  }
-}
-var nodeOps = {
-  mkdir: async (path) => {
-    await promises.mkdir(path, { recursive: true });
-  },
-  writeFile: (path, data) => promises.writeFile(path, data, "utf8"),
-  fsyncFile: (path) => fsyncPath(path),
-  rename: (from, to) => promises.rename(from, to),
-  fsyncDir: (path) => fsyncDirBestEffort(path),
-  rm: (path) => promises.rm(path, { force: true })
-};
-async function cleanup(ops, tmp) {
-  try {
-    await ops.rm(tmp);
-  } catch {
-  }
-}
-function tempFileName2(path$1) {
-  return path.join(path.dirname(path$1), `.${path.basename(path$1)}.tmp-${process.pid}-${Date.now()}-${crypto.randomUUID()}`);
-}
-async function atomicWriteFile(path$1, data, ops = nodeOps) {
-  const directory = path.dirname(path$1);
-  const tmp = tempFileName2(path$1);
-  try {
-    await ops.mkdir(directory);
-    await ops.writeFile(tmp, data);
-    await ops.fsyncFile(tmp);
-    await ops.rename(tmp, path$1);
-  } catch (error) {
-    await cleanup(ops, tmp);
-    throw error;
-  }
-  try {
-    await ops.fsyncDir(directory);
-  } catch {
-  }
-}
 function stripLeadingBom(content) {
   return content.charCodeAt(0) === 65279 ? content.slice(1) : content;
 }
-async function readBoundedUtf82(handle, size) {
-  const buffer = Buffer.allocUnsafe(size);
-  let offset = 0;
-  while (offset < size) {
-    const { bytesRead } = await handle.read(buffer, offset, size - offset, offset);
-    if (bytesRead === 0) {
-      break;
-    }
-    offset += bytesRead;
-  }
-  return stripLeadingBom(buffer.toString("utf8", 0, offset));
-}
-async function readBounded2(filePath) {
-  const handle = await promises.open(filePath, "r");
-  try {
-    const info = await handle.stat();
-    if (!info.isFile()) {
-      return { kind: "not-a-file" };
-    }
-    if (info.size > MAX_INPUT_BYTES) {
-      return { kind: "too-large" };
-    }
-    return { kind: "ok", content: await readBoundedUtf82(handle, info.size) };
-  } finally {
-    await handle.close();
-  }
+async function readBoundedFile(fs, filePath) {
+  const outcome = await fs.readBounded(filePath, MAX_INPUT_BYTES);
+  return outcome.kind === "ok" ? { kind: "ok", content: stripLeadingBom(outcome.content) } : outcome;
 }
 function outcomeToContent(outcome, notAFileMessage) {
   if (outcome.kind === "not-a-file") {
@@ -2807,8 +2976,8 @@ function outcomeToContent(outcome, notAFileMessage) {
   }
   return outcome.content;
 }
-async function readFileContent(filePath) {
-  const outcome = await readBounded2(filePath);
+async function readFileContent(fs, filePath) {
+  const outcome = await readBoundedFile(fs, filePath);
   return outcomeToContent(outcome, "The path is not a regular file.");
 }
 var BACKSLASH = "\\";
@@ -3019,7 +3188,8 @@ function createTreeFileAdapter(options) {
     buildWriteTree,
     comparePlaceholders,
     deriveDescriptions,
-    keyMode = "literal-leaf"
+    keyMode = "literal-leaf",
+    fs = nodeAdapterFs
   } = options;
   return {
     format,
@@ -3028,7 +3198,7 @@ function createTreeFileAdapter(options) {
     validateMessage: validateMessage ?? (() => true),
     ...comparePlaceholders !== void 0 ? { comparePlaceholders } : {},
     async read(filePath, locale) {
-      const content = await readFileContent(filePath);
+      const content = await readFileContent(fs, filePath);
       const namespace = namespaceOf(filePath);
       const { entries, excludedLeafPaths } = toEntries(
         content,
@@ -3044,8 +3214,8 @@ function createTreeFileAdapter(options) {
       return { resource, invalidIcuKeys, excludedLeafPaths };
     },
     async write(resource, filePath) {
-      const tree = buildWriteTree ? await buildWriteTree(resource.entries, filePath) : unflattenEntries(resource.entries);
-      await atomicWriteFile(filePath, serialize2(tree));
+      const tree = buildWriteTree ? await buildWriteTree(resource.entries, filePath, fs) : unflattenEntries(resource.entries);
+      await fs.writeFileAtomic(filePath, serialize2(tree));
     }
   };
 }
@@ -3106,10 +3276,10 @@ function messagesFromEntries(entries) {
   }
   return out;
 }
-async function readDestinationPairs(filePath) {
+async function readDestinationPairs(filePath, fs) {
   let content;
   try {
-    content = await readFileContent(filePath);
+    content = await readFileContent(fs, filePath);
   } catch (error) {
     if (isEnoent(error)) {
       return null;
@@ -3118,9 +3288,9 @@ async function readDestinationPairs(filePath) {
   }
   return [...parseArbObject(content)];
 }
-async function buildArbWriteTree(entries, filePath) {
+async function buildArbWriteTree(entries, filePath, fs) {
   const messages = messagesFromEntries(entries);
-  const pairs = await readDestinationPairs(filePath);
+  const pairs = await readDestinationPairs(filePath, fs);
   const out = /* @__PURE__ */ new Map();
   const consumed = /* @__PURE__ */ new Set();
   for (const [key, value] of pairs ?? []) {
@@ -3142,8 +3312,9 @@ async function buildArbWriteTree(entries, filePath) {
 function parseArb(content) {
   return assertJsonRecord(stripArbMetadata(parseArbObject(content)));
 }
-function createArbAdapter() {
+function createArbAdapter(fs = nodeAdapterFs) {
   return createTreeFileAdapter({
+    fs,
     format: "arb",
     extensions: [".arb"],
     sniff: sniffJsonObject,
@@ -3167,6 +3338,38 @@ function createJsonFileAdapter(options) {
     serialize: serializeJsonTree
   });
 }
+var SINGLE_BRACE_PATTERN = /(?<!\{)\{\s*([A-Za-z_][\w$-]*|\d+)\s*\}(?!\})/g;
+function extractSingleBraceTokens(value) {
+  return scanTokens(value, SINGLE_BRACE_PATTERN, (match) => {
+    const key = match[1];
+    return key !== void 0 ? `{${key}}` : void 0;
+  });
+}
+function fabricatedTokens(sourceValue, targetValue) {
+  const known = new Set(extractSingleBraceTokens(sourceValue));
+  const invented = /* @__PURE__ */ new Set();
+  for (const token of extractSingleBraceTokens(targetValue)) {
+    if (!known.has(token)) {
+      invented.add(token);
+    }
+  }
+  return [...invented].sort();
+}
+function createSingleBraceFabricationComparator(extract) {
+  return (sourceValue, targetValue) => {
+    const format = checkPlaceholders(extract(sourceValue), extract(targetValue));
+    const invented = fabricatedTokens(sourceValue, targetValue);
+    if (invented.length === 0) {
+      return format;
+    }
+    return {
+      matches: false,
+      missing: format.missing,
+      extra: [...format.extra, ...invented].sort(),
+      reordered: false
+    };
+  };
+}
 var DOUBLE_BRACE_PATTERN = /\{\{[^{}]*\}\}/g;
 var I18NEXT_PATTERN = /\{\{[^{}]*\}\}|\$t\([^()]*\)/g;
 function extractDoubleBracePlaceholders(value) {
@@ -3192,18 +3395,21 @@ function pluralBaseKey(key) {
 function makePluralKey(baseKey, category) {
   return `${baseKey}_${category}`;
 }
-function createI18nextJsonAdapter() {
+function createI18nextJsonAdapter(fs = nodeAdapterFs) {
   return createJsonFileAdapter({
+    fs,
     format: "i18next-json",
     extractPlaceholders: extractI18nextPlaceholders,
     deriveEntry: (key, value) => ({
       placeholders: extractI18nextPlaceholders(value),
       isPlural: isPluralKey(key)
-    })
+    }),
+    comparePlaceholders: createSingleBraceFabricationComparator(extractI18nextPlaceholders)
   });
 }
-function createNextIntlJsonAdapter() {
+function createNextIntlJsonAdapter(fs = nodeAdapterFs) {
   return createJsonFileAdapter({
+    fs,
     format: "next-intl-json",
     extractPlaceholders: icuPlaceholders,
     deriveEntry: icuDeriveEntry,
@@ -3244,10 +3450,10 @@ function assertNotMixed(tree) {
   }
   assertNoDottedNestedKey(tree);
 }
-async function detectStyle(filePath) {
+async function detectStyle(filePath, fs) {
   let parsed;
   try {
-    const outcome = await readBounded2(filePath);
+    const outcome = await readBoundedFile(fs, filePath);
     if (outcome.kind !== "ok") {
       return "nested";
     }
@@ -3272,18 +3478,20 @@ function buildFlatTree(entries) {
   }
   return out;
 }
-async function buildNgxWriteTree(entries, filePath) {
-  const style = await detectStyle(filePath);
+async function buildNgxWriteTree(entries, filePath, fs) {
+  const style = await detectStyle(filePath, fs);
   return style === "flat" ? buildFlatTree(entries) : unflattenEntries(entries);
 }
-function createNgxTranslateJsonAdapter() {
+function createNgxTranslateJsonAdapter(fs = nodeAdapterFs) {
   return createJsonFileAdapter({
+    fs,
     format: "ngx-translate-json",
     extractPlaceholders: extractDoubleBracePlaceholders,
     deriveEntry: (_key, value) => ({
       placeholders: extractDoubleBracePlaceholders(value),
       isPlural: false
     }),
+    comparePlaceholders: createSingleBraceFabricationComparator(extractDoubleBracePlaceholders),
     validateTree: assertNotMixed,
     buildWriteTree: buildNgxWriteTree,
     keyMode: "path-notation"
@@ -3305,7 +3513,8 @@ function createFlatFileAdapter(options) {
     serializeEntries,
     extractPlaceholders,
     validateMessage,
-    computeInvalidIcuKeys
+    computeInvalidIcuKeys,
+    fs = nodeAdapterFs
   } = options;
   return {
     format,
@@ -3313,7 +3522,7 @@ function createFlatFileAdapter(options) {
     extractPlaceholders,
     validateMessage: validateMessage ?? (() => true),
     async read(filePath, locale) {
-      const content = await readFileContent(filePath);
+      const content = await readFileContent(fs, filePath);
       const namespace = namespaceOf(filePath);
       const entries = toEntries2(content, namespace, parseEntries);
       const resource = { locale, namespace, format, entries };
@@ -3321,8 +3530,8 @@ function createFlatFileAdapter(options) {
       return { resource, invalidIcuKeys, excludedLeafPaths: [] };
     },
     async write(resource, filePath) {
-      const data = await serializeEntries(resource.entries, filePath);
-      await atomicWriteFile(filePath, data);
+      const data = await serializeEntries(resource.entries, filePath, fs);
+      await fs.writeFileAtomic(filePath, data);
     }
   };
 }
@@ -3330,13 +3539,13 @@ var SUBMESSAGE_TYPES = /* @__PURE__ */ new Set(["plural", "select", "selectordin
 var ARGUMENT_NAME = /^(?:\d+|[A-Za-z_$][\w$-]*)$/;
 function matchingBraces(value) {
   const close = new Int32Array(value.length).fill(-1);
-  const open3 = [];
+  const open22 = [];
   for (let i = 0; i < value.length; i += 1) {
     const char = value[i];
     if (char === "{") {
-      open3.push(i);
+      open22.push(i);
     } else if (char === "}") {
-      const start = open3.pop();
+      const start = open22.pop();
       if (start !== void 0) {
         close[start] = i;
       }
@@ -3356,13 +3565,13 @@ function findNameEnd(value, from, limit) {
   }
   return { comma: -1, hasBrace: false };
 }
-function parseArgumentAt(value, open3, close) {
-  const { comma, hasBrace } = findNameEnd(value, open3 + 1, close);
+function parseArgumentAt(value, open22, close) {
+  const { comma, hasBrace } = findNameEnd(value, open22 + 1, close);
   if (hasBrace) {
     return null;
   }
   const nameEnd = comma === -1 ? close : comma;
-  const name = value.slice(open3 + 1, nameEnd).trim();
+  const name = value.slice(open22 + 1, nameEnd).trim();
   if (!ARGUMENT_NAME.test(name)) {
     return null;
   }
@@ -3629,10 +3838,10 @@ function escapeString(input, isKey) {
 function formatEntry(key, value) {
   return `${escapeString(key, true)}=${escapeString(value, false)}`;
 }
-async function readStructure(filePath) {
+async function readStructure(filePath, fs) {
   let outcome;
   try {
-    outcome = await readBounded2(filePath);
+    outcome = await readBoundedFile(fs, filePath);
   } catch (error) {
     if (isEnoent(error)) {
       return { items: [], terminator: "\n" };
@@ -3645,8 +3854,8 @@ async function readStructure(filePath) {
     terminator: detectLineTerminator(content)
   };
 }
-async function serializePropertiesEntries(entries, filePath) {
-  const { items, terminator } = await readStructure(filePath);
+async function serializePropertiesEntries(entries, filePath, fs) {
+  const { items, terminator } = await readStructure(filePath, fs);
   const emitted = /* @__PURE__ */ new Set();
   const lines = [];
   for (const item of items) {
@@ -3667,8 +3876,9 @@ async function serializePropertiesEntries(entries, filePath) {
   }
   return lines.length === 0 ? "" : `${lines.join(terminator)}${terminator}`;
 }
-function createPropertiesAdapter() {
+function createPropertiesAdapter(fs = nodeAdapterFs) {
   return createFlatFileAdapter({
+    fs,
     format: "properties",
     extensions: [".properties"],
     parseEntries: parsePropertiesEntries,
@@ -3725,18 +3935,15 @@ var AdapterRegistry = class {
     return this.resolveByDetection(filePath, options.sample);
   }
 };
-var PLACEHOLDER_PATTERN = /(?<!\{)\{\s*([A-Za-z_][\w$-]*|\d+)\s*\}(?!\})/g;
 function extractVueI18nPlaceholders(value) {
-  return scanTokens(value, PLACEHOLDER_PATTERN, (match) => {
-    const key = match[1];
-    return key !== void 0 ? `{${key}}` : void 0;
-  });
+  return extractSingleBraceTokens(value);
 }
 function isPluralValue(value) {
   return value.includes("|");
 }
-function createVueI18nJsonAdapter() {
+function createVueI18nJsonAdapter(fs = nodeAdapterFs) {
   return createJsonFileAdapter({
+    fs,
     format: "vue-i18n-json",
     extractPlaceholders: extractVueI18nPlaceholders,
     deriveEntry: (_key, value) => ({
@@ -3883,10 +4090,10 @@ function parseXliffEntries(content, namespace) {
   }
   return out;
 }
-async function readDestination(filePath) {
+async function readDestination(filePath, fs) {
   let outcome;
   try {
-    outcome = await readBounded2(filePath);
+    outcome = await readBoundedFile(fs, filePath);
   } catch {
     throw new AdapterError("INVALID_STRUCTURE", "The destination XLIFF file does not exist.");
   }
@@ -3970,8 +4177,8 @@ function setTargetValue(doc, parser, element, value) {
     element.appendChild(doc.importNode(node, true));
   }
 }
-async function serializeXliffEntries(entries, filePath) {
-  const { doc, root } = parseXml(await readDestination(filePath));
+async function serializeXliffEntries(entries, filePath, fs) {
+  const { doc, root } = parseXml(await readDestination(filePath, fs));
   const parser = new xmldom.DOMParser({ onError: onFatal });
   for (const unit of walkUnits(root)) {
     const entry = entries.get(unit.key);
@@ -3989,8 +4196,9 @@ function sniffXliff(sample) {
   const head = sample.trimStart();
   return head.startsWith("<xliff") || head.startsWith("<?xml");
 }
-function createXliffAdapter() {
+function createXliffAdapter(fs = nodeAdapterFs) {
   return createFlatFileAdapter({
+    fs,
     format: "xliff",
     extensions: [".xlf", ".xliff"],
     sniff: sniffXliff,
@@ -4028,8 +4236,9 @@ function parseYamlObject(content) {
   assertWithinDepth(parsed, MAX_DEPTH);
   return assertJsonRecord(normalizeYamlTree(parsed));
 }
-function createYamlAdapter() {
+function createYamlAdapter(fs = nodeAdapterFs) {
   return createTreeFileAdapter({
+    fs,
     format: "yaml",
     extensions: [".yml", ".yaml"],
     parse: parseYamlObject,
@@ -4038,16 +4247,41 @@ function createYamlAdapter() {
     deriveEntry: (_key, value) => ({
       placeholders: extractDoubleBracePlaceholders(value),
       isPlural: false
-    })
+    }),
+    comparePlaceholders: createSingleBraceFabricationComparator(extractDoubleBracePlaceholders)
+  });
+}
+function createDefaultRegistry(fs = nodeAdapterFs) {
+  return new AdapterRegistry().register(createI18nextJsonAdapter(fs)).register(createVueI18nJsonAdapter(fs)).register(createNextIntlJsonAdapter(fs)).register(createNgxTranslateJsonAdapter(fs)).register(createXliffAdapter(fs)).register(createYamlAdapter(fs)).register(createArbAdapter(fs)).register(createPropertiesAdapter(fs));
+}
+function enoent(path) {
+  return Object.assign(new Error(`ENOENT: no such file or directory, open '${path}'`), {
+    code: "ENOENT"
   });
 }
-function createDefaultRegistry() {
-  return new AdapterRegistry().register(createI18nextJsonAdapter()).register(createVueI18nJsonAdapter()).register(createNextIntlJsonAdapter()).register(createNgxTranslateJsonAdapter()).register(createXliffAdapter()).register(createYamlAdapter()).register(createArbAdapter()).register(createPropertiesAdapter());
+function toAdapterFs(fs) {
+  return {
+    async readBounded(path, maxBytes) {
+      const outcome = await fs.readFileBounded(path, maxBytes);
+      if (outcome.kind === "missing") {
+        throw enoent(path);
+      }
+      if (outcome.kind === "too-large") {
+        return { kind: "too-large" };
+      }
+      return { kind: "ok", content: outcome.content };
+    },
+    async writeFileAtomic(path$1, data) {
+      await fs.mkdir?.(path.dirname(path$1));
+      await fs.writeFile(path$1, data);
+    }
+  };
 }
 
 // src/selection/select-adapter.ts
-function selectAdapter(format, registry = createDefaultRegistry()) {
-  const resolution = registry.resolve("", { format });
+function selectAdapter(format, registry, fs) {
+  const resolved = registry ?? createDefaultRegistry(fs === void 0 ? void 0 : toAdapterFs(fs));
+  const resolution = resolved.resolve("", { format });
   if (resolution.status === "resolved") {
     return resolution.adapter;
   }
@@ -4058,12 +4292,25 @@ function selectAdapter(format, registry = createDefaultRegistry()) {
 }
 
 // src/flow/read-target.ts
+function attributeTargetRead(error, locale, path) {
+  if (!(error instanceof AdapterError)) {
+    return error;
+  }
+  return new AdapterError(
+    error.code,
+    `The ${locale} locale file at ${path} could not be read: ${error.message}`
+  );
+}
 async function readTargetResource(input) {
   const path = input.resolver.pathFor(input.locale);
   if (!await input.fs.fileExists(path)) {
     return { locale: input.locale, namespace: "", format: input.format, entries: /* @__PURE__ */ new Map() };
   }
-  return (await input.adapter.read(path, input.locale)).resource;
+  try {
+    return (await input.adapter.read(path, input.locale)).resource;
+  } catch (error) {
+    throw attributeTargetRead(error, input.locale, path);
+  }
 }
 
 // src/flow/select-locales.ts
@@ -4121,7 +4368,7 @@ async function diffLocales(input, deps = {}) {
   const config = input.config;
   const cwd = input.cwd ?? process.cwd();
   const fs = deps.fs ?? defaultFs;
-  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const adapter = selectAdapter(config.format, deps.adapterRegistry, deps.fs);
   const resolver = createLocalePathResolver(cwd, config);
   const source = await readSourceResource(config, resolver, fs, adapter);
   const lock = await readLockFile(lockFilePath(cwd), fs);
@@ -4172,6 +4419,133 @@ async function diff(input, deps = {}) {
   return { hasPendingChanges: locales.some((entry) => entry.hasPendingChanges), locales };
 }
 
+// src/flow/doctor.ts
+var CHECK_TITLES = {
+  config: "Configuration",
+  "format-adapter": "Format adapter",
+  provider: "Provider",
+  "api-key": "API key environment variable",
+  "source-file": "Source locale file"
+};
+var CONFIG_DEPENDENT_IDS = [
+  "format-adapter",
+  "provider",
+  "api-key",
+  "source-file"
+];
+var SKIPPED_DETAIL = "Not checked: the configuration could not be loaded.";
+function check2(id, status, detail) {
+  return { id, title: CHECK_TITLES[id], status, detail };
+}
+function verdict(id, passed, detail) {
+  return check2(id, passed ? "pass" : "fail", detail);
+}
+function toResult(checks) {
+  return { ok: checks.every((entry) => entry.status !== "fail"), checks };
+}
+function loadOptionsFor(input, deps) {
+  return {
+    ...input.cwd !== void 0 ? { cwd: input.cwd } : {},
+    ...input.configPath !== void 0 ? { configPath: input.configPath } : {},
+    ...deps.fs !== void 0 ? { fs: deps.fs } : {}
+  };
+}
+function isMissingExplicitConfig(error, input) {
+  return input.configPath !== void 0 && error instanceof SdkError && error.code === "CONFIG_NOT_FOUND";
+}
+async function loadForDoctor(input, deps) {
+  const load = deps.loadConfig ?? loadConfigWithMeta;
+  try {
+    return { kind: "loaded", loaded: await load(loadOptionsFor(input, deps)) };
+  } catch (error) {
+    if (isMissingExplicitConfig(error, input)) {
+      throw error;
+    }
+    return { kind: "failed", detail: errorMessage(error) };
+  }
+}
+function configDetail(source) {
+  return source.kind === "override" ? "Validated the config supplied in memory." : `Loaded ${source.filepath}.`;
+}
+function resolveAdapter(config, deps) {
+  try {
+    const adapter = selectAdapter(config.format, deps.adapterRegistry, deps.fs);
+    return { kind: "resolved", adapter };
+  } catch (error) {
+    return { kind: "failed", detail: errorMessage(error) };
+  }
+}
+function checkAdapter(config, outcome) {
+  return outcome.kind === "resolved" ? verdict("format-adapter", true, `Format "${config.format}" resolves to an adapter.`) : verdict("format-adapter", false, outcome.detail);
+}
+function checkProvider(provider) {
+  return hasProviderFactory(provider.id) ? verdict("provider", true, `Provider "${provider.id}" resolves to a factory.`) : verdict(
+    "provider",
+    false,
+    `No factory is registered for provider "${provider.id}". Supported providers: ${PROVIDER_IDS.join(", ")}.`
+  );
+}
+function isEnvVarSet(name) {
+  const value = process.env[name];
+  return value !== void 0 && value.length > 0;
+}
+function envVarVerdict(name) {
+  return isEnvVarSet(name) ? verdict("api-key", true, `${name} is set.`) : verdict("api-key", false, `The ${name} environment variable is not set.`);
+}
+function checkOpenAiCompatibleKey(apiKeyEnvVar) {
+  if (apiKeyEnvVar === void 0) {
+    return verdict(
+      "api-key",
+      true,
+      `The openai-compatible provider needs no API key. Set ${OPENAI_COMPATIBLE_ENV_VAR} only if your server requires one, or name your own variable with provider.options.apiKeyEnvVar.`
+    );
+  }
+  return envVarVerdict(apiKeyEnvVar);
+}
+function checkApiKey(provider) {
+  return provider.id === "openai-compatible" ? checkOpenAiCompatibleKey(provider.options.apiKeyEnvVar) : envVarVerdict(PROVIDER_ENV[provider.id]);
+}
+var NOT_PARSED_DETAIL = "Its contents were not checked, because the configured format resolves to no adapter.";
+async function existenceOnlyVerdict(sourcePath, fs) {
+  return await fs.fileExists(sourcePath) ? verdict("source-file", true, `Found ${sourcePath}. ${NOT_PARSED_DETAIL}`) : verdict("source-file", false, `The source locale file was not found at ${sourcePath}.`);
+}
+async function parseSourceVerdict(config, resolver, fs, adapter, sourcePath) {
+  const { resource } = await readSourceResource(config, resolver, fs, adapter);
+  const count = resource.entries.size;
+  return verdict(
+    "source-file",
+    true,
+    `Read ${sourcePath} (${count} translatable ${count === 1 ? "key" : "keys"}).`
+  );
+}
+async function checkSourceFile(config, cwd, fs, outcome) {
+  try {
+    const resolver = createLocalePathResolver(cwd, config);
+    const sourcePath = resolver.pathFor(config.sourceLocale);
+    return outcome.kind === "resolved" ? await parseSourceVerdict(config, resolver, fs, outcome.adapter, sourcePath) : await existenceOnlyVerdict(sourcePath, fs);
+  } catch (error) {
+    return verdict("source-file", false, errorMessage(error));
+  }
+}
+async function doctor(input = {}, deps = {}) {
+  const outcome = await loadForDoctor(input, deps);
+  if (outcome.kind === "failed") {
+    return toResult([
+      verdict("config", false, outcome.detail),
+      ...CONFIG_DEPENDENT_IDS.map((id) => check2(id, "skipped", SKIPPED_DETAIL))
+    ]);
+  }
+  const { config, source } = outcome.loaded;
+  const adapter = resolveAdapter(config, deps);
+  return toResult([
+    verdict("config", true, configDetail(source)),
+    checkAdapter(config, adapter),
+    checkProvider(config.provider),
+    checkApiKey(config.provider),
+    await checkSourceFile(config, input.cwd ?? process.cwd(), deps.fs ?? defaultFs, adapter)
+  ]);
+}
+
 // src/cache/fingerprint.ts
 function fingerprintModel(provider) {
   const options = provider.options;
@@ -4208,13 +4582,51 @@ function gateCandidateValue(sourceEntry, candidateValue, adapter) {
   }
   return { accepted: true };
 }
+var REMEDY_BY_CODE = {
+  EACCES: "Check the write permissions on the containing directory, then run again.",
+  EPERM: "Check the write permissions on the containing directory, then run again.",
+  EROFS: "That file system is mounted read-only, so nothing can be written there.",
+  ENOSPC: "The device it lives on has no space left.",
+  ENOENT: "Check that the containing directory exists and is reachable, then run again.",
+  EISDIR: "A directory already exists at that path, so no file can take its place."
+};
+var DEFAULT_REMEDY = "Check that the containing directory exists and is writable, then run again.";
+function displayPath(targetPath, cwd) {
+  const relativePath = path.relative(cwd, targetPath);
+  if (relativePath.length === 0 || relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+    return targetPath;
+  }
+  return relativePath.split(path.sep).join("/");
+}
+function fsErrorCode(error) {
+  if (error instanceof Error && "code" in error && typeof error.code === "string") {
+    return error.code;
+  }
+  return void 0;
+}
+function targetUnwritableMessage(targetPath, cwd, error) {
+  const code = fsErrorCode(error);
+  const remedy = (code === void 0 ? void 0 : REMEDY_BY_CODE[code]) ?? DEFAULT_REMEDY;
+  const detail = code === void 0 ? "" : ` (${code})`;
+  return `Could not write the locale file ${displayPath(targetPath, cwd)}${detail}. ${remedy}`;
+}
+async function writeTargetResource(adapter, resource, targetPath, cwd) {
+  try {
+    await adapter.write(resource, targetPath);
+  } catch (error) {
+    if (error instanceof AdapterError || error instanceof SdkError) {
+      throw error;
+    }
+    throw new SdkError("TARGET_UNWRITABLE", targetUnwritableMessage(targetPath, cwd, error));
+  }
+}
 
 // src/flow/edit-entry.ts
 async function editEntry(input, deps = {}) {
   const config = input.config;
   const cwd = input.cwd ?? process.cwd();
   const fs = deps.fs ?? defaultFs;
-  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const adapter = selectAdapter(config.format, deps.adapterRegistry, deps.fs);
   const [locale] = selectLocales(config, [input.locale]);
   if (locale === void 0) {
     throw new SdkError("UNKNOWN_LOCALE", `Locale "${input.locale}" could not be resolved.`);
@@ -4236,9 +4648,11 @@ async function editEntry(input, deps = {}) {
     const merged = new Map(target.entries);
     merged.set(input.key, { ...sourceEntry, value: input.value, namespace: target.namespace });
     const path = createLocalePathResolver(cwd, config).pathFor(locale);
-    await adapter.write(
+    await writeTargetResource(
+      adapter,
       { locale, namespace: target.namespace, format: config.format, entries: merged },
-      path
+      path,
+      cwd
     );
     await updateLockFileLocale(cwd, fs, locale, {
       mode: "merge",
@@ -4289,7 +4703,7 @@ async function keyIntegrity(input, deps = {}) {
   const config = input.config;
   const cwd = input.cwd ?? process.cwd();
   const fs = deps.fs ?? defaultFs;
-  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const adapter = selectAdapter(config.format, deps.adapterRegistry, deps.fs);
   const resolver = createLocalePathResolver(cwd, config);
   const source = await readSourceResource(config, resolver, fs, adapter);
   const lock = await readLockFile(lockFilePath(cwd), fs);
@@ -4317,7 +4731,7 @@ async function keyValue(input, deps = {}) {
   const config = input.config;
   const cwd = input.cwd ?? process.cwd();
   const fs = deps.fs ?? defaultFs;
-  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const adapter = selectAdapter(config.format, deps.adapterRegistry, deps.fs);
   const [locale] = selectLocales(config, [input.locale]);
   if (locale === void 0) {
     throw new SdkError("UNKNOWN_LOCALE", `Locale "${input.locale}" could not be resolved.`);
@@ -4342,7 +4756,7 @@ async function keyValue(input, deps = {}) {
 async function readLocaleFileSnapshot(input, deps = {}) {
   const cwd = input.cwd ?? process.cwd();
   const fs = deps.fs ?? defaultFs;
-  const adapter = selectAdapter(input.config.format, deps.adapterRegistry);
+  const adapter = selectAdapter(input.config.format, deps.adapterRegistry, deps.fs);
   const resource = await readTarget(cwd, input.config, adapter, fs, input.locale);
   const hashes = /* @__PURE__ */ new Map();
   for (const [key, entry] of resource.entries) {
@@ -4391,7 +4805,7 @@ async function lockState(input, deps = {}) {
     return { exists: false };
   }
   const lock = await readLockFile(path, fs);
-  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const adapter = selectAdapter(config.format, deps.adapterRegistry, deps.fs);
   const source = await readSource(config, cwd, fs, adapter);
   const localeStates = await Promise.all(
     locales.map(async (locale) => {
@@ -4435,7 +4849,7 @@ async function retranslateEntry(input, deps = {}) {
   const config = input.config;
   const cwd = input.cwd ?? process.cwd();
   const fs = deps.fs ?? defaultFs;
-  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const adapter = selectAdapter(config.format, deps.adapterRegistry, deps.fs);
   const [locale] = selectLocales(config, [input.locale]);
   if (locale === void 0) {
     throw new SdkError("UNKNOWN_LOCALE", `Locale "${input.locale}" could not be resolved.`);
@@ -4477,9 +4891,11 @@ async function retranslateEntry(input, deps = {}) {
     const merged = new Map(target.entries);
     merged.set(input.key, { ...sourceEntry, value, namespace: target.namespace });
     const path = createLocalePathResolver(cwd, config).pathFor(locale);
-    await adapter.write(
+    await writeTargetResource(
+      adapter,
       { locale, namespace: target.namespace, format: config.format, entries: merged },
-      path
+      path,
+      cwd
     );
     await updateLockFileLocale(cwd, fs, locale, {
       mode: "merge",
@@ -4569,7 +4985,12 @@ function fromParsed(data) {
   };
 }
 async function readRunStatusFile(path, fs) {
-  const read = await fs.readFileBounded(path, MAX_RUN_STATUS_FILE_BYTES);
+  let read;
+  try {
+    read = await fs.readFileBounded(path, MAX_RUN_STATUS_FILE_BYTES);
+  } catch {
+    return void 0;
+  }
   if (read.kind !== "ok") {
     return void 0;
   }
@@ -5185,14 +5606,16 @@ async function runLocale(params) {
     generated: generation.accepted.length
   });
   if (writeNeeded) {
-    await params.adapter.write(
+    await writeTargetResource(
+      params.adapter,
       {
         locale: params.targetLocale,
         namespace: target.namespace,
         format: params.format,
         entries: merged
       },
-      path
+      path,
+      params.cwd
     );
   }
   const pluralNotices = params.generatePlurals ? pluralNoticeFor(params, merged) : sdkNotices;
@@ -5611,6 +6034,7 @@ async function translate2(input, deps = {}) {
   const config = input.config;
   const cwd = input.cwd ?? process.cwd();
   const dryRun = input.dryRun ?? false;
+  const targetLocales = selectLocales(config, input.locales);
   const concurrency = resolveRunConcurrency(input.concurrency, dryRun, config);
   const prune = input.prune ?? config.prune ?? false;
   const generatePlurals = input.generatePlurals ?? config.generatePlurals ?? false;
@@ -5621,7 +6045,7 @@ async function translate2(input, deps = {}) {
     config.budgetBehavior ?? DEFAULT_BUDGET_BEHAVIOR
   );
   const resolver = createLocalePathResolver(cwd, config);
-  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const adapter = selectAdapter(config.format, deps.adapterRegistry, deps.fs);
   const provider = dryRun ? void 0 : selectProvider(config.provider, deps.createProvider);
   const source = await readSourceResource(config, resolver, fs, adapter);
   const cache = await createRunCacheState(input, config, cwd, dryRun, fs);
@@ -5642,7 +6066,7 @@ async function translate2(input, deps = {}) {
     ...input.onProgress !== void 0 ? { onProgress: input.onProgress } : {},
     ...input.lockAcquireTimeoutMs !== void 0 ? { lockAcquireTimeoutMs: input.lockAcquireTimeoutMs } : {}
   };
-  const summaries = dryRun ? await runAllLocalesDry(context, config.targetLocales, concurrency) : await runAllLocalesLive(context, config.targetLocales, concurrency);
+  const summaries = dryRun ? await runAllLocalesDry(context, targetLocales, concurrency) : await runAllLocalesLive(context, targetLocales, concurrency);
   input.onProgress?.({ type: "run-finished", localesCompleted: summaries.length });
   const locales = withCacheNotices(summaries, cache);
   const { succeeded, partial, failed } = partition(locales);
@@ -6509,7 +6933,7 @@ async function exportWorkbook(input, deps = {}) {
   const config = input.config;
   const cwd = input.cwd ?? process.cwd();
   const fs = deps.fs ?? defaultFs;
-  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const adapter = selectAdapter(config.format, deps.adapterRegistry, deps.fs);
   const resolver = createLocalePathResolver(cwd, config);
   const source = await readSourceResource(config, resolver, fs, adapter);
   const lock = await readLockFile(lockFilePath(cwd), fs);
@@ -6860,14 +7284,16 @@ async function runSheet(ctx, sheet, lock) {
   const merged = mergeAccepted(target, accepted);
   if (accepted.size > 0) {
     const path = ctx.resolver.pathFor(sheet.locale);
-    await ctx.adapter.write(
+    await writeTargetResource(
+      ctx.adapter,
       {
         locale: sheet.locale,
         namespace: target.namespace,
         format: ctx.config.format,
         entries: merged
       },
-      path
+      path,
+      ctx.cwd
     );
   }
   return {
@@ -6881,7 +7307,7 @@ async function importWorkbook(input, deps = {}) {
   const cwd = input.cwd ?? process.cwd();
   const dryRun = input.dryRun ?? false;
   const fs = deps.fs ?? defaultFs;
-  const adapter = selectAdapter(config.format, deps.adapterRegistry);
+  const adapter = selectAdapter(config.format, deps.adapterRegistry, deps.fs);
   const resolver = createLocalePathResolver(cwd, config);
   const source = await readSourceResource(config, resolver, fs, adapter);
   const format = input.format ?? DEFAULT_EXCHANGE_FORMAT;
@@ -6894,6 +7320,7 @@ async function importWorkbook(input, deps = {}) {
   const lock = await readLockFile(lockFilePath(cwd), fs);
   const ctx = {
     config,
+    cwd,
     resolver,
     adapter,
     fs,
@@ -6924,6 +7351,9 @@ async function importWorkbook(input, deps = {}) {
       }
       summaries.push(summary);
     } catch (error) {
+      if (error instanceof SdkError && error.code === "LOCK_FILE_INVALID") {
+        throw error;
+      }
       summaries.push(failureSummary(sheet.locale, error));
     }
   }
@@ -6983,6 +7413,7 @@ async function watch(input, deps = {}) {
   const cwd = input.cwd ?? process.cwd();
   const debounceMs = input.debounceMs ?? DEFAULT_DEBOUNCE_MS;
   const fs = deps.fs ?? defaultFs;
+  selectLocales(input.config, input.locales);
   resolveRunConcurrency(input.concurrency, false, input.config);
   const resolver = createLocalePathResolver(cwd, input.config);
   const sourcePath = resolver.pathFor(input.config.sourceLocale);
@@ -6996,6 +7427,7 @@ async function watch(input, deps = {}) {
   const runInput = {
     config: input.config,
     cwd,
+    ...input.locales !== void 0 ? { locales: input.locales } : {},
     ...input.onLockWait !== void 0 ? { onLockWait: input.onLockWait } : {},
     ...input.onProgress !== void 0 ? { onProgress: input.onProgress } : {},
     ...input.lockAcquireTimeoutMs !== void 0 ? { lockAcquireTimeoutMs: input.lockAcquireTimeoutMs } : {},
@@ -7080,6 +7512,7 @@ exports.createLocalePathResolver = createLocalePathResolver;
 exports.defineConfig = defineConfig;
 exports.diff = diff;
 exports.diffLocaleSnapshots = diffLocaleSnapshots;
+exports.doctor = doctor;
 exports.editEntry = editEntry;
 exports.exportWorkbook = exportWorkbook;
 exports.importWorkbook = importWorkbook;
@@ -7089,11 +7522,13 @@ exports.loadConfig = loadConfig;
 exports.loadConfigWithMeta = loadConfigWithMeta;
 exports.loadLockFile = loadLockFile;
 exports.lockState = lockState;
+exports.readGlossaryFile = readGlossaryFile;
 exports.readLocaleFileSnapshot = readLocaleFileSnapshot;
 exports.retranslateEntry = retranslateEntry;
 exports.runStatus = runStatus;
 exports.scaffoldingMetadata = scaffoldingMetadata;
 exports.translate = translate2;
+exports.updateGlossaryTerm = updateGlossaryTerm;
 exports.verbatraConfigSchema = verbatraConfigSchema;
 exports.watch = watch;
 //# sourceMappingURL=index.cjs.map