@gfdelarue/testkit 0.3.0

package/dist/database/schema-source.d.ts

@@ -0,0 +1,93 @@
+import type { Hash } from "crypto";
+import type { NormalizedSourceSchemaConfig } from "../config/loader/index.js";
+import { type RepoState } from "../repo/state.js";
+import { type DatabaseTemplateServiceConfig, type DatabaseTemplateStepOptions } from "./template-steps.js";
+import { type SourceSchemaDumpResolution } from "./source-url.js";
+type UnknownRecord = Record<string, unknown>;
+type SourceSchemaUnavailableMode = "fail" | "warn-cache";
+type SourceSchemaTestkitConfig = DatabaseTemplateServiceConfig["testkit"] & {
+    fingerprints?: unknown;
+};
+export interface SourceSchemaCacheConfig {
+    name: string;
+    productDir: string;
+    testkit?: Pick<SourceSchemaTestkitConfig, "fingerprints">;
+}
+export interface SourceSchemaServiceConfig extends DatabaseTemplateServiceConfig {
+    testkit: SourceSchemaTestkitConfig;
+}
+export interface SourceSchemaCacheLocationOptions {
+    repoState?: RepoState | null;
+}
+export interface SourceSchemaCacheLocation {
+    cacheDir: string;
+    cacheKey: string;
+    cacheKind: string;
+    cachePath: string;
+    indexPath: string;
+    metadataPath: string;
+    repoState: RepoState;
+    rootDir: string;
+}
+type SourceSchemaOperationOptions = Pick<DatabaseTemplateStepOptions, "ownedContainer" | "parentOperation" | "reporter" | "setupRegistry">;
+export interface SourceSchemaOptions extends SourceSchemaCacheLocationOptions, SourceSchemaOperationOptions {
+    env?: NodeJS.ProcessEnv | null;
+    signal?: AbortSignal;
+    skipSchemaSourceVerify?: boolean;
+}
+export interface InactiveSourceSchemaState {
+    active: false;
+    cachePath?: string;
+}
+export interface ActiveSourceSchemaState extends SourceSchemaCacheLocation {
+    active: true;
+    cacheExists: boolean;
+    ci: boolean;
+    envName: string | null;
+    refreshed: boolean;
+    refreshError?: unknown;
+    refreshInfo?: SourceSchemaRefreshInfo;
+    sourceSchema: NormalizedSourceSchemaConfig;
+    sourceUrl: string | null;
+    unavailableMode: SourceSchemaUnavailableMode;
+}
+export interface RefreshedSourceSchemaState extends ActiveSourceSchemaState {
+    cacheExists: true;
+    refreshed: true;
+    refreshInfo: SourceSchemaRefreshInfo;
+}
+export type SourceSchemaState = ActiveSourceSchemaState | InactiveSourceSchemaState;
+interface SourceSchemaMetadata extends UnknownRecord {
+    refreshedAt: string;
+    sourceUrl?: SourceSchemaDumpResolution["metadata"];
+}
+export interface SourceSchemaRefreshInfo {
+    metadata: SourceSchemaMetadata;
+    reusedExistingRefresh: boolean;
+    waitedForLock: boolean;
+}
+export interface SourceSchemaMismatchDiagnostics {
+    diffPath: string;
+    localPath: string;
+    metaPath: string;
+    sourceCachePath: string;
+    sourcePath: string;
+}
+export type SourceSchemaVerification = {
+    status: "disabled" | "matched" | "skipped";
+} | {
+    diagnostics: SourceSchemaMismatchDiagnostics;
+    status: "mismatch";
+};
+export declare function getSourceSchemaRootDir(config: Readonly<SourceSchemaCacheConfig>): string;
+export declare function getSourceSchemaCachePath(config: Readonly<SourceSchemaCacheConfig>, options?: Readonly<SourceSchemaCacheLocationOptions>): Promise<string>;
+export declare function resolveSourceSchemaCacheLocation(config: Readonly<SourceSchemaCacheConfig>, options?: Readonly<SourceSchemaCacheLocationOptions>): Promise<SourceSchemaCacheLocation>;
+export declare function resolveSourceSchemaState(config: Readonly<SourceSchemaServiceConfig>, options?: Readonly<SourceSchemaOptions>): Promise<SourceSchemaState>;
+export declare function prepareSourceSchemaCache(config: Readonly<SourceSchemaServiceConfig>, options?: Readonly<SourceSchemaOptions>): Promise<SourceSchemaState>;
+export declare function forceRefreshSourceSchemaCache(config: Readonly<SourceSchemaServiceConfig>, previousState: Readonly<SourceSchemaState> | null, options?: Readonly<SourceSchemaOptions>): Promise<RefreshedSourceSchemaState>;
+export declare function applySourceSchemaCache(config: Readonly<SourceSchemaServiceConfig>, databaseUrl: string, state: Readonly<SourceSchemaState> | null | undefined, options?: Readonly<SourceSchemaOptions>): Promise<boolean>;
+export declare function verifyLocalSchemaMatchesSource(config: Readonly<SourceSchemaServiceConfig>, databaseUrl: string, state: Readonly<SourceSchemaState> | null | undefined, options?: Readonly<SourceSchemaOptions>): Promise<SourceSchemaVerification>;
+export declare function createSourceSchemaMismatchError(config: Readonly<SourceSchemaServiceConfig>, state: Readonly<ActiveSourceSchemaState>, verification: Readonly<SourceSchemaVerification> | null | undefined): Error;
+export declare function appendSourceSchemaCacheToHash(hash: Pick<Hash, "update">, config: Readonly<SourceSchemaServiceConfig>, state?: Readonly<SourceSchemaState> | null): Promise<void>;
+export declare function buildUnifiedDiffText(leftText: unknown, rightText: unknown, leftLabel?: string, rightLabel?: string): string;
+export {};

package/dist/database/schema-source.js

@@ -0,0 +1,3 @@
+import o from"fs";import s from"path";import{createTwoFilesPatch as q}from"diff";import{collectRepoState as z,summarizeRepoStateForMetadata as x}from"../repo/state.js";import{buildExecutionEnv as J}from"../steps/index.js";import{dumpPostgresSchemaToFile as W,captureTemplateSnapshotText as V,resolvePgDumpClientImage as X,runTemplateStep as Z,sanitizeSnapshotText as G}from"./template-steps.js";import{getSourceSchemaRefreshLockPath as Q,withSourceSchemaRefreshLock as Y}from"./source-refresh-lock.js";import{resolveSourceSchemaDumpUrl as ee}from"./source-url.js";import{makeTempDir as re,removeTempDir as te}from"../process/files/temp-dir.js";import{requireContainedDatabaseStateDirectory as C,resolveContainedDatabaseStateDirectory as v}from"./state.js";const K="db",R="source-schemas",w="source-schema.sql",P="source-schema.meta.json",ce="index.json",U=20,p=String;export function getSourceSchemaRootDir(e){return v(e.productDir,K,e.name,R)}export async function getSourceSchemaCachePath(e,r={}){return(await resolveSourceSchemaCacheLocation(e,r)).cachePath}export async function resolveSourceSchemaCacheLocation(e,r={}){const t=r.repoState||await z(e.productDir,{fingerprints:e.testkit?.fingerprints}),a=getSourceSchemaRootDir(e),c=v(e.productDir,K,e.name,R,...t.cacheKey.split("/").map(D));return{rootDir:a,cacheDir:c,cachePath:s.join(c,w),metadataPath:s.join(c,P),indexPath:s.join(a,ce),cacheKey:t.cacheKey,cacheKind:t.kind,repoState:t}}export async function resolveSourceSchemaState(e,r={}){const t=e.testkit.database?.sourceSchema||null;if(!t)return{active:!1};const a=await resolveSourceSchemaCacheLocation(e,r),c=a.cachePath,n=o.existsSync(c);n&&A(c);const i=r.env||process.env,u=J(e,{},i),h=(t.kind==="env"?[t.env]:[I(e.name),"TESTKIT_SCHEMA_SOURCE_DATABASE_URL"]).find(B=>{const _=u[B];return typeof _=="string"&&_.trim().length>0})||null,S=h?u[h]:void 0,f=typeof S=="string"?S.trim():null;return t.kind==="env"||!!f||n?{active:!0,cachePath:c,metadataPath:a.metadataPath,indexPath:a.indexPath,rootDir:a.rootDir,cacheDir:a.cacheDir,cacheKey:a.cacheKey,cacheKind:a.cacheKind,repoState:a.repoState,envName:h,sourceUrl:f,sourceSchema:t,cacheExists:n,refreshed:!1,ci:u.CI==="true",unavailableMode:ve(t.unavailable,i)}:{active:!1,cachePath:c}}export async function prepareSourceSchemaCache(e,r={}){r.signal?.throwIfAborted();const t=await resolveSourceSchemaState(e,r);if(!t.active)return t;if(j(t)){if(he(t))try{const c=await M(e,t,r),n={...t,refreshed:!0,cacheExists:!0,refreshInfo:c};return y(e,n,{refreshed:!0}),n}catch(c){r.signal?.throwIfAborted();const n=ae(e,t,c,r);if(n)return n;throw c}return y(e,t),r.setupRegistry?.recordCached({config:e,stage:"source-schema",kind:"database-source-schema",summary:"source schema cache hit"}),t}if(t.cacheExists&&t.unavailableMode==="warn-cache")return y(e,t),r.setupRegistry?.recordCached({config:e,stage:"source-schema",kind:"database-source-schema",summary:"source unavailable; using cached source schema"}),t;const a=t.sourceSchema.kind==="env"?t.sourceSchema.env:`${I(e.name)} or TESTKIT_SCHEMA_SOURCE_DATABASE_URL`;throw new Error(`Source schema database URL is unavailable for service "${e.name}". Set ${a}.`)}function ae(e,r,t,a={}){if(r.unavailableMode!=="warn-cache")return null;const c=ne(e,r);if(!c)return null;const n={...r,...c,cacheExists:!0,refreshed:!1,refreshError:Pe(t)};return a.setupRegistry?.recordCached({config:e,stage:"source-schema",kind:"database-source-schema",summary:`source unavailable; using cached source schema: ${s.relative(e.productDir,c.cachePath)}`}),n}function ne(e,r){const t=k(e,r,{cachePath:r.cachePath,metadataPath:r.metadataPath,cacheKey:r.cacheKey,cacheKind:r.cacheKind});if(t)return t;const a=L(r.indexPath);a.sort((c,n)=>Date.parse(n.lastUsedAt||n.refreshedAt||"0")-Date.parse(c.lastUsedAt||c.refreshedAt||"0"));for(const c of a){if(!c.cachePath)continue;const n=s.resolve(e.productDir,c.cachePath),i=k(e,r,{cachePath:n,metadataPath:s.join(s.dirname(n),P),cacheKey:c.cacheKey,cacheKind:c.kind||"unknown"});if(i)return i}return null}function k(e,r,t){const a=s.resolve(t.cachePath);if(s.basename(a)!==w)return null;const c=C(e.productDir,s.dirname(a),`Service "${e.name}" source schema cache directory`),n=s.join(c,w),i=s.resolve(r.rootDir);if(n!==i&&!n.startsWith(`${i}${s.sep}`)||!o.existsSync(n))return null;const u=o.lstatSync(n);if(u.isSymbolicLink()||!u.isFile())throw new Error(`Refusing unsafe source schema cache file at ${n}`);return{cachePath:n,metadataPath:s.join(c,P),cacheDir:c,cacheKey:t.cacheKey,cacheKind:t.cacheKind,indexPath:r.indexPath,rootDir:r.rootDir}}export async function forceRefreshSourceSchemaCache(e,r,t={}){const a=await resolveSourceSchemaState(e,t);if(!a.active||!j(a)){const i=r?.active?r.envName:null,u=r?.active&&r.sourceSchema.kind==="env"?r.sourceSchema.env:null,m=i||u||"source schema env";throw new Error(`Cannot refresh source schema for service "${e.name}" because ${m} is unavailable.`)}const c=await M(e,a,t),n={...a,refreshed:!0,cacheExists:!0,refreshInfo:c};return y(e,n,{refreshed:!0}),n}export async function applySourceSchemaCache(e,r,t,a={}){if(!t?.active)return!1;if(!o.existsSync(t.cachePath))throw new Error(`Missing source schema cache for service "${e.name}": ${t.cachePath}`);const c={kind:"sql-file",path:s.relative(e.productDir,t.cachePath).split(s.sep).join("/"),cwd:null,inputs:[]};return await Z(e,"source-schema",c,0,r,a),!0}export async function verifyLocalSchemaMatchesSource(e,r,t,a={}){if(!t?.active)return{status:"disabled"};if(!t.sourceSchema.verify||a.skipSchemaSourceVerify)return a.setupRegistry?.recordCached({config:e,stage:"source-schema:verify",kind:"database-source-schema",summary:"source schema verification skipped"}),{status:"skipped"};fe(e);const c=ue(t.cachePath),n=await V(e,r,{ownedContainer:a.ownedContainer||null,reporter:a.reporter||null,signal:a.signal});return n===c?{status:"matched"}:{status:"mismatch",diagnostics:await pe(e,t,c,n)}}export function createSourceSchemaMismatchError(e,r,t){const a=[`Local schema replay does not match source schema for service "${e.name}".`,`Source cache: ${s.relative(e.productDir,r.cachePath)}`];return t?.status==="mismatch"&&a.push(`Diff: ${s.relative(e.productDir,t.diagnostics.diffPath)}`),new Error(a.join(`
+`))}export async function appendSourceSchemaCacheToHash(e,r,t=null){if(!(r.testkit.database?.sourceSchema||null))return;const c=t?.cachePath||await getSourceSchemaCachePath(r),n=t?.active&&t.cacheKey?t.cacheKey:s.relative(getSourceSchemaRootDir(r),s.dirname(c));if(e.update(`source-schema-key:${n}`),e.update(`source-schema-cache:${s.relative(r.productDir,c)}`),!o.existsSync(c)){e.update(":missing");return}const i=o.statSync(c);e.update(`:${i.size.toString()}:${i.mtimeMs.toString()}`),e.update(o.readFileSync(c))}async function M(e,r,t={}){const a=t.setupRegistry,c=a?.start({config:e,stage:"source-schema:refresh",kind:"database-source-schema",summary:`source schema refresh: ${s.relative(e.productDir,r.cachePath)}`});try{const n=await Y(Q(r.cachePath),async({waited:u,requestedAt:m})=>{const h=oe(r,m);if(h)return{reusedExistingRefresh:!0,waitedForLock:u,metadata:h};const S=await se(e,r.sourceUrl,r.cachePath,{reporter:t.reporter||null,logRecord:c?._logRecord||null,env:t.env||process.env,signal:t.signal}),f=ie(e,r,S);return de(r.metadataPath,f),{reusedExistingRefresh:!1,waitedForLock:u,metadata:f}},{signal:t.signal}),i=c&&a?a.finish(c,{status:"passed",summary:`source schema refresh: ${s.relative(e.productDir,r.cachePath)}`}):null;return i&&t.reporter?.setupOperationFinished?.(i),n}catch(n){const i=c?a?.finish(c,{status:"failed",summary:`source schema refresh: ${s.relative(e.productDir,r.cachePath)}`,error:Ee(n)}):null;throw i&&t.reporter?.setupOperationFinished?.(i),n}}async function se(e,r,t,a={}){const c=ee(r);o.mkdirSync(s.dirname(t),{recursive:!0});const n=re(".source-schema-",{parentDir:s.dirname(t)}),i=s.join(n,s.basename(t));try{const u=await X(e,c.dumpUrl,{env:a.env||process.env,pgApplicationName:E(e.name),signal:a.signal});return await W(e,i,c.dumpUrl,{...a,image:u,pgApplicationName:E(e.name)}),o.renameSync(i,t),{resolution:c,pgDump:{args:["--schema-only","--no-owner","--no-privileges"],applicationName:E(e.name),image:u}}}finally{te(n)}}function ie(e,r,t){return{refreshedAt:new Date().toISOString(),serviceName:e.name,envName:r.envName,cacheKey:r.cacheKey,cacheKind:r.cacheKind,cachePath:s.relative(e.productDir,r.cachePath),repo:x(r.repoState),sourceUrl:t.resolution.metadata,pgDump:t.pgDump}}function oe(e,r){if(!o.existsSync(e.cachePath))return null;const t=b(e.metadataPath);if(!ge(t))return null;const a=Date.parse(t.refreshedAt);return!Number.isFinite(a)||a<r?null:t}function E(e){return`testkit:schema-source:${e.replace(/[^a-zA-Z0-9._:-]+/g,"-").slice(0,24)||"service"}`}function ue(e){return G(o.readFileSync(e,"utf8"))}function he(e){if(!e.cacheExists)return!0;if(e.sourceSchema.refresh.mode==="auto")return e.ci;if(e.sourceSchema.refresh.mode==="ttl"){const r=g(e.metadataPath),t=r?Date.parse(r):0;return!Number.isFinite(t)||t<=0?!0:Date.now()-t>=e.sourceSchema.refresh.ttlSeconds*1e3}return!0}function y(e,r,t={}){if(!r?.active)return;const a=new Date().toISOString(),c=L(r.indexPath).filter(u=>u.cacheKey!==r.cacheKey),n=g(r.metadataPath);c.push({cacheKey:r.cacheKey,kind:r.cacheKind,commitSha:r.repoState.commitSha||null,branch:r.repoState.branch||null,detached:r.repoState.detached,dirty:r.repoState.dirty,dirtyFingerprint:r.repoState.dirtyFingerprint||null,contentFingerprint:r.repoState.contentFingerprint||null,remoteUrl:r.repoState.remoteUrl||null,repository:r.repoState.repository,cachePath:s.relative(e.productDir,r.cachePath),refreshedAt:t.refreshed?a:n,lastUsedAt:a});const i=me(e,r,c);$(r.indexPath,{version:1,entries:i})}function me(e,r,t){if(t.length<=U)return t;const a=[...t].sort((n,i)=>Date.parse(i.lastUsedAt||"0")-Date.parse(n.lastUsedAt||"0")),c=new Set(a.slice(0,U).map(n=>n.cacheKey));c.add(r.cacheKey);for(const n of t){if(c.has(n.cacheKey))continue;const i=n.cachePath?s.join(e.productDir,n.cachePath):null,u=i?s.resolve(i):null,m=s.resolve(r.rootDir);if(!i||!u||u!==m&&!u.startsWith(`${m}${s.sep}`))continue;const h=C(e.productDir,s.dirname(i),`Service "${e.name}" pruned source schema cache directory`);o.rmSync(h,{recursive:!0,force:!0})}return t.filter(n=>c.has(n.cacheKey))}function de(e,r){F(e,r)}function $(e,r){F(e,r)}function F(e,r){o.mkdirSync(s.dirname(e),{recursive:!0}),A(e),o.writeFileSync(e,we(r))}function b(e){if(!e||!o.existsSync(e))return null;A(e);try{return JSON.parse(o.readFileSync(e,"utf8"))}catch{return null}}function N(e){return v(e.productDir,"results","schema")}function A(e){if(!o.existsSync(e))return;const r=o.lstatSync(e);if(r.isSymbolicLink()||!r.isFile())throw new Error(`Refusing unsafe source schema state file at ${e}`)}function le(e){return`${D(e.runtimeLabel||e.name)}__${D(e.name)}`}function fe(e){const r=N(e);if(!o.existsSync(r))return;const t=D(e.name);for(const a of o.readdirSync(r))Se(a,t)&&o.rmSync(s.join(r,a),{force:!0})}function Se(e,r){for(const t of["__source-schema.sql","__local-replay-schema.sql","__schema.diff","__schema.meta.json"])if(e.endsWith(t))return e.slice(0,-t.length).endsWith(`__${r}`);return!1}async function pe(e,r,t,a){const c=N(e);o.mkdirSync(c,{recursive:!0});const n=le(e),i=s.join(c,`${n}__source-schema.sql`),u=s.join(c,`${n}__local-replay-schema.sql`),m=s.join(c,`${n}__schema.diff`),h=s.join(c,`${n}__schema.meta.json`);return o.writeFileSync(i,t),o.writeFileSync(u,a),o.writeFileSync(m,await De(i,u)),$(h,ye(e,r)),{sourceCachePath:r.cachePath,sourcePath:i,localPath:u,diffPath:m,metaPath:h}}function ye(e,r){const t=g(r.metadataPath);return{version:1,createdAt:new Date().toISOString(),serviceName:e.name,runtimeLabel:e.runtimeLabel||e.name,sourceSchema:{envName:r.envName||null,cacheKey:r.cacheKey||null,cacheKind:r.cacheKind||null,cachePath:s.relative(e.productDir,r.cachePath),refreshedAt:t},repo:x(r.repoState)}}function De(e,r){return new Promise(t=>{t(buildUnifiedDiffText(o.readFileSync(e,"utf8"),o.readFileSync(r,"utf8"),e,r))})}export function buildUnifiedDiffText(e,r,t="source",a="target"){return e===r?"":q(t,a,p(e),p(r),"","",{context:3})}function ve(e,r){return e==="fail"||e==="warn-cache"?e:r.CI==="true"?"fail":"warn-cache"}function I(e){return`TESTKIT_${e.toUpperCase().replace(/[^A-Z0-9]+/g,"_")}_SCHEMA_SOURCE_DATABASE_URL`}function D(e){return e.trim().toLowerCase().replace(/[^a-z0-9._-]+/g,"-").replace(/^-+|-+$/g,"")||"schema"}function L(e){const r=b(e);return!l(r)||!Array.isArray(r.entries)?[]:r.entries.filter(be)}function g(e){const r=b(e);return l(r)&&typeof r.refreshedAt=="string"?r.refreshedAt:null}function we(e){return`${p(JSON.stringify(e,null,2))}
+`}function Pe(e){const r=T(e,"message");return!!r?r:p(e)}function Ee(e){const r=T(e,"message");return!!r?r:e}function T(e,r){if(!(e===null||typeof e!="object"&&typeof e!="function"))return Reflect.get(e,r)}function j(e){return!!e.sourceUrl}function be(e){return!l(e)||typeof e.cacheKey!="string"||e.cacheKey.length===0?!1:d(e.branch)&&d(e.cachePath)&&d(e.commitSha)&&d(e.contentFingerprint)&&H(e.detached)&&H(e.dirty)&&d(e.dirtyFingerprint)&&d(e.kind)&&d(e.lastUsedAt)&&d(e.refreshedAt)&&d(e.remoteUrl)&&Ae(e.repository)}function Ae(e){return e==null||l(e)&&typeof e.host=="string"&&typeof e.owner=="string"&&typeof e.name=="string"}function ge(e){return l(e)&&typeof e.refreshedAt=="string"&&(e.sourceUrl===void 0||_e(e.sourceUrl))}function _e(e){return l(e)&&typeof e.originalHost=="string"&&O(e.originalClassification)&&typeof e.resolvedHost=="string"&&O(e.resolvedClassification)&&typeof e.rewritten=="boolean"}function O(e){return e==="neon-pooler"||e==="neon-direct"||e==="unsupported-pooler"||e==="unknown-direct"}function xe(e){return e===null||typeof e=="string"}function d(e){return e===void 0||xe(e)}function H(e){return e===void 0||typeof e=="boolean"}function l(e){return e!==null&&typeof e=="object"&&!Array.isArray(e)}

package/dist/database/source-refresh-lock.d.ts

@@ -0,0 +1,8 @@
+import { type ProcessLockOptions } from "../process/locks.js";
+export interface SourceSchemaRefreshLockContext {
+    requestedAt: number;
+    waited: boolean;
+}
+export type SourceSchemaRefreshLockOptions = Pick<ProcessLockOptions, "retryIntervalMs" | "signal">;
+export declare function withSourceSchemaRefreshLock<Result>(lockPath: string, task: (context: Readonly<SourceSchemaRefreshLockContext>) => Promise<Result> | Result, options?: Readonly<SourceSchemaRefreshLockOptions>): Promise<Result>;
+export declare function getSourceSchemaRefreshLockPath(cachePath: string): string;

package/dist/database/source-refresh-lock.js

@@ -0,0 +1 @@
+import a from"node:fs";import r from"node:path";import{tryWithProcessLock as m,withProcessLock as n}from"../process/locks.js";export async function withSourceSchemaRefreshLock(e,t,o={}){a.mkdirSync(r.dirname(e),{recursive:!0});const c=Date.now(),i=await m(e,()=>t({requestedAt:c,waited:!1}),o);return i.acquired?i.value:n(e,()=>t({requestedAt:c,waited:!0}),o)}export function getSourceSchemaRefreshLockPath(e){return r.join(r.dirname(e),"source-schema.refresh.lock")}

package/dist/database/source-url.d.ts

@@ -0,0 +1,22 @@
+export type DatabaseHostKind = "neon-pooler" | "neon-direct" | "unsupported-pooler" | "unknown-direct";
+export interface DatabaseHostClassification {
+    kind: DatabaseHostKind;
+    host: string;
+}
+export interface SourceSchemaDumpResolution {
+    originalUrl: string;
+    dumpUrl: string;
+    rewritten: boolean;
+    notice: string | null;
+    metadata: {
+        originalHost: string;
+        originalClassification: DatabaseHostKind;
+        resolvedHost: string;
+        resolvedClassification: DatabaseHostKind;
+        rewritten: boolean;
+    };
+}
+export declare function resolveSourceSchemaDumpUrl(databaseUrl: string): SourceSchemaDumpResolution;
+export declare function classifyDatabaseHost(hostname: string): DatabaseHostClassification;
+export declare function redactDatabaseUrl(databaseUrl: string): string;
+export declare function assertPgDumpArgsAreSourceSafe(args: readonly string[]): void;

package/dist/database/source-url.js

@@ -0,0 +1,2 @@
+import{errorMessage as c}from"../kernel/error-serialization.js";const s=".neon.tech",a="-pooler.",l=/(^|[-.])(pgbouncer|pooler)([-.]|$)/i;export function resolveSourceSchemaDumpUrl(o){const e=d(o),r=classifyDatabaseHost(e.hostname);if(r.kind==="neon-pooler"){const n=new URL(e.url.href);return n.hostname=e.hostname.replace(a,"."),i({original:e,resolved:n,originalClassification:r,resolvedClassification:classifyDatabaseHost(n.hostname),rewritten:!0,notice:"Source schema URL uses Neon pooler; Testkit is using the direct endpoint for pg_dump."})}if(r.kind==="unsupported-pooler")throw new Error(["Refusing to run pg_dump through a pooled source database URL.",`Host: ${e.hostname}`,"Configure a direct source database URL."].join(`
+`));return i({original:e,resolved:e.url,originalClassification:r,resolvedClassification:r,rewritten:!1,notice:null})}export function classifyDatabaseHost(o){const e=o.toLowerCase();return e.endsWith(s)&&e.includes(a)?{kind:"neon-pooler",host:e}:e.endsWith(s)?{kind:"neon-direct",host:e}:l.test(e)?{kind:"unsupported-pooler",host:e}:{kind:"unknown-direct",host:e}}export function redactDatabaseUrl(o){try{const e=new URL(o);return e.username&&(e.username="REDACTED"),e.password&&(e.password="REDACTED"),e.toString()}catch{return"[invalid database URL]"}}export function assertPgDumpArgsAreSourceSafe(o){for(let e=0;e<o.length;e+=1){const r=o[e];if(r==="-j"||r==="--jobs"||r.startsWith("--jobs="))throw new Error("Source schema pg_dump must not use parallel jobs.")}}function d(o){try{const e=new URL(o);if(!e.hostname)throw new Error("missing host");return{url:e,hostname:e.hostname.toLowerCase()}}catch(e){throw new Error(`Invalid source database URL: ${c(e)}`,{cause:e})}}function i({original:o,resolved:e,originalClassification:r,resolvedClassification:n,rewritten:t,notice:u}){return{originalUrl:o.url.href,dumpUrl:e.href,rewritten:t,notice:u,metadata:{originalHost:o.hostname,originalClassification:r.kind,resolvedHost:e.hostname.toLowerCase(),resolvedClassification:n.kind,rewritten:t}}}

package/dist/database/state-files.d.ts

@@ -0,0 +1,13 @@
+import type { DatabaseConnection } from "./naming.js";
+export interface LocalPostgresState extends DatabaseConnection {
+    containerId: string;
+    containerName: string;
+    containerPort: number;
+    image: string;
+    maxConnections: number;
+    volumeMountPath?: string | null;
+    volumeName?: string | null;
+}
+export declare function writeLocalInfraState(infraDir: string, infra: Readonly<LocalPostgresState>): void;
+export declare function writeCacheState(cacheDir: string, infra: Readonly<LocalPostgresState>, templateDbName: string, fingerprint: string): void;
+export declare function writeStateValue(filePath: string, value: unknown): void;

package/dist/database/state-files.js

@@ -0,0 +1 @@
+import m from"fs";import e from"path";import{buildProductIdentity as p}from"./docker.js";const s=String;export function writeLocalInfraState(o,t){const n=p(e.resolve(o,"..","..",".."));writeStateValue(e.join(o,"database_backend"),""),writeStateValue(e.join(o,"container_name"),t.containerName),writeStateValue(e.join(o,"container_id"),t.containerId),t.volumeName&&writeStateValue(e.join(o,"volume_name"),t.volumeName),t.volumeMountPath&&writeStateValue(e.join(o,"volume_mount_path"),t.volumeMountPath),writeStateValue(e.join(o,"ownership_product_id"),n.id),writeStateValue(e.join(o,"image"),t.image),writeStateValue(e.join(o,"user"),t.user),writeStateValue(e.join(o,"password"),t.password),writeStateValue(e.join(o,"max_connections"),String(t.maxConnections)),writeStateValue(e.join(o,"host"),t.host),writeStateValue(e.join(o,"port"),String(t.port))}export function writeCacheState(o,t,n,u){writeStateValue(e.join(o,"database_backend"),""),writeStateValue(e.join(o,"template_database_name"),n),writeStateValue(e.join(o,"template_fingerprint"),u),writeStateValue(e.join(o,"container_name"),t.containerName),t.volumeName&&writeStateValue(e.join(o,"volume_name"),t.volumeName),t.volumeMountPath&&writeStateValue(e.join(o,"volume_mount_path"),t.volumeMountPath)}export function writeStateValue(o,t){m.writeFileSync(o,s(t??""),{mode:384}),m.chmodSync(o,384)}

package/dist/database/state.d.ts

@@ -0,0 +1,26 @@
+export type OwnedDatabaseStateKind = "cache" | "infra" | "legacy" | "runtime";
+export interface OwnedDatabaseStateDir {
+    readonly dir: string;
+    readonly kind: OwnedDatabaseStateKind;
+}
+export interface DatabaseInfo {
+    database: string;
+    host: string;
+    password: string;
+    port: number;
+    ssl: boolean;
+    sslMode: string;
+    url: string;
+    user: string;
+}
+export declare function getLocalInfraDir(productDir: string): string;
+export declare function getLocalLocksDir(productDir: string): string;
+export declare function getLocalServiceCacheDir(productDir: string, serviceName: string): string;
+export declare function listOwnedDatabaseStateDirs(productDir: string): OwnedDatabaseStateDir[];
+export declare function hasRemainingLocalArtifacts(productDir: string): boolean;
+export declare function readOwnedStateValues(productDir: string, fileNames: readonly string[]): Set<string>;
+export declare function readStateValue(filePath: string): string | null;
+export declare function readDatabaseUrl(stateDir: string): string | null;
+export declare function readDatabaseInfo(stateDir: string): DatabaseInfo | null;
+export declare function resolveContainedDatabaseStateDirectory(productDir: string, ...segments: readonly string[]): string;
+export declare function requireContainedDatabaseStateDirectory(productDir: string, candidateDirectory: string, label?: string): string;

package/dist/database/state.js

@@ -0,0 +1 @@
+import u from"fs";import o from"path";import{requireContainedTestkitStateDirectory as D,resolveContainedTestkitStateDirectory as b}from"../process/runs/product-state.js";const y=new Set(["_bundles","_config","_dbcache","_graphs","_infra","_locks","_runs","_template-steps","_toolchains","_typecheck","engines","history","lint","results"]);export function getLocalInfraDir(e){return resolveContainedDatabaseStateDirectory(e,"_infra","local-postgres")}export function getLocalLocksDir(e){return resolveContainedDatabaseStateDirectory(e,"_locks","local-postgres")}export function getLocalServiceCacheDir(e,t){return resolveContainedDatabaseStateDirectory(e,"_dbcache",t)}export function listOwnedDatabaseStateDirs(e){const t=resolveContainedDatabaseStateDirectory(e),r=[],n=getLocalInfraDir(e);u.existsSync(n)&&r.push({dir:n,kind:"infra"});const l=o.join(t,"_dbcache");for(const a of f(l))r.push({dir:a,kind:"cache"});const s=o.join(t,"_graphs");for(const a of f(s))for(const c of f(o.join(a,"runtimes")))for(const m of f(o.join(c,"services")))r.push({dir:m,kind:"runtime"});for(const a of p(t)){if(y.has(a.name)||!a.isDirectory())continue;const c=o.join(t,a.name);d(o.join(c,"database_backend"))&&r.push({dir:c,kind:"legacy"})}return r}export function hasRemainingLocalArtifacts(e){return listOwnedDatabaseStateDirs(e).map(({dir:t,kind:r})=>{const n=d(o.join(t,"database_backend"));return r!=="infra"&&(r==="cache"||n)}).some(Boolean)}export function readOwnedStateValues(e,t){const r=new Set;for(const{dir:n}of listOwnedDatabaseStateDirs(e))for(const l of t){const s=readStateValue(o.join(n,l));s&&r.add(s)}return r}function f(e){return p(e).flatMap(t=>{const r=o.join(e,t.name);if(t.isSymbolicLink())throw i(r,"symlink");if(!t.isDirectory()&&!t.isFile())throw i(r,"special node");return t.isDirectory()?[r]:[]})}function p(e){const t=h(e);if(!t)return[];if(!t.isDirectory())throw i(e,"non-directory node");return u.readdirSync(e,{withFileTypes:!0}).sort((r,n)=>r.name.localeCompare(n.name))}function d(e){const t=h(e);if(t&&!t.isFile())throw i(e,"non-file node");return!!t}function h(e){const t=u.lstatSync(e,{throwIfNoEntry:!1});if(t?.isSymbolicLink())throw i(e,"symlink");return t}export function readStateValue(e){return d(e)?u.readFileSync(e,"utf8").trim():null}export function readDatabaseUrl(e){return readStateValue(o.join(e,"database_url"))}export function readDatabaseInfo(e){return S(readDatabaseUrl(e))}function S(e){if(!e)return null;try{const t=new URL(e),r=Number(t.port||"5432"),n=t.searchParams.get("sslmode")||"disable";return{url:e,host:t.hostname,port:Number.isInteger(r)&&r>0?r:5432,database:t.pathname.replace(/^\//,""),user:decodeURIComponent(t.username||""),password:decodeURIComponent(t.password||""),sslMode:n,ssl:n!=="disable"}}catch{return null}}export function resolveContainedDatabaseStateDirectory(e,...t){return b(e,...t)}export function requireContainedDatabaseStateDirectory(e,t,r="Testkit database state directory"){return D(e,t,r)}function i(e,t){return new Error(`Refusing unsafe Testkit database state ${t} at ${e}`)}

package/dist/database/steps.d.ts

@@ -0,0 +1,16 @@
+import type { OwnedPostgresContainerRoute } from "../domain/postgres-route.js";
+export interface DatabaseStepContext {
+    args?: unknown;
+    cwd?: string;
+    databaseUrl?: string;
+    env?: Record<string, string | undefined>;
+    ownedContainer?: OwnedPostgresContainerRoute | null;
+    productDir?: string;
+}
+export declare function verifySeed(context?: DatabaseStepContext): Promise<void>;
+export declare function verifyRows(context?: DatabaseStepContext): Promise<void>;
+export declare function queryScalar(context?: DatabaseStepContext): Promise<string>;
+export declare function runSql(context?: DatabaseStepContext): Promise<void>;
+export declare function seedRows(context?: DatabaseStepContext): Promise<void>;
+export declare function materializePostgresBinding(context?: DatabaseStepContext): Promise<void>;
+export declare function updateRows(context?: DatabaseStepContext): Promise<void>;

package/dist/database/steps.js

@@ -0,0 +1,4 @@
+import j from"node:fs";import U from"node:path";import{runDockerPsql as P}from"./postgres/index.js";const d=String;export async function verifySeed(r={}){const e=f(r),t=l(e.table,"verifySeed.args.table"),n=_(e.where),s=z(e.minRows??1,"verifySeed.args.minRows"),o=g(r),u=`select count(*)::int from ${t}${n?` where ${n}`:""}`,i=Number(await q(o,u,r));if(!Number.isInteger(i)||i<s)throw new Error(`Expected at least ${String(s)} row(s) in ${t}, found ${String(i||0)}`)}export async function verifyRows(r={}){const e=f(r),t=Array.isArray(e.checks)?e.checks:[e],n=g(r),s=[];for(const[o,u]of t.entries()){const i=`verifyRows.args.checks[${String(o)}]`,a=S(u)?u:{},m=l(a.table,`${i}.table`),w=_(a.where),c=z(a.minRows??1,`${i}.minRows`),$=a.severity==="warn"?"warn":"error",k=`select count(*)::int from ${m}${w?` where ${w}`:""}`,y=Number(await q(n,k,r));if(!Number.isInteger(y)||y<c){const N=`Expected at least ${String(c)} row(s) in ${m}, found ${String(y||0)}`;$==="warn"?J(r,{code:"database_verify_rows_min_rows",message:N,table:m,where:w||null,expectedMinRows:c,actualRows:Number.isInteger(y)?y:0}):s.push(N)}}if(s.length>0)throw new Error(`Database row verification failed:
+${s.map(o=>`- ${o}`).join(`
+`)}`)}export async function queryScalar(r={}){const e=f(r),t=g(r),n=O(e.statement??e.query,"queryScalar.args.statement");return q(t,n,r)}export async function runSql(r={}){const e=f(r),t=L(e.statements??e.statement,"runSql.args.statements"),n=g(r);for(const s of t){const o=await b(n,s,r);o.stdout&&process.stdout.write(o.stdout),o.stderr&&process.stderr.write(o.stderr)}}export async function seedRows(r={}){const e=f(r),t=l(e.table,"seedRows.args.table"),n=D(e.rows,"seedRows.args.rows"),s=g(r);if(e.truncate===!0&&await b(s,`truncate table ${t}`,r),n.length===0)return;const o=I(e.columns,n),u=o.map(a=>l(a,`seedRows.args.columns.${a}`)),i=n.map(a=>`(${o.map(m=>E(a[m],r)).join(", ")})`);await b(s,`insert into ${t} (${u.join(", ")}) values ${i.join(", ")}`,r)}export async function materializePostgresBinding(r={}){const e=f(r),t=l(e.table,"materializePostgresBinding.args.table"),n=l(e.keyColumn||"slug","materializePostgresBinding.args.keyColumn"),s=T(e.key,"materializePostgresBinding.args.key"),o=R(e.values,"materializePostgresBinding.args.values"),u=g(r),i=Object.keys(o);if(i.length===0)throw new Error("materializePostgresBinding.args.values must contain at least one column");const a=i.map($=>`${l($,`materializePostgresBinding.args.values.${$}`)} = ${E(o[$],r)}`),m=`with updated as (update ${t} set ${a.join(", ")} where ${n} = ${h(s)} returning 1) select count(*)::int from updated`,w=await b(u,m,r,{scalar:!0}),c=Number((w.stdout||"").trim()||"0");if(c!==1)throw new Error(`Expected to materialize 1 ${t} row for ${n}=${String(s)}, updated ${String(c||0)}`)}export async function updateRows(r={}){const e=f(r),t=l(e.table,"updateRows.args.table"),n=B(e.where,"updateRows.args.where"),s=R(e.values??e.set,"updateRows.args.values"),o=g(r),u=e.expectRows==null?null:z(e.expectRows,"updateRows.args.expectRows"),i=Object.keys(s).map(c=>`${l(c,`updateRows.args.values.${c}`)} = ${E(s[c],r)}`);if(i.length===0)throw new Error("updateRows.args.values must contain at least one column");const a=`with updated as (update ${t} set ${i.join(", ")} where ${W(n,r)} returning 1) select count(*)::int from updated`,m=await b(o,a,r,{scalar:!0}),w=Number((m.stdout||"").trim()||"0");if(u!==null&&w!==u)throw new Error(`Expected to update ${String(u)} ${t} row(s), updated ${String(w||0)}`)}function f(r){return S(r.args)?r.args:{}}function g(r){const e=(r.databaseUrl||r.env?.DATABASE_URL||"").trim();if(!e)throw new Error("Database template step requires DATABASE_URL");return e}async function q(r,e,t){return((await b(r,e,t,{scalar:!0})).stdout||"").trim()}async function b(r,e,t,n={}){const s={args:[r,"-v","ON_ERROR_STOP=1","-X",...n.scalar?["-q","-t","-A"]:[],"-c",e],cwd:t.cwd||t.productDir||process.cwd(),env:t.env||process.env,databaseUrl:r,ownedContainer:t.ownedContainer||null},o=await P(s);if(o.exitCode!==0)throw new Error(o.stderr||`psql failed with exit code ${String(o.exitCode)}`);return o}function L(r,e){const t=Array.isArray(r)?r:r==null?[]:[r];if(t.length===0)throw new Error(`${e} must contain at least one SQL statement`);return t.map((n,s)=>O(n,`${e}[${String(s)}]`))}function O(r,e){const t=d(r||"").trim();if(!t||/;\s*\S/.test(t))throw new Error(`${e} must be one SQL statement`);return t}function D(r,e){if(!Array.isArray(r))throw new Error(`${e} must be an array`);return r.map((n,s)=>R(n,`${e}[${String(s)}]`))}function I(r,e){if(r!=null){if(!Array.isArray(r)||r.length===0)throw new Error("seedRows.args.columns must be a non-empty array");return r.map(n=>String(n))}return[...new Set(e.flatMap(t=>Object.keys(t)))].sort((t,n)=>t.localeCompare(n))}function B(r,e){const t=R(r,e);if(Object.keys(t).length===0)throw new Error(`${e} must contain at least one column`);return t}function W(r,e){return Object.entries(r).map(([t,n])=>`${l(t,`where.${t}`)} = ${E(n,e)}`).join(" and ")}function l(r,e){const t=d(r||"").trim();if(!/^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)?$/.test(t))throw new Error(`${e} must be a SQL identifier or schema-qualified identifier`);return t}function _(r){if(r==null||r==="")return"";const e=d(r).trim();if(!e||/;|--|\/\*/.test(e))throw new Error("verifySeed.args.where must be a single SQL predicate without comments or semicolons");return e}function z(r,e){const t=Number(r);if(!Number.isInteger(t)||t<0)throw new Error(`${e} must be a non-negative integer`);return t}function R(r,e){if(!S(r))throw new Error(`${e} must be an object`);return r}function T(r,e){if(r==null||d(r).length===0)throw new Error(`${e} is required`);return r}function h(r){return r===null?"null":typeof r=="number"&&Number.isFinite(r)?String(r):typeof r=="boolean"?r?"true":"false":`'${d(r).replaceAll("'","''")}'`}function E(r,e){if(!v(r))return h(r);switch(r.kind){case"now":return"now()";case"env":return h(p(e.env||process.env,r.name));case"json":return`${h(JSON.stringify(A(r.value,e)))}::jsonb`;case"postgres-connection-from-env":return`${h(JSON.stringify(C(e.env||process.env,r.prefix)))}::jsonb`;default:throw new Error(`Unsupported database value descriptor "${r.kind}"`)}}function v(r){return S(r)&&typeof r.kind=="string"}function A(r,e){if(Array.isArray(r))return r.map(n=>A(n,e));if(!S(r))return r;if(v(r)){if(r.kind==="env")return p(e.env||process.env,r.name);if(r.kind==="postgres-connection-from-env")return C(e.env||process.env,r.prefix)}return Object.fromEntries(Object.entries(r).map(([t,n])=>[t,A(n,e)]))}function C(r,e){const t=d(e||"").trim();if(!t)throw new Error("postgresConnectionFromEnv requires a non-empty prefix");return{host:p(r,`${t}_HOST`),port:F(r,`${t}_PORT`),database:p(r,`${t}_NAME`),username:p(r,`${t}_USER`),password:p(r,`${t}_PASSWORD`),ssl:Q(r[`${t}_SSL`])}}function p(r,e){const t=String(e),n=r?.[t];if(n==null||n.trim().length===0)throw new Error(`${t} environment variable is required`);return n.trim()}function F(r,e){const t=Number.parseInt(p(r,e),10);if(!Number.isInteger(t)||t<=0)throw new Error(`${e} must be a positive integer`);return t}function Q(r){return r?["1","true","yes","on"].includes(r.trim().toLowerCase()):!1}function J(r,e){const t={severity:"warn",source:"database.verifyRows",serviceName:r.serviceName||null,runtimeId:r.runtimeId||null,timestamp:new Date().toISOString(),...e};typeof r.recordWarning=="function"&&r.recordWarning(t);const n=r.warningFile;n&&(j.mkdirSync(U.dirname(n),{recursive:!0}),j.appendFileSync(n,JSON.stringify(t)+`
+`)),Z(r)&&console.warn(t.message)}function Z(r){const e=r.emitWarningsToStderr;return e==null?!0:!["0","false","no","off"].includes(d(e).trim().toLowerCase())}function S(r){return typeof r=="object"&&r!==null&&!Array.isArray(r)}

package/dist/database/template-steps.d.ts

@@ -0,0 +1,35 @@
+import type { NormalizedDatabaseConfig, NormalizedDatabaseTemplateConfig } from "../config/loader/index.js";
+import { type ConfiguredStepReporter, type ConfiguredStepServiceConfig, type ExecutionEnvironmentConfig, type ExecutionEnvironmentTestkitConfig } from "../steps/index.js";
+import { type RunConfiguredStepsOptions } from "./configured-steps.js";
+import { type StepLogRecord } from "../evidence/setup-progress.js";
+import type { NormalizedConfiguredStep } from "../steps/configured-steps.js";
+import type { OwnedPostgresContainerRoute } from "../domain/postgres-route.js";
+export type DatabaseTemplateStageName = "migrate" | "seed" | "verify";
+type DatabaseTemplateTestkitConfig = ExecutionEnvironmentTestkitConfig & ConfiguredStepServiceConfig["testkit"] & {
+    database?: Partial<Pick<NormalizedDatabaseConfig, "sourceSchema" | "template">> | null;
+};
+export interface DatabaseTemplateServiceConfig extends ExecutionEnvironmentConfig, ConfiguredStepServiceConfig {
+    runtimeLabel?: string | null;
+    testkit: DatabaseTemplateTestkitConfig;
+}
+export type DatabaseTemplateStepOptions = Pick<RunConfiguredStepsOptions, "afterStep" | "ownedContainer" | "parentOperation" | "reporter" | "setupRegistry" | "signal" | "stepTimeoutMs">;
+export interface PostgresDumpOptions {
+    env?: NodeJS.ProcessEnv | null;
+    image?: string | null;
+    logRecord?: StepLogRecord | null;
+    ownedContainer?: OwnedPostgresContainerRoute | null;
+    pgApplicationName?: string | null;
+    reporter?: ConfiguredStepReporter | null;
+    signal?: AbortSignal;
+}
+export declare function runTemplateStage(config: Readonly<DatabaseTemplateServiceConfig>, stageName: DatabaseTemplateStageName, databaseUrl: string, options?: Readonly<DatabaseTemplateStepOptions>): Promise<void>;
+export declare function runTemplateStep(config: Readonly<DatabaseTemplateServiceConfig>, stageName: string, step: Readonly<NormalizedConfiguredStep>, stepIndex: number, databaseUrl: string, options?: Readonly<DatabaseTemplateStepOptions>): Promise<void>;
+export declare function collectTemplateInputs(productDir: string, template?: Partial<Readonly<NormalizedDatabaseTemplateConfig>>): string[];
+export declare function captureTemplateSnapshotText(config: Readonly<DatabaseTemplateServiceConfig>, databaseUrl: string, options?: Readonly<PostgresDumpOptions>): Promise<string>;
+export declare function dumpPostgresSchemaToFile(config: Readonly<DatabaseTemplateServiceConfig>, outputPath: string, databaseUrl: string, options?: Readonly<PostgresDumpOptions>): Promise<void>;
+export declare function pgDumpArgs(): string[];
+export declare function resolvePgDumpClientImage(config: Readonly<DatabaseTemplateServiceConfig>, databaseUrl: string, options?: Readonly<PostgresDumpOptions>): Promise<string>;
+export declare function postgresClientImageForServerVersion(serverVersionNum: unknown): string;
+export declare function sanitizeSnapshotFile(filePath: string): void;
+export declare function sanitizeSnapshotText(dump: unknown): string;
+export {};

package/dist/database/template-steps.js

@@ -0,0 +1,4 @@
+import a from"fs";import h from"path";import{buildTemplateExecutionEnv as m,collectConfiguredInputs as P}from"../steps/index.js";import{runConfiguredSteps as w}from"./configured-steps.js";import"../evidence/setup-progress.js";import{makeTempDir as T,removeTempDir as A}from"../process/files/temp-dir.js";import{captureOutput as E}from"../process/index.js";import{assertPgDumpArgsAreSourceSafe as D}from"./source-url.js";import{runDockerPsql as v,startDockerPgDump as x}from"./postgres/index.js";const p=String,y=["migrate","seed","verify"];export function runTemplateStage(e,r,t,n={}){const o=e.testkit.database?.template?.[r]||[];return l(e,r,o,0,t,n)}export function runTemplateStep(e,r,t,n,o,i={}){return l(e,r,[t],n,o,i)}async function l(e,r,t,n,o,i){await w({...i,config:e,steps:t,env:{...m(e,{},process.env),DATABASE_URL:o},labelPrefix:`template:${r}`,startIndex:n})}export function collectTemplateInputs(e,r={}){const t=y.flatMap(n=>r[n]||[]);return P(e,{inputs:r.inputs||[],steps:t})}export async function captureTemplateSnapshotText(e,r,t={}){const n=T("testkit-schema-snapshot-"),o=h.join(n,"schema.sql");try{const i=t.image||await resolvePgDumpClientImage(e,r,t);return await dumpPostgresSchemaToFile(e,o,r,{...t,image:i}),a.readFileSync(o,"utf8")}finally{A(n)}}export async function dumpPostgresSchemaToFile(e,r,t,n={}){const o={...m(e,{},n.env||process.env),...f(t,{applicationName:n.pgApplicationName})},i=pgDumpArgs();D(i);const s=await b(e,i,o,n);if(s.exitCode!==0)throw new Error(s.shortMessage||s.stderr||s.stdout||"pg_dump failed");a.writeFileSync(r,s.stdout),sanitizeSnapshotFile(r)}export function pgDumpArgs(){return["--schema-only","--no-owner","--no-privileges"]}function d(e){return{host:e.PGHOST,port:e.PGPORT||5432,database:e.PGDATABASE,user:e.PGUSER,password:e.PGPASSWORD,sslMode:e.PGSSLMODE}}async function b(e,r,t,n={}){const o=x({args:r,cwd:e.productDir,env:t,image:n.image||null,ownedContainer:n.ownedContainer||null,signal:n.signal,connection:d(t)}),i=n.reporter,s=i?.outputMode==="debug"?c=>i.writeDebugLine?.(c):null,u=n.logRecord||null,g=[E(o.stderr,{livePrefix:`[${e.runtimeLabel||e.name}:${e.name}]`,liveWriter:s,onLine(c){u&&u.write(`${new Date().toISOString()} [stderr] ${c}
+`)}})],S=await o;return await Promise.all(g),S}export async function resolvePgDumpClientImage(e,r,t={}){const n=t.env||process.env,o=C(n);if(o)return o;const i={...n,...f(r,{applicationName:t.pgApplicationName})},s=await v({args:["-tAc","SHOW server_version_num"],cwd:e.productDir,env:i,ownedContainer:t.ownedContainer||null,signal:t.signal,connection:d(i)});if(s.exitCode!==0)throw new Error(s.shortMessage||s.stderr||s.stdout||"Failed to detect source Postgres version");return postgresClientImageForServerVersion(s.stdout)}export function postgresClientImageForServerVersion(e){const r=Number(p(_(e,"")).trim());if(!Number.isFinite(r)||r<1e5)throw new Error(`Unable to determine Postgres major version from server_version_num: ${JSON.stringify(e)}`);return`postgres:${String(Math.floor(r/1e4))}`}function C(e){return e.TESTKIT_POSTGRES_CLIENT_IMAGE||null}function f(e,r={}){const t=new URL(e);return G({PGHOST:t.hostname,PGPORT:t.port||"5432",PGDATABASE:decodeURIComponent(t.pathname.replace(/^\//,"")),PGUSER:decodeURIComponent(t.username||""),PGPASSWORD:decodeURIComponent(t.password||""),PGSSLMODE:t.searchParams.get("sslmode")||void 0,PGAPPNAME:r.applicationName||void 0})}function G(e){const r={};for(const[t,n]of Object.entries(e))n!=null&&n!==""&&(r[t]=n);return r}export function sanitizeSnapshotFile(e){const r=a.readFileSync(e,"utf8"),t=sanitizeSnapshotText(r);t!==r&&a.writeFileSync(e,t)}export function sanitizeSnapshotText(e){return O(p(e).split(`
+`)).filter(r=>{const t=r.trim();return!t.startsWith("-- Dumped from database version ")&&!t.startsWith("-- Dumped by pg_dump version ")&&t!=="SET transaction_timeout = 0;"&&!t.startsWith("\\restrict ")&&!t.startsWith("\\unrestrict ")}).join(`
+`)}function O(e){const r=[];for(let t=0;t<e.length;t+=1){if(e[t]?.trim()==="--"&&e[t+1]?.startsWith("-- Name: public; Type: SCHEMA;")){let n=t+1;for(;n<e.length&&!e[n]?.includes("*not* creating schema");)n+=1;if(n<e.length){for(;n+1<e.length&&e[n+1]?.trim()==="";)n+=1;t=n;continue}}r.push(e[t])}return r}function _(e,r){return!!e?e:r}

package/dist/domain/file-timeout.d.ts

@@ -0,0 +1,28 @@
+export declare const DEFAULT_FILE_TIMEOUT_SECONDS = 60;
+export declare const FILE_TIMEOUT_INTERVAL_SECONDS = 0.25;
+export declare const FILE_TIMEOUT_COOPERATIVE_ERROR_RESERVE_MAX_MS = 2000;
+export declare const FILE_TIMEOUT_COOPERATIVE_ERROR_RESERVE_MIN_MS = 250;
+export declare const FILE_TIMEOUT_COOPERATIVE_ERROR_RESERVE_RATIO = 0.2;
+export declare const FILE_TIMEOUT_SUBPROCESS_EXIT_GRACE_MS = 1000;
+export declare const INTERNAL_FILE_TIMEOUT_SECONDS_ENV = "TESTKIT_INTERNAL_FILE_TIMEOUT_SECONDS";
+export declare const INTERNAL_FILE_DEADLINE_MS_ENV = "TESTKIT_INTERNAL_FILE_DEADLINE_MS";
+export interface FileTimeoutBudget {
+    deadlineMs: number;
+    fileTimeoutSeconds: number;
+}
+export interface FileTimeoutEnv {
+    [INTERNAL_FILE_DEADLINE_MS_ENV]: string;
+    [INTERNAL_FILE_TIMEOUT_SECONDS_ENV]: string;
+}
+export declare function parseFileTimeoutOption(value: unknown): number;
+export declare function normalizeFileTimeoutSeconds(value: unknown, label?: string): number;
+export declare function normalizeWaitIntervalSeconds(value?: unknown): number;
+export declare function buildFileTimeoutEnv(fileTimeoutSeconds: number, startedAtMs: number): FileTimeoutEnv;
+export declare function readFileTimeoutBudget(env: unknown): FileTimeoutBudget;
+export declare function remainingFileTimeoutMs(budget: FileTimeoutBudget, nowMs?: number): number;
+export declare function remainingFileTimeoutSeconds(budget: FileTimeoutBudget, nowMs?: number): number;
+export declare function remainingCooperativeFileTimeoutMs(budget: FileTimeoutBudget, nowMs?: number): number;
+export declare function cooperativeFileTimeoutErrorReserveMs(fileTimeoutSeconds: number): number;
+export declare function subprocessFileTimeoutMs(fileTimeoutSeconds: number): number;
+export declare function formatWaitForTimeoutError(description: unknown, fileTimeoutSeconds: number): string;
+export declare function formatFileTimeoutBudgetError(fileTimeoutSeconds: number): string;

package/dist/domain/file-timeout.js

@@ -0,0 +1 @@
+export const DEFAULT_FILE_TIMEOUT_SECONDS=60,FILE_TIMEOUT_INTERVAL_SECONDS=.25,FILE_TIMEOUT_COOPERATIVE_ERROR_RESERVE_MAX_MS=2e3,FILE_TIMEOUT_COOPERATIVE_ERROR_RESERVE_MIN_MS=250,FILE_TIMEOUT_COOPERATIVE_ERROR_RESERVE_RATIO=.2,FILE_TIMEOUT_SUBPROCESS_EXIT_GRACE_MS=1e3,INTERNAL_FILE_TIMEOUT_SECONDS_ENV="TESTKIT_INTERNAL_FILE_TIMEOUT_SECONDS",INTERNAL_FILE_DEADLINE_MS_ENV="TESTKIT_INTERNAL_FILE_DEADLINE_MS";export function parseFileTimeoutOption(e){return i(e,"--file-timeout-seconds")}export function normalizeFileTimeoutSeconds(e,t="execution.fileTimeoutSeconds"){return o(e,t)}export function normalizeWaitIntervalSeconds(e){if(e==null)return .25;const t=Number(e);if(!Number.isFinite(t)||t<=0)throw new Error("waitFor intervalSeconds must be a positive number.");return t}export function buildFileTimeoutEnv(e,t){return{[INTERNAL_FILE_TIMEOUT_SECONDS_ENV]:String(e),[INTERNAL_FILE_DEADLINE_MS_ENV]:String(t+e*1e3)}}export function readFileTimeoutBudget(e){if(!E(e))throw new Error("Runtime file timeout budget is missing.");return{fileTimeoutSeconds:normalizeFileTimeoutSeconds(e[INTERNAL_FILE_TIMEOUT_SECONDS_ENV],INTERNAL_FILE_TIMEOUT_SECONDS_ENV),deadlineMs:n(e[INTERNAL_FILE_DEADLINE_MS_ENV],INTERNAL_FILE_DEADLINE_MS_ENV)}}export function remainingFileTimeoutMs(e,t=Date.now()){return Math.max(0,e.deadlineMs-t)}export function remainingFileTimeoutSeconds(e,t=Date.now()){return remainingFileTimeoutMs(e,t)/1e3}export function remainingCooperativeFileTimeoutMs(e,t=Date.now()){return Math.max(0,remainingFileTimeoutMs(e,t)-cooperativeFileTimeoutErrorReserveMs(e.fileTimeoutSeconds))}export function cooperativeFileTimeoutErrorReserveMs(e){return Math.min(2e3,Math.max(250,Math.floor(e*1e3*.2)))}export function subprocessFileTimeoutMs(e){return e*1e3+cooperativeFileTimeoutErrorReserveMs(e)+1e3}export function formatWaitForTimeoutError(e,t){return`Timed out waiting for ${String(e||"condition").trim()||"condition"} before the ${String(t)}s test file timeout`}export function formatFileTimeoutBudgetError(e){return`Test file exceeded the ${String(e)}s wall-clock timeout`}function i(e,t){const r=Number.parseInt(String(e),10);if(!Number.isInteger(r)||r<=0)throw new Error(`Invalid ${t} value "${String(e)}". Expected a positive integer.`);return r}function o(e,t){const r=Number(e);if(!Number.isInteger(r)||r<=0)throw new Error(`${t} must be a positive integer.`);return r}function n(e,t){const r=Number(e);if(!Number.isInteger(r)||r<=0)throw new Error(`${t} must be a positive integer timestamp.`);return r}function E(e){return e!==null&&typeof e=="object"}

package/dist/domain/identifiers.d.ts

@@ -0,0 +1,9 @@
+export declare const ENGINE_IDS: readonly ["k6", "node-vitest", "playwright"];
+export type EngineId = (typeof ENGINE_IDS)[number];
+export declare const PUBLIC_TEST_TYPES: readonly ["ui", "e2e", "int", "contract", "data", "dal", "load"];
+export type PublicTestType = (typeof PUBLIC_TEST_TYPES)[number];
+export declare const RUNNER_PROFILE_IDS: readonly ["k6-http", "k6-dal", "node-vitest-data", "node-vitest-contract", "playwright-ui"];
+export type RunnerProfileId = (typeof RUNNER_PROFILE_IDS)[number];
+export declare function isEngineId(value: unknown): value is EngineId;
+export declare function isPublicTestType(value: unknown): value is PublicTestType;
+export declare function isRunnerProfileId(value: unknown): value is RunnerProfileId;

package/dist/domain/identifiers.js

@@ -0,0 +1 @@
+export const ENGINE_IDS=Object.freeze(["k6","node-vitest","playwright"]),PUBLIC_TEST_TYPES=Object.freeze(["ui","e2e","int","contract","data","dal","load"]),RUNNER_PROFILE_IDS=Object.freeze(["k6-http","k6-dal","node-vitest-data","node-vitest-contract","playwright-ui"]);const e=new Set(ENGINE_IDS),n=new Set(PUBLIC_TEST_TYPES),o=new Set(RUNNER_PROFILE_IDS);export function isEngineId(t){return typeof t=="string"&&e.has(t)}export function isPublicTestType(t){return typeof t=="string"&&n.has(t)}export function isRunnerProfileId(t){return typeof t=="string"&&o.has(t)}

package/dist/domain/operation-display.d.ts

@@ -0,0 +1,10 @@
+export type OperationStatusKind = "failed" | "passed" | "running" | "skipped" | "unknown";
+export interface OperationStatusLabelOptions {
+    runningLabel?: string;
+}
+export declare function normalizeOperationStatus(status: unknown): string;
+export declare function operationStatusKind(status: unknown): OperationStatusKind;
+export declare function operationStatusLabel(status: unknown, { runningLabel }?: Readonly<OperationStatusLabelOptions>): string;
+export declare function isNeutralOperationStatus(status: unknown): boolean;
+export declare function isSuccessfulOperationStatus(status: unknown): boolean;
+export declare function formatOperationSummary(operation?: unknown): string;

package/dist/domain/operation-display.js

@@ -0,0 +1 @@
+import{redactSensitiveText as i}from"../kernel/redaction.js";const g=new Set(["passed","succeeded","success","ready","cached"]),h=new Set(["running","pending","queued","starting","applying","cancelling"]),y=new Set(["skipped","skip","noop","no-op","not_applicable","not-applicable","cancelled","canceled","interrupted"]),A=new Set(["failed","error"]);export function normalizeOperationStatus(n){return S(n||"unknown").trim().toLowerCase().replaceAll(" ","_")}export function operationStatusKind(n){const e=normalizeOperationStatus(n);return g.has(e)?"passed":h.has(e)?"running":y.has(e)?"skipped":A.has(e)?"failed":"unknown"}export function operationStatusLabel(n,{runningLabel:e="RUN"}={}){const t=operationStatusKind(n);return t==="passed"?"PASS":t==="running"?e:t==="skipped"?"SKIP":"FAIL"}export function isNeutralOperationStatus(n){return operationStatusKind(n)==="skipped"}export function isSuccessfulOperationStatus(n){return operationStatusKind(n)==="passed"}export function formatOperationSummary(n={}){const e=l(n),t=l(e.metadata),r=[];e.message?r.push(i(e.message)):e.summary?r.push(i(e.summary)):e.error&&r.push(i(e.error));const a=o(t.phase||e.phase),c=o(t.action||e.action),s=o(t.resource||e.resource),u=o(t.decision),p=o(t.reason),f=k(e.logRefs);if(!r.length&&(a||c||s)){const m=[a,c].filter(Boolean).join(".");r.push(m+(s?` ${s}`:""))}return u&&r.push(`decision=${i(u)}`),p&&r.push(`reason=${i(p)}`),f&&r.push(`log=${f}`),r.filter(Boolean).join(" \xB7 ")}function k(n=[]){if(!Array.isArray(n))return"";const e=n.find(d);if(!e)return"";const t=o(e.service||e.serviceName),r=o(e.category||e.kind),a=o(e.step||e.name),c=o(e.state),s=[t,[r,a].filter(Boolean).join("."),c].filter(Boolean).join(" ");return s?i(s):""}function l(n){return d(n)?n:{}}function d(n){return typeof n=="object"&&n!==null&&!Array.isArray(n)}function o(n){return n?S(n):""}const S=String;

package/dist/domain/operation-reason.d.ts

@@ -0,0 +1,5 @@
+export declare const MAX_OPERATION_REASON_LENGTH = 240;
+export interface OperationReasonOptions {
+    maxLength?: number;
+}
+export declare function normalizeOperationReason(value: unknown, fallback?: unknown, options?: OperationReasonOptions): string;

package/dist/domain/operation-reason.js

@@ -0,0 +1 @@
+import{redactSensitiveText as i}from"../kernel/redaction.js";export const MAX_OPERATION_REASON_LENGTH=240;export function normalizeOperationReason(r,n="requested",e={}){return o(r,e)||o(n,e)||"requested"}function o(r,n={}){const e=Math.floor(n.maxLength??MAX_OPERATION_REASON_LENGTH),t=i(r).replace(/\s+/g," ").trim();return t?t.length<=e?t:e<=3?t.slice(0,e):`${t.slice(0,e-3)}...`:""}

package/dist/domain/postgres-route.d.ts

@@ -0,0 +1,4 @@
+export interface OwnedPostgresContainerRoute {
+    containerId: string;
+    containerPort?: number | null;
+}

package/dist/domain/postgres-route.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/runtime-identity.d.ts

@@ -0,0 +1 @@
+export declare function buildRuntimeIds(count: number): string[];

package/dist/domain/runtime-identity.js

@@ -0,0 +1 @@
+export function buildRuntimeIds(n){return Array.from({length:n},(t,r)=>`runtime-${String(r+1)}`)}

package/dist/domain/runtime-isolation-contract.d.ts

@@ -0,0 +1,5 @@
+export declare const DEFAULT_RUNTIME_ISOLATION_POLICY: "shared";
+export declare const RUNTIME_ISOLATION_POLICIES: readonly ["shared", "resetBefore", "resetAfter", "exclusive"];
+export type RuntimeIsolationPolicy = (typeof RUNTIME_ISOLATION_POLICIES)[number];
+export declare function isRuntimeIsolationPolicy(value: unknown): value is RuntimeIsolationPolicy;
+export declare function normalizeRuntimeIsolationPolicy(value: unknown, label: string): RuntimeIsolationPolicy;

package/dist/domain/runtime-isolation-contract.js

@@ -0,0 +1 @@
+export const DEFAULT_RUNTIME_ISOLATION_POLICY="shared",RUNTIME_ISOLATION_POLICIES=Object.freeze(["shared","resetBefore","resetAfter","exclusive"]);const r=new Set(RUNTIME_ISOLATION_POLICIES);export function isRuntimeIsolationPolicy(e){return typeof e=="string"&&r.has(e)}export function normalizeRuntimeIsolationPolicy(e,t){if(isRuntimeIsolationPolicy(e))return e;throw new Error(`${t} must be one of ${RUNTIME_ISOLATION_POLICIES.map(o=>JSON.stringify(o)).join(", ")}`)}

package/dist/domain/service-name.d.ts

@@ -0,0 +1,2 @@
+export declare function requireServiceName(value: unknown, label?: string): string;
+export declare function assertPortableServiceNameSet(serviceNames: readonly string[]): void;

package/dist/domain/service-name.js

@@ -0,0 +1 @@
+const E=128,o=/^[A-Za-z0-9][A-Za-z0-9._-]*$/u,i=/^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)/iu;export function requireServiceName(e,t="Testkit service name"){if(typeof e=="string"&&e.length<=128&&o.test(e)&&!e.endsWith(".")&&!i.test(e))return e;throw new Error(`${t} must be 1-128 characters using only ASCII letters, digits, dot, underscore, or hyphen, must start with a letter or digit, must not end with a dot, and must not use a reserved Windows device name`)}export function assertPortableServiceNameSet(e){const t=new Map;for(const s of e){const r=s.toLowerCase(),n=t.get(r);if(n!==void 0&&n!==s)throw new Error(`Service names "${n}" and "${s}" collide on case-insensitive filesystems`);t.set(r,s)}}

package/dist/domain/suite-selection.d.ts

@@ -0,0 +1,20 @@
+import { type PublicTestType } from "./identifiers.js";
+export interface PlainSuiteSelector {
+    kind: "plain";
+    name: string;
+    raw: string;
+}
+export interface TypedSuiteSelector {
+    kind: "typed";
+    name: string;
+    raw: string;
+    testType: PublicTestType;
+}
+export type SuiteSelector = PlainSuiteSelector | TypedSuiteSelector;
+export declare function normalizeTypeValues(values?: readonly unknown[]): string[];
+export declare function isAllTypeSelection(typeValues?: readonly string[]): boolean;
+export declare function parseSuiteSelectors(values?: readonly unknown[]): SuiteSelector[];
+export declare function matchesSelectedTypes(selectionType: string, typeValues: readonly string[]): boolean;
+export declare function matchesSuiteSelectors(selectionType: null | string | undefined, suiteName: string, selectors?: null | readonly SuiteSelector[]): boolean;
+export declare function parseTypeOption(values: unknown, positionalType?: null | string): string[];
+export declare function parseSuiteOption(values: unknown): SuiteSelector[];

package/dist/domain/suite-selection.js

@@ -0,0 +1 @@
+import{RUN_TYPE_ORDER as s,RUN_TYPES as a,isPublicTestType as d,publicTestTypeListText as f}from"./test-types.js";import"./identifiers.js";const l=String;export function normalizeTypeValues(t=[]){const n=[];for(const r of t)if(r!=null)for(const o of l(r).split(",")){const i=o.trim();if(!i)continue;const c=i;if(!a.has(c))throw new Error(`Unknown type "${i}". Expected one of: ${f({includeAll:!0})}.`);n.push(c)}if(n.length===0)return["all"];const e=[...new Set(n)];if(e.includes("all")&&e.length>1)throw new Error('"--type all" cannot be combined with other types.');return e.sort((r,o)=>s.indexOf(r)-s.indexOf(o))}export function isAllTypeSelection(t=[]){return t.length===0||t.length===1&&t[0]==="all"}export function parseSuiteSelectors(t=[]){const n=[];for(const e of t)if(e!=null)for(const r of l(e).split(",")){const o=r.trim();if(!o)continue;const i=o.match(/^([a-z]+):(.*)$/);if(!i){n.push({kind:"plain",name:o,raw:o});continue}const c=i[1],p=i[2].trim(),u=c.trim();if(!d(u))throw new Error(`Unknown suite selector type "${c}". Expected one of: ${f()}.`);if(!p)throw new Error(`Invalid suite selector "${o}". Expected "<type>:<suite-name>".`);n.push({kind:"typed",testType:u,name:p,raw:`${u}:${p}`})}return n}export function matchesSelectedTypes(t,n){return isAllTypeSelection(n)||n.includes(t)}export function matchesSuiteSelectors(t,n,e=[]){return!e||e.length===0?!0:e.some(r=>(r.kind==="plain"||r.testType===t)&&r.name===n)}export function parseTypeOption(t,n=null){const e=[];if(n&&e.push(n),Array.isArray(t)){const r=t;e.push(...r)}else t&&e.push(t);return normalizeTypeValues(e)}export function parseSuiteOption(t){const n=Array.isArray(t)?t:t?[t]:[];return parseSuiteSelectors(n)}

package/dist/domain/test-outcomes.d.ts

@@ -0,0 +1,3 @@
+export declare const TEST_OUTCOME_STATUS_ORDER: readonly ["passed", "failed", "skipped", "not_run", "cancelled", "interrupted"];
+export type TestOutcomeStatus = (typeof TEST_OUTCOME_STATUS_ORDER)[number];
+export declare function isTestOutcomeStatus(value: unknown): value is TestOutcomeStatus;

package/dist/domain/test-outcomes.js

@@ -0,0 +1 @@
+export const TEST_OUTCOME_STATUS_ORDER=Object.freeze(["passed","failed","skipped","not_run","cancelled","interrupted"]);const t=new Set(TEST_OUTCOME_STATUS_ORDER);export function isTestOutcomeStatus(e){return typeof e=="string"&&t.has(e)}

package/dist/domain/test-types.d.ts

@@ -0,0 +1,16 @@
+import { type PublicTestType } from "./identifiers.js";
+export declare const TEST_TYPE_ORDER: readonly string[];
+declare const RUN_TYPE_VALUES: readonly ["ui", "e2e", "int", "contract", "data", "dal", "load", "all"];
+export type RunType = (typeof RUN_TYPE_VALUES)[number];
+export declare const RUN_TYPE_ORDER: readonly string[];
+export declare const RUN_TYPES: ReadonlySet<string>;
+export interface PublicTestTypeListOptions {
+    includeAll?: boolean;
+}
+export declare function isPublicTestType(value: unknown): value is PublicTestType;
+export declare function isRunType(value: unknown): value is RunType;
+export declare function formatPublicTestType(value: unknown): string;
+export declare function publicTestTypeList({ includeAll }?: PublicTestTypeListOptions): RunType[];
+export declare function publicTestTypeListText(options?: PublicTestTypeListOptions): string;
+export declare function formatTestTypeLabel(testType: PublicTestType): string;
+export {};

package/dist/domain/test-types.js

@@ -0,0 +1 @@
+import{PUBLIC_TEST_TYPES as e,isPublicTestType as T}from"./identifiers.js";export const TEST_TYPE_ORDER=e;const o=[...e,"all"];export const RUN_TYPE_ORDER=o,RUN_TYPES=new Set(RUN_TYPE_ORDER);const s={ui:"UI",e2e:"E2E",int:"INT",contract:"Contract",data:"Data",dal:"DAL",load:"Load"},i=String;export function isPublicTestType(t){return T(n(t))}export function isRunType(t){return RUN_TYPES.has(n(t))}export function formatPublicTestType(t){const r=n(t);return isPublicTestType(r)?s[r]:i(t||"")}export function publicTestTypeList({includeAll:t=!1}={}){return t?[...o]:[...e]}export function publicTestTypeListText(t={}){return publicTestTypeList(t).join(", ")}function n(t){return i(t||"").trim()}export function formatTestTypeLabel(t){return t==="int"?"Integration":formatPublicTestType(t)}

package/dist/engines/adapters/evidence-files.d.ts

@@ -0,0 +1,32 @@
+import { type BigIntStats } from "node:fs";
+import fs from "node:fs/promises";
+import type { EngineArtifactEvidence } from "../api/index.js";
+export interface EvidenceFileAccess {
+    lstat(filePath: string): Promise<BigIntStats>;
+    openReadOnly(filePath: string): Promise<fs.FileHandle>;
+    readonly platform: NodeJS.Platform;
+    readChunk(handle: fs.FileHandle, buffer: Buffer): Promise<number>;
+    statHandle(handle: fs.FileHandle): Promise<BigIntStats>;
+}
+export declare const evidenceFileAccess: EvidenceFileAccess;
+export interface EvidenceFileIdentity {
+    readonly sha256: string;
+    readonly sizeBytes: number;
+}
+export interface StableEvidenceFile extends EvidenceFileIdentity {
+    readonly contents: Buffer;
+}
+export interface OwnedEvidenceSnapshot {
+    readonly filePath: string;
+    readonly identity: EvidenceFileIdentity;
+}
+export interface StableJsonFile {
+    readonly file: StableEvidenceFile | null;
+    readonly value: unknown;
+}
+export declare function stableEvidenceFromBuffer(contents: Buffer): StableEvidenceFile;
+export declare function readStableJsonFile(filePath: string, maximumBytes: number, label: string, fileAccess: EvidenceFileAccess): Promise<StableJsonFile>;
+export declare function readStableEvidenceFile(filePath: string, maximumBytes: number, label: string, fileAccess: EvidenceFileAccess, expectedIdentity?: BigIntStats): Promise<StableEvidenceFile>;
+export declare function writeOwnedEvidenceFile(directory: string, filename: string, contents: Buffer | string): Promise<string>;
+export declare function snapshotStableEvidenceFile(sourcePath: string, maximumBytes: number, label: string, fileAccess: EvidenceFileAccess, expectedIdentity: BigIntStats, targetDirectory: string, filename: string): Promise<OwnedEvidenceSnapshot>;
+export declare function evidenceArtifact(filePath: string, file: EvidenceFileIdentity, contentType: string, kind: string, name: string, summary: string): EngineArtifactEvidence;

package/dist/engines/adapters/evidence-files.js

@@ -0,0 +1 @@
+import{requireNativeEvidenceJson as O}from"./native-report.js";import S from"node:crypto";import{constants as R}from"node:fs";import d from"node:fs/promises";import F from"node:path";import{readOnlyNoFollowOpenFlags as I,sameFileSnapshot as U,samePathAndHandleFileSnapshot as C}from"../../process/files/file-snapshot.js";const z=64*1024;export const evidenceFileAccess={lstat:async t=>d.lstat(t,{bigint:!0}),openReadOnly:async t=>d.open(t,I(process.platform,R)),platform:process.platform,readChunk:async(t,e)=>(await t.read(e,0,e.byteLength,null)).bytesRead,statHandle:async t=>t.stat({bigint:!0})};export function stableEvidenceFromBuffer(t){return{contents:t,sha256:S.createHash("sha256").update(t).digest("hex"),sizeBytes:t.byteLength}}export async function readStableJsonFile(t,e,n,r){let o;try{o=await readStableEvidenceFile(t,e,n,r)}catch(i){if(L(i))return{file:null,value:null};throw i}let a;try{a=JSON.parse(o.contents.toString("utf8"))}catch(i){throw new Error(`${n} is not valid JSON`,{cause:i})}return O(a,n),{file:o,value:a}}export async function readStableEvidenceFile(t,e,n,r,o){const a=await r.lstat(t);u(a,e,n),o!==void 0&&E(o,a,n);const i=await r.openReadOnly(t);try{const w=await r.statHandle(i);u(w,e,n),m(a,w,n,r.platform);const p=[],l=S.createHash("sha256");let h=0;const s=Buffer.allocUnsafe(z);for(;;){const f=await r.readChunk(i,s);if(N(f,s.byteLength,n),f===0)break;if(h+=f,h>e)throw new Error(`${n} exceeds its ${e.toString()} byte limit`);const g=Buffer.from(s.subarray(0,f));p.push(g),l.update(g)}const c=await r.statHandle(i),y=await r.lstat(t);if(u(c,e,n),u(y,e,n),E(w,c,n),E(a,y,n),m(y,c,n,r.platform),BigInt(h)!==w.size)throw new Error(`${n} changed while it was read`);return{contents:Buffer.concat(p,h),sha256:l.digest("hex"),sizeBytes:h}}finally{await i.close()}}export async function writeOwnedEvidenceFile(t,e,n){const r=F.join(t,e),o=F.join(t,`.${e}.${S.randomUUID()}.tmp`);let a=null;try{return a=await d.open(o,"wx",384),await a.writeFile(n),await a.sync(),await a.close(),a=null,await d.rename(o,r),process.platform!=="win32"&&await d.chmod(r,384),r}catch(i){throw a!==null&&await a.close().catch(()=>{}),await d.rm(o,{force:!0}).catch(()=>{}),i}}export async function snapshotStableEvidenceFile(t,e,n,r,o,a,i){const w=await r.lstat(t);u(w,e,n),E(o,w,n);const p=await r.openReadOnly(t),l=F.join(a,i),h=F.join(a,`.${i}.${S.randomUUID()}.tmp`);let s=null;try{const c=await r.statHandle(p);u(c,e,n),m(w,c,n,r.platform),s=await d.open(h,"wx",384);const y=S.createHash("sha256");let f=0;const g=Buffer.allocUnsafe(z);for(;;){const $=await r.readChunk(p,g);if(N($,g.byteLength,n),$===0)break;if(f+=$,f>e)throw new Error(`${n} exceeds its ${e.toString()} byte limit`);const k=g.subarray(0,$);await s.write(k),y.update(k)}const v=await r.statHandle(p),H=await r.lstat(t);if(u(v,e,n),u(H,e,n),E(c,v,n),E(w,H,n),m(H,v,n,r.platform),BigInt(f)!==c.size)throw new Error(`${n} changed while it was read`);return await s.sync(),await s.close(),s=null,await d.rename(h,l),process.platform!=="win32"&&await d.chmod(l,384),{filePath:l,identity:{sha256:y.digest("hex"),sizeBytes:f}}}catch(c){throw s!==null&&await s.close().catch(()=>{}),await d.rm(h,{force:!0}).catch(()=>{}),c}finally{await p.close()}}export function evidenceArtifact(t,e,n,r,o,a){return{contentType:n,kind:r,metadata:{sha256:e.sha256,sizeBytes:e.sizeBytes},name:o,path:t,summary:a}}function N(t,e,n){if(!Number.isSafeInteger(t)||t<0||t>e)throw new Error(`${n} returned an invalid read length`)}function u(t,e,n){if(!t.isFile()||t.isSymbolicLink())throw new Error(`${n} must be a regular non-symbolic-link file`);if(t.size<0n||t.size>BigInt(e))throw new Error(`${n} exceeds its ${e.toString()} byte limit`)}function E(t,e,n){if(!U(t,e))throw new Error(`${n} changed while it was read`)}function m(t,e,n,r){if(!C(t,e,r))throw new Error(`${n} changed while it was read`)}function L(t){return t instanceof Error&&"code"in t&&t.code==="ENOENT"}

package/dist/engines/adapters/evidence-identity.d.ts

@@ -0,0 +1,12 @@
+import type { EngineJsonObject, RunnerProfileDescriptor } from "../api/index.js";
+import type { EngineId } from "../../domain/identifiers.js";
+import { type PlatformTarget } from "../../process/host/platform.js";
+export type EngineInstallationKind = "direct-package" | "root-direct-packages" | "root-playwright-family";
+interface EngineEvidenceIdentityRequest {
+    readonly engineId: EngineId;
+    readonly installationKind: EngineInstallationKind;
+    readonly profile: Readonly<RunnerProfileDescriptor>;
+    readonly target?: Readonly<PlatformTarget>;
+}
+export declare function engineEvidenceIdentity(request: Readonly<EngineEvidenceIdentityRequest>): EngineJsonObject;
+export {};

package/dist/engines/adapters/evidence-identity.js

@@ -0,0 +1 @@
+import o from"node:fs";import{fileURLToPath as i}from"node:url";import{currentPlatformTarget as a,platformTargetKey as n,SUPPORTED_PLATFORM_TARGETS as f,UnsupportedPlatformTargetError as p}from"../../process/host/platform.js";const s=c();export function engineEvidenceIdentity(e){if(e.profile.engineId!==e.engineId)throw new TypeError(`Evidence profile ${e.profile.id} belongs to ${e.profile.engineId}, expected ${e.engineId}`);const t=e.target??a();if(!f.some(r=>n(r)===n(t)))throw new p(t.platform,t.arch,"engine evidence target");return Object.freeze({engineId:e.engineId,installationKind:e.installationKind,nodeVersion:process.versions.node,profileId:e.profile.id,target:Object.freeze({arch:t.arch,platform:t.platform}),testkitVersion:s})}function c(){const e=i(new URL("../../../package.json",import.meta.url));let t;try{t=JSON.parse(o.readFileSync(e,"utf8"))}catch(r){throw new TypeError(`Root Testkit package manifest could not be read from ${e}`,{cause:r})}if(!d(t)||t.name!=="@gfdelarue/testkit")throw new TypeError(`Root Testkit package manifest at ${e} has an invalid package identity`);if(typeof t.version!="string"||!/^(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u.test(t.version))throw new TypeError(`Root Testkit package manifest at ${e} has an invalid version`);return t.version}function d(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}