@elench/testkit 0.1.117 → 0.1.119

package/lib/config-api/index.d.ts

@@ -9,14 +9,13 @@ export interface DatabaseTemplateConfig {
 
 export interface DatabaseTemplateOptions {
   inputs?: string[];
-  migrate?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[];
-  seed?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[];
-  verify?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[];
+  migrate?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
+  seed?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
+  verify?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
 }
 
 export interface DatabaseSourceSchemaOptions {
-  cachePath?: string;
-  refresh?: "always" | { ttlSeconds: number };
+  refresh?: "auto" | "always" | { ttlSeconds: number };
   unavailable?: "auto" | "fail" | "warn-cache";
   verify?: boolean;
 }
@@ -27,6 +26,7 @@ export interface DatabaseSourceSchemaConfig extends DatabaseSourceSchemaOptions
 }
 
 export interface TemplateStepBaseConfig {
+  args?: unknown;
   cwd?: string;
   inputs?: string[];
 }
@@ -51,6 +51,8 @@ export type TemplateLifecycleStepConfig =
   | TemplateSqlFileStepConfig
   | TemplateModuleStepConfig;
 
+export interface TemplateLifecycleStepOptions extends TemplateStepBaseConfig {}
+
 export interface TscBuildConfig {
   kind: "tsc";
   cwd?: string;
@@ -380,6 +382,8 @@ export interface NodeAppOptions extends Omit<ServiceConfig, "local" | "runtime"
 }
 
 export interface NextAppOptions extends Omit<ServiceConfig, "local" | "runtime" | "env"> {
+  api?: string | { baseUrl: string };
+  auth?: "disabled-clerk" | { kind: "disabled-clerk" };
   baseUrl?: string;
   build?: BuildConfig | null;
   buildInputs?: string[];
@@ -414,6 +418,14 @@ export interface TestkitConfig {
   };
 }
 
+export interface NodeNextPresetOptions {
+  fileTimeoutSeconds?: number;
+  install?: "require-host" | "download";
+  node?: string;
+  npm?: string;
+  workers?: number;
+}
+
 export declare function defineConfig<T extends TestkitConfig>(config: T): T;
 export declare function defineFile<T extends TestkitFileMetadata>(metadata: T): T;
 export declare const app: {
@@ -424,19 +436,39 @@ export declare const database: {
   schema: {
     fromEnv(envName: string, options?: DatabaseSourceSchemaOptions): DatabaseSourceSchemaConfig;
   };
+  steps: {
+    materializePostgresBinding(options?: unknown): TemplateModuleStepConfig;
+    verifySeed(options?: unknown): TemplateModuleStepConfig;
+  };
   postgres(
     options?: Omit<LocalDatabaseConfig, "provider" | "template"> & {
+      inputs?: string[];
+      migrate?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
+      seed?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
       template?: DatabaseTemplateOptions;
+      verify?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
     }
   ): LocalDatabaseConfig;
   fixture(
     options?: Omit<LocalDatabaseConfig, "provider" | "template"> & {
+      inputs?: string[];
+      migrate?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
+      seed?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
       template?: DatabaseTemplateOptions;
+      verify?: TemplateLifecycleStepConfig | TemplateLifecycleStepConfig[] | string | string[];
       discovery?: DiscoveryConfig;
       envFiles?: string[];
     }
   ): ServiceConfig;
 };
+export declare const step: {
+  command(run: string, options?: TemplateLifecycleStepOptions): TemplateCommandStepConfig;
+  module(target: string, options?: TemplateLifecycleStepOptions): TemplateModuleStepConfig;
+  sqlFile(path: string, options?: TemplateLifecycleStepOptions): TemplateSqlFileStepConfig;
+};
+export declare const presets: {
+  nodeNext(options?: NodeNextPresetOptions): Pick<TestkitConfig, "execution" | "toolchains">;
+};
 export declare const toolchain: {
   node(options?: NodeToolchainConfig): NodeToolchainConfig;
 };

package/lib/config-api/index.mjs

@@ -53,10 +53,47 @@ function buildDatabaseTemplateConfig(options = {}) {
   };
 }
 
+function commandStep(run, options = {}) {
+  return {
+    kind: "command",
+    run,
+    ...copyStepOptions(options),
+  };
+}
+
+function sqlFileStep(filePath, options = {}) {
+  return {
+    kind: "sql-file",
+    path: filePath,
+    ...copyStepOptions(options),
+  };
+}
+
+function moduleStep(target, options = {}) {
+  return {
+    kind: "module",
+    target,
+    ...copyStepOptions(options),
+  };
+}
+
+function copyStepOptions(options = {}) {
+  return {
+    ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+    ...(options.inputs !== undefined ? { inputs: [...options.inputs] } : {}),
+    ...(options.args !== undefined ? { args: options.args } : {}),
+  };
+}
+
 function sourceSchemaFromEnv(envName, options = {}) {
   if (typeof envName !== "string" || envName.trim().length === 0) {
     throw new Error("database.schema.fromEnv(...) requires a non-empty env var name");
   }
+  if (Object.prototype.hasOwnProperty.call(options, "cachePath")) {
+    throw new Error(
+      "database.schema.fromEnv(...) no longer accepts cachePath. Testkit now manages commit-scoped source schema caches automatically."
+    );
+  }
   return {
     kind: "env",
     env: envName.trim(),
@@ -64,15 +101,30 @@ function sourceSchemaFromEnv(envName, options = {}) {
   };
 }
 
+function databaseStepTarget(exportName) {
+  return `@elench/testkit/config/database-steps#${exportName}`;
+}
+
+function verifySeedStep(options = {}) {
+  return moduleStep(databaseStepTarget("verifySeed"), { args: options });
+}
+
+function materializePostgresBindingStep(options = {}) {
+  return moduleStep(databaseStepTarget("materializePostgresBinding"), { args: options });
+}
+
 function postgresFixture(options = {}) {
-  const { discovery, envFiles, template, ...databaseOptions } = options;
-  for (const legacyKey of ["inputs", "schema", "migrate", "seed", "verify"]) {
+  const { discovery, envFiles, template, inputs, migrate, seed, verify, ...databaseOptions } = options;
+  for (const legacyKey of ["schema"]) {
     if (Object.prototype.hasOwnProperty.call(options, legacyKey)) {
       throw new Error(
-        `database.fixture(...) no longer accepts top-level "${legacyKey}". Move lifecycle config under database.fixture({ template: { ... } }).`
+        `database.fixture(...) no longer accepts "${legacyKey}". Configure database.sourceSchema instead.`
       );
     }
   }
+  const resolvedTemplate = template || hasTemplateLifecycle(options)
+    ? buildDatabaseTemplateConfig({ inputs, migrate, seed, verify, ...(template || {}) })
+    : undefined;
   return {
     discovery: discovery || {
       roots: [".testkit-fixture"],
@@ -80,16 +132,22 @@ function postgresFixture(options = {}) {
     envFiles,
     local: false,
     database: postgresDatabase(
-      template
+      resolvedTemplate
         ? {
             ...databaseOptions,
-            template: buildDatabaseTemplateConfig(template),
+            template: resolvedTemplate,
           }
         : databaseOptions
     ),
   };
 }
 
+function hasTemplateLifecycle(options = {}) {
+  return ["inputs", "migrate", "seed", "verify"].some((key) =>
+    Object.prototype.hasOwnProperty.call(options, key)
+  );
+}
+
 function nodeToolchain(options = {}) {
   return {
     kind: "node",
@@ -190,6 +248,8 @@ function nodeApp(options = {}) {
 
 function nextApp(options = {}) {
   const {
+    api,
+    auth: authMode,
     baseUrl: explicitBaseUrl,
     browser,
     build: explicitBuild,
@@ -209,7 +269,10 @@ function nextApp(options = {}) {
   } = options;
 
   const normalizedPort = requiredNumber(port, "app.next port");
-  const normalizedEnv = normalizePresetEnv(env);
+  const normalizedEnv = {
+    ...normalizeNextPresetEnv({ api, authMode }),
+    ...normalizePresetEnv(env),
+  };
   const baseUrl = explicitBaseUrl || "http://127.0.0.1:{port}";
   const build =
     explicitBuild === undefined
@@ -261,12 +324,16 @@ export const database = {
   schema: {
     fromEnv: sourceSchemaFromEnv,
   },
+  steps: {
+    materializePostgresBinding: materializePostgresBindingStep,
+    verifySeed: verifySeedStep,
+  },
   postgres(options = {}) {
-    const { template, sourceSchema, ...databaseOptions } = options;
-    for (const legacyKey of ["inputs", "schema", "migrate", "seed", "verify"]) {
+    const { template, sourceSchema, inputs, migrate, seed, verify, ...databaseOptions } = options;
+    for (const legacyKey of ["schema"]) {
       if (Object.prototype.hasOwnProperty.call(options, legacyKey)) {
         throw new Error(
-          `database.postgres(...) no longer accepts top-level "${legacyKey}". Move lifecycle config under database.postgres({ template: { ... } }).`
+          `database.postgres(...) no longer accepts "${legacyKey}". Use database.postgres({ sourceSchema: database.schema.fromEnv(...) }) instead.`
         );
       }
     }
@@ -276,11 +343,14 @@ export const database = {
           ...databaseOptions,
           sourceSchema,
         };
+    const resolvedTemplate = template || hasTemplateLifecycle(options)
+      ? buildDatabaseTemplateConfig({ inputs, migrate, seed, verify, ...(template || {}) })
+      : undefined;
     return postgresDatabase(
-      template
+      resolvedTemplate
         ? {
             ...normalizedDatabaseOptions,
-            template: buildDatabaseTemplateConfig(template),
+            template: resolvedTemplate,
           }
         : normalizedDatabaseOptions
     );
@@ -288,6 +358,30 @@ export const database = {
   fixture: postgresFixture,
 };
 
+export const step = {
+  command: commandStep,
+  module: moduleStep,
+  sqlFile: sqlFileStep,
+};
+
+export const presets = {
+  nodeNext(options = {}) {
+    return {
+      execution: {
+        workers: options.workers ?? 1,
+        fileTimeoutSeconds: options.fileTimeoutSeconds ?? 120,
+      },
+      toolchains: {
+        node: nodeToolchain({
+          install: options.install ?? "download",
+          ...(options.node ? { node: options.node } : {}),
+          ...(options.npm ? { npm: options.npm } : {}),
+        }),
+      },
+    };
+  },
+};
+
 export const toolchain = {
   node: nodeToolchain,
 };
@@ -378,6 +472,22 @@ function normalizeDatabaseEnvToken(value, label, sanitize = true) {
   return normalized;
 }
 
+function normalizeNextPresetEnv({ api, authMode } = {}) {
+  const env = {};
+  if (api) {
+    const baseUrlToken = typeof api === "string" ? api : api.baseUrl;
+    if (baseUrlToken) {
+      env.NEXT_PUBLIC_API_URL = baseUrlToken;
+    }
+  }
+  if (authMode === "disabled-clerk" || authMode?.kind === "disabled-clerk") {
+    env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY = "testkit_disabled";
+    env.CLERK_SECRET_KEY = "testkit_disabled";
+    env.CLERK_WEBHOOK_SECRET = "testkit_disabled";
+  }
+  return env;
+}
+
 function resolveNodeAppStart(build, entry) {
   if (build?.kind === "tsc") {
     const compiled = compiledEntryFromSource(entry || build.entry || "src/index.ts", build.outDir || "dist");
@@ -388,7 +498,8 @@ function resolveNodeAppStart(build, entry) {
 
 function normalizeTemplateStepList(value) {
   if (value == null) return [];
-  return Array.isArray(value) ? [...value] : [value];
+  const values = Array.isArray(value) ? value : [value];
+  return values.map((entry) => typeof entry === "string" ? commandStep(entry) : entry);
 }
 
 function compiledEntryFromSource(entry, outDir) {

package/lib/database/fingerprint.mjs

@@ -8,7 +8,7 @@ import { appendSourceSchemaCacheToHash } from "./schema-source.mjs";
 const LOCAL_IMAGE = "pgvector/pgvector:pg16";
 const LOCAL_USER = "testkit";
 
-export async function computeTemplateFingerprint(config) {
+export async function computeTemplateFingerprint(config, options = {}) {
   const hash = crypto.createHash("sha256");
   const db = config.testkit.database;
   hash.update(JSON.stringify({
@@ -25,7 +25,7 @@ export async function computeTemplateFingerprint(config) {
   for (const input of collectTemplateInputs(config.productDir, db.template || {})) {
     appendResolvedInputToHash(hash, config.productDir, input);
   }
-  appendSourceSchemaCacheToHash(hash, config);
+  appendSourceSchemaCacheToHash(hash, config, options.sourceSchemaState || null);
 
   return hash.digest("hex");
 }

package/lib/database/index.mjs

@@ -147,7 +147,7 @@ async function prepareLocalDatabase(config, options = {}) {
 
   await withLock(path.join(lockDir, `template-${serviceName}.lock`), async () => {
     const sourceSchemaState = await prepareSourceSchemaCache(config, options);
-    templateFingerprint = await computeTemplateFingerprint(config);
+    templateFingerprint = await computeTemplateFingerprint(config, { sourceSchemaState });
     templateFingerprint = await ensureTemplateDatabase(
       config,
       infra,
@@ -209,7 +209,7 @@ async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerpri
       await dropDatabaseIfExists(infra, desiredDbName);
       sourceSchemaState = await forceRefreshSourceSchemaCache(config, sourceSchemaState, options);
       refreshedSourceAfterMismatch = true;
-      activeFingerprint = await computeTemplateFingerprint(config);
+      activeFingerprint = await computeTemplateFingerprint(config, { sourceSchemaState });
       continue;
     }
 
@@ -638,8 +638,8 @@ function isUnsupportedForceDropError(error) {
   );
 }
 
-async function computeTemplateFingerprint(config) {
-  return computeTemplateFingerprintModel(config);
+async function computeTemplateFingerprint(config, options = {}) {
+  return computeTemplateFingerprintModel(config, options);
 }
 
 function appendInputToHash(hash, productDir, input) {

package/lib/database/schema-source.mjs

@@ -2,33 +2,54 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 import { execa } from "execa";
-import { resolveServiceCwd } from "../config/paths.mjs";
+import { collectRepoState, summarizeRepoStateForMetadata } from "../repo/state.mjs";
 import { buildExecutionEnv } from "../runner/template.mjs";
 import { dumpPostgresSchemaToFile, captureTemplateSnapshotText, runTemplateStep, sanitizeSnapshotText } from "./template-steps.mjs";
 import { getSourceSchemaRefreshLockPath, withSourceSchemaRefreshLock } from "./source-refresh-lock.mjs";
 import { resolveSourceSchemaDumpUrl } from "./source-url.mjs";
 
 const SOURCE_SCHEMA_DIR = path.join(".testkit", "db");
+const SOURCE_SCHEMA_CACHE_DIR = "source-schemas";
 const SOURCE_SCHEMA_FILE = "source-schema.sql";
 const SOURCE_SCHEMA_META_FILE = "source-schema.meta.json";
+const SOURCE_SCHEMA_INDEX_FILE = "index.json";
+const SOURCE_SCHEMA_MAX_ENTRIES = 20;
 
-export function getSourceSchemaCachePath(config) {
-  const configured = config.testkit.database?.sourceSchema?.cachePath || null;
-  return configured
-    ? resolveServiceCwd(config.productDir, configured)
-    : path.join(config.productDir, SOURCE_SCHEMA_DIR, config.name, SOURCE_SCHEMA_FILE);
+export function getSourceSchemaRootDir(config) {
+  return path.join(config.productDir, SOURCE_SCHEMA_DIR, config.name, SOURCE_SCHEMA_CACHE_DIR);
 }
 
-export function getSourceSchemaMetadataPath(config) {
-  const cachePath = getSourceSchemaCachePath(config);
+export function getSourceSchemaCachePath(config, options = {}) {
+  return resolveSourceSchemaCacheLocation(config, options).cachePath;
+}
+
+export function getSourceSchemaMetadataPath(config, options = {}) {
+  const cachePath = getSourceSchemaCachePath(config, options);
   return path.join(path.dirname(cachePath), SOURCE_SCHEMA_META_FILE);
 }
 
+export function resolveSourceSchemaCacheLocation(config, options = {}) {
+  const repoState = options.repoState || collectRepoState(config.productDir);
+  const rootDir = getSourceSchemaRootDir(config);
+  const cacheDir = path.join(rootDir, ...repoState.cacheKey.split("/").map(sanitizePathSegment));
+  return {
+    rootDir,
+    cacheDir,
+    cachePath: path.join(cacheDir, SOURCE_SCHEMA_FILE),
+    metadataPath: path.join(cacheDir, SOURCE_SCHEMA_META_FILE),
+    indexPath: path.join(rootDir, SOURCE_SCHEMA_INDEX_FILE),
+    cacheKey: repoState.cacheKey,
+    cacheKind: repoState.kind,
+    repoState,
+  };
+}
+
 export function resolveSourceSchemaState(config, options = {}) {
   const sourceSchema = config.testkit.database?.sourceSchema || null;
   if (!sourceSchema) return { active: false };
 
-  const cachePath = getSourceSchemaCachePath(config);
+  const location = resolveSourceSchemaCacheLocation(config, options);
+  const cachePath = location.cachePath;
   const cacheExists = fs.existsSync(cachePath);
   const env = buildExecutionEnv(config, {}, options.env || process.env);
   const envNames = sourceSchema.kind === "env"
@@ -43,12 +64,19 @@ export function resolveSourceSchemaState(config, options = {}) {
   return {
     active: true,
     cachePath,
-    metadataPath: getSourceSchemaMetadataPath(config),
+    metadataPath: location.metadataPath,
+    indexPath: location.indexPath,
+    rootDir: location.rootDir,
+    cacheDir: location.cacheDir,
+    cacheKey: location.cacheKey,
+    cacheKind: location.cacheKind,
+    repoState: location.repoState,
     envName,
     sourceUrl,
     sourceSchema,
     cacheExists,
     refreshed: false,
+    ci: env.CI === "true",
     unavailableMode: resolveUnavailableMode(sourceSchema.unavailable, options.env || process.env),
   };
 }
@@ -60,8 +88,11 @@ export async function prepareSourceSchemaCache(config, options = {}) {
   if (state.sourceUrl) {
     if (shouldRefreshSourceSchema(state)) {
       const refreshInfo = await refreshSourceSchemaCache(config, state, options);
-      return { ...state, refreshed: true, cacheExists: true, refreshInfo };
+      const refreshedState = { ...state, refreshed: true, cacheExists: true, refreshInfo };
+      updateSourceSchemaIndex(config, refreshedState, { refreshed: true });
+      return refreshedState;
     }
+    updateSourceSchemaIndex(config, state);
     options.setupRegistry?.recordCached({
       config,
       stage: "source-schema",
@@ -72,6 +103,7 @@ export async function prepareSourceSchemaCache(config, options = {}) {
   }
 
   if (state.cacheExists && state.unavailableMode === "warn-cache") {
+    updateSourceSchemaIndex(config, state);
     options.setupRegistry?.recordCached({
       config,
       stage: "source-schema",
@@ -96,7 +128,9 @@ export async function forceRefreshSourceSchemaCache(config, previousState, optio
     throw new Error(`Cannot refresh source schema for service "${config.name}" because ${envLabel} is unavailable.`);
   }
   const refreshInfo = await refreshSourceSchemaCache(config, state, options);
-  return { ...state, refreshed: true, cacheExists: true, refreshInfo };
+  const refreshedState = { ...state, refreshed: true, cacheExists: true, refreshInfo };
+  updateSourceSchemaIndex(config, refreshedState, { refreshed: true });
+  return refreshedState;
 }
 
 export async function applySourceSchemaCache(config, databaseUrl, state, options = {}) {
@@ -158,10 +192,12 @@ export function createSourceSchemaMismatchError(config, state, verification) {
   return new Error(parts.join("\n"));
 }
 
-export function appendSourceSchemaCacheToHash(hash, config) {
+export function appendSourceSchemaCacheToHash(hash, config, state = null) {
   const sourceSchema = config.testkit.database?.sourceSchema || null;
   if (!sourceSchema) return;
-  const cachePath = getSourceSchemaCachePath(config);
+  const cachePath = state?.cachePath || getSourceSchemaCachePath(config);
+  const cacheKey = state?.cacheKey || path.relative(getSourceSchemaRootDir(config), path.dirname(cachePath));
+  hash.update(`source-schema-key:${cacheKey}`);
   hash.update(`source-schema-cache:${path.relative(config.productDir, cachePath)}`);
   if (!fs.existsSync(cachePath)) {
     hash.update(":missing");
@@ -255,7 +291,10 @@ function buildSourceSchemaMetadata(config, state, result) {
     refreshedAt: new Date().toISOString(),
     serviceName: config.name,
     envName: state.envName,
+    cacheKey: state.cacheKey,
+    cacheKind: state.cacheKind,
     cachePath: path.relative(config.productDir, state.cachePath),
+    repo: summarizeRepoStateForMetadata(state.repoState),
     sourceUrl: result.resolution.metadata,
     pgDump: result.pgDump,
   };
@@ -280,6 +319,9 @@ function readSourceSchemaCacheText(cachePath) {
 
 function shouldRefreshSourceSchema(state) {
   if (!state.cacheExists) return true;
+  if (state.sourceSchema.refresh?.mode === "auto") {
+    return state.ci;
+  }
   if (state.sourceSchema.refresh?.mode === "ttl") {
     const meta = readJson(state.metadataPath);
     const refreshedAt = meta?.refreshedAt ? Date.parse(meta.refreshedAt) : 0;
@@ -289,11 +331,62 @@ function shouldRefreshSourceSchema(state) {
   return true;
 }
 
+function updateSourceSchemaIndex(config, state, options = {}) {
+  if (!state?.active || !state.indexPath) return;
+  const now = new Date().toISOString();
+  const index = readJson(state.indexPath) || { version: 1, entries: [] };
+  const entries = Array.isArray(index.entries) ? index.entries.filter((entry) => entry?.cacheKey !== state.cacheKey) : [];
+  const existingMeta = readJson(state.metadataPath) || {};
+  entries.push({
+    cacheKey: state.cacheKey,
+    kind: state.cacheKind,
+    commitSha: state.repoState?.commitSha || null,
+    branch: state.repoState?.branch || null,
+    detached: Boolean(state.repoState?.detached),
+    dirty: Boolean(state.repoState?.dirty),
+    dirtyFingerprint: state.repoState?.dirtyFingerprint || null,
+    contentFingerprint: state.repoState?.contentFingerprint || null,
+    remoteUrl: state.repoState?.remoteUrl || null,
+    repoSlug: state.repoState?.repoSlug || null,
+    cachePath: path.relative(config.productDir, state.cachePath),
+    refreshedAt: options.refreshed ? now : existingMeta.refreshedAt || null,
+    lastUsedAt: now,
+  });
+  const prunedEntries = pruneSourceSchemaEntries(config, state, entries);
+  writeJson(state.indexPath, { version: 1, entries: prunedEntries });
+}
+
+function pruneSourceSchemaEntries(config, currentState, entries) {
+  if (entries.length <= SOURCE_SCHEMA_MAX_ENTRIES) return entries;
+  const sorted = [...entries].sort((a, b) => Date.parse(b.lastUsedAt || 0) - Date.parse(a.lastUsedAt || 0));
+  const keep = new Set(sorted.slice(0, SOURCE_SCHEMA_MAX_ENTRIES).map((entry) => entry.cacheKey));
+  keep.add(currentState.cacheKey);
+  for (const entry of entries) {
+    if (keep.has(entry.cacheKey)) continue;
+    const cachePath = entry.cachePath ? path.join(config.productDir, entry.cachePath) : null;
+    const resolvedCachePath = cachePath ? path.resolve(cachePath) : null;
+    const resolvedRoot = path.resolve(currentState.rootDir);
+    if (
+      !resolvedCachePath ||
+      (resolvedCachePath !== resolvedRoot && !resolvedCachePath.startsWith(`${resolvedRoot}${path.sep}`))
+    ) {
+      continue;
+    }
+    fs.rmSync(path.dirname(cachePath), { recursive: true, force: true });
+  }
+  return entries.filter((entry) => keep.has(entry.cacheKey));
+}
+
 function writeSourceSchemaMetadata(metadataPath, metadata) {
   fs.mkdirSync(path.dirname(metadataPath), { recursive: true });
   fs.writeFileSync(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`);
 }
 
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
 function readJson(filePath) {
   if (!filePath || !fs.existsSync(filePath)) return null;
   try {