@gfdelarue/testkit 0.3.0

package/dist/cloud/historical.d.ts

@@ -0,0 +1,69 @@
+import { CloudClient, type CloudClientOptions } from "./client.js";
+import { type HistoricalBatch, type HistoricalBegin, type HistoricalEvidence } from "./historical-contract.js";
+export interface HistoricalClientOptions extends CloudClientOptions {
+    campaignId: string;
+}
+export declare class HistoricalClient {
+    readonly origin: URL;
+    readonly projectId: string;
+    readonly campaignId: string;
+    readonly snapshot: CloudClient["snapshot"];
+    private readonly token;
+    private readonly ordinary;
+    private readonly staged;
+    constructor(options: Readonly<HistoricalClientOptions>);
+    private get base();
+    private importPath;
+    begin(command: HistoricalBegin): Promise<import("./historical-contract.js").HistoricalImport>;
+    stage(importId: string, evidence: HistoricalEvidence): Promise<import("./historical-contract.js").HistoricalUploadPlan>;
+    upload(target: string, filePath: string, bytes: number, contentType: "application/octet-stream" | "application/zip", onProgress?: (bytes: number) => void): Promise<void>;
+    completeEvidence(returnedURL: string): Promise<import("./historical-contract.js").HistoricalReceipt>;
+    batch(importId: string, command: HistoricalBatch): Promise<import("./historical-contract.js").HistoricalBatchResult>;
+    page(importId: string, cursor?: string, limit?: number): Promise<import("./historical-contract.js").HistoricalPage>;
+    complete(importId: string): Promise<import("./historical-contract.js").HistoricalPage>;
+    repository(): Promise<{
+        projectId: string;
+        host: string;
+        owner: string;
+        name: string;
+    }>;
+    cases(cursor?: string, limit?: number): Promise<import("./historical-contract.js").HistoricalCasePage>;
+    caseHistory(caseId: string, cursor?: string, limit?: number): Promise<import("./historical-contract.js").HistoricalCaseHistoryPage>;
+    receipt(id: string): Promise<import("./historical-contract.js").HistoricalReceipt>;
+    currentReceipt(id: string): Promise<{
+        acceptedAt: string;
+        commitSha: string;
+        decision: "hold" | "ineligible" | "ship";
+        decisionReasons: {
+            ruleId: string;
+            message: string;
+        }[];
+        fullRun: boolean;
+        id: string;
+        manifestDigest: string;
+        policyId: string;
+        policyRevision: number;
+        projectId: string;
+        regressions: {
+            fixed: number;
+            known: number;
+            new: number;
+            returning: number;
+        };
+        repository: string;
+        runId: string;
+        runStatus: string;
+        testkitVersion: string;
+    }>;
+    campaign(): Promise<import("./campaigns.js").Campaign>;
+    finding(id: string): Promise<import("./campaigns.js").FindingDetail>;
+    artifactURL(receiptId: string, path: string): string;
+    checkArtifactAvailable(receiptId: string, artifactPath: string): Promise<void>;
+    download(target: string, filePath: string, expected: {
+        bytes: number;
+        sha256: string;
+    }): Promise<void>;
+    private target;
+    private json;
+    private read;
+}

package/dist/cloud/historical.js

@@ -0,0 +1 @@
+import j from"node:fs";import{stat as I}from"node:fs/promises";import{downloadVerifiedArtifact as C}from"./download.js";import{CloudClient as R,CloudResponseError as $}from"./client.js";import{request as p,invalidResponse as n}from"./transport.js";import{attachErrorDiagnostics as b}from"../kernel/error-serialization.js";import{isUnknownRecord as u}from"../kernel/unknown-values.js";import{canonicalHistoricalJson as v}from"./historical-json.js";import{HISTORICAL_BODY_LIMIT as H,parseHistoricalBatchResult as T,parseHistoricalCaseHistory as E,parseHistoricalCases as U,parseHistoricalImport as S,parseHistoricalPage as m,parseHistoricalReceipt as g,parseHistoricalResponse as w,parseHistoricalUploadPlan as P}from"./historical-contract.js";export class HistoricalClient{origin;projectId;campaignId;snapshot;token;ordinary;staged=new Map;constructor(t){const e=new R(t,{decodeJSON:w,maxResponseBytes:33554432});if(this.ordinary=e,this.snapshot=e.snapshot.bind(e),!/^[A-Za-z0-9_-]{1,128}$/.test(t.projectId)||!/^[A-Za-z0-9_-]{1,128}$/.test(t.campaignId))throw new Error("Historical Cloud project and campaign IDs must be valid Cloud identifiers");this.origin=e.origin,this.projectId=e.projectId,this.campaignId=t.campaignId,this.token=t.token}get base(){return`/api/v1/projects/${encodeURIComponent(this.projectId)}/campaigns/${encodeURIComponent(this.campaignId)}/imports`}importPath(t){if(!t.trim())throw new Error("Historical import ID is required");return`${this.base}/${encodeURIComponent(t)}`}async begin(t){const e=S(await this.json("POST",this.base,t),this.projectId,this.campaignId);if(e.namespace!==t.namespace||e.inventoryDigest!==t.inventoryDigest||e.total!==t.inventory.length)throw n("historical begin inventory identity");return e}async stage(t,e){const r=P(await this.json("POST",`${this.importPath(t)}/evidence`,e),e),i=this.target(r.completeUrl).href;for(const o of r.uploads)this.target(o.url);return r.archive&&this.target(r.archive.url),this.staged.set(i,{importId:t,evidence:e,reused:r.reused}),r}async upload(t,e,r,i,o){const c=this.target(t);if(!Number.isSafeInteger(r)||r<0)throw new Error("Historical upload byte length must be a nonnegative safe integer");const a=await I(e);if(!a.isFile()||a.size!==r)throw new Error("Historical upload file size does not match the manifest");const h=j.createReadStream(e),y=new Promise(d=>h.once("close",d));try{const d=await p({body:h,onUploadChunk:o,headers:{Authorization:`Bearer ${this.token}`,"Content-Length":String(r),"Content-Type":i},method:"PUT",timeoutMs:6e5,url:c});if(d.status<200||d.status>=300)throw f(d)}finally{h.destroy(),await y}}async completeEvidence(t){const e=this.target(t);return g(await this.json("POST",e.href),this.projectId,this.staged.get(e.href))}async batch(t,e){const{value:r,status:i}=await this.read("POST",`${this.importPath(t)}/batches`,e,!0),o=T(r,t,e);if(i===422!==o.rejected)throw n("historical batch HTTP status");return o}async page(t,e,r=100){const i=m(await this.json("GET",`${this.importPath(t)}${l(e,r)}`),this.projectId,this.campaignId,t,r);if(e!==void 0&&i.nextCursor===e)throw n("historical repeated cursor");return i}async complete(t){const e=m(await this.json("POST",`${this.importPath(t)}/complete`),this.projectId,this.campaignId,t);if(!e.import.completedAt||Object.values(e.counts).some(r=>Object.entries(r).some(([i,o])=>!["accepted","reused"].includes(i)&&o>0)))throw n("historical completion state");return e}async repository(){const t=await this.json("GET",`/api/v1/projects/${encodeURIComponent(this.projectId)}/repository`);if(!u(t)||t.projectId!==this.projectId||Object.keys(t).length!==4||Object.keys(t).some(r=>!["projectId","host","owner","name"].includes(r)))throw n("project repository identity");const e=r=>{const i=t[r];if(typeof i!="string"||!i.trim()||i.includes("\0")||Buffer.byteLength(i)>256)throw n(`project repository ${r}`);return i};return{projectId:this.projectId,host:e("host"),owner:e("owner"),name:e("name")}}async cases(t,e=100){const r=U(await this.json("GET",`/api/v1/projects/${encodeURIComponent(this.projectId)}/cases${l(t,e)}`),e);if(t!==void 0&&r.nextCursor===t)throw n("historical repeated cursor");return r}async caseHistory(t,e,r=100){const i=E(await this.json("GET",`/api/v1/projects/${encodeURIComponent(this.projectId)}/cases/${encodeURIComponent(t)}/history${l(e,r)}`),r);if(e!==void 0&&i.nextCursor===e)throw n("historical repeated cursor");return i}async receipt(t){const e=await this.json("GET",`/api/v1/receipts/${encodeURIComponent(t)}`);if(!u(e))throw n("historical receipt view");return g(e.receipt,this.projectId,{id:t})}async currentReceipt(t){return this.ordinary.receipt(t)}campaign(){return this.ordinary.campaign(this.campaignId)}finding(t){return this.ordinary.finding(this.campaignId,t)}artifactURL(t,e){if(e.split("/").some(r=>!r||r==="."||r==="..")||e.includes("\\"))throw new Error("Historical artifact path must be a normalized relative path");return`/api/v1/receipts/${encodeURIComponent(t)}/artifacts/${e.split("/").map(encodeURIComponent).join("/")}`}async checkArtifactAvailable(t,e){const r=await p({body:null,headers:{Authorization:`Bearer ${this.token}`,"Accept-Encoding":"identity"},method:"HEAD",timeoutMs:3e4,url:this.target(this.artifactURL(t,e))});if(r.status<200||r.status>=300)throw f(r)}async download(t,e,r){const i=this.target(t);await C(i,this.token,e,r)}target(t){if(!t)throw new Error("Testkit Cloud returned an empty historical URL");const e=new URL(t,this.origin);if(e.origin!==this.origin.origin||e.username||e.password||e.hash)throw new Error("Testkit Cloud returned a historical URL outside its configured origin or containing credentials/fragment");return e}async json(t,e,r){return(await this.read(t,e,r)).value}async read(t,e,r,i=!1){const o=this.target(e),c=r===void 0?null:Buffer.from(v(r));if(c&&c.length>H)throw new Error("Historical Cloud request exceeds 2 MiB; split its records or reduce the source inventory");const a=await p({body:c,headers:{Accept:"application/json",Authorization:`Bearer ${this.token}`,...c?{"Content-Length":String(c.length),"Content-Type":"application/json"}:{}},method:t,timeoutMs:3e4,url:o,maxResponseBytes:32*1024**2});if((a.status<200||a.status>=300)&&!(i&&a.status===422))throw f(a);try{return{value:w(new TextDecoder("utf-8",{fatal:!0}).decode(a.body)),status:a.status}}catch(h){throw n(`historical JSON response: ${h instanceof Error?h.message:String(h)}`)}}}function l(s,t){if(!Number.isSafeInteger(t)||t<1||t>100||s!==void 0&&(!s||Buffer.byteLength(s)>1024))throw new Error("Historical pagination requires limit 1\u2013100 and a cursor of at most 1024 bytes");const e=new URLSearchParams({limit:String(t)});return s!==void 0&&e.set("cursor",s),`?${e}`}function f(s){let t=s.body.toString("utf8").trim(),e=null,r={};try{const i=JSON.parse(t);u(i)&&(r=i,typeof i.detail=="string"&&(t=i.detail),typeof i.code=="string"&&(e=i.code))}catch{}return b(new $(s.status,t||`Testkit Cloud returned HTTP ${String(s.status)}`,e),{source:"cloud",...r})}

package/dist/cloud/pagination.d.ts

@@ -0,0 +1,5 @@
+/** Bound a complete read even if Cloud keeps issuing fresh cursors. */
+export declare function walkCloudPages<T>(read: (cursor?: string) => Promise<{
+    items: T[];
+    nextCursor?: string;
+}>, visit: (items: T[]) => void): Promise<void>;

package/dist/cloud/pagination.js

@@ -0,0 +1 @@
+export async function walkCloudPages(t,s){const r=new Set;let n;for(let o=0;o<1e4;o++){const e=await t(n);if(e.nextCursor!==void 0&&(e.items.length===0||r.has(e.nextCursor)))throw new Error("Cloud pagination repeated a cursor or returned an empty continuing page");if(s(e.items),e.nextCursor===void 0)return;r.add(e.nextCursor),n=e.nextCursor}throw new Error("Cloud pagination exceeded 10,000 pages; the read is inconclusive")}

package/dist/cloud/transport.d.ts

@@ -0,0 +1,18 @@
+import fs from "node:fs";
+export interface ResponseDocument {
+    body: Buffer;
+    status: number;
+}
+interface RequestInput {
+    body: Buffer | fs.ReadStream | null;
+    headers: Readonly<Record<string, string>>;
+    method: string;
+    timeoutMs: number;
+    url: URL;
+    onUploadChunk?: (bytes: number) => void;
+    onResponseChunk?: (chunk: Uint8Array) => Promise<void>;
+    maxResponseBytes?: number;
+}
+export declare function request(input: Readonly<RequestInput>): Promise<ResponseDocument>;
+export declare function invalidResponse(field: string): Error;
+export {};

package/dist/cloud/transport.js

@@ -0,0 +1 @@
+import i from"node:fs";import{Agent as f,fetch as h}from"undici";import{attachErrorDiagnostics as l}from"../kernel/error-serialization.js";import{isUnknownRecord as d}from"../kernel/unknown-values.js";const m=new f({connectTimeout:3e4,headersTimeout:10*6e4,bodyTimeout:10*6e4});export async function request(e){const s=new AbortController,a=setTimeout(()=>{s.abort(new Error("Testkit Cloud request timed out"))},e.timeoutMs);if(a.unref(),e.body instanceof i.ReadStream){const o=e.body,t=n=>{s.abort(n)};o.once("error",t),o.once("close",()=>o.off("error",t))}let r;try{const o=await h(e.url,{body:e.body instanceof i.ReadStream&&e.onUploadChunk?b(e.body,e.onUploadChunk):e.body,headers:e.headers,method:e.method,redirect:"manual",signal:s.signal,dispatcher:m,duplex:"half"});r=o.body?.getReader();const t=[];let n=0;for(;r;){const{done:u,value:c}=await r.read();if(u)break;if(e.onResponseChunk&&o.status>=200&&o.status<300){await e.onResponseChunk(c);continue}if(n+=c.byteLength,n>(e.maxResponseBytes??4*1024*1024))throw invalidResponse("response: exceeded byte limit");t.push(c)}return{body:Buffer.concat(t),status:o.status}}catch(o){const t=d(o)&&d(o.cause)?o.cause:o,n=d(t)&&typeof t.code=="string"?t.code:void 0;throw n==="invalid_cloud_response"?o:l(Object.assign(new Error(`Testkit Cloud transport failed: ${t instanceof Error?t.message:String(t)}`,{cause:o}),{code:"cloud_transport_error"}),{source:"transport",...n?{transportCode:n}:{}})}finally{clearTimeout(a),await r?.cancel().catch(()=>{}),r?.releaseLock()}}export function invalidResponse(e){return l(Object.assign(new Error(`Testkit Cloud returned an invalid ${e}`),{code:"invalid_cloud_response"}),{source:"cloud"})}async function*b(e,s){for await(const a of e){const r=a;s(r.byteLength),yield r}}

package/dist/config/authoring/build-config-contract.d.ts

@@ -0,0 +1,27 @@
+import type { ConfiguredStepInput } from "./configured-step-contract.js";
+export interface BuildConfigInputBase {
+    inputs?: string[];
+}
+export interface TscBuildConfigInput extends BuildConfigInputBase {
+    cwd?: string;
+    entry?: string;
+    kind: "tsc";
+    outDir?: string;
+    tsconfig?: string;
+}
+export interface ScriptBuildConfigInput extends BuildConfigInputBase {
+    cwd?: string;
+    kind: "script";
+    script: string;
+}
+export interface NextBuildConfigInput extends BuildConfigInputBase {
+    cwd?: string;
+    distDir?: string;
+    kind: "next";
+    tsconfig?: string;
+}
+export interface StepsBuildConfigInput extends BuildConfigInputBase {
+    kind: "steps";
+    steps?: ConfiguredStepInput[];
+}
+export type BuildConfigInput = TscBuildConfigInput | ScriptBuildConfigInput | NextBuildConfigInput | StepsBuildConfigInput;

package/dist/config/authoring/build-config-contract.js

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

package/dist/config/authoring/configured-step-contract.d.ts

@@ -0,0 +1,18 @@
+export interface ConfiguredStepBaseInput {
+    args?: unknown;
+    cwd?: string;
+    inputs?: string[];
+}
+export interface ConfiguredCommandStepInput extends ConfiguredStepBaseInput {
+    kind: "command";
+    run: string;
+}
+export interface ConfiguredSqlFileStepInput extends ConfiguredStepBaseInput {
+    kind: "sql-file";
+    path: string;
+}
+export interface ConfiguredModuleStepInput extends ConfiguredStepBaseInput {
+    kind: "module";
+    target: string;
+}
+export type ConfiguredStepInput = ConfiguredCommandStepInput | ConfiguredSqlFileStepInput | ConfiguredModuleStepInput;

package/dist/config/authoring/configured-step-contract.js

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

package/dist/config/authoring/http-execution-contract.d.ts

@@ -0,0 +1,70 @@
+export type RuntimeMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type RuntimeResponseBody = string | ArrayBuffer | null;
+export type RuntimeResponseType = "binary" | "none" | "text";
+export type RuntimeResponseBodyFor<TResponseType extends RuntimeResponseType | undefined> = TResponseType extends "binary" ? ArrayBuffer : TResponseType extends "none" ? null : TResponseType extends "text" ? string : string | null;
+export type RuntimeHeaderValue = string | string[] | null | undefined;
+export interface RuntimeHeaders {
+    [key: string]: string;
+}
+export interface RuntimeCookie {
+    value: string;
+}
+export interface RuntimeHttpTraceResponse {
+    bodyPreview: string | null;
+    bodyTruncated: boolean;
+    contentType: string | null;
+    status: number | null;
+}
+export interface RuntimeHttpTrace {
+    actorName: string | null;
+    durationMs?: number;
+    finishedAt?: string;
+    id: string;
+    method: RuntimeMethod;
+    organizationKey: string | null;
+    organizationName: string | null;
+    path: string;
+    requestHeaders: Record<string, string | string[] | null>;
+    requestId: string;
+    response?: RuntimeHttpTraceResponse;
+    startedAt: string;
+    url: string;
+}
+export interface RuntimeResponse<TBody extends RuntimeResponseBody = string> {
+    __testkit?: {
+        httpTrace?: RuntimeHttpTrace;
+        rawResponse?: unknown;
+    };
+    body: TBody;
+    cookies?: Record<string, RuntimeCookie[]>;
+    headers?: Record<string, RuntimeHeaderValue>;
+    json?(selector?: string): unknown;
+    status: number;
+    timings?: {
+        duration: number;
+    };
+}
+export interface RuntimeOptions {
+    [key: string]: unknown;
+    thresholds?: Record<string, unknown>;
+}
+export interface RuntimeEnv {
+    BASE: string;
+    rawEnv?: Record<string, string | undefined>;
+}
+export interface HttpRequestParams<TResponseType extends RuntimeResponseType | undefined = RuntimeResponseType | undefined> {
+    [key: string]: unknown;
+    headers?: RuntimeHeaders;
+    redirects?: number;
+    responseType?: TResponseType;
+    tags?: RuntimeHeaders;
+    timeout?: string | number;
+}
+export interface RuntimeHttpClient {
+    del<TResponseType extends RuntimeResponseType | undefined = undefined>(url: string, body?: unknown, params?: HttpRequestParams<TResponseType>): RuntimeResponse<RuntimeResponseBodyFor<TResponseType>>;
+    file(data: unknown, filename?: string, contentType?: string): unknown;
+    get<TResponseType extends RuntimeResponseType | undefined = undefined>(url: string, params?: HttpRequestParams<TResponseType>): RuntimeResponse<RuntimeResponseBodyFor<TResponseType>>;
+    patch<TResponseType extends RuntimeResponseType | undefined = undefined>(url: string, body?: unknown, params?: HttpRequestParams<TResponseType>): RuntimeResponse<RuntimeResponseBodyFor<TResponseType>>;
+    post<TResponseType extends RuntimeResponseType | undefined = undefined>(url: string, body?: unknown, params?: HttpRequestParams<TResponseType>): RuntimeResponse<RuntimeResponseBodyFor<TResponseType>>;
+    put<TResponseType extends RuntimeResponseType | undefined = undefined>(url: string, body?: unknown, params?: HttpRequestParams<TResponseType>): RuntimeResponse<RuntimeResponseBodyFor<TResponseType>>;
+}

package/dist/config/authoring/http-execution-contract.js

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

package/dist/config/authoring/http-methods.d.ts

@@ -0,0 +1,18 @@
+import type { RuntimeMethod } from "./http-execution-contract.js";
+export interface HttpMethods<Response, Extra extends unknown[]> {
+    get: (path: string, ...extra: Extra) => Response;
+    delete: (path: string, body?: unknown, ...extra: Extra) => Response;
+    post: (path: string, body?: unknown, ...extra: Extra) => Response;
+    put: (path: string, body?: unknown, ...extra: Extra) => Response;
+    patch: (path: string, body?: unknown, ...extra: Extra) => Response;
+}
+export type RawHttpMethods<Response, Extra extends unknown[]> = {
+    [Method in keyof HttpMethods<Response, Extra> as `raw${Capitalize<Method>}`]: HttpMethods<Response, Extra>[Method];
+};
+export interface BodyMethods<Body, Response, Extra extends unknown[]> {
+    post: (path: string, body: Body, ...extra: Extra) => Response;
+    put: (path: string, body: Body, ...extra: Extra) => Response;
+    patch: (path: string, body: Body, ...extra: Extra) => Response;
+}
+export declare function createBodyMethods<Body, Response, Extra extends unknown[]>(invoke: (method: "POST" | "PUT" | "PATCH", path: string, body: Body, ...extra: Extra) => Response): BodyMethods<Body, Response, Extra>;
+export declare function createHttpMethods<Response, Extra extends unknown[]>(invoke: (method: RuntimeMethod, path: string, body: unknown, ...extra: Extra) => Response, emptyBody: unknown): HttpMethods<Response, Extra>;

package/dist/config/authoring/http-methods.js

@@ -0,0 +1 @@
+export function createBodyMethods(c){return{post:(r,t,...e)=>c("POST",r,t,...e),put:(r,t,...e)=>c("PUT",r,t,...e),patch:(r,t,...e)=>c("PATCH",r,t,...e)}}export function createHttpMethods(c,r){return{...createBodyMethods(c),get:(t,...e)=>c("GET",t,r,...e),delete:(t,e=r,...p)=>c("DELETE",t,e,...p)}}

package/dist/config/authoring/index.d.ts

@@ -0,0 +1,376 @@
+import { clearRepoConfig, getRepoConfig, registerRepoConfig, type HttpProfileConfig } from "./runtime.js";
+import { type PresetEnvConfig } from "./preset-env.js";
+import type { BuildConfigInput, NextBuildConfigInput, ScriptBuildConfigInput, StepsBuildConfigInput, TscBuildConfigInput } from "./build-config-contract.js";
+import type { ConfiguredCommandStepInput, ConfiguredModuleStepInput, ConfiguredSqlFileStepInput, ConfiguredStepBaseInput, ConfiguredStepInput } from "./configured-step-contract.js";
+import type { RuntimeIsolationPolicy } from "../../domain/runtime-isolation-contract.js";
+export type { HttpProfileAuth, HttpProfileConfig, HttpProfileEnv, HttpProfileEnvironment, HttpProfileHeaderBuilder, HttpProfileHeaderContext, HttpProfileRequestClient, HttpProfileResolvedEnv, HttpProfileResponse, HttpProfileSetupContext, RepoConfig, } from "./runtime.js";
+export type { BuildConfigInput, NextBuildConfigInput, ScriptBuildConfigInput, StepsBuildConfigInput, TscBuildConfigInput, } from "./build-config-contract.js";
+export type { ConfiguredCommandStepInput, ConfiguredModuleStepInput, ConfiguredSqlFileStepInput, ConfiguredStepBaseInput, ConfiguredStepInput, } from "./configured-step-contract.js";
+export type { RuntimeIsolationPolicy } from "../../domain/runtime-isolation-contract.js";
+export type { DatabaseBindingEnvConfig, PresetEnvConfig } from "./preset-env.js";
+type UnknownRecord = Record<string, unknown>;
+export type TemplateCommandStepConfig = ConfiguredCommandStepInput;
+export type TemplateSqlFileStepConfig = ConfiguredSqlFileStepInput;
+export type TemplateModuleStepConfig = ConfiguredModuleStepInput;
+export type TemplateLifecycleStepConfig = ConfiguredStepInput;
+export type TemplateLifecycleStepOptions = ConfiguredStepBaseInput;
+export type TemplateStepBaseConfig = ConfiguredStepBaseInput;
+export type BuildConfig = BuildConfigInput;
+export type TscBuildConfig = TscBuildConfigInput;
+export type ScriptBuildConfig = ScriptBuildConfigInput;
+export type NextBuildConfig = NextBuildConfigInput;
+export type StepsBuildConfig = StepsBuildConfigInput;
+export interface DatabaseTemplateConfig {
+    inputs?: string[];
+    migrate?: ConfiguredStepInput[];
+    seed?: ConfiguredStepInput[];
+    verify?: ConfiguredStepInput[];
+}
+export interface DatabaseTemplateOptions {
+    inputs?: string[];
+    migrate?: ConfiguredStepInput | ConfiguredStepInput[] | string | string[];
+    seed?: ConfiguredStepInput | ConfiguredStepInput[] | string | string[];
+    verify?: ConfiguredStepInput | ConfiguredStepInput[] | string | string[];
+}
+export interface DatabaseSourceSchemaOptions {
+    refresh?: "auto" | "always" | {
+        ttlSeconds: number;
+    };
+    unavailable?: "auto" | "fail" | "warn-cache";
+    verify?: boolean;
+}
+export interface DatabaseSourceSchemaConfig extends DatabaseSourceSchemaOptions {
+    env: string;
+    kind: "env";
+}
+export interface DatabaseRoleConfig {
+    name: string;
+    login: false;
+}
+interface PostgresDatabaseFields {
+    binding?: "shared" | "per-runtime";
+    image?: string;
+    maxConnections?: number;
+    password?: string;
+    reservedConnections?: number;
+    reset?: boolean;
+    roles?: DatabaseRoleConfig[];
+    runtimeConnections?: number;
+    sourceSchema?: DatabaseSourceSchemaConfig | null;
+    user?: string;
+}
+export interface PostgresDatabaseConfig extends PostgresDatabaseFields {
+    template?: DatabaseTemplateConfig;
+}
+export interface DatabaseLifecycleOptions extends PostgresDatabaseFields {
+    inputs?: string[];
+    migrate?: ConfiguredStepInput | ConfiguredStepInput[] | string | string[];
+    seed?: ConfiguredStepInput | ConfiguredStepInput[] | string | string[];
+    template?: DatabaseTemplateOptions;
+    verify?: ConfiguredStepInput | ConfiguredStepInput[] | string | string[];
+}
+export interface DatabaseFixtureOptions extends DatabaseLifecycleOptions {
+    discovery?: DiscoveryConfig;
+    envFiles?: string[];
+}
+export interface SkipFileRule {
+    path: string;
+    reason: string;
+}
+export interface SkipSuiteRule {
+    selector: string;
+    reason: string;
+}
+export interface SkipConfig {
+    files?: SkipFileRule[];
+    suites?: SkipSuiteRule[];
+}
+export interface RuntimePrepareConfig {
+    inputs?: string[];
+    steps?: ConfiguredStepInput[];
+}
+export interface RuntimeConfig {
+    build?: BuildConfigInput | null;
+    instances?: number;
+    maxConcurrentTasks?: number;
+    prepare?: RuntimePrepareConfig;
+    toolchain?: string | NodeToolchainConfig;
+}
+export interface NodeToolchainConfig {
+    cwd?: string;
+    detect?: "auto" | "off";
+    install?: "require-host" | "download";
+    node?: string;
+    npm?: string;
+}
+export type ToolchainConfig = NodeToolchainConfig;
+export interface SuiteRequirementRule {
+    locks?: string[];
+    selector: string;
+}
+export interface FileRequirementRule {
+    locks?: string[];
+    path: string;
+}
+export interface ServiceRequirementConfig {
+    files?: FileRequirementRule[];
+    suites?: SuiteRequirementRule[];
+}
+export interface SuiteRuntimeIsolationRule {
+    policy: RuntimeIsolationPolicy;
+    selector: string;
+}
+export interface FileRuntimeIsolationRule {
+    path: string;
+    policy: RuntimeIsolationPolicy;
+}
+export interface RuntimeIsolationConfig {
+    default?: RuntimeIsolationPolicy;
+    files?: FileRuntimeIsolationRule[];
+    suites?: SuiteRuntimeIsolationRule[];
+}
+export interface TestkitExecutionConfig {
+    fileTimeoutSeconds?: number;
+    taskConcurrency?: number;
+    /** @deprecated Use taskConcurrency. Removed in 0.3.0. */
+    workers?: number;
+}
+export interface FingerprintConfig {
+    exclude?: string[];
+    include?: string[];
+}
+export interface TestkitLintRuleConfig {
+    enabled?: boolean;
+    exclude?: string[];
+    include?: string[];
+}
+export interface TestkitBoundaryLintRuleConfig extends TestkitLintRuleConfig {
+    allowed?: string[];
+    trackedOnly?: boolean;
+}
+export type TestkitLintRuleName = "engineImports" | "uiSpecShape" | "dalParallelSafety" | "dataSuiteContract" | "configImports" | "testkitBoundary" | "unitTestBoundaries";
+type NonBoundaryTestkitLintRuleName = Exclude<TestkitLintRuleName, "testkitBoundary">;
+export interface TestkitLintConfig {
+    rules?: Partial<Record<NonBoundaryTestkitLintRuleName, boolean | TestkitLintRuleConfig>> & {
+        testkitBoundary?: boolean | TestkitBoundaryLintRuleConfig;
+    };
+    ui?: {
+        maxLines?: number;
+        maxTests?: number;
+    };
+}
+export interface UiConfig {
+    allowRemote?: boolean;
+    backendBaseUrl?: string;
+    frontendBaseUrl?: string;
+}
+export interface DiscoveryConfig {
+    exclude?: string[];
+    roots?: string[];
+}
+export interface ServiceLocalConfig {
+    baseUrl: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    port?: number;
+    readyTimeoutMs?: number;
+    shutdownTimeoutMs?: number;
+    readyUrl?: string | false | null;
+    start: string;
+}
+export interface ServiceConfig {
+    database?: PostgresDatabaseConfig;
+    databaseFrom?: string;
+    dependsOn?: string[];
+    discovery?: DiscoveryConfig;
+    env?: Record<string, string>;
+    envFile?: string;
+    envFiles?: string[];
+    local?: false | ServiceLocalConfig;
+    runtime?: RuntimeConfig;
+    runtimeIsolation?: RuntimeIsolationPolicy | RuntimeIsolationConfig;
+    requirements?: ServiceRequirementConfig;
+    skip?: SkipConfig;
+}
+export interface AppServiceConfig extends ServiceConfig {
+    local: ServiceLocalConfig;
+    runtime: RuntimeConfig;
+}
+interface PresetServiceOptions extends UnknownRecord {
+    database?: PostgresDatabaseConfig;
+    databaseFrom?: string;
+    dependsOn?: string[];
+    discovery?: DiscoveryConfig;
+    envFile?: string;
+    envFiles?: string[];
+    runtimeIsolation?: RuntimeIsolationPolicy | RuntimeIsolationConfig;
+    requirements?: ServiceRequirementConfig;
+    skip?: SkipConfig;
+}
+export interface AppRuntimeOptions {
+    instances?: number;
+    maxConcurrentTasks?: number;
+    prepare?: RuntimePrepareConfig;
+    toolchain?: string | NodeToolchainConfig;
+}
+interface NodeAppBoundaryOptions extends PresetServiceOptions {
+    baseUrl?: string;
+    build?: BuildConfigInput | null;
+    buildInputs?: string[];
+    cwd?: string;
+    entry?: string;
+    env?: PresetEnvConfig;
+    outDir?: string;
+    port?: number;
+    readyPath?: string;
+    readyTimeoutMs?: number;
+    shutdownTimeoutMs?: number;
+    readyUrl?: string | false | null;
+    runtime?: AppRuntimeOptions;
+    start?: string;
+    toolchain?: string | NodeToolchainConfig;
+    tsconfig?: string;
+}
+export interface NodeAppOptions extends NodeAppBoundaryOptions {
+    port: number;
+}
+interface NextAppBoundaryOptions extends PresetServiceOptions {
+    api?: string | {
+        baseUrl: string;
+    };
+    baseUrl?: string;
+    build?: BuildConfigInput | null;
+    buildInputs?: string[];
+    cwd?: string;
+    env?: PresetEnvConfig;
+    mode?: "dev" | "start";
+    port?: number;
+    readyTimeoutMs?: number;
+    shutdownTimeoutMs?: number;
+    readyUrl?: string | false | null;
+    runtime?: AppRuntimeOptions;
+    start?: string;
+    toolchain?: string | NodeToolchainConfig;
+}
+export interface NextAppOptions extends NextAppBoundaryOptions {
+    port: number;
+}
+export interface NodeNextPresetOptions {
+    fileTimeoutSeconds?: number;
+    install?: "require-host" | "download";
+    node?: string;
+    npm?: string;
+    taskConcurrency?: number;
+    /** @deprecated Use taskConcurrency. Removed in 0.3.0. */
+    workers?: number;
+}
+export interface TestkitConfig {
+    cloud?: {
+        verification?: {
+            minimumConfirmingRuns?: number;
+        };
+    };
+    artifacts?: {
+        publication?: {
+            directory: string;
+            required?: boolean;
+        };
+        retention?: {
+            maxAgeDays?: number;
+            maxRuns?: number;
+            preserveSuites?: string[];
+        };
+    };
+    discovery?: DiscoveryConfig;
+    execution?: TestkitExecutionConfig;
+    fingerprints?: FingerprintConfig;
+    lint?: TestkitLintConfig;
+    profiles?: {
+        http?: Record<string, HttpProfileConfig>;
+    };
+    services?: Record<string, ServiceConfig>;
+    toolchains?: Record<string, ToolchainConfig>;
+    ui?: UiConfig;
+}
+export declare function defineConfig<const TConfig extends TestkitConfig>(config: TConfig): TConfig;
+declare function commandStep(run: string, options?: ConfiguredStepBaseInput): ConfiguredCommandStepInput;
+declare function sqlFileStep(filePath: string, options?: ConfiguredStepBaseInput): ConfiguredSqlFileStepInput;
+declare function moduleStep(target: string, options?: ConfiguredStepBaseInput): ConfiguredModuleStepInput;
+declare function sourceSchemaFromEnv(envName: string, options?: DatabaseSourceSchemaOptions): DatabaseSourceSchemaConfig;
+declare function verifySeedStep(options?: unknown): ConfiguredModuleStepInput;
+declare function verifyRowsStep(options?: unknown): ConfiguredModuleStepInput;
+declare function runSqlStep(options?: unknown): ConfiguredModuleStepInput;
+declare function seedRowsStep(options?: unknown): ConfiguredModuleStepInput;
+declare function materializePostgresBindingStep(options?: unknown): ConfiguredModuleStepInput;
+declare function updateRowsStep(options?: unknown): ConfiguredModuleStepInput;
+declare function nowValue(): {
+    kind: "now";
+};
+declare function envValue(name: string): {
+    kind: "env";
+    name: string;
+};
+declare function jsonValue<TValue>(value: TValue): {
+    kind: "json";
+    value: TValue;
+};
+declare function postgresConnectionFromEnvValue(prefix: string): {
+    kind: "postgres-connection-from-env";
+    prefix: string;
+};
+declare function postgresFixture(options?: DatabaseFixtureOptions): ServiceConfig;
+declare function nodeToolchain(options?: NodeToolchainConfig): NodeToolchainConfig;
+declare function nodeApp(options: NodeAppOptions): AppServiceConfig;
+declare function nextApp(options: NextAppOptions): AppServiceConfig;
+export declare const app: {
+    node: typeof nodeApp;
+    next: typeof nextApp;
+};
+export declare const database: {
+    schema: {
+        fromEnv: typeof sourceSchemaFromEnv;
+    };
+    steps: {
+        materializePostgresBinding: typeof materializePostgresBindingStep;
+        runSql: typeof runSqlStep;
+        seedRows: typeof seedRowsStep;
+        updateRows: typeof updateRowsStep;
+        verifyRows: typeof verifyRowsStep;
+        verifySeed: typeof verifySeedStep;
+    };
+    values: {
+        env: typeof envValue;
+        json: typeof jsonValue;
+        now: typeof nowValue;
+        postgresConnectionFromEnv: typeof postgresConnectionFromEnvValue;
+    };
+    postgres(options?: DatabaseLifecycleOptions): PostgresDatabaseConfig;
+    fixture: typeof postgresFixture;
+};
+export declare const endpoint: {
+    baseUrl(serviceName: string): string;
+    readyUrl(serviceName: string): string;
+    publicBaseUrl(serviceName: string): string;
+    privateBaseUrl(serviceName: string): string;
+    serviceContextUrl(serviceName: string): string;
+};
+export declare const step: {
+    command: typeof commandStep;
+    module: typeof moduleStep;
+    sqlFile: typeof sqlFileStep;
+};
+export declare const presets: {
+    nodeNext(options?: NodeNextPresetOptions): {
+        execution: {
+            taskConcurrency: number;
+            fileTimeoutSeconds: number;
+        };
+        toolchains: {
+            node: NodeToolchainConfig;
+        };
+    };
+};
+export declare const toolchain: {
+    node: typeof nodeToolchain;
+};
+export { clearRepoConfig, getRepoConfig, registerRepoConfig };

package/dist/config/authoring/index.js

@@ -0,0 +1 @@
+import{clearRepoConfig as $,getRepoConfig as j,registerRepoConfig as O}from"./runtime.js";import{normalizeDatabaseEnvToken as b,normalizeNextPresetEnv as q,normalizePresetEnv as A}from"./preset-env.js";const _=String;export function defineConfig(e){return e||{}}function F(e={}){return{...e,...e.maxConnections?{maxConnections:e.maxConnections}:{},...e.reservedConnections?{reservedConnections:e.reservedConnections}:{},...e.runtimeConnections?{runtimeConnections:e.runtimeConnections}:{}}}function g(e,n="baseUrl"){const t=b(e,"service name",!1);return`{${b(n,"endpoint field",!1)}:${t}}`}function R(e={}){const n=z(e.migrate),t=z(e.seed),r=z(e.verify);return{inputs:Array.isArray(e.inputs)?[...e.inputs]:void 0,migrate:n,seed:t,verify:r}}function D(e,n={}){return{kind:"command",run:e,...E(n)}}function M(e,n={}){return{kind:"sql-file",path:e,...E(n)}}function u(e,n={}){return{kind:"module",target:e,...E(n)}}function E(e={}){return{...e.cwd!==void 0?{cwd:e.cwd}:{},...e.inputs!==void 0?{inputs:[...e.inputs]}:{},...e.args!==void 0?{args:e.args}:{}}}function V(e,n={}){if(typeof e!="string"||e.trim().length===0)throw new Error("database.schema.fromEnv(...) requires a non-empty env var name");return{kind:"env",env:e.trim(),...n}}function p(e){return`@gfdelarue/testkit/config/database-steps#${e}`}function X(e={}){return u(p("verifySeed"),{args:e})}function G(e={}){return u(p("verifyRows"),{args:e})}function H(e={}){return u(p("runSql"),{args:e})}function L(e={}){return u(p("seedRows"),{args:e})}function W(e={}){return u(p("materializePostgresBinding"),{args:e})}function J(e={}){return u(p("updateRows"),{args:e})}function K(){return{kind:"now"}}function Q(e){return{kind:"env",name:b(e,"database.values.env(...) name",!1)}}function Y(e){return{kind:"json",value:e}}function Z(e){return{kind:"postgres-connection-from-env",prefix:b(e,"database.values.postgresConnectionFromEnv(...) prefix",!1)}}function ee(e={}){const{discovery:n,envFiles:t,template:r,inputs:s,migrate:o,seed:a,verify:d,...c}=e,i=r||B(e)?R({inputs:s,migrate:o,seed:a,verify:d,...r||{}}):void 0;return{discovery:n||{roots:[".testkit-fixture"]},envFiles:t,local:!1,database:F(i?{...c,template:i}:c)}}function B(e={}){return["inputs","migrate","seed","verify"].some(n=>Object.prototype.hasOwnProperty.call(e,n))}function I(e={}){return{...e}}function ne(e={}){return{kind:"tsc",cwd:e.cwd,entry:e.entry||"src/index.ts",tsconfig:e.tsconfig||"tsconfig.json",outDir:e.outDir||"dist",inputs:Array.isArray(e.inputs)?[...e.inputs]:void 0}}function te(e={}){return{kind:"next",cwd:e.cwd,distDir:e.distDir||"dist",tsconfig:e.tsconfig||"tsconfig.json",inputs:Array.isArray(e.inputs)?[...e.inputs]:void 0}}function re(e={}){const{baseUrl:n,build:t,buildInputs:r,cwd:s=".",entry:o="src/index.ts",env:a,envFiles:d,outDir:c="dist",port:i,readyPath:w="/health",readyTimeoutMs:S,shutdownTimeoutMs:f,readyUrl:h,runtime:m,start:C,toolchain:k,tsconfig:T="tsconfig.json",...U}=e,l=N(i,"app.node port"),v=A(a),y=n||"http://127.0.0.1:{port}",x=t===void 0?ne({cwd:s,entry:o,tsconfig:T,outDir:c,inputs:r}):t,P=C||se(x,o);return{...U,envFiles:d,runtime:{...m||{},build:x,toolchain:k??m?.toolchain},local:{cwd:s,start:P,port:l,baseUrl:y,readyUrl:h??`${y}${w}`,readyTimeoutMs:S,...f===void 0?{}:{shutdownTimeoutMs:f},env:v}}}function ie(e={}){const{api:n,baseUrl:t,build:r,buildInputs:s,cwd:o=".",dependsOn:a,env:d,envFiles:c,mode:i="dev",port:w,readyTimeoutMs:S,shutdownTimeoutMs:f,readyUrl:h,runtime:m,start:C,toolchain:k,...T}=e,U=N(w,"app.next port"),l={...q({api:n}),...A(d)},v=t||"http://127.0.0.1:{port}",y=r===void 0?i==="start"?te({cwd:o,inputs:s}):null:r,x=C||(i==="start"?"{bin:next} start --port {port}":"{bin:next} dev -p {port}");return{...T,envFiles:c,dependsOn:Array.isArray(a)?[...a]:a,runtime:{...m||{},build:y,toolchain:k??m?.toolchain},local:{cwd:o,start:x,port:U,baseUrl:v,readyUrl:h??v,readyTimeoutMs:S,...f===void 0?{}:{shutdownTimeoutMs:f},env:i==="start"?{NEXT_DIST_DIR:l.NEXT_DIST_DIR||".next-testkit/{runtimeId}/dist",NEXT_TSCONFIG_PATH:l.NEXT_TSCONFIG_PATH||".next-testkit/{runtimeId}/tsconfig.json",...l}:l}}}export const app={node:re,next:ie},database={schema:{fromEnv:V},steps:{materializePostgresBinding:W,runSql:H,seedRows:L,updateRows:J,verifyRows:G,verifySeed:X},values:{env:Q,json:Y,now:K,postgresConnectionFromEnv:Z},postgres(e={}){const{template:n,sourceSchema:t,inputs:r,migrate:s,seed:o,verify:a,...d}=e,c=t===void 0?d:{...d,sourceSchema:t},i=n||B(e)?R({inputs:r,migrate:s,seed:o,verify:a,...n||{}}):void 0;return F(i?{...c,template:i}:c)},fixture:ee},endpoint={baseUrl(e){return g(e,"baseUrl")},readyUrl(e){return g(e,"readyUrl")},publicBaseUrl(e){return g(e,"publicBaseUrl")},privateBaseUrl(e){return g(e,"privateBaseUrl")},serviceContextUrl(e){return g(e,"serviceContextUrl")}},step={command:D,module:u,sqlFile:M},presets={nodeNext(e={}){const n=e.workers;if(e.taskConcurrency!=null&&n!=null&&e.taskConcurrency!==n)throw new Error("presets.nodeNext taskConcurrency and workers must match when both are provided.");return{execution:{taskConcurrency:e.taskConcurrency??n??1,fileTimeoutSeconds:e.fileTimeoutSeconds??120},toolchains:{node:I({install:e.install??"download",...e.node?{node:e.node}:{},...e.npm?{npm:e.npm}:{}})}}}},toolchain={node:I};export{$ as clearRepoConfig,j as getRepoConfig,O as registerRepoConfig};function N(e,n){if(typeof e!="number"||!Number.isInteger(e)||e<=0)throw new Error(`${n} must be a positive integer`);return e}function se(e,n){return e?.kind==="tsc"?`node {prepareDir}/${oe(n||e.entry||"src/index.ts",e.outDir||"dist")}`:`{bin:tsx} ${n||"src/index.ts"}`}function z(e){return e==null?[]:(Array.isArray(e)?e:[e]).map(t=>typeof t=="string"?D(t):t)}function oe(e,n){const r=_(e||"src/index.ts").replaceAll("\\","/").replace(/\.[cm]?[jt]sx?$/i,".js"),s=r.startsWith("src/")?r.slice(4):r;return`${n}/${s}`.replace(/\/+/g,"/")}