@verbatra/sdk 0.9.0 → 0.9.3

package/dist/index.d.cts

@@ -1,6 +1,5 @@
 import { z } from 'zod';
 import Anthropic from '@anthropic-ai/sdk';
-import { Interactions } from '@google/genai';
 import OpenAI from 'openai';
 
 /**
@@ -236,12 +235,22 @@ interface TranslationProvider {
 type AnthropicModel = Anthropic.Messages.Model;
 
 /**
- * The Gemini authoring model type, sourced from the installed SDK's own model union so
- * verbatra restates no model IDs. It is an open union, so unknown model IDs are still
- * accepted. Type-only: it informs editor completions and is never validated at runtime,
- * where the schema stays `z.string().min(1)`.
- */
-type GeminiModel = Interactions.Model;
+ * The Gemini authoring model type. Unlike the sibling Anthropic and OpenAI model types, this
+ * union is hand-maintained rather than re-exported from `@google/genai`: every entry point of
+ * that package's `.d.ts` carries an unconditional top-level import of
+ * `@modelcontextprotocol/sdk/client/index.js`, an optional peer dependency it does not install.
+ * Re-exporting any type from that package, including its model union, drags that import into
+ * this package's own published types and breaks `tsc --noEmit` with `skipLibCheck: false` for
+ * any consumer who has not separately installed the MCP SDK. Keeping this list literal avoids
+ * that transitive dependency entirely.
+ *
+ * It is an open union (`(string & {})` at the end), so unknown or newly released model IDs are
+ * still accepted. Type-only: it informs editor completions and is never validated at runtime,
+ * where the schema stays `z.string().min(1)`. The list is current as of `@google/genai` 2.17.1
+ * and does not update automatically; refresh it by hand when adopting a newer SDK version that
+ * adds models worth completing on.
+ */
+type GeminiModel = "gemini-2.5-flash" | "gemini-2.5-pro" | "gemma-4-26b-a4b-it" | "gemma-4-31b-it" | "gemini-flash-latest" | "gemini-flash-lite-latest" | "gemini-pro-latest" | "gemini-2.5-flash-lite" | "gemini-2.5-flash-image" | "gemini-3-flash-preview" | "gemini-3.1-pro-preview" | "gemini-3.1-pro-preview-customtools" | "gemini-3.1-flash-lite" | "gemini-3-pro-image" | "nano-banana-pro-preview" | "gemini-3.1-flash-image" | "gemini-3.5-flash" | "gemini-3.6-flash" | "gemini-3.7-flash" | "lyria-3-clip-preview" | "lyria-3-pro-preview" | "gemini-robotics-er-1.6-preview" | "gemini-robotics-er-2-preview" | (string & {});
 
 /**
  * The OpenAI authoring model type, sourced from the OpenAI SDK's published chat-model union
@@ -795,8 +804,8 @@ interface LoadConfigOptions {
  */
 type ConfigSource = {
     /**
-     * `search` means cosmiconfig found the file by walking up from the working directory;
-     * `explicit` means the caller named it through `configPath`.
+     * `search` means cosmiconfig found the file by walking up from the working directory, up to
+     * the nearest `.git` directory; `explicit` means the caller named it through `configPath`.
      */
     readonly kind: "search" | "explicit";
     /** The absolute path of the config file that was loaded. */
@@ -821,12 +830,26 @@ interface LoadedConfig {
  *
  * Resolution order is: an explicit `configOverride`, then an explicit `configPath`, then a
  * cosmiconfig search upward from `cwd` across `verbatra.config.ts`, the `.verbatrarc` family, and a
- * `verbatra` property in `package.json`. A `configPath` that does not exist is an error rather than
- * a fallback to searching, so a typo in a path never silently loads a different project's config.
+ * `verbatra` property in `package.json`. The upward search stops at the nearest ancestor directory
+ * containing a `.git` entry; if none is found, it stops at the user's home directory when that is an
+ * ancestor of `cwd`, and otherwise it does not search above `cwd` at all, so a nested workspace
+ * package finds a config at its monorepo root without wandering above it, and a project outside the
+ * home directory tree (a CI checkout, for instance) never triggers an unbounded walk to the
+ * filesystem root. A config file outside that directory chain, including cosmiconfig's own OS-level
+ * global config directory, is never used, even though the underlying search strategy checks it; it is
+ * treated the same as no config found. A `configPath` that does not exist is an error rather than a
+ * fallback to searching, so a typo in a path never silently loads a different project's config.
  *
  * A glossary given as a path is read and validated here, so the returned config always carries a
  * resolved term map.
  *
+ * A `verbatra.config.ts` file is transpiled and loaded through jiti. When it imports `@verbatra/sdk`
+ * or `@verbatra/cli`, those bare specifiers are aliased to the package that is actually running this
+ * function, so the import resolves to the running version even when a different, conflicting version
+ * of either package also happens to be reachable from the config file's own location. A package is
+ * only aliased when its own entry point can be resolved from the running code; otherwise the import
+ * falls back to jiti's ordinary bare-specifier resolution, unchanged from before this behavior existed.
+ *
  * @param options - Where and how to look for the config.
  * @returns The validated config with its config-source and glossary provenance.
  *
@@ -841,8 +864,10 @@ declare function loadConfigWithMeta(options?: LoadConfigOptions): Promise<Loaded
  * pass the result to {@link translate}, {@link check}, {@link diff}, or any other entry point.
  *
  * Resolution order is an explicit `configOverride`, then an explicit `configPath`, then a
- * cosmiconfig search upward from `cwd`. A glossary declared as a file path is read and validated
- * here, so the returned {@link VerbatraConfig} always carries a resolved term map.
+ * cosmiconfig search upward from `cwd`, stopping at the nearest ancestor `.git` directory, or
+ * failing that, the user's home directory when it is an ancestor of `cwd`, or failing that, `cwd`
+ * itself. A glossary declared as a file path is read and validated here, so the returned
+ * {@link VerbatraConfig} always carries a resolved term map.
  *
  * Reach for {@link loadConfigWithMeta} when you also need to know which file was loaded.
  *

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 import { z } from 'zod';
 import Anthropic from '@anthropic-ai/sdk';
-import { Interactions } from '@google/genai';
 import OpenAI from 'openai';
 
 /**
@@ -236,12 +235,22 @@ interface TranslationProvider {
 type AnthropicModel = Anthropic.Messages.Model;
 
 /**
- * The Gemini authoring model type, sourced from the installed SDK's own model union so
- * verbatra restates no model IDs. It is an open union, so unknown model IDs are still
- * accepted. Type-only: it informs editor completions and is never validated at runtime,
- * where the schema stays `z.string().min(1)`.
- */
-type GeminiModel = Interactions.Model;
+ * The Gemini authoring model type. Unlike the sibling Anthropic and OpenAI model types, this
+ * union is hand-maintained rather than re-exported from `@google/genai`: every entry point of
+ * that package's `.d.ts` carries an unconditional top-level import of
+ * `@modelcontextprotocol/sdk/client/index.js`, an optional peer dependency it does not install.
+ * Re-exporting any type from that package, including its model union, drags that import into
+ * this package's own published types and breaks `tsc --noEmit` with `skipLibCheck: false` for
+ * any consumer who has not separately installed the MCP SDK. Keeping this list literal avoids
+ * that transitive dependency entirely.
+ *
+ * It is an open union (`(string & {})` at the end), so unknown or newly released model IDs are
+ * still accepted. Type-only: it informs editor completions and is never validated at runtime,
+ * where the schema stays `z.string().min(1)`. The list is current as of `@google/genai` 2.17.1
+ * and does not update automatically; refresh it by hand when adopting a newer SDK version that
+ * adds models worth completing on.
+ */
+type GeminiModel = "gemini-2.5-flash" | "gemini-2.5-pro" | "gemma-4-26b-a4b-it" | "gemma-4-31b-it" | "gemini-flash-latest" | "gemini-flash-lite-latest" | "gemini-pro-latest" | "gemini-2.5-flash-lite" | "gemini-2.5-flash-image" | "gemini-3-flash-preview" | "gemini-3.1-pro-preview" | "gemini-3.1-pro-preview-customtools" | "gemini-3.1-flash-lite" | "gemini-3-pro-image" | "nano-banana-pro-preview" | "gemini-3.1-flash-image" | "gemini-3.5-flash" | "gemini-3.6-flash" | "gemini-3.7-flash" | "lyria-3-clip-preview" | "lyria-3-pro-preview" | "gemini-robotics-er-1.6-preview" | "gemini-robotics-er-2-preview" | (string & {});
 
 /**
  * The OpenAI authoring model type, sourced from the OpenAI SDK's published chat-model union
@@ -795,8 +804,8 @@ interface LoadConfigOptions {
  */
 type ConfigSource = {
     /**
-     * `search` means cosmiconfig found the file by walking up from the working directory;
-     * `explicit` means the caller named it through `configPath`.
+     * `search` means cosmiconfig found the file by walking up from the working directory, up to
+     * the nearest `.git` directory; `explicit` means the caller named it through `configPath`.
      */
     readonly kind: "search" | "explicit";
     /** The absolute path of the config file that was loaded. */
@@ -821,12 +830,26 @@ interface LoadedConfig {
  *
  * Resolution order is: an explicit `configOverride`, then an explicit `configPath`, then a
  * cosmiconfig search upward from `cwd` across `verbatra.config.ts`, the `.verbatrarc` family, and a
- * `verbatra` property in `package.json`. A `configPath` that does not exist is an error rather than
- * a fallback to searching, so a typo in a path never silently loads a different project's config.
+ * `verbatra` property in `package.json`. The upward search stops at the nearest ancestor directory
+ * containing a `.git` entry; if none is found, it stops at the user's home directory when that is an
+ * ancestor of `cwd`, and otherwise it does not search above `cwd` at all, so a nested workspace
+ * package finds a config at its monorepo root without wandering above it, and a project outside the
+ * home directory tree (a CI checkout, for instance) never triggers an unbounded walk to the
+ * filesystem root. A config file outside that directory chain, including cosmiconfig's own OS-level
+ * global config directory, is never used, even though the underlying search strategy checks it; it is
+ * treated the same as no config found. A `configPath` that does not exist is an error rather than a
+ * fallback to searching, so a typo in a path never silently loads a different project's config.
  *
  * A glossary given as a path is read and validated here, so the returned config always carries a
  * resolved term map.
  *
+ * A `verbatra.config.ts` file is transpiled and loaded through jiti. When it imports `@verbatra/sdk`
+ * or `@verbatra/cli`, those bare specifiers are aliased to the package that is actually running this
+ * function, so the import resolves to the running version even when a different, conflicting version
+ * of either package also happens to be reachable from the config file's own location. A package is
+ * only aliased when its own entry point can be resolved from the running code; otherwise the import
+ * falls back to jiti's ordinary bare-specifier resolution, unchanged from before this behavior existed.
+ *
  * @param options - Where and how to look for the config.
  * @returns The validated config with its config-source and glossary provenance.
  *
@@ -841,8 +864,10 @@ declare function loadConfigWithMeta(options?: LoadConfigOptions): Promise<Loaded
  * pass the result to {@link translate}, {@link check}, {@link diff}, or any other entry point.
  *
  * Resolution order is an explicit `configOverride`, then an explicit `configPath`, then a
- * cosmiconfig search upward from `cwd`. A glossary declared as a file path is read and validated
- * here, so the returned {@link VerbatraConfig} always carries a resolved term map.
+ * cosmiconfig search upward from `cwd`, stopping at the nearest ancestor `.git` directory, or
+ * failing that, the user's home directory when it is an ancestor of `cwd`, or failing that, `cwd`
+ * itself. A glossary declared as a file path is read and validated here, so the returned
+ * {@link VerbatraConfig} always carries a resolved term map.
  *
  * Reach for {@link loadConfigWithMeta} when you also need to know which file was loaded.
  *

package/dist/index.js

@@ -2,12 +2,13 @@ import { dirname, resolve, join, basename, relative, isAbsolute, sep, extname }
 import { z } from 'zod';
 import { randomUUID } from 'crypto';
 import { mkdir, rm, access, open, writeFile, rename } from 'fs/promises';
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
+import { homedir } from 'os';
 import { cosmiconfig } from 'cosmiconfig';
 import { TypeScriptLoader } from 'cosmiconfig-typescript-loader';
+import { createRequire } from 'module';
 import Anthropic from '@anthropic-ai/sdk';
 import * as deepl from 'deepl-node';
-import { createRequire } from 'module';
 import log from 'loglevel';
 import { GoogleGenAI } from '@google/genai';
 import OpenAI from 'openai';
@@ -500,6 +501,67 @@ async function updateGlossaryTerm(input, deps = {}) {
     return entries;
   });
 }
+var SELF_ALIASED_PACKAGES = ["@verbatra/sdk", "@verbatra/cli"];
+var ENTRY_CONDITION_ORDER = ["import", "node", "default", "require"];
+function resolvePathsFromRunningModule(packageName) {
+  return createRequire(import.meta.url).resolve.paths(packageName) ?? [];
+}
+function readPackageManifestFromDisk(packageRoot) {
+  try {
+    return JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+var defaultModuleAliasDeps = {
+  resolvePaths: resolvePathsFromRunningModule,
+  readPackageManifest: readPackageManifestFromDisk
+};
+function resolveRootExportPath(manifest) {
+  const exportsField = manifest.exports;
+  if (typeof exportsField === "string") {
+    return exportsField;
+  }
+  if (typeof exportsField === "object" && exportsField !== null) {
+    const rootExport = exportsField["."];
+    if (typeof rootExport === "string") {
+      return rootExport;
+    }
+    if (typeof rootExport === "object" && rootExport !== null) {
+      for (const condition of ENTRY_CONDITION_ORDER) {
+        const candidate = rootExport[condition];
+        if (typeof candidate === "string") {
+          return candidate;
+        }
+      }
+    }
+  }
+  return manifest.main;
+}
+function findPackageEntry(packageName, deps) {
+  for (const candidateDir of deps.resolvePaths(packageName)) {
+    const packageRoot = join(candidateDir, packageName);
+    const manifest = deps.readPackageManifest(packageRoot);
+    if (manifest === void 0) {
+      continue;
+    }
+    const relativeEntry = resolveRootExportPath(manifest);
+    if (relativeEntry !== void 0) {
+      return join(packageRoot, relativeEntry);
+    }
+  }
+  return void 0;
+}
+function resolveSelfPackageAliases(deps = defaultModuleAliasDeps) {
+  const aliases = {};
+  for (const packageName of SELF_ALIASED_PACKAGES) {
+    const entry = findPackageEntry(packageName, deps);
+    if (entry !== void 0) {
+      aliases[packageName] = entry;
+    }
+  }
+  return aliases;
+}
 async function resolveGlossary(glossary, baseDir, fs) {
   if (glossary === void 0) {
     return { glossary: void 0, provenance: { source: "none" } };
@@ -2164,6 +2226,50 @@ var SEARCH_PLACES = [
   `${MODULE_NAME}.config.cjs`,
   `${MODULE_NAME}.config.ts`
 ];
+function isAncestorOrSelf(ancestor, startDir) {
+  const target = resolve(ancestor);
+  let dir = resolve(startDir);
+  while (true) {
+    if (dir === target) {
+      return true;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return false;
+    }
+    dir = parent;
+  }
+}
+function findSearchStopDir(startDir) {
+  let dir = resolve(startDir);
+  while (true) {
+    if (existsSync(join(dir, ".git"))) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  const home = resolve(homedir());
+  return isAncestorOrSelf(home, startDir) ? home : resolve(startDir);
+}
+function collectSearchChain(startDir, stopDir) {
+  const stop = resolve(stopDir);
+  const chain = /* @__PURE__ */ new Set();
+  let dir = resolve(startDir);
+  while (dir !== stop) {
+    chain.add(dir);
+    const parent = dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  chain.add(stop);
+  return chain;
+}
 function formatIssues(error) {
   return error.issues.map((issue) => {
     const path = issue.path.join(".");
@@ -2213,20 +2319,30 @@ async function loadConfigWithMeta(options = {}) {
     const { config: config2, glossary: glossary2 } = await finalizeConfig(parsed2, options.cwd ?? process.cwd(), fs);
     return { config: config2, source: { kind: "override" }, glossary: glossary2 };
   }
+  const cwd = options.cwd ?? process.cwd();
+  const stopDir = findSearchStopDir(cwd);
   const explorer = cosmiconfig(MODULE_NAME, {
     searchPlaces: SEARCH_PLACES,
-    loaders: { ".ts": TypeScriptLoader() }
+    loaders: { ".ts": TypeScriptLoader({ alias: resolveSelfPackageAliases() }) },
+    searchStrategy: "global",
+    stopDir
   });
   if (options.configPath !== void 0) {
     return loadExplicitWithMeta(explorer, options.configPath, options.cwd, fs);
   }
   let result;
   try {
-    result = await explorer.search(options.cwd);
+    result = await explorer.search(cwd);
   } catch (error) {
     const detail = errorMessage(error);
     throw new SdkError("CONFIG_INVALID", `Failed to load the verbatra configuration: ${detail}`);
   }
+  if (result !== null && result.isEmpty !== true) {
+    const resultDir = dirname(resolve(result.filepath));
+    if (!collectSearchChain(cwd, stopDir).has(resultDir)) {
+      result = null;
+    }
+  }
   if (result === null || result.isEmpty === true) {
     throw new SdkError(
       "CONFIG_NOT_FOUND",