@gfdelarue/testkit 0.3.0

package/dist/database/constants.js

@@ -0,0 +1 @@
+export const LOCAL_IMAGE="pgvector/pgvector:pg16",LOCAL_USER="testkit",LOCAL_PASSWORD="testkit",LOCAL_ADMIN_DB="postgres",LOCAL_MAX_CONNECTIONS=200,LOCAL_READY_TIMEOUT_MS=6e4,LOCAL_POLL_INTERVAL_MS=1e3,LOCAL_ADMIN_QUERY_RETRY_MS=15e3,LOCAL_ADMIN_QUERY_RETRY_INTERVAL_MS=250,LOCAL_DROP_DATABASE_TIMEOUT_MS=15e3,LOCAL_DROP_DATABASE_POLL_INTERVAL_MS=250;

package/dist/database/docker.d.ts

@@ -0,0 +1,65 @@
+import type { ManagedProcessResult } from "../process/index.js";
+export declare const TESTKIT_MANAGED_LABEL = "com.elench.testkit.managed";
+export declare const TESTKIT_RESOURCE_KIND_LABEL = "com.elench.testkit.resource.kind";
+export declare const TESTKIT_RESOURCE_NAME_LABEL = "com.elench.testkit.resource.name";
+export declare const TESTKIT_PRODUCT_DIR_LABEL = "com.elench.testkit.product.dir";
+export declare const TESTKIT_PRODUCT_ID_LABEL = "com.elench.testkit.product.id";
+export declare const TESTKIT_SCOPE_LABEL = "com.elench.testkit.scope";
+export declare const TESTKIT_CACHE_POLICY_LABEL = "com.elench.testkit.cache.policy";
+export declare const TESTKIT_CREATED_AT_LABEL = "com.elench.testkit.created-at";
+export declare const TESTKIT_RESOURCE_GENERATION_LABEL = "com.elench.testkit.resource.generation";
+export declare const DOCKER_OWNERSHIP_OPERATION_TIMEOUTS_MS: Readonly<{
+    inspect: 30000;
+    list: 30000;
+    remove: 120000;
+    stop: 30000;
+}>;
+export type DockerLabels = Readonly<Record<string, string>>;
+export interface ProductIdentity {
+    dir: string;
+    id: string;
+}
+export interface DockerOwnershipOperationOptions {
+    signal?: AbortSignal;
+}
+export interface DockerResourceIdentity {
+    cachePolicy?: null | string;
+    createdAt?: null | string;
+    generation: string;
+    kind: string;
+    name: string;
+    scope?: null | string;
+}
+export interface ManagedDockerContainer {
+    createdAt: null | string;
+    id: string;
+    image: string;
+    labels: DockerLabels;
+    name: string;
+    running: boolean;
+    shortId: string;
+    status: string;
+}
+export interface ManagedDockerVolume {
+    createdAt: null | string;
+    driver: string;
+    labels: DockerLabels;
+    mountpoint: string;
+    name: string;
+}
+type DockerInspectRecord = Record<string, unknown>;
+export declare function buildProductIdentity(productDir: string): ProductIdentity;
+export declare function buildDockerResourceLabels(productDir: string, resource: Readonly<DockerResourceIdentity>): DockerLabels;
+export declare function dockerLabelArgs(labels: Readonly<Record<string, unknown>>): string[];
+export declare function inspectDockerContainer(containerRef: string, options?: Readonly<DockerOwnershipOperationOptions>): Promise<DockerInspectRecord | null>;
+export declare function listManagedDockerContainers(product: Readonly<ProductIdentity>): Promise<ManagedDockerContainer[]>;
+export declare function inspectDockerVolume(volumeRef: string, options?: Readonly<DockerOwnershipOperationOptions>): Promise<DockerInspectRecord | null>;
+export declare function listManagedDockerVolumes(product: Readonly<ProductIdentity>): Promise<ManagedDockerVolume[]>;
+export declare function removeDockerContainer(containerRef: string, displayName?: string): Promise<boolean>;
+export declare function removeDockerVolume(volumeRef: string, expected: Readonly<ManagedDockerVolume>, options?: Readonly<DockerOwnershipOperationOptions>): Promise<boolean>;
+export declare function sameDockerVolumeGeneration(current: Readonly<ManagedDockerVolume>, expected: Readonly<ManagedDockerVolume>): boolean;
+export declare function stopDockerContainer(containerRef: string, displayName?: string): Promise<boolean>;
+export declare function normalizeDockerContainerInspect(value: unknown): ManagedDockerContainer | null;
+export declare function normalizeDockerVolumeInspect(value: unknown): ManagedDockerVolume | null;
+export declare function runDockerCommand(args: readonly string[], displayLabel: string, timeoutMs: number, signal?: AbortSignal): Promise<ManagedProcessResult>;
+export {};

package/dist/database/docker.js

@@ -0,0 +1,5 @@
+import b from"crypto";import D from"fs";import C from"path";import{managedHostProcessInfrastructureError as T,runManagedHostProcess as w}from"../process/index.js";export const TESTKIT_MANAGED_LABEL="com.elench.testkit.managed",TESTKIT_RESOURCE_KIND_LABEL="com.elench.testkit.resource.kind",TESTKIT_RESOURCE_NAME_LABEL="com.elench.testkit.resource.name",TESTKIT_PRODUCT_DIR_LABEL="com.elench.testkit.product.dir",TESTKIT_PRODUCT_ID_LABEL="com.elench.testkit.product.id",TESTKIT_SCOPE_LABEL="com.elench.testkit.scope",TESTKIT_CACHE_POLICY_LABEL="com.elench.testkit.cache.policy",TESTKIT_CREATED_AT_LABEL="com.elench.testkit.created-at",TESTKIT_RESOURCE_GENERATION_LABEL="com.elench.testkit.resource.generation";const I=4e3,d=String;export const DOCKER_OWNERSHIP_OPERATION_TIMEOUTS_MS=Object.freeze({inspect:3e4,list:3e4,remove:12e4,stop:3e4});export function buildProductIdentity(e){const t=A(e);return{dir:t,id:O(t,24)}}export function buildDockerResourceLabels(e,t){if(!t.generation)throw new Error("Docker resource generation must be non-empty");const r=buildProductIdentity(e);return{[TESTKIT_MANAGED_LABEL]:"true",[TESTKIT_RESOURCE_KIND_LABEL]:t.kind,[TESTKIT_RESOURCE_NAME_LABEL]:t.name,[TESTKIT_PRODUCT_DIR_LABEL]:r.dir,[TESTKIT_PRODUCT_ID_LABEL]:r.id,[TESTKIT_SCOPE_LABEL]:t.scope||t.kind,[TESTKIT_CACHE_POLICY_LABEL]:t.cachePolicy||"ephemeral",[TESTKIT_CREATED_AT_LABEL]:t.createdAt||new Date().toISOString(),[TESTKIT_RESOURCE_GENERATION_LABEL]:t.generation}}export function dockerLabelArgs(e){return Object.entries(e).flatMap(([t,r])=>["--label",`${t}=${d(r)}`])}export async function inspectDockerContainer(e,t={}){const r=`Docker container inspect for ${e}`,n=await runDockerCommand(["inspect",e],r,DOCKER_OWNERSHIP_OPERATION_TIMEOUTS_MS.inspect,t.signal);if(n.exitCode!==0){if(p(n))return null;throw s(r,n)}return m(n,r,"Id")}export async function listManagedDockerContainers(e){return y(["--filter",`label=${TESTKIT_MANAGED_LABEL}=true`,"--filter",`label=${TESTKIT_PRODUCT_ID_LABEL}=${e.id}`])}export async function inspectDockerVolume(e,t={}){const r=`Docker volume inspect for ${e}`,n=await runDockerCommand(["volume","inspect",e],r,DOCKER_OWNERSHIP_OPERATION_TIMEOUTS_MS.inspect,t.signal);if(n.exitCode!==0){if(E(n))return null;throw s(r,n)}return m(n,r,"Name")}export async function listManagedDockerVolumes(e){return _(["--filter",`label=${TESTKIT_MANAGED_LABEL}=true`,"--filter",`label=${TESTKIT_PRODUCT_ID_LABEL}=${e.id}`])}export async function removeDockerContainer(e,t=e){const r=`Docker container removal for ${t}`,n=await runDockerCommand(["rm","-f","-v",e],r,DOCKER_OWNERSHIP_OPERATION_TIMEOUTS_MS.remove);if(n.exitCode===0)return n.stdout.trim().length>0;if(p(n))return!1;throw s(r,n)}export async function removeDockerVolume(e,t,r={}){const n=normalizeDockerVolumeInspect(await inspectDockerVolume(e,r));if(n===null||!sameDockerVolumeGeneration(n,t))return!1;const o=`Docker volume removal for ${e}`,c=await runDockerCommand(["volume","rm","-f",e],o,DOCKER_OWNERSHIP_OPERATION_TIMEOUTS_MS.remove,r.signal);if(c.exitCode===0)return!0;if(E(c))return!1;throw s(o,c)}export function sameDockerVolumeGeneration(e,t){return e.name===t.name&&e.createdAt===t.createdAt&&e.driver===t.driver&&e.mountpoint===t.mountpoint&&x(e.labels,t.labels)}export async function stopDockerContainer(e,t=e){const r=`Docker container stop for ${t}`,n=await runDockerCommand(["stop","--time","5",e],r,DOCKER_OWNERSHIP_OPERATION_TIMEOUTS_MS.stop);if(n.exitCode===0)return!0;if(p(n))return!1;throw s(r,n)}async function y(e){const t="Docker container inventory",r=await runDockerCommand(["ps","-a","--format","{{.ID}}",...e],t,DOCKER_OWNERSHIP_OPERATION_TIMEOUTS_MS.list);if(r.exitCode!==0)throw s(t,r);const{stdout:n}=r,o=n.split(/\r?\n/).map(i=>i.trim()).filter(Boolean);if(o.length===0)return[];const c=[];for(const i of o){const f=await inspectDockerContainer(i),u=normalizeDockerContainerInspect(f);u&&c.push(u)}return c}async function _(e){const t="Docker volume inventory",r=await runDockerCommand(["volume","ls","-q",...e],t,DOCKER_OWNERSHIP_OPERATION_TIMEOUTS_MS.list);if(r.exitCode!==0)throw s(t,r);const{stdout:n}=r,o=n.split(/\r?\n/).map(i=>i.trim()).filter(Boolean);if(o.length===0)return[];const c=[];for(const i of o){const f=await inspectDockerVolume(i),u=normalizeDockerVolumeInspect(f);u&&c.push(u)}return c}export function normalizeDockerContainerInspect(e){const t=a(e);if(!t||typeof t.Id!="string"||!t.Id)return null;const r=a(t.Config),n=a(t.State),o=d(t.Name||"").replace(/^\//,"");return{id:t.Id,shortId:t.Id.slice(0,12),name:o,image:l(r?.Image)||"",createdAt:l(t.Created),running:!!n?.Running,status:l(n?.Status)||"unknown",labels:h(r?.Labels)}}export function normalizeDockerVolumeInspect(e){const t=a(e);return!t||typeof t.Name!="string"||!t.Name?null:{name:t.Name,driver:l(t.Driver)||"",mountpoint:l(t.Mountpoint)||"",labels:h(t.Labels),createdAt:l(t.CreatedAt)}}function m(e,t,r){let n;try{n=JSON.parse(e.stdout)}catch(i){throw g(t,r,e,i)}const o=Array.isArray(n)?n:null,c=o?a(o[0]):null;if(o?.length!==1||!c||typeof c[r]!="string"||c[r].length===0)throw g(t,r,e);return c}function h(e){const t={},r=a(e);if(!r)return t;for(const[n,o]of Object.entries(r))typeof o=="string"&&(t[n]=o);return t}function x(e,t){const r=Object.entries(e).sort(([o],[c])=>o.localeCompare(c)),n=Object.entries(t).sort(([o],[c])=>o.localeCompare(c));return r.length===n.length&&r.every(([o,c],i)=>n[i]?.[0]===o&&n[i]?.[1]===c)}function a(e){return k(e)?e:null}function k(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function l(e){return typeof e=="string"&&e?e:null}function L(e,t){return k(e)&&e.code===t}function A(e){const t=C.resolve(e||process.cwd());try{return D.realpathSync.native(t)}catch(r){if(L(r,"ENOENT"))return t;throw r}}function O(e,t=24){return b.createHash("sha256").update(d(e)).digest("hex").slice(0,t)}export async function runDockerCommand(e,t,r,n){const o=await w({args:e,cwd:process.cwd(),displayLabel:t,env:process.env,executable:"docker",signal:n,timeoutMs:r}),c=T(t,o);if(c)throw c;return o}function p(e){const t=`${e.stderr}
+${e.stdout}`.toLowerCase();return/\bno such (?:container|object)\b/u.test(t)}function E(e){const t=`${e.stderr}
+${e.stdout}`.toLowerCase();return/\bno such (?:object|volume)\b/u.test(t)}function s(e,t){const r=[t.stderr,t.stdout].filter(Boolean).join(`
+`).trim(),n=r?`
+${r.slice(-I)}`:"",o=new Error(`${e} exited with code ${String(t.exitCode)}${n}`);return Object.defineProperty(o,"result",{enumerable:!1,value:Object.freeze({...t})}),o}function g(e,t,r,n){const o=new Error(`${e} returned malformed Docker inspect output; expected exactly one record with a non-empty ${t}`,n===void 0?void 0:{cause:n});return Object.defineProperty(o,"result",{enumerable:!1,value:Object.freeze({...r})}),o}

package/dist/database/drizzle/index.d.ts

@@ -0,0 +1,13 @@
+type UnknownRecord = Record<string, unknown>;
+export interface DrizzleConfigOptions {
+    consumer?: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    files?: string[];
+    onlyWhenAllowed?: boolean;
+    override?: boolean;
+    requireLocalDatabase?: boolean;
+}
+export declare function defineConfig(): Record<string, never>;
+export declare function defineConfig<TConfig extends UnknownRecord>(config: TConfig, options?: DrizzleConfigOptions): TConfig;
+export {};

package/dist/database/drizzle/index.js

@@ -0,0 +1 @@
+import{assertLocalDatabaseUrl as l,loadDotenvFiles as a}from"../../config/runtime/env/index.js";export function defineConfig(r={},e={}){return a({cwd:e.cwd,env:e.env,files:e.files,onlyWhenAllowed:e.onlyWhenAllowed,override:e.override}),e.requireLocalDatabase!==!1&&l(e.env??process.env,e.consumer??"drizzle.config.ts"),r}

package/dist/database/fingerprint.d.ts

@@ -0,0 +1,12 @@
+import { type NormalizedDatabaseConfig } from "../config/loader/index.js";
+import { type SourceSchemaServiceConfig, type SourceSchemaState } from "./schema-source.js";
+export type TemplateFingerprintConfig = Omit<SourceSchemaServiceConfig, "testkit"> & {
+    testkit: SourceSchemaServiceConfig["testkit"] & {
+        database: NonNullable<SourceSchemaServiceConfig["testkit"]["database"]> & Pick<NormalizedDatabaseConfig, "image" | "user" | "roles">;
+        envFiles?: readonly string[];
+    };
+};
+export interface TemplateFingerprintOptions {
+    sourceSchemaState?: SourceSchemaState | null;
+}
+export declare function computeTemplateFingerprint(config: Readonly<TemplateFingerprintConfig>, options?: Readonly<TemplateFingerprintOptions>): Promise<string>;

package/dist/database/fingerprint.js

@@ -0,0 +1 @@
+import a from"crypto";import{resolveServiceCwd as i}from"../config/loader/index.js";import{appendFileToHash as n,appendFingerprintPathToHash as m,normalizeFingerprintPolicy as c}from"../repo/fingerprint-policy.js";import{collectTemplateInputs as l}from"./template-steps.js";import{appendSourceSchemaCacheToHash as u}from"./schema-source.js";const d="pgvector/pgvector:pg16",h="testkit";export async function computeTemplateFingerprint(t,s={}){const e=a.createHash("sha256"),r=t.testkit.database,p=c(t.testkit.fingerprints);e.update(JSON.stringify({image:r.image||d,user:r.user||h,roles:r.roles,template:r.template||null}));for(const o of t.testkit.envFiles||[])n(e,t.productDir,i(t.productDir,o),p);for(const o of l(t.productDir,r.template||{}))m(e,t.productDir,o,p);return await u(e,t,s.sourceSchemaState||null),e.digest("hex")}

package/dist/database/index.d.ts

@@ -0,0 +1,41 @@
+import { type NormalizedDatabaseConfig } from "../config/loader/index.js";
+import { type SourceSchemaServiceConfig } from "./schema-source.js";
+import { type UserHostLocalPostgresActivityOptions } from "./activity-gate.js";
+import { type LocalPostgresCleanupOptions, type LocalPostgresCleanupResult } from "./cleanup.js";
+import { type TerminalRunDatabaseCleanupAuthority } from "../process/runs/ownership.js";
+import type { DatabaseProgress } from "./progress.js";
+import { type ProductLifecycleFence } from "../process/lifecycle-fence.js";
+export { dropDatabaseWithForceOrDrain, isTransientAdminQueryConnectionError, waitForDatabaseConnectionsToDrain, } from "./admin.js";
+export { readDatabaseInfo, readDatabaseUrl, type DatabaseInfo } from "./state.js";
+export type { DatabaseProgress } from "./progress.js";
+export { refreshDatabaseSchema, verifyDatabaseSchema, type DatabaseSchemaOperationContext, type ResolvedSchemaOperationPlan, type SchemaOperationConfigResolver, type VerifyDatabaseSchemaOptions, } from "./schema-operations.js";
+export type DatabaseRuntimeConfig = Omit<SourceSchemaServiceConfig, "stateDir" | "testkit"> & {
+    stateDir: string;
+    testkit: SourceSchemaServiceConfig["testkit"] & {
+        database?: NormalizedDatabaseConfig | null;
+    };
+};
+export interface RuntimeDatabaseStateLocation {
+    productDir: string;
+    stateDir: string;
+}
+export type DatabaseCleanupOptions = Pick<LocalPostgresCleanupOptions, "dryRun" | "stopIdle">;
+export interface ProvisionDatabaseOptions {
+    progress?: DatabaseProgress | null;
+    signal?: AbortSignal;
+    skipSchemaSourceVerify?: boolean;
+}
+export interface ReadyDatabase {
+    container: string;
+    databaseName: string;
+    templateFingerprint: string;
+    url: string;
+}
+export declare function provisionDatabase(config: Readonly<DatabaseRuntimeConfig>, options?: Readonly<ProvisionDatabaseOptions>): Promise<ReadyDatabase | null>;
+export declare function destroyRuntimeDatabase({ productDir, stateDir }: Readonly<RuntimeDatabaseStateLocation>, activityOptions?: Readonly<UserHostLocalPostgresActivityOptions>): Promise<void>;
+export declare function destroyServiceDatabaseCache(productDir: string, serviceName: string, activityOptions?: Readonly<UserHostLocalPostgresActivityOptions>): Promise<void>;
+export declare function cleanupOrphanedLocalInfrastructure(productDir: string, activityOptions?: Readonly<UserHostLocalPostgresActivityOptions>): Promise<LocalPostgresCleanupResult>;
+export declare function cleanupTerminalRunLocalInfrastructure(fence: Readonly<ProductLifecycleFence>, terminalRunAuthority: Readonly<TerminalRunDatabaseCleanupAuthority>, activityOptions?: Readonly<UserHostLocalPostgresActivityOptions>): Promise<LocalPostgresCleanupResult>;
+export declare function destroyOwnedLocalDatabaseResources(fence: Readonly<ProductLifecycleFence>, options?: Readonly<DatabaseCleanupOptions>): Promise<LocalPostgresCleanupResult>;
+export declare function cleanupOwnedLocalDatabaseResources(productDir: string, options?: Readonly<DatabaseCleanupOptions>): Promise<LocalPostgresCleanupResult>;
+export declare function isDatabaseStateDir(dir: string): boolean;

package/dist/database/index.js

@@ -0,0 +1 @@
+import d from"fs";import m from"path";import{computeTemplateFingerprint as O}from"./fingerprint.js";import{buildDatabaseUrl as v,buildRuntimeDatabaseName as E,buildTemplateDatabaseName as q,hashString as A}from"./naming.js";import{getLocalInfraDir as C,getLocalLocksDir as N,getLocalServiceCacheDir as j,hasRemainingLocalArtifacts as R,requireContainedDatabaseStateDirectory as T,readStateValue as h}from"./state.js";import{runTemplateStage as V,runTemplateStep as B}from"./template-steps.js";import{materializeDatabaseConfig as U}from"../config/loader/index.js";import{applySourceSchemaCache as W,createSourceSchemaMismatchError as z,forceRefreshSourceSchemaCache as H,prepareSourceSchemaCache as Q,verifyLocalSchemaMatchesSource as G}from"./schema-source.js";import{cloneDatabaseFromTemplate as J,createEmptyDatabase as K,databaseExists as k,dropDatabaseIfExists as b}from"./admin.js";import{withUserHostLocalPostgresActivity as y}from"./activity-gate.js";import{ensureLocalContainer as X,loadExistingLocalContainer as P}from"./local-postgres.js";import{writeCacheState as F,writeStateValue as f}from"./state-files.js";import{withProcessLock as _}from"../process/locks.js";import{ensureDatabaseRoles as Y}from"./roles.js";import{assertTerminalRunDatabaseCleanupAuthority as Z,cleanupLocalPostgresDockerResources as ee,cleanupTerminalRunLocalPostgresDockerResources as te,destroyLocalPostgresDockerResources as ae,hasActiveProductRuntime as re}from"./cleanup.js";import"../process/runs/ownership.js";import{requireProductLifecycleFenceProductDir as w}from"../process/lifecycle-fence.js";export{dropDatabaseWithForceOrDrain,isTransientAdminQueryConnectionError,waitForDatabaseConnectionsToDrain}from"./admin.js";export{readDatabaseInfo,readDatabaseUrl}from"./state.js";export{refreshDatabaseSchema,verifyDatabaseSchema}from"./schema-operations.js";export async function provisionDatabase(e,t={}){const r=e.testkit.database;if(!r)return null;const s=U(r),a={...e,stateDir:T(e.productDir,e.stateDir,`Service "${e.name}" database runtime state directory`),testkit:{...e.testkit,database:s}},n={reporter:t.progress?.reporter||null,setupRegistry:t.progress?.setupRegistry||null,signal:t.signal,skipSchemaSourceVerify:t.skipSchemaSourceVerify};return y(a.productDir,async()=>(d.mkdirSync(a.stateDir,{recursive:!0}),ne(a,n)),{signal:t.signal})}export async function destroyRuntimeDatabase({productDir:e,stateDir:t},r={}){const s=T(e,t,"Runtime database state directory");await y(e,async()=>{await le(e,s)},r)}export async function destroyServiceDatabaseCache(e,t,r={}){await y(e,()=>se(e,t),r)}async function se(e,t){const r=j(e,t);if(!d.existsSync(r))return;const s=N(e);d.mkdirSync(s,{recursive:!0}),await _(m.join(s,`template-${t}.lock`),async()=>{const a=await P(e);if(!a){d.rmSync(r,{recursive:!0,force:!0});return}const n=h(m.join(r,"template_database_name"));n&&await b(a,n),d.rmSync(r,{recursive:!0,force:!0})})}export async function cleanupOrphanedLocalInfrastructure(e,t={}){const r=C(e);return g(e,r)?y(e,async()=>{if(!g(e,r)||re(e))return D();const s=await I(e,{stopIdle:!0});return R(e)||d.rmSync(r,{recursive:!0,force:!0}),s},t):D()}export async function cleanupTerminalRunLocalInfrastructure(e,t,r={}){const s=w(e),a=C(s);return g(s,a)?y(s,async()=>{if(w(e),!g(s,a))return D();const n=await te(e,t,{stopIdle:!0});return R(s)||(Z(e,t),d.rmSync(a,{recursive:!0,force:!0})),n},r):D()}function g(e,t){return d.existsSync(t)||R(e)}function D(){return{kept:[],removed:[],skipped:[],stopped:[],targets:[]}}export async function destroyOwnedLocalDatabaseResources(e,t={}){const r=w(e);return y(r,()=>(w(e),ae(e,t)))}export async function cleanupOwnedLocalDatabaseResources(e,t={}){return y(e,()=>I(e,t))}async function I(e,t){return ee({productDir:e,dryRun:!!t.dryRun,stopIdle:t.stopIdle!==!1})}export function isDatabaseStateDir(e){return d.existsSync(e)?d.existsSync(m.join(e,"database_backend")):!1}async function ne(e,t={}){const r=e.testkit.database,s=e.productDir,a=e.name,n=me(e),c=N(s),i=j(s,a);d.mkdirSync(c,{recursive:!0}),d.mkdirSync(i,{recursive:!0});const u=await X(s,r,{signal:t.signal}),p=await _(m.join(c,`template-${a}.lock`),async()=>{const l=await Q(e,t),S=await M(e,{sourceSchemaState:l});return await Y(e,u,t),ie(e,u,i,S,{...t,sourceSchemaState:l})},{signal:t.signal,timeoutMs:null}),o=await _(m.join(c,`runtime-${a}-${A(n,10)}.lock`),()=>ue(e,u,i,p,n,t.signal),{signal:t.signal,timeoutMs:null});return{container:u.containerName,databaseName:o.databaseName,templateFingerprint:o.templateFingerprint,url:v(u,o.databaseName)}}async function ie(e,t,r,s,a={}){const n=e.name;let c=s,i=a.sourceSchemaState||null,u=!1;for(;;){const p=h(m.join(r,"template_fingerprint")),o=h(m.join(r,"template_database_name")),l=q(n,c);if(p===c&&o&&await k(t,o,{signal:a.signal}))return a.setupRegistry?.recordCached({config:e,stage:"template",kind:"database-template",summary:"template cache hit"}),F(r,t,o,c),c;o&&o!==l&&await b(t,o,{signal:a.signal}),await k(t,l,{signal:a.signal})&&await b(t,l,{signal:a.signal});const S=v(t,l);if(await K(t,l,{signal:a.signal}),(await ce(e,t,l,S,{...a,sourceSchemaState:i,refreshedSourceAfterMismatch:u})).refreshSourceSchema){await b(t,l,{signal:a.signal}),i=await H(e,i,a),u=!0,c=await M(e,{sourceSchemaState:i});continue}return F(r,t,l,c),c}}async function ce(e,t,r,s,a={}){const n=a.setupRegistry?.start({config:e,stage:"template",kind:"database-template",summary:"template rebuild",recordLog:!1}),c={ownedContainer:{containerId:t.containerId,containerPort:t.containerPort},parentOperation:n,reporter:a.reporter||null,setupRegistry:a.setupRegistry||null,signal:a.signal};try{await W(e,s,a.sourceSchemaState,c);const i=async()=>{const o=await G(e,s,a.sourceSchemaState,{...c,skipSchemaSourceVerify:a.skipSchemaSourceVerify});if(o.status!=="mismatch")return null;if(a.refreshedSourceAfterMismatch)throw z(e,de(a.sourceSchemaState),o);return o},u=async o=>{const S=e.testkit.database?.template?.[o]||[];for(const[x,$]of S.entries())if(await B(e,o,$,x,s,c),await i())return!0;return!1};return await u("migrate")||await u("seed")||!!await i()?(L(n,a,{status:"passed",summary:"source schema refresh requested"}),{refreshSourceSchema:!0}):(await V(e,"verify",s,c),L(n,a,{status:"passed",summary:"template rebuild"}),{refreshSourceSchema:!1})}catch(i){throw L(n,a,{status:"failed",summary:"template rebuild",error:pe(i)||i}),await b(t,r),i}}function L(e,t,r){const s=e&&t.setupRegistry?t.setupRegistry.finish(e,r):null;s&&t.reporter?.setupOperationFinished?.(s)}async function ue(e,t,r,s,a,n){const c=e.name,i=h(m.join(r,"template_database_name"));if(!i)throw new Error(`Missing template database for service "${c}"`);const u=E(c,a,s),p=h(m.join(e.stateDir,"local_database_name")),o=h(m.join(e.stateDir,"local_template_fingerprint")),l=be(e.testkit.database.reset)||o!==s||p!==u||!await k(t,u,{signal:n});return p&&p!==u&&await b(t,p,{signal:n}),l&&(await b(t,u,{signal:n}),await J(t,u,i,{signal:n})),d.mkdirSync(e.stateDir,{recursive:!0}),oe(e,t,{bindingKey:a,databaseName:u,templateFingerprint:s,templateDbName:i}),{bindingKey:a,databaseName:u,templateFingerprint:s,templateDbName:i}}function oe(e,t,r){f(m.join(e.stateDir,"database_backend"),""),f(m.join(e.stateDir,"database_url"),v(t,r.databaseName)),f(m.join(e.stateDir,"local_database_name"),r.databaseName),f(m.join(e.stateDir,"local_template_fingerprint"),r.templateFingerprint),f(m.join(e.stateDir,"local_template_database_name"),r.templateDbName),f(m.join(e.stateDir,"local_container_name"),t.containerName),t.volumeName&&f(m.join(e.stateDir,"volume_name"),t.volumeName),t.volumeMountPath&&f(m.join(e.stateDir,"volume_mount_path"),t.volumeMountPath)}function me(e){return fe(e.testkit.database.binding)==="shared"?`${e.name}:shared`:e.runtimeId?`${e.name}:${String(e.runtimeId)}`:`${e.name}:${e.stateDir}`}async function le(e,t){const r=h(m.join(t,"local_database_name"));if(!r)return;const s=await P(e);s&&await b(s,r)}function M(e,t={}){return O(e,t)}function de(e){if(!e?.active)throw new Error("Source schema mismatch requires active source schema state");return e}function pe(e){return typeof e!="object"&&typeof e!="function"||e===null?void 0:Reflect.get(e,"message")}function be(e){return e!==!1}function fe(e){return e||"per-runtime"}function Fe(e){return e}

package/dist/database/local-postgres.d.ts

@@ -0,0 +1,71 @@
+import { type DockerLabels } from "./docker.js";
+import type { DatabaseMaterializationInput } from "../config/loader/index.js";
+import { type LocalPostgresState } from "./state-files.js";
+export declare const LOCAL_POSTGRES_DOCKER_TIMEOUTS_MS: Readonly<{
+    inspect: 30000;
+    readinessAttempt: 10000;
+    remove: 120000;
+    run: number;
+    start: 120000;
+    volumeCreate: 120000;
+}>;
+interface DockerRunOptions {
+    containerName: string;
+    image: string;
+    labels: DockerLabels;
+    maxConnections: number;
+    password: string;
+    user: string;
+    volumeMountPath: string;
+    volumeName: string;
+}
+interface LocalPostgresContainerReuseOptions {
+    image: string;
+    maxConnections: number;
+    volumeMountPath: string;
+    volumeName: string;
+}
+export interface LocalPostgresOperationOptions {
+    signal?: AbortSignal;
+}
+interface DockerContainerConfig {
+    Cmd?: string[] | null;
+    Image?: string | null;
+    Labels?: DockerLabels | null;
+}
+interface DockerContainerHostConfig {
+    NetworkMode?: string | null;
+}
+interface DockerContainerMount {
+    Destination?: string | null;
+    Name?: string | null;
+    Type?: string | null;
+}
+interface DockerContainerPortBinding {
+    HostPort?: string | null;
+}
+export interface DockerContainerInspect {
+    Config?: DockerContainerConfig | null;
+    HostConfig?: DockerContainerHostConfig | null;
+    Id?: string | null;
+    Mounts?: (DockerContainerMount | null | undefined)[] | null;
+    NetworkSettings?: {
+        Ports?: Record<string, DockerContainerPortBinding[] | null> | null;
+    } | null;
+    State?: {
+        Running?: boolean | null;
+    } | null;
+}
+export type InspectedDockerContainer = DockerContainerInspect & {
+    Id: string;
+};
+export declare function ensureLocalContainer(productDir: string, database?: Readonly<DatabaseMaterializationInput>, options?: Readonly<LocalPostgresOperationOptions>): Promise<LocalPostgresState>;
+export declare function buildDockerRunArgs({ containerName, labels, volumeName, volumeMountPath, user, password, image, maxConnections, }: Readonly<DockerRunOptions>): string[];
+export declare function loadExistingLocalContainer(productDir: string, options?: Readonly<LocalPostgresOperationOptions>): Promise<LocalPostgresState | null>;
+export declare function isReusableLocalPostgresContainer(inspect: Readonly<DockerContainerInspect>, options: Readonly<LocalPostgresContainerReuseOptions>): boolean;
+export declare function inspectContainer(containerName: string, options?: Readonly<LocalPostgresOperationOptions>): Promise<InspectedDockerContainer | null>;
+export declare function normalizeLocalPostgresContainerInspect(value: unknown): DockerContainerInspect | null;
+export declare function stopAndRemoveContainer(containerRef: string, displayName?: string, options?: Readonly<LocalPostgresOperationOptions>): Promise<void>;
+export declare function matchesStableDockerLabels(existingLabels: Readonly<Record<string, unknown>>, expectedLabels: Readonly<Record<string, unknown>>): boolean;
+export declare function resolveLocalPostgresVolumeTarget(image: unknown): string;
+export {};

package/dist/database/local-postgres.js

@@ -0,0 +1,2 @@
+import{randomUUID as C}from"node:crypto";import ne from"fs";import u from"path";import{LOCAL_ADMIN_DB as D,LOCAL_IMAGE as M,LOCAL_MAX_CONNECTIONS as N,LOCAL_PASSWORD as R,LOCAL_POLL_INTERVAL_MS as te,LOCAL_READY_TIMEOUT_MS as $,LOCAL_USER as j}from"./constants.js";import{buildContainerName as re,buildVolumeName as S}from"./naming.js";import{getLocalInfraDir as V,readStateValue as l}from"./state.js";import{TESTKIT_CREATED_AT_LABEL as U,TESTKIT_RESOURCE_GENERATION_LABEL as z,buildDockerResourceLabels as G,dockerLabelArgs as v,inspectDockerVolume as L,normalizeDockerVolumeInspect as E,removeDockerVolume as oe,runDockerCommand as h}from"./docker.js";import{writeLocalInfraState as ie}from"./state-files.js";const se="/var/lib/postgresql/data",ae="/var/lib/postgresql",A=String;export const LOCAL_POSTGRES_DOCKER_TIMEOUTS_MS=Object.freeze({inspect:3e4,readinessAttempt:1e4,remove:12e4,run:10*6e4,start:12e4,volumeCreate:12e4});export async function ensureLocalContainer(e,n={},t={}){const o=V(e);ne.mkdirSync(o,{recursive:!0});const r=l(u.join(o,"container_name"))||re(e),i=l(u.join(o,"volume_name")),s=n.image||l(u.join(o,"image"))||M,f=l(u.join(o,"image")),c=resolveLocalPostgresVolumeTarget(s),w=n.user||l(u.join(o,"user"))||j,b=n.password||l(u.join(o,"password"))||R,_=q(n.maxConnections||l(u.join(o,"max_connections"))||N);let a=await inspectContainer(r,t);a&&p(a,e,r);let d=K(a,c)||i||S(e,C());a&&await F(e,d,t);const O=a?.Config?.Image||f||null;if(a&&!isReusableLocalPostgresContainer(a,{image:s,maxConnections:_,volumeMountPath:c,volumeName:d})&&(await stopAndRemoveContainer(a.Id,r,t),O&&O!==s&&(await me(e,d,t),d=S(e,C())),a=null),a)a.State?.Running||(await k(["start",a.Id],`Docker local Postgres container start for ${r}`,LOCAL_POSTGRES_DOCKER_TIMEOUTS_MS.start,t.signal),a=await inspectContainer(r,t),a&&p(a,e,r));else{d=await le(e,d,t);const ee=Y(e,r,C());await k(buildDockerRunArgs({containerName:r,labels:ee,volumeName:d,volumeMountPath:c,user:w,password:b,image:s,maxConnections:_}),`Docker local Postgres container creation for ${r}`,LOCAL_POSTGRES_DOCKER_TIMEOUTS_MS.run,t.signal),a=await inspectContainer(r,t),a&&p(a,e,r)}const I=B(a);if(!a||!I)throw new Error(`Could not determine host port for local database container ${r}`);const x={containerName:r,containerId:a.Id,volumeName:d,volumeMountPath:c,image:s,user:w,password:b,maxConnections:_,host:"127.0.0.1",port:Number(I),containerPort:5432};return await W(x,t),ie(o,x),x}export function buildDockerRunArgs({containerName:e,labels:n,volumeName:t,volumeMountPath:o,user:r,password:i,image:s,maxConnections:f}){return["run","-d","--name",e,...v(n),"-p","127.0.0.1::5432","--mount",`type=volume,source=${t},target=${o}`,"-e",`POSTGRES_USER=${r}`,"-e",`POSTGRES_PASSWORD=${i}`,"-e",`POSTGRES_DB=${D}`,s,"postgres","-c",`max_connections=${String(f)}`]}export async function loadExistingLocalContainer(e,n={}){const t=V(e),o=l(u.join(t,"container_name"));if(!o)return null;const r=await inspectContainer(o,n);if(!r)return null;p(r,e,o);const i=r.Config?.Image||l(u.join(t,"image"))||M,s=l(u.join(t,"volume_mount_path"))||resolveLocalPostgresVolumeTarget(i),f=K(r,s)||l(u.join(t,"volume_name"));if(!f)return null;await F(e,f,n),r.State?.Running||await k(["start",r.Id],`Docker local Postgres container start for ${o}`,LOCAL_POSTGRES_DOCKER_TIMEOUTS_MS.start,n.signal);const c=await inspectContainer(o,n);c&&p(c,e,o);const w=B(c);if(!c||!w)return null;const b={containerName:o,containerId:c.Id,volumeName:f,volumeMountPath:s,image:i,user:l(u.join(t,"user"))||j,password:l(u.join(t,"password"))||R,maxConnections:q(l(u.join(t,"max_connections"))||N),host:"127.0.0.1",port:Number(w),containerPort:H(c)==="host"?Number(w):5432};return await W(b,n),b}function ce(e,n){const t=e.Config?.Cmd;return Array.isArray(t)?t.includes("-c")&&t.includes(`max_connections=${String(n)}`):!1}function ue(e,n,t){return(Array.isArray(e.Mounts)?e.Mounts:[]).some(r=>r?.Type==="volume"&&r.Name===n&&r.Destination===t)}export function isReusableLocalPostgresContainer(e,n){return e.Config?.Image===n.image&&ce(e,n.maxConnections)&&ue(e,n.volumeName,n.volumeMountPath)&&H(e)==="bridge"}function H(e){return e.HostConfig?.NetworkMode==="host"?"host":"bridge"}function B(e){return e?.NetworkSettings?.Ports?.["5432/tcp"]?.[0]?.HostPort||null}function q(e){const n=Number(e);if(!Number.isInteger(n)||n<10)throw new Error("database.maxConnections must be an integer greater than or equal to 10");return n}export async function inspectContainer(e,n={}){const t=`Docker local Postgres container inspect for ${e}`,o=await h(["inspect",e],t,LOCAL_POSTGRES_DOCKER_TIMEOUTS_MS.inspect,n.signal);if(o.exitCode!==0){if(Z(o))return null;throw T(t,o)}let r;try{r=JSON.parse(o.stdout)}catch(s){throw Q(t,o,s)}const i=P(r)&&r.length===1?normalizeLocalPostgresContainerInspect(r[0]):null;if(!i?.Id)throw Q(t,o);return{...i,Id:i.Id}}export function normalizeLocalPostgresContainerInspect(e){return m(e)?{Config:we(e.Config),HostConfig:pe(e.HostConfig),Id:g(e.Id),Mounts:Ce(e.Mounts),NetworkSettings:Le(e.NetworkSettings),State:he(e.State)}:null}export async function stopAndRemoveContainer(e,n=e,t={}){const o=`Docker local Postgres container removal for ${n}`,r=await h(["rm","-f","-v",e],o,LOCAL_POSTGRES_DOCKER_TIMEOUTS_MS.remove,t.signal);if(!(r.exitCode===0||Z(r)))throw T(o,r)}async function le(e,n,t={}){const o=y(e,n,"existing-generation"),r=await L(n,t);if(r){if(!matchesStableDockerLabels(X(r)||{},o))throw new Error(`Docker volume ${n} already exists but is not owned by this Testkit product. Remove or rename it before running Testkit.`);return n}const i=C(),s=S(e,i),f=y(e,s,i);await k(["volume","create",...v(f),s],`Docker local Postgres volume creation for ${s}`,LOCAL_POSTGRES_DOCKER_TIMEOUTS_MS.volumeCreate,t.signal);const c=E(await L(s,t));if(c===null||!fe(c.labels,f))throw new Error(`Docker volume ${s} was not published with the expected Testkit generation identity`);return s}async function F(e,n,t){const o=y(e,n,"existing-generation"),r=E(await L(n,t));if(r===null||!matchesStableDockerLabels(r.labels,o))throw new Error(`Docker volume ${n} is missing or is not owned by this Testkit product`);return r}export function matchesStableDockerLabels(e,n){const t=e[U],o=e[z];return typeof t=="string"&&t.length>0&&typeof o=="string"&&o.length>0&&Object.entries(n).every(([r,i])=>r===U||r===z||e[r]===A(i))}function fe(e,n){const t=Object.entries(e).sort(([r],[i])=>r.localeCompare(i)),o=Object.entries(n).map(([r,i])=>[r,A(i)]).sort(([r],[i])=>r.localeCompare(i));return t.length===o.length&&t.every(([r,i],s)=>o[s]?.[0]===r&&o[s]?.[1]===i)}async function me(e,n,t={}){const o=y(e,n,"existing-generation"),r=await L(n,t);if(!r)return;const i=X(r)||{};if(!matchesStableDockerLabels(i,o))return;const f=E(r);f!==null&&await oe(n,f,t)}function K(e,n){return(Array.isArray(e?.Mounts)?e.Mounts:[]).find(r=>r?.Type==="volume"&&typeof r.Name=="string"&&r.Name.length>0&&r.Destination===n)?.Name||null}function p(e,n,t){const o=Y(n,t);if(!matchesStableDockerLabels(e.Config?.Labels||{},o))throw new Error(`Docker container ${t} already exists but is not owned by this Testkit product. Remove or rename it before running Testkit.`)}export function resolveLocalPostgresVolumeTarget(e){return de(e)>=18?ae:se}function de(e){const t=A(e||"").match(/(?:^|[:@/-])(?:pg|postgres)?(\d{2})(?:\D|$)/i);return t?Number(t[1]):16}async function W(e,n={}){const t=Date.now();for(;Date.now()-t<$;){const o=Math.max(1,$-(Date.now()-t));if((await h(["exec",e.containerId,"pg_isready","-U",e.user,"-d",D,"-p",String(e.containerPort||5432)],`Docker local Postgres readiness probe for ${e.containerName}`,Math.min(LOCAL_POSTGRES_DOCKER_TIMEOUTS_MS.readinessAttempt,o),n.signal)).exitCode===0)return;await ge(Math.min(te,o),n.signal)}throw new Error(`Timed out waiting for local database container ${e.containerName}`)}function Y(e,n,t="existing-generation"){return G(e,{generation:t,kind:"postgres-container",name:n,scope:"local-postgres",cachePolicy:"product-cache"})}function y(e,n,t){return G(e,{generation:t,kind:"postgres-volume",name:n,scope:"local-postgres",cachePolicy:"product-cache"})}function ge(e,n){return new Promise((t,o)=>{if(n?.aborted){o(J(n));return}const r=setTimeout(i,e);n?.addEventListener("abort",s,{once:!0});function i(){n?.removeEventListener("abort",s),t()}function s(){clearTimeout(r),o(n?J(n):new Error("Local Postgres operation aborted"))}})}function J(e){return e.reason instanceof Error?e.reason:new Error("Local Postgres operation aborted",{cause:e.reason})}function X(e){if(!m(e))return null;const n=e.Labels;return m(n)?n:null}function we(e){if(e===null)return null;if(m(e))return{Cmd:ye(e.Cmd),Image:g(e.Image),Labels:be(e.Labels)}}function be(e){if(!m(e))return null;const n={};for(const[t,o]of Object.entries(e))typeof o=="string"&&(n[t]=o);return n}function pe(e){if(e===null)return null;if(m(e))return{NetworkMode:g(e.NetworkMode)}}function Ce(e){if(e===null)return null;if(P(e))return e.flatMap(n=>m(n)?[{Destination:g(n.Destination),Name:g(n.Name),Type:g(n.Type)}]:[])}function Le(e){if(e===null)return null;if(!m(e))return;const n=e.Ports;if(n===null)return{Ports:null};if(!m(n))return{};const t={};for(const[o,r]of Object.entries(n)){if(r===null){t[o]=null;continue}P(r)&&(t[o]=r.flatMap(i=>{if(!m(i))return[];const s=g(i.HostPort);return i.HostPort!==void 0&&s===void 0?[]:[{HostPort:s}]}))}return{Ports:t}}function he(e){if(e===null)return null;if(m(e))return{Running:e.Running===null||typeof e.Running=="boolean"?e.Running:void 0}}function g(e){if(e===null||typeof e=="string")return e}function m(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function P(e){return Array.isArray(e)}function ye(e){if(e===null)return null;if(P(e))return e.filter(n=>typeof n=="string")}async function k(e,n,t,o){const r=await h(e,n,t,o);if(r.exitCode===0)return r;throw T(n,r)}function T(e,n){const t=n.stderr.trim()||n.stdout.trim(),o=new Error(`${e} failed with exit code ${String(n.exitCode)}${t?`: ${t}`:""}`);return Object.defineProperty(o,"result",{enumerable:!1,value:Object.freeze({...n})}),o}function Q(e,n,t){const o=new Error(`${e} returned malformed Docker inspect output; expected exactly one container record with a non-empty Id`,t===void 0?void 0:{cause:t});return Object.defineProperty(o,"result",{enumerable:!1,value:Object.freeze({...n})}),o}function Z(e){return/\bno such (?:container|object)\b/iu.test(`${e.stderr}
+${e.stdout}`)}

package/dist/database/naming.d.ts

@@ -0,0 +1,17 @@
+export interface DatabaseConnection {
+    host: string;
+    password: string;
+    port: number;
+    sslMode?: string | null;
+    user: string;
+}
+export declare function buildDatabaseUrl(infra: Readonly<DatabaseConnection>, dbName: string): string;
+export declare function buildContainerName(productDir: string): string;
+export declare function buildVolumeName(productDir: string, generation: string): string;
+export declare function buildTemplateDatabaseName(serviceName: string, fingerprint: string): string;
+export declare function buildRuntimeDatabaseName(serviceName: string, bindingKey: string, fingerprint: string): string;
+export declare function hashString(value: string, length?: number): string;
+export declare function slugSegment(value: string): string;
+export declare function limitIdentifier(value: string, maxLength: number): string;
+export declare function escapeIdentifier(value: unknown): string;
+export declare function escapeSqlLiteral(value: unknown): string;

package/dist/database/naming.js

@@ -0,0 +1 @@
+import p from"crypto";import f from"fs";import l from"path";export function buildDatabaseUrl(e,t){const n=e.sslMode||"disable";return`postgresql://${encodeURIComponent(e.user)}:${encodeURIComponent(e.password)}@${e.host}:${String(e.port)}/${t}?sslmode=${encodeURIComponent(n)}`}export function buildContainerName(e){const t=u(e);return i("testkit_pg",l.basename(t),[hashString(t,10)],63)}export function buildVolumeName(e,t){const n=u(e);if(!t)throw new Error("Local Postgres volume generation must be non-empty");return i("testkit_pgdata",l.basename(n),[hashString(n,10),hashString(t,32)],128)}export function buildTemplateDatabaseName(e,t){return i("tk_tpl",e,[t.slice(0,16)],63)}export function buildRuntimeDatabaseName(e,t,n){return i("tk",e,[hashString(t,10),n.slice(0,12)],63)}function i(e,t,n,a){const c=`${e}_`,s=slugSegment(t);let r=`_${n.join("_")}`,o=a-c.length-r.length;if(s.length>o&&(r=`_${hashString(t,10)}${r}`,o=a-c.length-r.length),o<1)throw new Error(`Cannot retain the identity suffix within a ${String(a)}-character identifier`);const d=limitIdentifier(s,o);return`${c}${d}${r}`}function u(e){const t=l.resolve(e);try{return f.realpathSync.native(t)}catch(n){if(m(n,"ENOENT"))return t;throw n}}function m(e,t){return typeof e=="object"&&e!==null&&"code"in e&&Reflect.get(e,"code")===t}export function hashString(e,t=12){return p.createHash("sha256").update(e).digest("hex").slice(0,t)}export function slugSegment(e){return e.toLowerCase().replace(/[^a-z0-9]+/g,"_").replace(/^_+|_+$/g,"")||"db"}export function limitIdentifier(e,t){return e.length<=t?e:e.slice(0,t)}export function escapeIdentifier(e){return String(e).replace(/"/g,'""')}export function escapeSqlLiteral(e){return String(e).replace(/'/g,"''")}

package/dist/database/postgres/index.d.ts

@@ -0,0 +1,71 @@
+import type { Readable } from "node:stream";
+import type { OwnedPostgresContainerRoute } from "../../domain/postgres-route.js";
+export declare const POSTGRES_CLIENT_CONTAINER_LABEL = "com.elench.testkit.postgres-client.container";
+export declare const POSTGRES_CLIENT_TIMEOUT_MS: number;
+export interface PostgresConnectionInput {
+    database?: string | null;
+    host?: string | null;
+    password?: string | null;
+    port?: number | string | null;
+    rawUrl?: unknown;
+    sslMode?: string | null;
+    user?: string | null;
+}
+export interface PostgresConnection extends PostgresConnectionInput {
+    database: string;
+    host: string;
+    port: number | string;
+    user: string;
+}
+export interface DockerPsqlOptions {
+    args?: readonly unknown[];
+    connection?: PostgresConnectionInput | null;
+    cwd?: string;
+    databaseUrl?: string | null;
+    env?: NodeJS.ProcessEnv;
+    image?: string | null;
+    ownedContainer?: OwnedPostgresContainerRoute | null;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface DockerPostgresClientOptions extends DockerPsqlOptions {
+    clientCommand?: string | null;
+}
+export interface BuildDockerPostgresClientArgsOptions {
+    args?: readonly unknown[];
+    clientCommand: string;
+    connection: PostgresConnection;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    image?: string;
+    ownedContainer?: OwnedPostgresContainerRoute | null;
+}
+export interface PostgresCommandResult {
+    command: string;
+    escapedCommand: string;
+    exitCode: number | null;
+    failed: boolean;
+    shortMessage?: string;
+    signal: NodeJS.Signals | null;
+    stderr: string;
+    stdout: string;
+}
+export interface PostgresClientProcess extends Promise<PostgresCommandResult> {
+    pid: number | undefined;
+    stderr: Readable | null;
+    stop(): boolean;
+    stdout: Readable | null;
+}
+interface RewritePostgresFileArgsResult {
+    args: string[];
+    mountArgs: string[];
+}
+export declare function postgresClientImage(env?: NodeJS.ProcessEnv): string;
+export declare function runDockerPsql(options: DockerPsqlOptions): Promise<PostgresCommandResult>;
+export declare function startDockerPgDump(options: DockerPsqlOptions): PostgresClientProcess;
+export declare function runDockerPostgresClient(options?: DockerPostgresClientOptions): Promise<PostgresCommandResult>;
+export declare function startDockerPostgresClient({ clientCommand, args, cwd, env, connection, databaseUrl, image, ownedContainer, signal, timeoutMs, }?: DockerPostgresClientOptions): PostgresClientProcess;
+export declare function buildDockerPostgresClientArgs(options: BuildDockerPostgresClientArgsOptions): string[];
+export declare function rewritePostgresFileArgsForDocker(args: readonly string[], cwd?: string): RewritePostgresFileArgsResult;
+export declare function connectionFromDatabaseUrl(rawUrl: unknown): PostgresConnection | null;
+export {};

package/dist/database/postgres/index.js

@@ -0,0 +1,2 @@
+import P from"node:path";import{randomUUID as k}from"node:crypto";import{errorMessage as D}from"../../kernel/error-serialization.js";import{dockerHostAddress as x,shouldUseDockerHostNetwork as T}from"../../process/host/platform.js";import{managedHostProcessInfrastructureError as A,runManagedHostProcess as h,startManagedHostProcess as N}from"../../process/index.js";export const POSTGRES_CLIENT_CONTAINER_LABEL="com.elench.testkit.postgres-client.container";const I="postgres:16",w="postgres";export const POSTGRES_CLIENT_TIMEOUT_MS=30*6e4;const M=["-h","--host","-p","--port","-U","--username","-d","--dbname"],O=/^(?:--host|--port|--username|--dbname)=/,f=String;export function postgresClientImage(e=process.env){return e.TESTKIT_POSTGRES_CLIENT_IMAGE||I}export function runDockerPsql(e){return runDockerPostgresClient({...e,clientCommand:"psql"})}export function startDockerPgDump(e){return startDockerPostgresClient({...e,clientCommand:"pg_dump"})}export async function runDockerPostgresClient(e={}){try{return await startDockerPostgresClient(e)}catch(t){throw b(t)}}export function startDockerPostgresClient({clientCommand:e,args:t=[],cwd:r,env:n=process.env,connection:c=null,databaseUrl:u=null,image:s=null,ownedContainer:i=null,signal:o,timeoutMs:p=POSTGRES_CLIENT_TIMEOUT_MS}={}){const l=v({args:t,connection:c,databaseUrl:u});if(!z(l))throw new Error(`Dockerized ${e||"Postgres client"} requires a Postgres connection URL or connection object`);if(!e)throw new Error("buildDockerPostgresClientArgs requires clientCommand");const m=buildDockerPostgresClientArgs({clientCommand:e,args:t,connection:l,cwd:r,env:n,image:s||postgresClientImage(n),ownedContainer:i}),a=`testkit-postgres-client-${k()}`;return m.splice(1,0,"--name",a),y("docker",m,{containerName:a,cwd:r,env:C(n,l),signal:o,timeoutMs:R(p)})}function b(e){return _(e)&&e.code==="ENOENT"||e instanceof Error&&e.message.includes('managed host executable "docker"')?new Error("Docker is required for Testkit Postgres client operations, but the docker command was not found."):e}function _(e){return e instanceof Error&&"code"in e}function y(e,t,r){let n;try{n=N({args:t,cwd:r.cwd||process.cwd(),displayLabel:"Dockerized Postgres client",env:r.env,executable:e,outputMode:"bounded-capture",signal:r.signal,timeoutMs:r.timeoutMs})}catch(o){throw b(o)}let c=!1,u=!1;const s=n.completion.then(async o=>{const p=u&&G(o)?null:A("Dockerized Postgres client",o);if(o.cancelled||o.timedOut||o.outputLimitExceeded||u){const l={executable:"docker",cwd:r.cwd||process.cwd(),env:r.env,displayLabel:"Postgres client container cleanup"},m=async()=>{const a=await h({...l,args:["rm","--force",r.containerName],timeoutMs:3e4}),d=A("Postgres client container cleanup",a);if(d)throw d;if(a.exitCode!==0)throw new Error(`Postgres client container cleanup failed: ${a.stderr}`)};try{try{(await h({...l,args:["kill","--signal=SIGINT",r.containerName],timeoutMs:5e3})).exitCode===0&&await h({...l,args:["wait",r.containerName],timeoutMs:2e3})}finally{await m()}}catch(a){const d=p||(o.exitCode!==0?new Error(`Dockerized Postgres client failed with exit code ${String(o.exitCode)}`):null);if(!d)throw a;const g=new AggregateError([d,a],[d.message,o.stderr.trim(),o.stdout.trim(),D(a)].filter(Boolean).join(`
+`),{cause:d});throw Object.defineProperty(g,"result",{enumerable:!1,value:Object.freeze({...o})}),g}}if(p)throw b(p);return{command:e,escapedCommand:[e,...t].join(" "),exitCode:o.exitCode,failed:o.exitCode!==0,signal:o.exitSignal,stderr:o.stderr,stdout:o.stdout}});s.then(()=>{c=!0},()=>{c=!0});const i=s;return Object.defineProperties(i,{pid:{enumerable:!0,get:()=>n.pid},stdout:{enumerable:!0,value:n.stdout},stderr:{enumerable:!0,value:n.stderr},stop:{enumerable:!0,value:()=>c?!1:(u=!0,n.stop(),!0)}}),i}function G(e){return e.error===null&&e.terminationError===null&&!e.timedOut&&!e.cancelled&&!e.outputLimitExceeded}function R(e){if(!Number.isSafeInteger(e)||Number(e)<=0)throw new TypeError("Dockerized Postgres client timeoutMs must be a positive safe integer");return Number(e)}export function buildDockerPostgresClientArgs({clientCommand:e,args:t=[],connection:r,cwd:n,env:c=process.env,image:u=postgresClientImage(c),ownedContainer:s=null}={}){if(!e)throw new Error("buildDockerPostgresClientArgs requires clientCommand");if(!r)throw new TypeError("buildDockerPostgresClientArgs requires connection");const i=$(t,r),{args:o,mountArgs:p}=rewritePostgresFileArgsForDocker(i,n),[l,m,a]=U(r,s),d=C(c,r),g=["PGPASSWORD","PGSSLMODE","PGAPPNAME"].filter(E=>d[E]!=null).flatMap(E=>["-e",E]);return["run","--rm",...l,...s?["--label",`${POSTGRES_CLIENT_CONTAINER_LABEL}=${s.containerId}`]:[],...g,...p,u,e,"-h",m,"-p",a,"-U",r.user,"-d",r.database||w,...o]}function U(e,t){if(!t)return[T()?["--network","host"]:[],f(x(e.host)),f(e.port||5432)];if(!t.containerId)throw new TypeError("ownedContainer.containerId must be a container id");return[["--network",`container:${t.containerId}`],"127.0.0.1",f(t.containerPort||5432)]}export function rewritePostgresFileArgsForDocker(e,t){const r=[],n=[];let c=0;const u=s=>{const i=P.resolve(t||process.cwd(),s),o=`/testkit-postgres-files-${String(c)}`;return c+=1,n.push("--mount",`type=bind,source=${P.dirname(i)},target=${o},readonly`),`${o}/${P.basename(i)}`};for(let s=0;s<e.length;s+=1){const i=e[s],o=e[s+1];if((i==="-f"||i==="--file")&&o){r.push(i,u(o)),s+=1;continue}if(i.startsWith("--file=")){r.push(`--file=${u(i.slice(7))}`);continue}r.push(i)}return{args:r,mountArgs:n}}function v({args:e,connection:t,databaseUrl:r}){return t?{...t,port:t.port||5432,database:t.database||w}:connectionFromDatabaseUrl(r||L(e))}function L(e){const t=e[0];return S(t)?t:null}function $(e,t){const r=t?.rawUrl,n=r&&e[0]===r||S(e[0])?e.slice(1):e;return q(n).map(c=>f(c))}function q(e){const t=[];for(let r=0;r<e.length;r+=1){const n=e[r];if(typeof n=="string"&&M.includes(n)){r+=1;continue}O.test(f(n))||t.push(n)}return t}function C(e,t){return{...e,PGPASSWORD:t.password||"",...t.sslMode?{PGSSLMODE:t.sslMode}:{},...e.PGAPPNAME?{PGAPPNAME:e.PGAPPNAME}:{}}}function S(e){return/^postgres(?:ql)?:\/\//i.test(f(e||""))}function z(e){return!!(e?.host&&e.user)}export function connectionFromDatabaseUrl(e){if(!e)return null;let t;try{t=new URL(f(e))}catch{return null}return["postgres:","postgresql:"].includes(t.protocol)?{rawUrl:e,host:t.hostname,port:t.port||"5432",database:decodeURIComponent(t.pathname.replace(/^\//,""))||w,user:decodeURIComponent(t.username||""),password:decodeURIComponent(t.password||""),sslMode:t.searchParams.get("sslmode")||void 0}:null}

package/dist/database/progress.d.ts

@@ -0,0 +1,6 @@
+import type { ConfiguredStepReporter } from "../steps/index.js";
+import type { SetupOperationRegistry } from "../evidence/setup-progress.js";
+export interface DatabaseProgress {
+    reporter?: ConfiguredStepReporter | null;
+    setupRegistry?: SetupOperationRegistry | null;
+}

package/dist/database/progress.js

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

package/dist/database/roles.d.ts

@@ -0,0 +1,19 @@
+import type { NormalizedDatabaseConfig } from "../config/loader/index.js";
+import type { StepServiceIdentity } from "../evidence/setup-progress.js";
+import type { LocalPostgresState } from "./state-files.js";
+import type { DatabaseTemplateStepOptions } from "./template-steps.js";
+export declare const DATABASE_ROLES_LOCK: readonly [1952805748, 1919904869];
+type DatabaseRoleConfig = NormalizedDatabaseConfig["roles"][number];
+interface DatabaseRoleServiceConfig extends StepServiceIdentity {
+    productDir: string;
+    testkit: {
+        database: {
+            roles: readonly DatabaseRoleConfig[];
+        };
+    };
+}
+interface DatabaseRoleOptions extends Pick<DatabaseTemplateStepOptions, "reporter" | "setupRegistry" | "signal"> {
+    timeoutMs?: number;
+}
+export declare function ensureDatabaseRoles(config: Readonly<DatabaseRoleServiceConfig>, infra: Readonly<LocalPostgresState>, options?: Readonly<DatabaseRoleOptions>): Promise<void>;
+export {};

package/dist/database/roles.js

@@ -0,0 +1,41 @@
+import{errorMessage as d}from"../kernel/error-serialization.js";import{awaitCapturedResult as R,writeCapturedLine as l}from"../evidence/step-output.js";import{LOCAL_ADMIN_DB as c}from"./constants.js";import{escapeSqlLiteral as S}from"./naming.js";import{runDockerPsql as A}from"./postgres/index.js";export const DATABASE_ROLES_LOCK=[1952805748,1919904869];const T=6e4;export async function ensureDatabaseRoles(t,i,e={}){const o=t.testkit.database.roles;if(o.length===0)return;const s=e.setupRegistry?.start({config:t,kind:"database-prerequisites",stage:"database-prerequisites",summary:"ensure declared PostgreSQL roles"}),n=s?._logRecord||null;try{e.signal?.throwIfAborted();const r=e.timeoutMs??T;if(!Number.isSafeInteger(r)||r<=0)throw new Error("PostgreSQL role setup timeout must be a positive integer");if(o.some(O=>O.name===i.user))throw new Error("A declared PostgreSQL role cannot be the owned bootstrap user");const E=await A({args:["-X","-v","ON_ERROR_STOP=1","-c",L(o,r)],connection:{...i,database:c},ownedContainer:{containerId:i.containerId,containerPort:i.containerPort},cwd:t.productDir,env:{...process.env,PGAPPNAME:"testkit:database-prerequisites"},signal:e.signal,timeoutMs:r});R(E,{logRecord:n});const a=s&&e.setupRegistry?.finish(s,{status:"passed",summary:"declared PostgreSQL roles ready"});a&&e.reporter?.setupOperationFinished?.(a)}catch(r){const E=e.signal?.aborted?e.signal.reason:r;E!==r&&l(n,"stderr",d(r)),l(n,"stderr",d(E));const a=s&&e.setupRegistry?.finish(s,{status:e.signal?.aborted?"cancelled":"failed",error:d(E)});throw a&&e.reporter?.setupOperationFinished?.(a),E}}function L(t,i){const e=t.map(s=>N(s.name)).join(", "),o=`DECLARE
+  desired text;
+  existing pg_authid%ROWTYPE;
+  conflicts text[];
+  created text[] := ARRAY[]::text[];
+  reused text[] := ARRAY[]::text[];
+BEGIN
+  PERFORM pg_advisory_xact_lock(${DATABASE_ROLES_LOCK.join(", ")});
+  FOREACH desired IN ARRAY ARRAY[${e}]::text[] LOOP
+    SELECT * INTO existing FROM pg_authid WHERE rolname = desired;
+    IF NOT FOUND THEN
+      EXECUTE format('CREATE ROLE %I WITH NOLOGIN INHERIT NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS CONNECTION LIMIT -1 PASSWORD NULL', desired);
+      created := array_append(created, desired);
+    ELSE
+      conflicts := array_remove(ARRAY[
+        CASE WHEN existing.rolcanlogin THEN 'LOGIN' END,
+        CASE WHEN existing.rolsuper THEN 'SUPERUSER' END,
+        CASE WHEN existing.rolcreatedb THEN 'CREATEDB' END,
+        CASE WHEN existing.rolcreaterole THEN 'CREATEROLE' END,
+        CASE WHEN existing.rolreplication THEN 'REPLICATION' END,
+        CASE WHEN existing.rolbypassrls THEN 'BYPASSRLS' END,
+        CASE WHEN NOT existing.rolinherit THEN 'NOINHERIT' END,
+        CASE WHEN existing.rolconnlimit <> -1 THEN 'CONNECTION LIMIT' END,
+        CASE WHEN existing.rolpassword IS NOT NULL THEN 'PASSWORD' END,
+        CASE WHEN existing.rolvaliduntil IS NOT NULL THEN 'VALID UNTIL' END,
+        CASE WHEN EXISTS (SELECT FROM pg_auth_members WHERE roleid = existing.oid OR member = existing.oid) THEN 'memberships' END,
+        CASE WHEN EXISTS (SELECT FROM pg_db_role_setting WHERE setrole = existing.oid) THEN 'role settings' END
+      ], NULL);
+      IF cardinality(conflicts) > 0 THEN
+        RAISE EXCEPTION 'PostgreSQL role "%" conflicts with declared NOLOGIN role: %', desired, array_to_string(conflicts, ', ');
+      END IF;
+      reused := array_append(reused, desired);
+    END IF;
+  END LOOP;
+  FOREACH desired IN ARRAY created LOOP
+    RAISE NOTICE 'Created declared PostgreSQL role "%"', desired;
+  END LOOP;
+  FOREACH desired IN ARRAY reused LOOP
+    RAISE NOTICE 'Reused declared PostgreSQL role "%"', desired;
+  END LOOP;
+END`;return`BEGIN; SET LOCAL statement_timeout = ${N(String(i))}; DO ${N(o)}; COMMIT;`}function N(t){return`E'${S(t).replaceAll("\\","\\\\")}'`}

package/dist/database/runtime-config.d.ts

@@ -0,0 +1,16 @@
+import { type NormalizedDatabaseConfig, type NormalizedDatabaseTemplateConfig, type NormalizedSourceSchemaConfig } from "../config/loader/index.js";
+import { type TemplateResolutionContext } from "../steps/index.js";
+export declare function finalizeRuntimeDatabaseConfig(database: NormalizedDatabaseConfig | null | undefined, context: TemplateResolutionContext): import("../config/loader/database-materialization.js").MaterializedDatabaseConfig<{
+    sourceSchema: NormalizedSourceSchemaConfig | null;
+    template: NormalizedDatabaseTemplateConfig;
+    image?: string | undefined;
+    password?: string | undefined;
+    user?: string | undefined;
+    binding: import("../config/loader/execution-model.js").DatabaseBinding;
+    maxConnections: number | undefined;
+    reservedConnections: number | undefined;
+    reset: boolean;
+    roles: import("../config/authoring/index.js").DatabaseRoleConfig[];
+    runtimeConnections: number | undefined;
+    serviceName: string;
+}> | undefined;

package/dist/database/runtime-config.js

@@ -0,0 +1 @@
+import{materializeDatabaseConfig as u}from"../config/loader/index.js";import{finalizeConfiguredInputs as t,finalizeConfiguredSteps as f}from"../steps/configured-steps.js";import{finalizeString as r}from"../steps/index.js";export function finalizeRuntimeDatabaseConfig(i,n){return i?u({...i,sourceSchema:a(i.sourceSchema,n),template:o(i.template,n)}):void 0}function o(i,n){return i?{inputs:t(i.inputs,e=>r(e,n)),migrate:f(i.migrate,e=>r(e,n)),seed:f(i.seed,e=>r(e,n)),verify:f(i.verify,e=>r(e,n))}:{inputs:[],migrate:[],seed:[],verify:[]}}function a(i,n){return i?{...i,..."env"in i&&typeof i.env=="string"?{env:r(i.env,n)}:{}}:null}

package/dist/database/runtime-reservations.d.ts

@@ -0,0 +1,19 @@
+import { type DatabaseMaterializationInput } from "../config/loader/index.js";
+export interface DatabaseReservationService {
+    name: string;
+    testkit: {
+        database?: DatabaseMaterializationInput | null;
+    };
+}
+export interface RuntimeDatabaseReservation {
+    available: number;
+    capacity: number;
+    key: string;
+    kind: "postgres";
+    perRuntime: number;
+    reserved: number;
+    resourceName: "local";
+    scope: "local";
+    services: string[];
+}
+export declare function buildGraphResourceReservations(runtimeConfigs: readonly DatabaseReservationService[]): RuntimeDatabaseReservation[];

package/dist/database/runtime-reservations.js

@@ -0,0 +1 @@
+import{materializeDatabaseConfig as r}from"../config/loader/index.js";export function buildGraphResourceReservations(c){const n=new Map;for(const e of c){const t=e.testkit.database,a=t?r(t):void 0;if(!a)continue;const o="postgres:local",s=n.get(o)||{key:o,kind:"postgres",scope:"local",resourceName:"local",capacity:a.maxConnections,reserved:a.reservedConnections||0,perRuntime:0,services:[]};s.capacity=Math.max(s.capacity||0,a.maxConnections||0),s.reserved=Math.max(s.reserved||0,a.reservedConnections||0),s.perRuntime+=a.runtimeConnections||1,s.services.push(e.name),n.set(o,s)}return[...n.values()].map(e=>({...e,available:Math.max(0,(e.capacity||0)-(e.reserved||0)),services:[...new Set(e.services)].sort()})).sort((e,t)=>e.key.localeCompare(t.key))}

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

@@ -0,0 +1,18 @@
+import { type DatabaseRuntimeConfig } from "./index.js";
+import type { DatabaseProgress } from "./progress.js";
+import { type RefreshedSourceSchemaState } from "./schema-source.js";
+export interface ResolvedSchemaOperationPlan {
+    /** Configs in provisioning order; dependencies before dependents. */
+    configs: readonly DatabaseRuntimeConfig[];
+    target: DatabaseRuntimeConfig;
+}
+export type SchemaOperationConfigResolver = (runtimeRootDir: string) => ResolvedSchemaOperationPlan;
+export interface DatabaseSchemaOperationContext {
+    progress?: DatabaseProgress | null;
+    signal?: AbortSignal;
+}
+export interface VerifyDatabaseSchemaOptions extends DatabaseSchemaOperationContext {
+    skipSchemaSourceVerify?: boolean;
+}
+export declare function verifyDatabaseSchema(productDir: string, resolveConfigs: SchemaOperationConfigResolver, options?: Readonly<VerifyDatabaseSchemaOptions>): Promise<void>;
+export declare function refreshDatabaseSchema(productDir: string, resolveConfigs: SchemaOperationConfigResolver, options?: Readonly<DatabaseSchemaOperationContext>): Promise<RefreshedSourceSchemaState>;

package/dist/database/schema-operations.js

@@ -0,0 +1 @@
+import u from"fs";import{resolveContainedTestkitStateDirectory as f}from"../process/runs/product-state.js";import{makeTempDir as p,removeTempDir as h}from"../process/files/temp-dir.js";import{cleanupOrphanedLocalInfrastructure as y,destroyRuntimeDatabase as l,provisionDatabase as g}from"./index.js";import{forceRefreshSourceSchemaCache as S}from"./schema-source.js";export async function verifyDatabaseSchema(r,o,t={}){await m(r,"verify",o,t,async(e,s)=>{for(const a of e.configs)await s(a)})}export async function refreshDatabaseSchema(r,o,t={}){return m(r,"refresh",o,t,async(e,s)=>{for(const a of e.configs){if(a.name===e.target.name)break;await s(a)}return S(e.target,null,{reporter:t.progress?.reporter||null,setupRegistry:t.progress?.setupRegistry||null,signal:t.signal})})}async function m(r,o,t,e,s){const a=v(r,o),c=[];try{const n=t(a.path);return await s(n,async i=>{i.testkit.database&&(c.push(i.stateDir),await g(i,{progress:e.progress,signal:e.signal,skipSchemaSourceVerify:e.skipSchemaSourceVerify}))})}finally{for(const n of c.reverse())await l({productDir:r,stateDir:n}).catch(()=>{});await y(r).catch(()=>{}),a.remove()}}function v(r,o){const t=f(r);u.mkdirSync(t,{recursive:!0});const e=f(r),s=p(`_schema-${o}-`,{parentDir:e});let a=!1;return{path:s,remove(){a||(a=!0,h(s))}}}