@gfdelarue/testkit 0.3.0

package/dist/repo/state.js

@@ -0,0 +1,5 @@
+import x from"crypto";import f from"fs";import s from"path";import{appendFingerprintPathToHash as Z,hasIncludedFingerprintDescendantAtPrefix as tt,normalizeFingerprintPolicy as et,shouldIgnoreCanonicalFingerprintPathAtPrefix as W}from"./fingerprint-policy.js";import{decodeGitPathRecord as F}from"./git-path.js";import{runManagedGitCommand as rt}from"./managed-git.js";import{physicalNodeMode as z,readPhysicalNode as j}from"./physical-tree.js";import{normalizeManagedHostEnvironment as nt,requireManagedHostCommandSuccess as C,resolveManagedHostExecutableIfAvailable as ot}from"../process/index.js";import{readCiPullRequestHeadSha as it,resolveCiGitReference as at}from"./ci-environment.js";import{parseGitRepository as ct}from"./remote.js";export async function collectRepoState(t,e={}){const r=et(e.fingerprints),o=e.env??process.env,n=at(o),i=it(o);if(!ot("git",s.resolve(t),nt(process.env))&&!jt(t))return N(t,r,n);const c=await B(t);if(c===null)return N(t,r,n);const u=_(c,t),p=await R(u.repoRoot,["rev-parse","--verify","--quiet","HEAD"]),m=await st(u.repoRoot,p,i),b=await R(u.repoRoot,["symbolic-ref","--quiet","--short","HEAD"]),P=await R(u.repoRoot,["config","--get","remote.origin.url"]),w=p!==null&&b===null,g=await lt(u,r,p,""),d=!!g,h=p||"unborn";return{kind:d?"dirty":"commit",repoRoot:u.repoRoot,worktreePath:u.repoRoot,branch:b??(w?n.branch:null),detached:w,commitSha:p,pullRequest:n.pullRequest,pullRequestHeadSha:m,remoteUrl:P,repository:ct(P),dirty:d,dirtyFingerprint:g,contentFingerprint:null,cacheKey:g?`dirty/${h}-${g}`:`commits/${h}`}}function N(t,e,r){const o=f.realpathSync.native(s.resolve(t)),n=V(o,e);if(V(o,e)!==n)throw new Error("Physical repository snapshot changed while collecting repository state");const a=n.slice(0,24);return{kind:"nogit",repoRoot:null,worktreePath:o,branch:null,detached:!1,commitSha:null,pullRequest:r.pullRequest,pullRequestHeadSha:null,remoteUrl:null,repository:null,dirty:!1,dirtyFingerprint:null,contentFingerprint:a,cacheKey:`nogit/${a}`}}async function B(t){const e=["rev-parse","--show-toplevel"],r=await A(t,e);if(r.exitCode===0){const o=r.stdout.trim();if(o.length>0)return o;throw new Error("Git rev-parse returned an empty repository root")}if(Ft(r))return null;throw C(T(e),r),new Error("Unreachable Git repository probe result")}function _(t,e){const r=f.realpathSync.native(s.resolve(t)),o=f.realpathSync.native(s.resolve(e)),n=xt(s.relative(r,o));if(n===".."||n.startsWith("../")||s.isAbsolute(n)||process.platform==="win32"&&s.win32.isAbsolute(n))throw new Error(`Product directory must be inside its Git worktree: ${o}`);return{productDir:o,productPathspec:n?$t(n):".",productRootRelativePath:n,repoRoot:r}}export function summarizeRepoStateForMetadata(t){return t?{kind:t.kind,cacheKey:t.cacheKey,branch:t.branch,detached:t.detached,commitSha:t.commitSha,dirty:t.dirty,dirtyFingerprint:t.dirtyFingerprint,contentFingerprint:t.contentFingerprint,pullRequest:t.pullRequest,pullRequestHeadSha:t.pullRequestHeadSha,repoRoot:t.repoRoot,repository:t.repository,worktreePath:t.worktreePath,remoteUrl:t.remoteUrl}:null}async function st(t,e,r){if(e===null||r===null)return null;if(e===r)return r;const o=await v(t,["cat-file","commit","HEAD"]),n=[];for(const i of o.split(`
+`)){if(i.length===0)break;i.startsWith("parent ")&&n.push(i.slice(7))}return n.length>=2&&n.includes(r)?r:null}async function lt(t,e,r,o){const n=await q(t,e,r,o),i=await q(t,e,r,o);if(n!==i)throw new Error("Git HEAD, index, untracked inventory, submodule state, or physical snapshot changed while collecting repository state");return n?.slice(0,24)??null}async function q(t,e,r,o){await J(t.repoRoot,r);const n=x.createHash("sha256");let i=!1;const a=await yt(t.repoRoot),[c,u]=await Promise.all([K(t,a),dt(t,r,a)]),p=wt(c),m=vt(u),b=[...new Set([...p.keys(),...m.keys()])].sort(y);for(const d of b){const h=p.get(d)??[],G=m.get(d)??[],M=h.some($=>$.mode==="160000")||G.some($=>$.mode==="160000");if(W(d,o,e)&&(!M||!tt(d,o,e)))continue;const X=h.length>0?h[0]:G[0],H=j(t.productDir,d),U=M?await pt(t,X,H,e,o):null;(!ht(h,G)||!ft(h,H,U,a))&&(i=!0,mt(n,d,G,h,H,U,a))}const P=await v(t.repoRoot,["ls-files","--others","--exclude-per-directory=.gitignore","--",t.productPathspec]),w=Ht(t,O(P,"Git ls-files").map(d=>F(d))).filter(d=>!W(d.productRelativePath,o,e));if(w.length>0){i=!0,n.update("untracked-state-v2\0");for(const d of w)l(n,"path",d.productRelativePath),D(n,j(t.productDir,d.productRelativePath),a)}const g=await K(t,a);if(!Pt(c,g))throw new Error("Git index changed while collecting repository state");return await J(t.repoRoot,r),i?n.digest("hex"):null}async function K(t,e){const r=await v(t.repoRoot,["ls-files","--stage","--abbrev=64","--",t.productPathspec]);return ut(t,r,e)}function ut(t,e,r){const o=[];for(const n of O(e,"Git ls-files")){const i=n.indexOf("	");if(i<0)throw new Error("Git ls-files returned malformed stage metadata");const a=n.slice(0,i).split(" "),c=I(F(n.slice(i+1)));if(a.length!==3||!/^[0-7]{6}$/u.test(a[0])||!Y(a[1],r)||!/^[0-3]$/u.test(a[2]))throw new Error("Git ls-files returned invalid stage metadata");const u=L(t,c);if(!u)throw new Error(`Git ls-files returned a path outside the product: ${c}`);o.push({mode:a[0],objectId:a[1],productRelativePath:u,rootRelativePath:c,stage:Number(a[2])})}return o.sort(St)}async function dt(t,e,r){if(e===null)return[];const o=await v(t.repoRoot,["ls-tree","-r","--full-tree",e,"--",t.productPathspec]);return gt(t,o,r)}async function pt(t,e,r,o,n){if(r.kind==="missing"||r.kind==="ancestor-missing")return{kind:"missing",node:r};if(r.kind!=="directory")return{kind:"non-directory",node:r};const i=Et(t,e),a=await B(i);if(a===null||!It(a,i))throw new Error(`Gitlink is not initialized as a repository: ${e.productRelativePath}`);const c=_(a,i),u=await R(c.repoRoot,["rev-parse","--verify","--quiet","HEAD"]),p=await q(c,o,u,kt(n,e.productRelativePath)),m=j(t.productDir,e.productRelativePath);if(m.kind!=="directory"||!Gt(m.identity,r.identity))throw new Error(`Gitlink path changed while collecting repository state: ${e.productRelativePath}`);return{kind:"initialized",dirtyFingerprint:p,head:u,identity:m.identity}}function ft(t,e,r,o){if(t.length!==1||t[0]?.stage!==0)return!1;const n=t[0];return n.mode==="160000"?r?.kind==="initialized"&&r.head===n.objectId&&r.dirtyFingerprint===null:n.mode==="120000"?e.kind==="symlink"&&k(o,e.target)===n.objectId:n.mode==="100644"||n.mode==="100755"?e.kind==="file"&&bt(e.mode,n.mode)===n.mode&&k(o,e.contents)===n.objectId:!1}function ht(t,e){return e.length===0&&t.length===0?!0:e.length!==1||t.length!==1||t[0]?.stage!==0?!1:e[0]?.mode===t[0]?.mode&&e[0]?.objectId===t[0]?.objectId}function mt(t,e,r,o,n,i,a){t.update("tracked-path-state-v2\0"),l(t,"path",e),r.length===0&&t.update("head-missing\0");for(const c of r)t.update("head-entry\0"),l(t,"mode",c.mode),l(t,"object",c.objectId);o.length===0&&t.update("index-missing\0");for(const c of o)t.update("index-entry\0"),l(t,"mode",c.mode),l(t,"object",c.objectId),l(t,"stage",c.stage.toString());i?Rt(t,i,a):D(t,n,a)}function gt(t,e,r){const o=[];for(const n of O(e,"Git ls-tree")){const i=n.indexOf("	"),a=n.slice(0,i).split(" ");if(i<0||a.length!==3||!/^[0-7]{6}$/u.test(a[0])||!/^(?:blob|commit)$/u.test(a[1])||!Y(a[2],r))throw new Error("Git ls-tree returned invalid tree metadata");const c=I(F(n.slice(i+1))),u=L(t,c);if(!u)throw new Error(`Git ls-tree returned a path outside the product: ${c}`);o.push({mode:a[0],objectId:a[2],productRelativePath:u,rootRelativePath:c})}return o.sort((n,i)=>y(n.productRelativePath,i.productRelativePath))}async function yt(t){const e=(await v(t,["rev-parse","--show-object-format"])).trim();if(e==="sha1"||e==="sha256")return e;throw new Error(`Unsupported Git object format: ${e||"empty"}`)}function wt(t){const e=new Map;for(const r of t){const o=e.get(r.productRelativePath);o?o.push(r):e.set(r.productRelativePath,[r])}return e}function vt(t){const e=new Map;for(const r of t){const o=e.get(r.productRelativePath);o?o.push(r):e.set(r.productRelativePath,[r])}return e}function Rt(t,e,r){if(t.update("gitlink-worktree-state-v2\0"),l(t,"kind",e.kind),e.kind==="initialized"){e.head===null?t.update("head-missing\0"):l(t,"head",e.head),e.dirtyFingerprint===null?t.update("nested-clean\0"):l(t,"nested-dirty",e.dirtyFingerprint);return}D(t,e.node,r)}function D(t,e,r){switch(t.update("physical-node-v2\0"),l(t,"kind",e.kind),e.kind){case"file":l(t,"mode",process.platform==="win32"?"platform-mode-ignored":e.mode&73n?"100755":"100644"),l(t,"blob",k(r,e.contents)),E(t,e.contents);break;case"symlink":l(t,"blob",k(r,e.target)),E(t,e.target);break;case"directory":l(t,"mode",z(e.mode));break;case"ancestor-symlink":l(t,"obstacle",e.obstaclePath),E(t,e.target);break;case"ancestor-non-directory":l(t,"obstacle",e.obstaclePath),l(t,"mode",z(e.mode));break;case"ancestor-missing":l(t,"obstacle",e.obstaclePath);break;case"missing":break}}function bt(t,e){return process.platform==="win32"?e:t&73n?"100755":"100644"}function k(t,e){return x.createHash(t).update(`blob ${e.byteLength.toString()}\0`).update(e).digest("hex")}function Pt(t,e){return t.length===e.length&&t.every((r,o)=>{const n=e[o];return r.mode===n.mode&&r.objectId===n.objectId&&r.productRelativePath===n.productRelativePath&&r.rootRelativePath===n.rootRelativePath&&r.stage===n.stage})}function Gt(t,e){return t.dev===e.dev&&t.ino===e.ino&&t.type===e.type}function Y(t,e){const r=e==="sha1"?40:64;return t.length===r&&/^[0-9a-f]+$/u.test(t)}function kt(t,e){return t?e?`${t}/${e}`:t:e}function Et(t,e){const r=e.productRelativePath.split("/");if(r.some(i=>i.length===0||i==="."||i===".."))throw new Error(`Git returned an invalid product path: ${e.productRelativePath}`);const o=s.resolve(t.productDir,...r),n=s.relative(t.productDir,o);if(n===".."||n.startsWith(`..${s.sep}`)||s.isAbsolute(n))throw new Error(`Git returned a path outside the product: ${e.rootRelativePath}`);return o}function It(t,e){const r=f.realpathSync.native(s.resolve(t)),o=f.realpathSync.native(s.resolve(e));return process.platform==="win32"?r.toLocaleLowerCase("en-US")===o.toLocaleLowerCase("en-US"):r===o}function l(t,e,r){t.update(`${e}\0`),E(t,Buffer.from(r))}function E(t,e){t.update(`${e.byteLength.toString()}\0`),t.update(e),t.update("\0")}function St(t,e){return y(t.productRelativePath,e.productRelativePath)||t.stage-e.stage||y(t.mode,e.mode)||y(t.objectId,e.objectId)}function Ht(t,e){const r=new Map;for(const o of e){const n=I(o);if(n===".."||n.startsWith("../")||s.isAbsolute(n)||process.platform==="win32"&&s.win32.isAbsolute(n))throw new Error(`Git returned a path outside its worktree: ${n}`);const i=L(t,n);i&&r.set(n,{productRelativePath:i,rootRelativePath:n})}return[...r.values()].sort((o,n)=>y(o.productRelativePath,n.productRelativePath))}function L(t,e){if(!e)return null;if(!t.productRootRelativePath)return e;const r=`${t.productRootRelativePath}/`;return(process.platform==="win32"?e.toLocaleLowerCase("en-US").startsWith(r.toLocaleLowerCase("en-US")):e.startsWith(r))?e.slice(r.length):null}function $t(t){return`:(top,literal)${t}`}function I(t){return t.replace(/^\.\/+/,"").replace(/\/+$/,"")}function xt(t){return I(t.split(s.sep).join("/"))}function y(t,e){return t<e?-1:t>e?1:0}function V(t,e){const r=x.createHash("sha256");return Z(r,t,t,e),r.digest("hex")}async function v(t,e){const r=await A(t,e);return C(T(e),r).stdout}async function R(t,e){const r=await A(t,e);if(r.exitCode===0)return r.stdout.trim()||null;if(r.exitCode===1&&r.stdout.trim().length===0&&r.stderr.trim().length===0)return null;throw C(T(e),r),new Error("Unreachable Git command result")}function A(t,e){return rt(t,["--no-replace-objects","--no-pager","--no-optional-locks","-c","core.fsmonitor=false","-c","core.quotePath=true",...e],{repositoryConfigOnly:!0})}async function J(t,e){if(await R(t,["rev-parse","--verify","--quiet","HEAD"])!==e)throw new Error("Git HEAD changed while collecting repository state")}function O(t,e){if(t.length===0)return[];if(!t.endsWith(`
+`))throw new Error(`${e} returned an unterminated path record`);return t.slice(0,-1).split(`
+`)}function T(t){const e=t.find(r=>!r.startsWith("-"));return e?`Git ${e}`:"Git command"}function Ft(t){return`${t.stderr}
+${t.stdout}`.toLowerCase().includes("not a git repository")}function jt(t){let e=f.realpathSync.native(s.resolve(t)),r=f.statSync(e).dev;const o=Ct(),n=Dt(process.env.GIT_DISCOVERY_ACROSS_FILESYSTEM);let i=s.dirname(e);for(;i!==e;){if(o.has(e))return!1;if(Q(s.join(e,".git")))return!0;const a=f.statSync(i).dev;if(!n&&a!==r)return!1;e=i,r=a,i=s.dirname(e)}return o.has(e)?!1:Q(s.join(e,".git"))}function Ct(){const t=process.env.GIT_CEILING_DIRECTORIES;return t?new Set(t.split(s.delimiter).filter(Boolean).map(e=>qt(e))):new Set}function qt(t){const e=s.resolve(t);try{return f.realpathSync.native(e)}catch(r){if(S(r,"ENOENT")||S(r,"ENOTDIR"))return e;throw r}}function Dt(t){return/^(?:1|on|true|yes)$/iu.test(t||"")}function Q(t){try{return f.lstatSync(t),!0}catch(e){if(S(e,"ENOENT")||S(e,"ENOTDIR"))return!1;throw e}}function S(t,e){return t!==null&&typeof t=="object"&&"code"in t&&Reflect.get(t,"code")===e}

package/dist/steps/build-config.d.ts

@@ -0,0 +1,35 @@
+import { type NormalizedConfiguredStep } from "./configured-steps.js";
+export type { BuildConfigInput, BuildConfigInputBase, NextBuildConfigInput, ScriptBuildConfigInput, StepsBuildConfigInput, TscBuildConfigInput, } from "../config/authoring/build-config-contract.js";
+export interface NormalizedBuildConfigBase {
+    inputs: string[];
+}
+export interface NormalizedTscBuildConfig extends NormalizedBuildConfigBase {
+    cwd: string | null;
+    entry: string;
+    kind: "tsc";
+    outDir: string;
+    tsconfig: string;
+}
+export interface NormalizedScriptBuildConfig extends NormalizedBuildConfigBase {
+    cwd: string | null;
+    kind: "script";
+    script: string;
+}
+export interface NormalizedNextBuildConfig extends NormalizedBuildConfigBase {
+    cwd: string | null;
+    distDir: string;
+    kind: "next";
+    tsconfig: string;
+}
+export interface NormalizedStepsBuildConfig extends NormalizedBuildConfigBase {
+    kind: "steps";
+    steps: NormalizedConfiguredStep[];
+}
+export type NormalizedBuildConfig = NormalizedTscBuildConfig | NormalizedScriptBuildConfig | NormalizedNextBuildConfig | NormalizedStepsBuildConfig;
+export interface NormalizedBuildPrepareConfig {
+    inputs: string[];
+    steps: NormalizedConfiguredStep[];
+}
+export declare function normalizeBuildConfig(value: unknown, label: string): NormalizedBuildConfig | null;
+export declare function buildConfigToPrepare(build: NormalizedBuildConfig | null | undefined): NormalizedBuildPrepareConfig;
+export declare function compiledEntryFromBuild(build: NormalizedBuildConfig | null | undefined): string | null;

package/dist/steps/build-config.js

@@ -0,0 +1 @@
+import o from"path";import{normalizeConfiguredInputs as c,normalizeConfiguredSteps as p,normalizeOptionalString as e}from"./configured-steps.js";export function normalizeBuildConfig(t,s){if(t==null)return null;if(!m(t))throw new Error(`${s} must be an object`);const n=e(t.kind);if(n==="tsc")return{kind:n,cwd:e(t.cwd),entry:e(t.entry)||"src/index.ts",tsconfig:e(t.tsconfig)||"tsconfig.json",outDir:e(t.outDir)||"dist",inputs:c(t.inputs,s)};if(n==="script"){const r=e(t.script);if(!r)throw new Error(`${s}.script must be a non-empty string`);return{kind:n,cwd:e(t.cwd),script:r,inputs:c(t.inputs,s)}}if(n==="next")return{kind:n,cwd:e(t.cwd),distDir:e(t.distDir)||"dist",tsconfig:e(t.tsconfig)||"tsconfig.json",inputs:c(t.inputs,s)};if(n==="steps")return{kind:n,inputs:c(t.inputs,s),steps:p(t.steps,`${s}.steps`)};throw new Error(`${s}.kind must be one of: tsc, script, next, steps`)}export function buildConfigToPrepare(t){if(!t)return{inputs:[],steps:[]};if(t.kind==="steps")return{inputs:[...t.inputs],steps:[...t.steps]};if(t.kind==="script")return{inputs:[...t.inputs],steps:[{kind:"command",cmd:t.script,cwd:t.cwd||void 0,inputs:[]}]};if(t.kind==="next")return{inputs:t.inputs.length>0?[...t.inputs]:w(t),steps:[{kind:"module",specifier:"@gfdelarue/testkit/config/next-runtime-tsconfig#writeNextRuntimeTsconfig",cwd:t.cwd||void 0,inputs:[]},{kind:"command",cmd:"{bin:next} build",cwd:t.cwd||void 0,inputs:[]}]};const s=t.inputs.length>0?[...t.inputs]:d(t),n=`{bin:tsc} -p ${t.tsconfig} --outDir "{prepareDir}/${t.outDir}"`,r=u(t.entry);return{inputs:s,steps:[{kind:"command",cmd:n,cwd:t.cwd||void 0,inputs:[]},{kind:"module",specifier:"@gfdelarue/testkit/config/build-assets#copyTscRuntimeAssets",cwd:t.cwd||void 0,inputs:[],args:{sourceDir:r,outDir:t.outDir}}]}}export function compiledEntryFromBuild(t){return!t||t.kind!=="tsc"?null:o.posix.join(t.outDir,f(t.entry))}function f(t){const n=t.split(o.sep).join("/").replace(/\.[cm]?[jt]sx?$/i,".js");return n.startsWith("src/")?n.slice(4):n}function u(t){const s=t.split(o.sep).join("/");if(s.startsWith("src/"))return"src";const n=s.split("/").filter(Boolean);return n.length>1?n[0]??".":"."}function d(t){const s=new Set([i(t.cwd,t.tsconfig),i(t.cwd,"package.json")]),n=i(t.cwd,t.entry.split(o.sep).join("/")),r=n.includes("/")?n.slice(0,n.indexOf("/")):n;return r&&s.add(r),[...s]}function w(t){return[...new Set([i(t.cwd,t.tsconfig),i(t.cwd,"package.json"),i(t.cwd,"src"),i(t.cwd,"app"),i(t.cwd,"public"),i(t.cwd,"next.config.js"),i(t.cwd,"next.config.mjs"),i(t.cwd,"next.config.ts")])]}function i(t,s){const n=(t||"").split(o.sep).join("/").replace(/^\.\/+/,"").replace(/\/+$/g,""),r=s.split(o.sep).join("/").replace(/^\.\/+/,"");return!n||n==="."?r:`${n}/${r}`.replace(/\/+/g,"/")}function m(t){return t!==null&&typeof t=="object"}

package/dist/steps/configured-step-testkit-modules.d.ts

@@ -0,0 +1,19 @@
+/** Public Testkit modules safe to bundle into Node-hosted lifecycle steps. */
+export declare const CONFIGURED_STEP_TESTKIT_MODULE_SPECIFIERS: readonly ["@gfdelarue/testkit", "@gfdelarue/testkit/config", "@gfdelarue/testkit/config/build-assets", "@gfdelarue/testkit/config/database-steps", "@gfdelarue/testkit/config/next-runtime-tsconfig", "@gfdelarue/testkit/drizzle", "@gfdelarue/testkit/env", "@gfdelarue/testkit/tooling/vitest"];
+export type ConfiguredStepTestkitModuleSpecifier = (typeof CONFIGURED_STEP_TESTKIT_MODULE_SPECIFIERS)[number];
+/**
+ * Where each configured-step module lives under dist/, as extensionless path
+ * segments. Runtime entry points append ".js"; type lookups append ".d.ts".
+ */
+export declare const CONFIGURED_STEP_TESTKIT_MODULE_DIST_PATHS: {
+    readonly "@gfdelarue/testkit": readonly ["index"];
+    readonly "@gfdelarue/testkit/config": readonly ["config", "authoring", "index"];
+    readonly "@gfdelarue/testkit/config/build-assets": readonly ["config", "runtime", "build-assets"];
+    readonly "@gfdelarue/testkit/config/database-steps": readonly ["database", "steps"];
+    readonly "@gfdelarue/testkit/config/next-runtime-tsconfig": readonly ["config", "runtime", "next-runtime-tsconfig"];
+    readonly "@gfdelarue/testkit/drizzle": readonly ["database", "drizzle", "index"];
+    readonly "@gfdelarue/testkit/env": readonly ["config", "runtime", "env", "index"];
+    readonly "@gfdelarue/testkit/tooling/vitest": readonly ["toolchains", "vitest", "index"];
+};
+export declare function isTestkitPackageSpecifier(specifier: string): boolean;
+export declare function requireConfiguredStepTestkitModuleSpecifier(specifier: string): ConfiguredStepTestkitModuleSpecifier;

package/dist/steps/configured-step-testkit-modules.js

@@ -0,0 +1 @@
+export const CONFIGURED_STEP_TESTKIT_MODULE_SPECIFIERS=["@gfdelarue/testkit","@gfdelarue/testkit/config","@gfdelarue/testkit/config/build-assets","@gfdelarue/testkit/config/database-steps","@gfdelarue/testkit/config/next-runtime-tsconfig","@gfdelarue/testkit/drizzle","@gfdelarue/testkit/env","@gfdelarue/testkit/tooling/vitest"];const n=new Set(["@gfdelarue/testkit/k6","@gfdelarue/testkit/node-vitest/contract","@gfdelarue/testkit/node-vitest/data","@gfdelarue/testkit/playwright"]);export const CONFIGURED_STEP_TESTKIT_MODULE_DIST_PATHS={"@gfdelarue/testkit":["index"],"@gfdelarue/testkit/config":["config","authoring","index"],"@gfdelarue/testkit/config/build-assets":["config","runtime","build-assets"],"@gfdelarue/testkit/config/database-steps":["database","steps"],"@gfdelarue/testkit/config/next-runtime-tsconfig":["config","runtime","next-runtime-tsconfig"],"@gfdelarue/testkit/drizzle":["database","drizzle","index"],"@gfdelarue/testkit/env":["config","runtime","env","index"],"@gfdelarue/testkit/tooling/vitest":["toolchains","vitest","index"]};export function isTestkitPackageSpecifier(t){return t==="@gfdelarue/testkit"||t.startsWith("@gfdelarue/testkit/")}export function requireConfiguredStepTestkitModuleSpecifier(t){if(n.has(t))throw new Error(`Configured lifecycle modules run in Node and may not import engine authoring module ${JSON.stringify(t)}`);const e=CONFIGURED_STEP_TESTKIT_MODULE_SPECIFIERS.find(i=>i===t);if(!e)throw new Error(`Unsupported configured Testkit module specifier ${JSON.stringify(t)}`);return e}

package/dist/steps/configured-steps.d.ts

@@ -0,0 +1,51 @@
+import type { ConfiguredStepInput } from "../config/authoring/configured-step-contract.js";
+export type { ConfiguredCommandStepInput, ConfiguredModuleStepInput, ConfiguredSqlFileStepInput, ConfiguredStepBaseInput, ConfiguredStepInput, } from "../config/authoring/configured-step-contract.js";
+export type JsonValue = boolean | null | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface NormalizedConfiguredStepBase {
+    args?: JsonValue;
+    cwd?: string | null;
+    inputs: string[];
+}
+export interface NormalizedConfiguredCommandStep extends NormalizedConfiguredStepBase {
+    cmd: string;
+    kind: "command";
+}
+export interface NormalizedConfiguredSqlFileStep extends NormalizedConfiguredStepBase {
+    kind: "sql-file";
+    path: string;
+}
+export interface NormalizedConfiguredModuleStep extends NormalizedConfiguredStepBase {
+    kind: "module";
+    specifier: string;
+}
+export type NormalizedConfiguredStep = NormalizedConfiguredCommandStep | NormalizedConfiguredSqlFileStep | NormalizedConfiguredModuleStep;
+export type ConfiguredStepReference = ConfiguredStepInput | NormalizedConfiguredStep;
+export interface ConfiguredStepCollection {
+    inputs?: readonly string[];
+    steps?: readonly ConfiguredStepReference[];
+}
+export interface ConfiguredStepCollectionValidation extends ConfiguredStepCollection {
+    label: string;
+    productDir: string;
+}
+export type ConfiguredStringTransform = (value: string) => string;
+export declare function normalizeOptionalString(value: unknown): string | null;
+export declare function normalizeConfiguredInputs(value: unknown, label: string): string[];
+export declare function normalizeConfiguredSteps(value: unknown, label: string): NormalizedConfiguredStep[];
+export declare function normalizeConfiguredStep(step: unknown, label: string): NormalizedConfiguredStep;
+export declare function parseModuleSpecifier(specifier: unknown): {
+    exportName: string;
+    modulePath: string;
+};
+export declare function normalizeStepArgs(value: unknown, label: string): JsonValue | undefined;
+export declare function isBareModuleSpecifier(modulePath: unknown): boolean;
+export declare function resolveConfiguredCwd(productDir: string, stepCwd: string | null | undefined): string;
+export declare function resolveConfiguredPath(productDir: string, stepCwd: string | null | undefined, targetPath: string): string;
+export declare function collectConfiguredInputs(productDir: string, { inputs, steps }?: ConfiguredStepCollection): string[];
+export declare function summarizeConfiguredStep(step: NormalizedConfiguredStep): string;
+export declare function finalizeConfiguredInputs(inputs: readonly string[] | undefined, transform: ConfiguredStringTransform): string[];
+export declare function finalizeConfiguredStep(step: NormalizedConfiguredStep, transform: ConfiguredStringTransform): NormalizedConfiguredStep;
+export declare function finalizeConfiguredSteps(steps: readonly NormalizedConfiguredStep[] | undefined, transform: ConfiguredStringTransform): NormalizedConfiguredStep[];
+export declare function validateConfiguredCollection({ productDir, label, inputs, steps, }: ConfiguredStepCollectionValidation): void;

package/dist/steps/configured-steps.js

@@ -0,0 +1 @@
+import c from"fs";import s from"path";import{isTestkitPackageSpecifier as m,requireConfiguredStepTestkitModuleSpecifier as w}from"./configured-step-testkit-modules.js";export function normalizeOptionalString(n){if(typeof n!="string")return null;const r=n.trim();return r.length>0?r:null}export function normalizeConfiguredInputs(n,r){if(n==null)return[];if(!g(n))throw new Error(`${r}.inputs must be an array`);return n.map((t,e)=>{const i=normalizeOptionalString(t);if(!i)throw new Error(`${r}.inputs[${String(e)}] must be a non-empty string`);return i})}export function normalizeConfiguredSteps(n,r){if(n==null)return[];if(!g(n))throw new Error(`${r} must be an array`);return n.map((t,e)=>normalizeConfiguredStep(t,`${r}[${String(e)}]`))}export function normalizeConfiguredStep(n,r){if(!p(n))throw new Error(`${r} must be an object`);const t=normalizeOptionalString(n.kind);if(t==="command"){const e=normalizeOptionalString(n.run);if(!e)throw new Error(`${r}.run must be a non-empty string`);const i=normalizeStepArgs(n.args,r);return{kind:t,cmd:e,cwd:normalizeOptionalString(n.cwd),inputs:normalizeConfiguredInputs(n.inputs,r),...i!==void 0?{args:i}:{}}}if(t==="sql-file"){const e=normalizeOptionalString(n.path);if(!e)throw new Error(`${r}.path must be a non-empty string`);const i=normalizeStepArgs(n.args,r);return{kind:t,path:e,cwd:normalizeOptionalString(n.cwd),inputs:normalizeConfiguredInputs(n.inputs,r),...i!==void 0?{args:i}:{}}}if(t==="module"){const e=normalizeOptionalString(n.target);if(!e)throw new Error(`${r}.target must be a non-empty string`);const i=normalizeStepArgs(n.args,r);return{kind:t,specifier:e,cwd:normalizeOptionalString(n.cwd),inputs:normalizeConfiguredInputs(n.inputs,r),...i!==void 0?{args:i}:{}}}throw new Error(`${r}.kind must be one of: command, sql-file, module`)}export function parseModuleSpecifier(n){const[r="",t]=String(n).split("#",2);return{modulePath:r,exportName:t||"default"}}export function normalizeStepArgs(n,r){if(n!=null)try{const t=JSON.stringify(n);if(typeof t!="string")throw new Error("JSON serialization returned undefined");return JSON.parse(t)}catch{throw new Error(`${r}.args must be JSON-serializable`)}}export function isBareModuleSpecifier(n){return typeof n!="string"||n.length===0||n.startsWith("./")||n.startsWith("../")?!1:!s.isAbsolute(n)}export function resolveConfiguredCwd(n,r){return s.resolve(n,r||".")}export function resolveConfiguredPath(n,r,t){return s.resolve(resolveConfiguredCwd(n,r),t)}export function collectConfiguredInputs(n,{inputs:r=[],steps:t=[]}={}){const e=new Set;for(const i of r)e.add(resolveConfiguredPath(n,null,i));for(const i of t){if(i.kind==="sql-file"&&e.add(resolveConfiguredPath(n,i.cwd,i.path)),i.kind==="module"){const f=a(i),{modulePath:o}=parseModuleSpecifier(f),u=resolveConfiguredPath(n,i.cwd,o);o.startsWith("@gfdelarue/testkit")||c.existsSync(u)?o.startsWith("@gfdelarue/testkit")||e.add(u):isBareModuleSpecifier(o)||e.add(u)}for(const f of i.inputs||[])e.add(resolveConfiguredPath(n,i.cwd,f))}return[...e].sort()}export function summarizeConfiguredStep(n){return n.kind==="command"?`command: ${n.cmd.trim()}`:n.kind==="sql-file"?`sql: ${n.path}`:`module: ${n.specifier}`}export function finalizeConfiguredInputs(n=[],r){return n.map(t=>r(t))}export function finalizeConfiguredStep(n,r){return n.kind==="command"?{...n,cmd:r(n.cmd),...typeof n.cwd=="string"?{cwd:r(n.cwd)}:{},inputs:finalizeConfiguredInputs(n.inputs,r),...n.args!==void 0?{args:n.args}:{}}:n.kind==="sql-file"?{...n,path:r(n.path),...typeof n.cwd=="string"?{cwd:r(n.cwd)}:{},inputs:finalizeConfiguredInputs(n.inputs,r),...n.args!==void 0?{args:n.args}:{}}:{...n,specifier:r(n.specifier),...typeof n.cwd=="string"?{cwd:r(n.cwd)}:{},inputs:finalizeConfiguredInputs(n.inputs,r),...n.args!==void 0?{args:n.args}:{}}}export function finalizeConfiguredSteps(n=[],r){return n.map(t=>finalizeConfiguredStep(t,r))}export function validateConfiguredCollection({productDir:n,label:r,inputs:t=[],steps:e=[]}){for(const i of t)d(resolveConfiguredPath(n,null,i),`${r} input`);for(const i of e){if(i.cwd&&d(resolveConfiguredCwd(n,i.cwd),`${r} step cwd`),i.kind==="sql-file"&&d(resolveConfiguredPath(n,i.cwd,i.path),`${r} sql file`),i.kind==="module"){const f=a(i),{modulePath:o}=parseModuleSpecifier(f),u=resolveConfiguredPath(n,i.cwd,o);m(o)?w(o):c.existsSync(u)?d(u,`${r} module`):isBareModuleSpecifier(o)||d(u,`${r} module`)}for(const f of i.inputs||[])d(resolveConfiguredPath(n,i.cwd,f),`${r} step input`)}}function d(n,r){if(!c.existsSync(n))throw new Error(`${r} does not exist: ${n}`)}function a(n){const r="specifier"in n?n.specifier:void 0,t="target"in n?n.target:void 0;return r||t}function p(n){return n!==null&&typeof n=="object"}function g(n){return Array.isArray(n)}

package/dist/steps/environment.d.ts

@@ -0,0 +1,78 @@
+type RuntimeIdentifier = number | string;
+export type RuntimeUrlMapping = readonly [false | null | string | undefined, string];
+type StringMap = ReadonlyMap<string, string>;
+export interface ExecutionEnvironmentLease {
+    leaseDir?: null | string;
+    leaseId?: null | RuntimeIdentifier;
+}
+export interface BuildExecutionEnvironmentOptions {
+    includeTestkitControls?: boolean;
+    inheritProcessEnv?: boolean;
+    mode?: string;
+    omitRuntimeDatabaseBindings?: boolean;
+}
+export interface DatabaseTemplateBindings {
+    database: string;
+    host: string;
+    password: string;
+    port: number | string;
+    sslMode: string;
+    url: string;
+    user: string;
+}
+export type DatabaseTemplateBindingsReader = (stateDir: string) => DatabaseTemplateBindings | null;
+export interface ExecutionTemplateContextValues {
+    [key: string]: unknown;
+    baseUrlByService?: StringMap;
+    databaseBindingsByService?: ReadonlyMap<string, Readonly<DatabaseTemplateBindings> | null>;
+    databaseBindingsReader?: DatabaseTemplateBindingsReader;
+    leaseDir?: null | string;
+    leaseId?: null | RuntimeIdentifier;
+    portMap?: ReadonlyMap<string, number>;
+    prepareDir?: null | string;
+    privateBaseUrlByService?: StringMap;
+    productDir?: null | string;
+    publicBaseUrlByService?: StringMap;
+    publicHost?: null | string;
+    readyUrlByService?: StringMap;
+    runtimeDir?: string;
+    runtimeId?: null | RuntimeIdentifier;
+    runtimeLabel?: null | RuntimeIdentifier;
+    serviceContextUrlByService?: StringMap;
+    serviceCwd?: null | string;
+    serviceName?: string;
+    serviceStateDir?: null | string;
+    stateDirByService?: StringMap;
+    urlMappings?: readonly RuntimeUrlMapping[];
+}
+export interface ExecutionEnvironmentLocalConfig {
+    env?: Readonly<Record<string, string>>;
+}
+export interface ExecutionEnvironmentTestkitConfig {
+    local?: ExecutionEnvironmentLocalConfig | null;
+    mode?: string;
+    prepareDir?: null | string;
+    serviceEnv?: Readonly<Record<string, string>>;
+    templateContext?: ExecutionTemplateContextValues;
+    ui?: unknown;
+}
+export interface ExecutionEnvironmentConfig {
+    name: string;
+    productDir: string;
+    runtimeId?: null | RuntimeIdentifier;
+    runtimeLabel?: null | RuntimeIdentifier;
+    stateDir?: null | string;
+    testkit: ExecutionEnvironmentTestkitConfig;
+}
+export interface TemplateResolutionContext extends ExecutionTemplateContextValues {
+    serviceName: string;
+}
+export declare function buildExecutionEnv(config: Readonly<ExecutionEnvironmentConfig>, extraEnv?: Readonly<NodeJS.ProcessEnv> | null, processEnv?: Readonly<NodeJS.ProcessEnv> | null, options?: Readonly<BuildExecutionEnvironmentOptions>): NodeJS.ProcessEnv;
+export declare function buildTemplateExecutionEnv(config: Readonly<ExecutionEnvironmentConfig>, extraEnv?: Readonly<NodeJS.ProcessEnv> | null, processEnv?: Readonly<NodeJS.ProcessEnv> | null, options?: Readonly<BuildExecutionEnvironmentOptions>): NodeJS.ProcessEnv;
+export declare function buildTaskExecutionEnv(config: Readonly<ExecutionEnvironmentConfig>, lease: Readonly<ExecutionEnvironmentLease> | null, extraEnv?: Readonly<NodeJS.ProcessEnv> | null, processEnv?: Readonly<NodeJS.ProcessEnv> | null, options?: Readonly<BuildExecutionEnvironmentOptions>): NodeJS.ProcessEnv;
+export declare function buildTemplateContext(config: Readonly<ExecutionEnvironmentConfig>, lease: Readonly<ExecutionEnvironmentLease> | null): TemplateResolutionContext;
+export declare function finalizeString(value: string, context: TemplateResolutionContext): string;
+export declare function finalizeSerializable(value: unknown, context: TemplateResolutionContext): unknown;
+export declare function resolveTemplateString(value: string, context: TemplateResolutionContext): string;
+export declare function resolveTemplateString(value: unknown, context: TemplateResolutionContext): unknown;
+export {};

package/dist/steps/environment.js

@@ -0,0 +1 @@
+import u from"path";import{joinPathList as m,packageBinPath as b,shellQuote as f}from"../process/host/platform.js";export function buildExecutionEnv(r,e={},t=process.env,a={}){return o(r,null,e,t,a)}export function buildTemplateExecutionEnv(r,e={},t=process.env,a={}){return o(r,null,e,t,{...a,omitRuntimeDatabaseBindings:!0})}export function buildTaskExecutionEnv(r,e,t={},a=process.env,s={}){return o(r,e,t,a,s)}function o(r,e,t,a,s={}){const i=s.inheritProcessEnv===!1?{}:{...a};delete i.DATABASE_URL;const n=buildTemplateContext(r,e),p=s.omitRuntimeDatabaseBindings?d(r.testkit.serviceEnv||{}):r.testkit.serviceEnv||{},v=s.omitRuntimeDatabaseBindings?d(r.testkit.local?.env||{}):r.testkit.local?.env||{};return{...i,...c(p,n),...c(v,n),...c(t,n),...s.includeTestkitControls===!1?{}:{TESTKIT_ACTIVE:"1",TESTKIT_MODE:s.mode||r.testkit.mode||"test",...r.runtimeId?{TESTKIT_RUNTIME_ID:String(r.runtimeId)}:{},...e?.leaseId?{TESTKIT_LEASE_ID:String(e.leaseId)}:{},...e?.leaseDir?{TESTKIT_LEASE_DIR:e.leaseDir}:{}}}}export function buildTemplateContext(r,e){const t=r.testkit.templateContext||{};return{...t,runtimeId:r.runtimeId||t.runtimeId||null,runtimeLabel:r.runtimeLabel||t.runtimeLabel||null,productDir:r.productDir||t.productDir||null,serviceName:r.name,serviceStateDir:r.stateDir||t.serviceStateDir||null,prepareDir:r.testkit.prepareDir||t.prepareDir||null,leaseId:e?.leaseId||null,leaseDir:e?.leaseDir||null}}export function finalizeString(r,e){let t=resolveTemplateString(r,e);for(const[a,s]of e.urlMappings||[])a&&s&&a!==s&&(t=t.split(a).join(s));return t}export function finalizeSerializable(r,e){return typeof r=="string"?finalizeString(r,e):Array.isArray(r)?r.map(t=>finalizeSerializable(t,e)):r===null||typeof r!="object"?r:Object.fromEntries(Object.entries(r).map(([t,a])=>[t,finalizeSerializable(a,e)]))}export function resolveTemplateString(r,e){return typeof r!="string"?r:r.replace(/\{([a-zA-Z]+)(?::([^}]+))?\}/g,(t,a,s)=>{switch(a){case"runtime":case"runtimeId":return String(e.runtimeId);case"service":return e.serviceName;case"stateDir":return String(e.serviceStateDir);case"productDir":return e.productDir||"";case"bin":{const i=u.resolve(e.productDir||process.cwd(),e.serviceCwd||".");return f(b(i,s))}case"pathList":{const i=l(s||"").split(",").map(n=>n.trim()).filter(Boolean).map(n=>u.resolve(e.productDir||process.cwd(),n));return m(i)}case"prepareDir":return e.prepareDir||"";case"lease":return e.leaseId?String(e.leaseId):"";case"leaseDir":return e.leaseDir||"";case"port":{const i=s||e.serviceName,n=e.portMap?.get(i);if(!n)throw new Error(`Unknown port placeholder for service "${i}"`);return String(n)}case"baseUrl":{const i=s||e.serviceName,n=e.baseUrlByService?.get(i);if(!n)throw new Error(`Unknown baseUrl placeholder for service "${i}"`);return n}case"readyUrl":{const i=s||e.serviceName,n=e.readyUrlByService?.get(i);if(!n)throw new Error(`Unknown readyUrl placeholder for service "${i}"`);return n}case"publicHost":return e.publicHost||"127.0.0.1";case"publicBaseUrl":{const i=s||e.serviceName,n=e.publicBaseUrlByService?.get(i)||e.baseUrlByService?.get(i);if(!n)throw new Error(`Unknown publicBaseUrl placeholder for service "${i}"`);return n}case"privateBaseUrl":{const i=s||e.serviceName,n=e.privateBaseUrlByService?.get(i)||e.baseUrlByService?.get(i);if(!n)throw new Error(`Unknown privateBaseUrl placeholder for service "${i}"`);return n}case"serviceContextUrl":{const i=s||e.serviceName,n=e.serviceContextUrlByService?.get(i)||e.baseUrlByService?.get(i);if(!n)throw new Error(`Unknown serviceContextUrl placeholder for service "${i}"`);return n}case"dbUrl":case"dbHost":case"dbPort":case"dbName":case"dbUser":case"dbPassword":case"dbSsl":{const i=s||e.serviceName;return E(a,i,e)}default:throw new Error(`Unsupported template token "{${a}${s?`:${s}`:""}}"`)}})}function c(r,e){return Object.fromEntries(Object.entries(r||{}).map(([t,a])=>[t,typeof a=="string"?finalizeString(a,e):a]))}function d(r={}){return Object.fromEntries(Object.entries(r).filter(e=>{const t=e[1];return typeof t!="string"?!0:!/\{db(?:Url|Host|Port|Name|User|Password|Ssl)(?::[^}]+)?\}/.test(t)}))}function E(r,e,t){const a=t.stateDirByService?.get(e),s=t.databaseBindingsByService?t.databaseBindingsByService.get(e):a?t.databaseBindingsReader?.(a):null;if(!s)throw new Error(`Unknown database placeholder for service "${e}"`);switch(r){case"dbUrl":return s.url;case"dbHost":return s.host;case"dbPort":return String(s.port);case"dbName":return s.database;case"dbUser":return s.user;case"dbPassword":return s.password;case"dbSsl":return w(s)}}function w(r){const e=r.sslMode,t=l(e||"").trim();return t&&!U(t)?t:S(r.sslMode)?"1":"0"}function S(r){const e=l(r||"").trim().toLowerCase();return!!(e&&!["0","false","no","off","disable","disabled"].includes(e))}function U(r){return["0","1","true","false","yes","no","on","off","disable","disabled","require","verify-ca","verify-full"].includes(l(r||"").trim().toLowerCase())}function l(r){const e=Reflect.apply(String,void 0,[r]);if(typeof e!="string")throw new Error("String conversion returned an invalid result");return e}

package/dist/steps/index.d.ts

@@ -0,0 +1,2 @@
+export { buildExecutionEnv, buildTaskExecutionEnv, buildTemplateContext, buildTemplateExecutionEnv, finalizeSerializable, finalizeString, resolveTemplateString, type BuildExecutionEnvironmentOptions, type DatabaseTemplateBindings, type DatabaseTemplateBindingsReader, type ExecutionEnvironmentConfig, type ExecutionEnvironmentLease, type ExecutionEnvironmentLocalConfig, type ExecutionEnvironmentTestkitConfig, type ExecutionTemplateContextValues, type RuntimeUrlMapping, type TemplateResolutionContext, } from "./environment.js";
+export { collectConfiguredInputs, configuredCommandInvocation, parseModuleSpecifier, resolveConfiguredCwd, resolveConfiguredPath, type ConfiguredCommandInvocation, type ConfiguredStepReporter, type ConfiguredStepServiceConfig, } from "./run.js";

package/dist/steps/index.js

@@ -0,0 +1 @@
+export{buildExecutionEnv,buildTaskExecutionEnv,buildTemplateContext,buildTemplateExecutionEnv,finalizeSerializable,finalizeString,resolveTemplateString}from"./environment.js";export{collectConfiguredInputs,configuredCommandInvocation,parseModuleSpecifier,resolveConfiguredCwd,resolveConfiguredPath}from"./run.js";

package/dist/steps/module-runner.d.ts

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

package/dist/steps/module-runner.js

@@ -0,0 +1 @@
+import c from"fs";import{pathToFileURL as f}from"url";import{errorDetail as p}from"../kernel/error-serialization.js";const[,,r,o,i]=process.argv;(!r||!o||!i)&&(console.error("Usage: node module-runner.js <module-file> <export-name> <context-file>"),process.exit(1));try{const e=JSON.parse(c.readFileSync(i,"utf8")),t=await import(f(r).href),n=s(t,o);if(!a(n))throw new Error(`Template module step "${r}#${o}" did not export a function named "${o}"`);await n(e)}catch(e){console.error(p(e)),process.exit(1)}function s(e,t){if(!(typeof e!="object"||e===null))return Reflect.get(e,t)}function a(e){return typeof e=="function"}

package/dist/steps/run.d.ts

@@ -0,0 +1,36 @@
+import { type CaptureStepOutputOptions } from "../evidence/step-output.js";
+import { type NormalizedConfiguredStep } from "./configured-steps.js";
+export { collectConfiguredInputs, parseModuleSpecifier, resolveConfiguredCwd, resolveConfiguredPath, } from "./configured-steps.js";
+import { type ResolvedNodeToolchain, type ToolchainEnvironment, type ToolchainReportConfig, type ToolchainResolvedReporter, type ToolchainRuntimeConfig } from "../toolchains/index.js";
+import type { SetupOperationHandle } from "../evidence/setup-progress.js";
+import type { OwnedPostgresContainerRoute } from "../domain/postgres-route.js";
+import { type OutputLineHandler } from "../process/index.js";
+type RuntimeIdentifier = number | string;
+export interface ConfiguredStepServiceConfig extends ToolchainRuntimeConfig, ToolchainReportConfig {
+    runtimeId?: RuntimeIdentifier | null;
+    stateDir?: string | null;
+    testkit: NonNullable<ToolchainRuntimeConfig["testkit"]> & {
+        prepareDir?: string | null;
+    };
+}
+export interface ConfiguredStepReporter extends ToolchainResolvedReporter<ConfiguredStepServiceConfig> {
+    outputMode?: string;
+    phaseStarted?: (label: string) => unknown;
+    setupOperationFinished?: (operation: SetupOperationHandle) => unknown;
+    writeDebugLine?: OutputLineHandler;
+}
+export interface ConfiguredCommandInvocation {
+    readonly args: readonly string[];
+    readonly command: string;
+    readonly windowsVerbatimArguments?: boolean;
+}
+interface RunConfiguredStepOptions extends CaptureStepOutputOptions {
+    ownedContainer?: OwnedPostgresContainerRoute | null;
+    signal?: AbortSignal;
+    timeoutMs: number;
+}
+export declare function runConfiguredStep(config: ConfiguredStepServiceConfig, step: Exclude<NormalizedConfiguredStep, {
+    kind: "sql-file";
+}>, runtimeEnv: Readonly<ToolchainEnvironment>, resolvedToolchain: ResolvedNodeToolchain | null, options: Readonly<RunConfiguredStepOptions>): Promise<void>;
+export declare function configuredCommandInvocation(command: string, env: Readonly<NodeJS.ProcessEnv>, platform?: NodeJS.Platform): ConfiguredCommandInvocation;
+export declare function applySetupNodeOptions(env?: Readonly<ToolchainEnvironment>): ToolchainEnvironment;

package/dist/steps/run.js

@@ -0,0 +1,3 @@
+import{formatCapturedFailure as g,writeCapturedLine as S}from"../evidence/step-output.js";import w from"crypto";import m from"fs";import{createRequire as M}from"module";import u from"path";import{fileURLToPath as x}from"url";import"../config/runtime/build-assets.js";import{buildWithEsbuildRetry as D}from"../toolchains/esbuild.js";import{isBareModuleSpecifier as k,parseModuleSpecifier as f,resolveConfiguredCwd as C,resolveConfiguredPath as N}from"./configured-steps.js";import{CONFIGURED_STEP_TESTKIT_MODULE_DIST_PATHS as j,isTestkitPackageSpecifier as I,requireConfiguredStepTestkitModuleSpecifier as U}from"./configured-step-testkit-modules.js";export{collectConfiguredInputs,parseModuleSpecifier,resolveConfiguredCwd,resolveConfiguredPath}from"./configured-steps.js";import"../toolchains/index.js";import{resolvePosixCommandShell as L}from"../process/index.js";import{captureOutput as b,managedHostProcessInfrastructureError as R,startManagedHostProcess as h}from"../process/index.js";const y=String,E=u.resolve(u.dirname(x(import.meta.url)),"..",".."),$=Object.fromEntries(Object.entries(j).map(([e,t])=>[e,u.join(E,"dist",...t)+".js"])),A=u.join(E,"dist","steps","module-runner.js");export async function runConfiguredStep(e,t,r,o,n){const i=C(e.productDir,t.cwd);if(t.kind==="command"){const s=configuredCommandInvocation(t.cmd,r),d=h({args:s.args,cwd:i,displayLabel:`Configured step ${e.name}`,env:r,executable:s.command,windowsVerbatimArguments:s.windowsVerbatimArguments,outputMode:"caller-drained",signal:n.signal,timeoutMs:n.timeoutMs});await T(d,n);return}if(!H(t))return B(t);const{exportName:c}=f(t.specifier),a={args:t.args??{},databaseUrl:r.DATABASE_URL||null,productDir:e.productDir,cwd:i,serviceName:e.name,env:{...r},ownedContainer:n.ownedContainer||null,runtimeId:e.runtimeId||null,stateDir:e.stateDir,prepareDir:e.testkit.prepareDir||null},p=await F(e.productDir,t),l=`${p.outputFile}.${String(process.pid)}.${w.randomUUID()}.context.json`;m.writeFileSync(l,JSON.stringify(a));try{const s=h({args:[A,p.outputFile,c,l],cwd:i,displayLabel:`Configured module step ${e.name}`,env:r,executable:o?.nodeExecutable||process.execPath,outputMode:"caller-drained",signal:n.signal,timeoutMs:n.timeoutMs});await T(s,n)}finally{m.rmSync(l,{force:!0})}}export function configuredCommandInvocation(e,t,r=process.platform){return r==="win32"?{command:t.ComSpec?.trim()||"cmd.exe",args:["/d","/s","/c",`"${e}"`],windowsVerbatimArguments:!0}:{command:L(t),args:["-lc",e]}}export function applySetupNodeOptions(e={}){const t=y(e.TESTKIT_SETUP_NODE_OPTIONS||"").trim();return t?{...e,NODE_OPTIONS:[e.NODE_OPTIONS,t].filter(Boolean).join(" ")}:e}async function F(e,t){const{modulePath:r}=f(t.specifier),o=K(e,t),n=u.join(e,".testkit","_template-steps");m.mkdirSync(n,{recursive:!0});const i=v(o),c=u.join(n,`${u.basename(r).replace(/\W+/g,"-")}-${i.slice(0,12)}.mjs`);return await D({absWorkingDir:e,bundle:!0,entryPoints:[o],format:"esm",legalComments:"none",outfile:c,platform:"node",sourcemap:"inline",target:"es2020",plugins:[q()]}),{outputFile:c,cacheKey:i}}function K(e,t){const{modulePath:r}=f(t.specifier);if(I(r))return P(r);const o=N(e,t.cwd,r);if(m.existsSync(o)||!k(r))return o;const n=C(e,t.cwd);return M(u.join(n,"__testkit__.cjs")).resolve(r)}function v(e){const t=m.readFileSync(e,"utf8");return w.createHash("sha256").update(e).update("\0").update(t).digest("hex")}function q(){return{name:"testkit-configured-step-modules",setup(e){e.onResolve({filter:/^@gfdelarue\/testkit(?:\/.*)?$/},t=>({namespace:"file",path:P(t.path)}))}}}function P(e){const t=U(e);return $[t]}async function T(e,{livePrefix:t="",liveWriter:r=null,logRecord:o=null}={}){const n=[],i=[],c=[b(O(e.stdout),{livePrefix:t,liveWriter:r,onLine:d=>{n.push(d),S(o,"stdout",d)}}),b(O(e.stderr),{livePrefix:t,liveWriter:r,onLine:d=>{i.push(d),S(o,"stderr",d)}})],a=await e.completion;await Promise.all(c);const p=n.join(`
+`),l=i.join(`
+`),s=R("Configured step",a);if(s)throw new Error(g(s.message,p,l,"Configured step process supervision failed"),{cause:s});if(a.exitCode!==0)throw new Error(g(a.exitSignal?`Configured step terminated by ${a.exitSignal}`:null,p,l,`Step failed with exit code ${String(a.exitCode)}`))}function O(e){return!e||!("read"in e)?null:e}function H(e){return _(e,"kind")==="module"}function B(e){throw new Error(`Unsupported template step kind "${y(_(e,"kind"))}"`)}function _(e,t){if(!((typeof e!="object"||e===null)&&typeof e!="function"))return Reflect.get(e,t)}

package/dist/toolchains/archive.d.ts

@@ -0,0 +1,53 @@
+export declare const ARCHIVE_FORMATS: readonly ["tar", "tar.gz", "zip"];
+export declare const MAX_ARCHIVE_ENTRIES = 100000;
+export type ArchiveFormat = (typeof ARCHIVE_FORMATS)[number];
+export type ArchiveEntryKind = "directory" | "file" | "symlink";
+export interface ArchiveEntry {
+    readonly kind: ArchiveEntryKind | "forbidden";
+    readonly linkTarget?: string;
+    readonly mode: number;
+    readonly path: string;
+    readonly rawType: string;
+    readonly sizeBytes: number;
+}
+export interface ArchiveInspectionOptions {
+    readonly maxEntries?: number;
+    readonly maxUnpackedSizeBytes?: number;
+    readonly signal?: AbortSignal;
+}
+export interface ArchiveInspector {
+    readonly formats: readonly ArchiveFormat[];
+    inspect(archivePath: string, format: ArchiveFormat, options?: Readonly<ArchiveInspectionOptions>): Promise<readonly ArchiveEntry[]>;
+}
+export interface ArchiveExtractor extends ArchiveInspector {
+    extract(archivePath: string, destination: string, format: ArchiveFormat, options?: Readonly<ArchiveInspectionOptions>): Promise<void>;
+}
+export declare class UnsafeArchiveError extends Error {
+    readonly code = "TESTKIT_ARCHIVE_UNSAFE";
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class TarArchiveInspector implements ArchiveInspector {
+    readonly formats: readonly ["tar", "tar.gz"];
+    inspect(archivePath: string, format: ArchiveFormat, options?: Readonly<ArchiveInspectionOptions>): Promise<readonly ArchiveEntry[]>;
+}
+export declare class ZipArchiveExtractor implements ArchiveExtractor {
+    readonly formats: readonly ["zip"];
+    inspect(archivePath: string, format: ArchiveFormat, options?: Readonly<ArchiveInspectionOptions>): Promise<readonly ArchiveEntry[]>;
+    extract(archivePath: string, destination: string, format: ArchiveFormat, options?: Readonly<ArchiveInspectionOptions>): Promise<void>;
+}
+/**
+ * Validates archive paths and the complete symbolic-link graph independently
+ * of a caller's exact entry and byte counts. Extractors call this before writing
+ * anything so a caller cannot bypass the topology checks by using extract()
+ * directly.
+ */
+export declare function validateArchiveEntryTopology(entries: readonly ArchiveEntry[]): void;
+export declare function assertSafeArchiveEntry(entry: Readonly<ArchiveEntry>): string;
+export declare function normalizeArchivePath(value: string): string;
+export declare function portableCollisionKey(value: string): string;
+export declare function normalizeSymlinkTarget(value: string, linkPath: string): string;
+export declare function assertInstalledSymlinkTarget(linkPath: string, relativeLinkPath: string, realRoot: string): Promise<void>;
+export declare function decodeUtf8(value: Buffer, label: string): string;
+export declare function requireSafeMode(value: number, entryPath: string): number;
+export declare function requireSafeSize(value: number, entryPath: string): number;
+export declare function throwIfAborted(signal?: AbortSignal): void;

package/dist/toolchains/archive.js

@@ -0,0 +1 @@
+import h from"node:fs";import{createRequire as L}from"node:module";import u from"node:path";import{pipeline as _}from"node:stream/promises";import{open as F}from"yauzl";import{isPathWithin as p}from"../process/files/paths.js";export const ARCHIVE_FORMATS=["tar","tar.gz","zip"],MAX_ARCHIVE_ENTRIES=1e5;export class UnsafeArchiveError extends Error{code="TESTKIT_ARCHIVE_UNSAFE";constructor(e,i){super(e,i),this.name="UnsafeArchiveError"}}const I=L(import.meta.url),D=I("tar"),C=new Set(["File","OldFile","ContiguousFile"]),M=new Set(["Directory","GNUDumpDir"]),S=4096,P=255,U=128,W=/[<>:"|?*]/u,Z=/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/iu,N=new TextDecoder("utf-8",{fatal:!0});export class TarArchiveInspector{formats=["tar","tar.gz"];async inspect(e,i,r={}){x(this.formats,i);const n=v(r),o=[],s=h.createReadStream(e),c=new D.Parser({onReadEntry(a){if(r.signal?.aborted){const d=g(r.signal);s.destroy(d),c.abort(d);return}try{n.countEntry();const d=q(a);o.push(d),n.addPayload(d)}catch(d){const f=B(d,"Tar archive processing failed");s.destroy(f),c.abort(f);return}a.resume()},strict:!0});return await j(s,c,r.signal),o}}export class ZipArchiveExtractor{formats=["zip"];async inspect(e,i,r={}){x(this.formats,i);const n=v(r),o=[];return await $(e,r.signal,async(s,c)=>{n.countEntry();const a=await T(c,s,r.signal);o.push(a),n.addPayload(a)}),o}async extract(e,i,r,n={}){x(this.formats,r);const o=v(n,"extraction"),s=u.resolve(i),c=await this.inspect(e,r,n);validateArchiveEntryTopology(c),await Q(s);const a=[];await $(e,n.signal,async(f,y)=>{const l=await T(y,f,n.signal);o.countEntry(),o.addPayload(l);const w=assertSafeArchiveEntry(l),m=u.resolve(s,w);if(!p(s,m))throw new UnsafeArchiveError(`Archive path escapes its destination: ${JSON.stringify(w)}`);if(l.kind==="directory"){await k(s,m),await h.promises.chmod(m,l.mode);return}if(await k(s,u.dirname(m)),l.kind==="symlink"){if(l.linkTarget===void 0)throw new UnsafeArchiveError(`Archive symbolic link ${JSON.stringify(w)} has no target`);a.push({destinationPath:m,entry:{...l,kind:"symlink",linkTarget:l.linkTarget},normalized:w});return}const R=await O(y,f);await _(R,h.createWriteStream(m,{flags:"wx",mode:l.mode}),{signal:n.signal}),await h.promises.chmod(m,l.mode)});for(const f of a)throwIfAborted(n.signal),await k(s,u.dirname(f.destinationPath)),await h.promises.symlink(f.entry.linkTarget,f.destinationPath,V(f.normalized,c));const d=await h.promises.realpath(s);for(const f of a)await assertInstalledSymlinkTarget(f.destinationPath,f.normalized,d);throwIfAborted(n.signal)}}function v(t,e="inspection"){const i=Math.min(t.maxEntries??MAX_ARCHIVE_ENTRIES,MAX_ARCHIVE_ENTRIES),r=t.maxUnpackedSizeBytes??Number.MAX_SAFE_INTEGER,n=e==="extraction"?" during extraction":"";let o=0,s=0;return{countEntry(){if(e==="inspection"?o>=i:o+1>i)throw new UnsafeArchiveError(`Archive exceeds the ${i.toString()} entry limit${n}`);o+=1},addPayload(c){if(!(c.kind!=="file"&&c.kind!=="symlink")&&(s+=c.sizeBytes,s>r))throw new UnsafeArchiveError(`Archive exceeds its configured unpacked byte limit${n}`)}}}async function j(t,e,i){await new Promise((r,n)=>{let o=!1;const s=()=>{const d=g(i);t.destroy(d),e.abort(d)},c=d=>{o||(o=!0,i?.removeEventListener("abort",s),n(d))},a=()=>{o||(o=!0,i?.removeEventListener("abort",s),r())};t.once("error",c),e.once("error",c),e.once("end",a),i?.addEventListener("abort",s,{once:!0}),t.pipe(e)}),throwIfAborted(i)}export function validateArchiveEntryTopology(t){const e=new Map,i=new Map;for(const n of t){const o=assertSafeArchiveEntry(n),s=portableCollisionKey(o),c=i.get(s);if(c!==void 0)throw new UnsafeArchiveError(`Archive contains colliding entries ${JSON.stringify(c)} and ${JSON.stringify(o)}`);i.set(s,o),e.set(o,n)}const r=E(e);for(const[n,o]of e){for(const s of J(n)){const c=e.get(s);if(c?.kind==="symlink")throw new UnsafeArchiveError(`Archive entry ${JSON.stringify(n)} would write through symbolic-link ancestor ${JSON.stringify(s)}`);if(c?.kind==="file")throw new UnsafeArchiveError(`Archive entry ${JSON.stringify(n)} has regular-file ancestor ${JSON.stringify(s)}`)}o.kind==="symlink"&&z(n,e,r)}}export function assertSafeArchiveEntry(t){const e=normalizeArchivePath(t.path);if(t.kind==="forbidden")throw new UnsafeArchiveError(`Archive entry ${JSON.stringify(e)} has forbidden type ${JSON.stringify(t.rawType)}`);if(requireSafeMode(t.mode,e),requireSafeSize(t.sizeBytes,e),t.kind==="directory"&&t.sizeBytes!==0)throw new UnsafeArchiveError(`Archive directory ${JSON.stringify(e)} has non-zero size`);if(t.kind==="symlink"){if(t.linkTarget===void 0)throw new UnsafeArchiveError(`Archive symbolic link ${JSON.stringify(e)} has no target`);const i=normalizeSymlinkTarget(t.linkTarget,e),r=Buffer.byteLength(i,"utf8");if(t.sizeBytes!==r)throw new UnsafeArchiveError(`Archive symbolic link ${JSON.stringify(e)} has inconsistent target size`)}else if(t.linkTarget!==void 0)throw new UnsafeArchiveError(`Archive entry ${JSON.stringify(e)} has unexpected link target data`);return e}export function normalizeArchivePath(t){b(t,"archive path");const e=t.replace(/\/+$/u,"");if(!e||e.includes("\\")||e.startsWith("/")||Buffer.byteLength(e,"utf8")>S||X(e))throw new UnsafeArchiveError(`Archive path is not a portable relative path: ${JSON.stringify(t)}`);const i=e.split("/");if(i.length>U)throw new UnsafeArchiveError(`Archive path has too many segments: ${JSON.stringify(t)}`);for(const r of i)G(r,t);return i.join("/")}function X(t){for(let e=0;e<t.length;e+=1){const i=t.charCodeAt(e);if(i<=31||i===127)return!0}return!1}function q(t){const e=Y(t.type),i=e==="symlink"?t.linkpath:void 0;return{kind:e,...i===void 0?{}:{linkTarget:i},mode:t.mode,path:t.path,rawType:t.type,sizeBytes:e==="symlink"&&i!==void 0?Buffer.byteLength(i,"utf8"):t.size}}function H(t){const e=t.externalFileAttributes>>>16&65535,i=e&61440,r=t.versionMadeBy>>>8,n=t.fileName.endsWith("/")||i===16384||r===0&&(t.externalFileAttributes&16)!==0,o=i===40960,s=i!==0&&i!==16384&&i!==32768&&i!==40960,c=t.isEncrypted()||s?"forbidden":o?"symlink":n?"directory":"file",a=e&511;return{kind:c,mode:a||(n?493:420),path:t.fileName,rawType:t.isEncrypted()?"encrypted":o?"SymbolicLink":s?`mode-${i.toString(8)}`:n?"Directory":"File",sizeBytes:t.uncompressedSize}}async function T(t,e,i){const r=H(e);if(r.kind!=="symlink")return r;if(r.sizeBytes>S)throw new UnsafeArchiveError(`Archive symbolic link ${JSON.stringify(r.path)} exceeds the portable target size limit`);const n=await O(t,e),o=await tt(n,S,i);if(o.byteLength!==r.sizeBytes)throw new UnsafeArchiveError(`Archive symbolic link ${JSON.stringify(r.path)} has inconsistent target size`);return{...r,linkTarget:decodeUtf8(o,`archive symbolic link ${r.path}`),sizeBytes:o.byteLength}}async function $(t,e,i){const r=await K(t);await new Promise((n,o)=>{let s=!1;const c=()=>{s||(s=!0,e?.removeEventListener("abort",d),n())},a=f=>{s||(s=!0,e?.removeEventListener("abort",d),r.close(),o(B(f,"ZIP archive processing failed")))},d=()=>{a(g(e))};if(r.once("error",a),r.once("end",c),r.on("entry",f=>{Promise.resolve(i(f,r)).then(()=>{r.readEntry()},a)}),e?.addEventListener("abort",d,{once:!0}),e?.aborted){d();return}r.readEntry()})}function K(t){return new Promise((e,i)=>{F(t,{autoClose:!0,decodeStrings:!0,lazyEntries:!0,strictFileNames:!0,validateEntrySizes:!0},(r,n)=>{if(r!==null){i(r);return}e(n)})})}function O(t,e){return new Promise((i,r)=>{t.openReadStream(e,(n,o)=>{if(n!==null){r(n);return}i(o)})})}function Y(t){return C.has(t)?"file":M.has(t)?"directory":t==="SymbolicLink"?"symlink":"forbidden"}function G(t,e){if(!t||t==="."||t===".."||t.trim()!==t||t.endsWith(".")||t.normalize("NFC")!==t||Buffer.byteLength(t,"utf8")>P||W.test(t)||Z.test(t))throw new UnsafeArchiveError(`Archive path contains a non-portable segment: ${JSON.stringify(e)}`)}export function portableCollisionKey(t){return t.normalize("NFC").toLowerCase()}export function normalizeSymlinkTarget(t,e){b(t,`symbolic link ${e}`);const i=normalizeArchivePath(t);if(i!==t)throw new UnsafeArchiveError(`Archive symbolic link ${JSON.stringify(e)} has a non-canonical relative target: ${JSON.stringify(t)}`);return A(e,i),i}function J(t){const e=t.split("/"),i=[];for(let r=1;r<e.length;r+=1)i.push(e.slice(0,r).join("/"));return i}function V(t,e){const i=new Map(e.map(r=>[normalizeArchivePath(r.path),r]));return z(t,i,E(i))==="directory"?"dir":"file"}function z(t,e,i=E(e)){const r=e.get(t);if(r?.kind!=="symlink"||r.linkTarget===void 0)throw new UnsafeArchiveError(`Archive symbolic link ${JSON.stringify(t)} has no target`);let n=A(t,normalizeSymlinkTarget(r.linkTarget,t));const o=new Set;for(let s=0;s<=e.size;s+=1){const c=n.split("/");let a=!1;for(let f=0;f<c.length;f+=1){const y=c.slice(0,f+1).join("/"),l=e.get(y);if(l?.kind==="symlink"){if(l.linkTarget===void 0||o.has(y))throw new UnsafeArchiveError(`Archive symbolic link ${JSON.stringify(t)} has a cyclic target`);o.add(y);const w=A(y,normalizeSymlinkTarget(l.linkTarget,y)),m=c.slice(f+1).join("/");n=m?normalizeArchivePath(`${w}/${m}`):w,a=!0;break}if(l?.kind==="file"&&f<c.length-1)throw new UnsafeArchiveError(`Archive symbolic link ${JSON.stringify(t)} traverses regular file ${JSON.stringify(y)}`);if(l===void 0&&!i.has(y))throw new UnsafeArchiveError(`Archive symbolic link ${JSON.stringify(t)} has dangling target ${JSON.stringify(r.linkTarget)}`)}if(a)continue;const d=e.get(n);if(d?.kind==="file")return"file";if(d?.kind==="directory"||i.has(n))return"directory";throw new UnsafeArchiveError(`Archive symbolic link ${JSON.stringify(t)} has dangling target ${JSON.stringify(r.linkTarget)}`)}throw new UnsafeArchiveError(`Archive symbolic link ${JSON.stringify(t)} has a cyclic target`)}function E(t){const e=new Set;for(const[i,r]of t){for(const n of J(i))e.add(n);r.kind==="directory"&&e.add(i)}return e}function A(t,e){if(u.posix.isAbsolute(e))throw new UnsafeArchiveError(`Archive symbolic link ${JSON.stringify(t)} has an absolute target`);const i=u.posix.join(u.posix.dirname(t),e);if(i===".."||i.startsWith("../")||u.posix.isAbsolute(i))throw new UnsafeArchiveError(`Archive symbolic link ${JSON.stringify(t)} escapes the archive root`);return normalizeArchivePath(i)}export async function assertInstalledSymlinkTarget(t,e,i){let r;try{r=await h.promises.realpath(t)}catch(o){throw new UnsafeArchiveError(`Installed archive symbolic link ${JSON.stringify(e)} is dangling or cyclic`,{cause:o})}if(!p(i,r))throw new UnsafeArchiveError(`Installed archive symbolic link ${JSON.stringify(e)} resolves outside its root`);const n=await h.promises.lstat(r);if(!n.isFile()&&!n.isDirectory())throw new UnsafeArchiveError(`Installed archive symbolic link ${JSON.stringify(e)} resolves to a special file`)}async function Q(t){const e=await h.promises.lstat(t);if(!e.isDirectory()||e.isSymbolicLink())throw new UnsafeArchiveError("Archive extraction root must be a real directory");if((await h.promises.readdir(t)).length!==0)throw new UnsafeArchiveError("Archive extraction root must be empty")}async function k(t,e){if(!p(t,e))throw new UnsafeArchiveError(`Archive extraction path escapes its destination: ${JSON.stringify(e)}`);const i=u.relative(t,e);let r=t;for(const n of i.split(u.sep).filter(Boolean)){r=u.join(r,n);try{await h.promises.mkdir(r,{mode:493})}catch(s){if(!et(s,"EEXIST"))throw s}const o=await h.promises.lstat(r);if(!o.isDirectory()||o.isSymbolicLink())throw new UnsafeArchiveError(`Archive refuses to write through non-directory path ${JSON.stringify(r)}`)}}async function tt(t,e,i){const r=[];let n=0;const o=()=>t.destroy(g(i));i?.addEventListener("abort",o,{once:!0});try{for await(const s of t){throwIfAborted(i);const c=Buffer.isBuffer(s)?s:Buffer.from(s);if(n+=c.byteLength,n>e){const a=new UnsafeArchiveError("Archive symbolic-link target exceeds its byte limit");throw t.destroy(a),a}r.push(c)}}finally{i?.removeEventListener("abort",o)}return Buffer.concat(r,n)}export function decodeUtf8(t,e){try{const i=N.decode(t);return b(i,e),i}catch(i){throw i instanceof UnsafeArchiveError?i:new UnsafeArchiveError(`Archive ${e} is not valid UTF-8`,{cause:i})}}function b(t,e){if(t.includes("\uFFFD")||N.decode(Buffer.from(t,"utf8"))!==t)throw new UnsafeArchiveError(`Archive ${e} is not valid canonical UTF-8`)}function et(t,e){return typeof t=="object"&&t!==null&&Reflect.get(t,"code")===e}export function requireSafeMode(t,e){if(!Number.isSafeInteger(t)||t<0||t>4095)throw new UnsafeArchiveError(`Archive entry ${JSON.stringify(e)} has an invalid mode`);return t&511}export function requireSafeSize(t,e){if(!Number.isSafeInteger(t)||t<0)throw new UnsafeArchiveError(`Archive entry ${JSON.stringify(e)} has an invalid size`);return t}function x(t,e){if(!t.includes(e))throw new Error(`Archive format ${e} requires another extractor`)}export function throwIfAborted(t){if(t?.aborted)throw g(t)}function g(t){return t?.reason instanceof Error?t.reason:new Error("Archive operation was aborted")}function B(t,e){return t instanceof Error?t:new Error(e)}

package/dist/toolchains/esbuild.d.ts

@@ -0,0 +1,9 @@
+import { build, type BuildOptions, type BuildResult } from "esbuild";
+export interface EsbuildRetryOptions {
+    attemptTimeoutMs?: unknown;
+    retries?: unknown;
+}
+type EsbuildBuildOptions<T extends BuildOptions> = Parameters<typeof build<T>>[0];
+export declare function buildWithEsbuildRetry<T extends BuildOptions>(options: EsbuildBuildOptions<T>, retryOptions?: EsbuildRetryOptions): Promise<BuildResult<T>>;
+export declare function isEsbuildServiceStoppedError(error: unknown): boolean;
+export {};

package/dist/toolchains/esbuild.js

@@ -0,0 +1 @@
+import{build as c,stop as a}from"esbuild";const m=[/service is no longer running/iu,/service was stopped/iu,/cannot call write after a stream was destroyed/iu],o=3e4,l=String;class u extends Error{constructor(e){super(`The esbuild service operation did not settle within ${e.toString()}ms`),this.name="EsbuildServiceAttemptTimeoutError"}}export async function buildWithEsbuildRetry(t,e={}){const i=p(e.retries??1),r=E(e.attemptTimeoutMs);let s=0;for(;;)try{return await f(()=>c(t),r)}catch(n){if(s>=i||!isEsbuildServiceStoppedError(n))throw n;s+=1;try{await T()}catch{}}}export function isEsbuildServiceStoppedError(t){if(t instanceof u)return!0;const e=d(t);return m.some(i=>i.test(e))}async function f(t,e){let i;const r=new Promise((s,n)=>{i=setTimeout(()=>{n(new u(e))},e)});try{return await Promise.race([Promise.resolve().then(t),r])}finally{i!==void 0&&clearTimeout(i)}}function d(t){const e=typeof t=="object"&&t!==null||typeof t=="function"?Reflect.get(t,"message"):void 0;return l(e||t||"")}function p(t){const e=Number(t);return!Number.isFinite(e)||e<0?0:Math.floor(e)}function E(t){if(t===void 0)return o;const e=Number(t);return!Number.isSafeInteger(e)||e<=0?o:e}async function T(){try{await a()}catch{}await b()}function b(){return new Promise(t=>setTimeout(t,25))}

package/dist/toolchains/host-node-support.d.ts

@@ -0,0 +1,3 @@
+export declare const TESTKIT_SUPPORTED_HOST_NODE_RANGE = ">=22.15.0 <23.0.0 || >=24.14.1 <25.0.0";
+export declare const TESTKIT_SUPPORTED_HOST_NPM_RANGE = ">=11.6.0 <12.0.0";
+export declare function hostNodeIsSupported(version: unknown): boolean;

package/dist/toolchains/host-node-support.js

@@ -0,0 +1 @@
+export const TESTKIT_SUPPORTED_HOST_NODE_RANGE=">=22.15.0 <23.0.0 || >=24.14.1 <25.0.0",TESTKIT_SUPPORTED_HOST_NPM_RANGE=">=11.6.0 <12.0.0";const o=new Map([[22,Object.freeze([22,15,0])],[24,Object.freeze([24,14,1])]]);export function hostNodeIsSupported(r){const n=s(r);if(n===null)return!1;const e=o.get(n[0]);return e===void 0?!1:u(n,e)>=0}function s(r){const n=String(r).split(".");if(n.length!==3)return null;const e=n.map(t=>Number(t));return e.every(t=>Number.isSafeInteger(t)&&t>=0)?[e[0]??0,e[1]??0,e[2]??0]:null}function u(r,n){for(const e of[0,1,2]){if(r[e]>n[e])return 1;if(r[e]<n[e])return-1}return 0}

package/dist/toolchains/index.d.ts

@@ -0,0 +1,114 @@
+import type { NodeToolchainConfig } from "../config/authoring/index.js";
+export interface NormalizedNodeToolchainConfig {
+    cwd: string;
+    detect: "auto" | "off";
+    install: "download" | "require-host";
+    node: string | null;
+    npm: string | null;
+}
+export type NormalizedToolchainRegistry = Readonly<Partial<Record<string, NormalizedNodeToolchainConfig>>>;
+export interface NormalizedRuntimeToolchain extends NormalizedNodeToolchainConfig {
+    refName: string | null;
+    sourceLabel: string;
+}
+export interface ResolvedNodeToolchain {
+    binDir: string;
+    cwd: string;
+    fingerprint: string;
+    install: NormalizedNodeToolchainConfig["install"];
+    nodeExecutable: string;
+    nodeSource: string;
+    nodeSpec: string | null;
+    nodeVersion: string;
+    npmSource: string;
+    npmSpec: string | null;
+    npmVersion: string | null;
+    summary: string;
+    toolchainDir: string;
+}
+export interface RuntimeToolchainResolutionConfig {
+    cwd: string;
+    detect: NormalizedNodeToolchainConfig["detect"];
+    install: NormalizedNodeToolchainConfig["install"];
+    node: string | null;
+    npm: string | null;
+    refName: string | null;
+    sourceLabel: string;
+}
+export interface ToolchainRuntimeConfig {
+    name: string;
+    productDir: string;
+    testkit?: {
+        runtime?: {
+            toolchain?: RuntimeToolchainResolutionConfig | null;
+        } | null;
+    } | null;
+}
+export interface ToolchainReportConfig {
+    name: string;
+    runtimeLabel?: string | null;
+}
+export interface ToolchainResolvedReporter<Config extends ToolchainReportConfig = ToolchainReportConfig> {
+    toolchainResolved?: (config: Config, resolvedToolchain: ResolvedNodeToolchain) => unknown;
+}
+export type ToolchainEnvironment = Record<string, string | undefined>;
+export interface ToolchainDownloadResponse {
+    arrayBuffer: () => PromiseLike<ArrayBuffer>;
+    body?: AsyncIterable<Uint8Array> | null;
+    ok: boolean;
+    status: number;
+}
+export interface ToolchainFetchOptions {
+    signal?: AbortSignal;
+}
+export type ToolchainFetch = (downloadUrl: string, options?: ToolchainFetchOptions) => PromiseLike<ToolchainDownloadResponse>;
+export interface ToolchainCommandOptions {
+    cwd?: string;
+    env?: ToolchainEnvironment;
+    signal?: AbortSignal;
+    stdio?: "pipe";
+    timeoutMs?: number;
+    windowsHide?: boolean;
+}
+export interface ToolchainCommandResult {
+    stdout?: string | Uint8Array | null;
+}
+export interface PreparedManagedToolchainCommand {
+    readonly args: readonly string[];
+    readonly executable: string;
+}
+export type ToolchainCommandExecutor = (command: string, args: string[], options?: ToolchainCommandOptions) => PromiseLike<ToolchainCommandResult>;
+export interface ResolveConfiguredToolchainOptions {
+    commandExecutor?: ToolchainCommandExecutor;
+    fetchImpl?: ToolchainFetch;
+    hostNodeVersion?: string;
+    hostNpmVersion?: string;
+    signal?: AbortSignal;
+}
+export interface ProvisionNodeToolchainOptions {
+    commandExecutor?: ToolchainCommandExecutor;
+    fetchImpl?: ToolchainFetch;
+    productDir: string;
+    signal?: AbortSignal;
+    version: string;
+}
+export interface ProvisionedNodeToolchain {
+    binDir: string;
+    nodeExecutable: string;
+    npmVersion: string | null;
+    toolchainDir: string;
+}
+export declare function nodeToolchain(options?: NodeToolchainConfig): NodeToolchainConfig;
+export declare function normalizeToolchainRegistry(value: unknown): NormalizedToolchainRegistry;
+export declare function normalizeRuntimeToolchain(value: unknown, label: string, registry?: NormalizedToolchainRegistry): NormalizedRuntimeToolchain | null;
+export declare function resolveConfiguredToolchain(config: ToolchainRuntimeConfig | null | undefined, options?: ResolveConfiguredToolchainOptions): Promise<ResolvedNodeToolchain | null>;
+export declare function announceResolvedToolchain<Config extends ToolchainReportConfig>(config: Config, resolvedToolchain: ResolvedNodeToolchain | null, reporter?: ToolchainResolvedReporter<Config> | null): Promise<void>;
+export declare function applyToolchainEnv(baseEnv: Readonly<ToolchainEnvironment>, resolvedToolchain: ResolvedNodeToolchain | null, processEnv?: Readonly<ToolchainEnvironment>): ToolchainEnvironment;
+export declare function provisionNodeToolchain({ productDir, version, fetchImpl, commandExecutor, signal, }: ProvisionNodeToolchainOptions): Promise<ProvisionedNodeToolchain>;
+export declare function fetchToolchain(downloadUrl: string, options?: Readonly<ToolchainFetchOptions>): Promise<ToolchainDownloadResponse>;
+export declare function prepareToolchainCommandForManagedHost(command: string, args: readonly string[], options?: Readonly<{
+    env?: ToolchainEnvironment;
+    hostNodeExecutable?: string;
+    platform?: NodeJS.Platform;
+}>): PreparedManagedToolchainCommand;
+export declare function executeToolchainCommand(command: string, args: string[], options?: ToolchainCommandOptions): Promise<ToolchainCommandResult>;

package/dist/toolchains/index.js

@@ -0,0 +1,4 @@
+import _ from"crypto";import f from"fs";import u from"path";import{prepareCommandForSpawn as I,resolveCommandForSpawn as A}from"../process/host/platform.js";import{normalizeContainedRelativePath as V,resolveContainedPath as D}from"../process/files/contained-path.js";import{deriveSemverMinimum as k,isExactSemver as L,normalizeSemver as p,satisfiesSemver as g}from"./semver.js";import{managedHostProcessInfrastructureError as M,runManagedHostProcess as j}from"../process/index.js";import{managedNodeRelease as H}from"./managed-node-releases.js";import{provisionNodeToolchainWithRelease as R}from"./node-provisioning.js";import{createSharedToolchainOperation as F,waitForSharedToolchainOperation as P}from"./shared-operation.js";import{TOOLCHAIN_METADATA_TIMEOUT_MS as $}from"./timeouts.js";const z=".",W="auto",q="require-host",U=600*1e3,B=['"use strict";','const { spawn } = require("node:child_process");',"const [command, ...args] = process.argv.slice(1);",'if (typeof command !== "string" || command.length === 0) {','  process.stderr.write("Missing Windows toolchain command\\n");',"  process.exitCode = 126;","} else {","  let spawnFailed = false;","  const child = spawn(command, args, {","    shell: false,",'    stdio: "inherit",',"    windowsHide: true,","    windowsVerbatimArguments: true,","  });",'  child.once("error", (error) => {',"    spawnFailed = true;","    process.stderr.write(`${error.stack ?? String(error)}\\n`);","    process.exitCode = 126;","  });",'  child.once("close", (code, signal) => {',"    if (spawnFailed) return;","    if (signal !== null) {","      process.stderr.write(`Windows toolchain command exited on signal ${signal}\\n`);","      process.exitCode = 1;","      return;","    }","    process.exitCode = code ?? 1;","  });","}"].join(`
+`),T=new WeakMap,O=new WeakSet;export function nodeToolchain(n={}){return{...n}}export function normalizeToolchainRegistry(n){if(n==null)return{};if(!N(n))throw new Error("testkit.config.ts toolchains must be an object");const e={};for(const[o,r]of Object.entries(n))e[o]=x(r,`testkit.config.ts toolchains.${o}`);return e}export function normalizeRuntimeToolchain(n,e,o={}){if(n==null)return null;if(typeof n=="string"){const t=n.trim();if(!t)throw new Error(`${e} must reference a non-empty toolchain name`);const i=o[t];if(!i)throw new Error(`${e} references unknown toolchain "${t}"`);return{...i,refName:t,sourceLabel:`${e} -> ${t}`}}return{...x(n,e),refName:null,sourceLabel:e}}export async function resolveConfiguredToolchain(n,e={}){const o=n?.testkit?.runtime?.toolchain;if(!n||!o)return null;let r=T.get(n);if(r===void 0){r=F(i=>J(n,o,{...e,signal:i})),T.set(n,r);const t=r;r.promise.catch(()=>{T.get(n)===t&&T.delete(n)})}return P(r,e.signal)}export function announceResolvedToolchain(n,e,o=null){return!e||O.has(n)||(O.add(n),o?.toolchainResolved&&o.toolchainResolved(n,e)),Promise.resolve()}export function applyToolchainEnv(n,e,o=process.env){if(!e)return{...n};const r={...n,PATH:ne(e.binDir,n.PATH||o.PATH||""),TESTKIT_TOOLCHAIN_KIND:"node",TESTKIT_TOOLCHAIN_NODE_VERSION:e.nodeVersion,TESTKIT_TOOLCHAIN_NODE_SOURCE:e.nodeSource,TESTKIT_TOOLCHAIN_INSTALL_MODE:e.install};return e.npmVersion&&(r.TESTKIT_TOOLCHAIN_NPM_VERSION=e.npmVersion,r.TESTKIT_TOOLCHAIN_NPM_SOURCE=e.npmSource),r}function x(n,e){if(!N(n))throw new Error(`${e} must be an object`);const o=V(d(n.cwd)||z,`${e}.cwd`),r=d(n.detect)||W,t=d(n.install)||q;if(r!=="auto"&&r!=="off")throw new Error(`${e}.detect must be "auto" or "off"`);if(t!=="require-host"&&t!=="download")throw new Error(`${e}.install must be "require-host" or "download"`);return{cwd:o,detect:r,install:t,node:d(n.node),npm:d(n.npm)}}async function J(n,e,o){const r=n.productDir,t=D(r,e.cwd,`${e.sourceLabel}.cwd`),i=K(t),s=e.node||(e.detect==="auto"?i.nodeSpec:null),a=e.node?"toolchain.node":e.detect==="auto"?i.nodeSource??"none":"none",l=e.npm||(e.detect==="auto"?i.npmSpec:null),c=e.npm?"toolchain.npm":e.detect==="auto"?i.npmSource??"none":"none";if(!s&&!l)throw new Error(`Service "${n.name}" enables runtime.toolchain but no Node/npm version could be resolved in ${e.cwd}`);return e.install==="require-host"?G({config:n,cwd:t,nodeSpec:s,nodeSource:a,npmSpec:l,npmSource:c,toolchain:e,options:o}):Q({config:n,cwd:t,nodeSpec:s,nodeSource:a,npmSpec:l,npmSource:c,toolchain:e,options:o})}function K(n){const e=u.join(n,"package.json"),o=Z(e),r=ee(u.join(n,".tool-versions")),t=b(u.join(n,".nvmrc")),i=b(u.join(n,".node-version")),s=d(w(o,"volta","node")),a=d(w(o,"engines","node")),l=d(r.nodejs),c=s||t||i||l||a;let m=null;s?m="package.json#volta.node":t?m=".nvmrc":i?m=".node-version":l?m=".tool-versions#nodejs":a&&(m="package.json#engines.node");const y=d(w(o,"volta","npm")),E=d(w(o,"engines","npm")),v=Y(w(o,"packageManager")),C=y||(v?.name==="npm"?v.version:null)||E;let h=null;return y?h="package.json#volta.npm":v?.name==="npm"?h="package.json#packageManager":E&&(h="package.json#engines.npm"),{nodeSpec:c,nodeSource:m,npmSpec:C,npmSource:h}}async function G({config:n,cwd:e,nodeSpec:o,nodeSource:r,npmSpec:t,npmSource:i,toolchain:s,options:a}){const l=p(a.hostNodeVersion||process.versions.node);if(o&&!g(l,o))throw new Error(`Service "${n.name}" requires Node ${o} (${r}), but host Node is ${l}`);let c=null;if(t&&(c=p(a.hostNpmVersion||await X({command:"npm",args:["--version"],cwd:e,env:process.env,commandExecutor:a.commandExecutor,signal:a.signal})),!g(c,t)))throw new Error(`Service "${n.name}" requires npm ${t} (${i}), but host npm is ${c}`);return{install:s.install,cwd:s.cwd,nodeVersion:l,nodeSource:r,nodeSpec:o,npmVersion:c,npmSource:i,npmSpec:t,nodeExecutable:process.execPath,binDir:u.dirname(process.execPath),toolchainDir:u.dirname(process.execPath),fingerprint:S({install:s.install,nodeVersion:l,npmVersion:c,nodeSource:r,npmSource:i}),summary:`${s.install} node=${l}${c?` npm=${c}`:""} (${r})`}}async function Q({config:n,nodeSpec:e,nodeSource:o,npmSpec:r,npmSource:t,toolchain:i,options:s}){if(!e)throw new Error(`Service "${n.name}" download toolchain mode requires a resolvable Node version`);const a=L(e)?p(e):k(e);if(!a)throw new Error(`Service "${n.name}" cannot deterministically provision Node from "${e}". Provide an exact version in runtime.toolchain.node, .nvmrc, .node-version, .tool-versions, or package.json#volta.node.`);const l=await provisionNodeToolchain({productDir:n.productDir,version:a,fetchImpl:s.fetchImpl||fetchToolchain,commandExecutor:s.commandExecutor||executeToolchainCommand,signal:s.signal});if(!g(a,e))throw new Error(`Service "${n.name}" resolved Node ${a}, which does not satisfy ${e}`);const c=l.npmVersion?p(l.npmVersion):null;if(r&&(!c||!g(c,r)))throw new Error(`Service "${n.name}" requires npm ${r} (${t}), but Node ${a} bundles npm ${c||"unknown"}`);return{install:i.install,cwd:i.cwd,nodeVersion:a,nodeSource:o,nodeSpec:e,npmVersion:c,npmSource:t,npmSpec:r,nodeExecutable:l.nodeExecutable,binDir:l.binDir,toolchainDir:l.toolchainDir,fingerprint:S({install:i.install,nodeVersion:a,npmVersion:c,nodeSource:o,npmSource:t}),summary:`download node=${a}${c?` npm=${c}`:""} (${o})`}}export async function provisionNodeToolchain({productDir:n,version:e,fetchImpl:o=fetchToolchain,commandExecutor:r=executeToolchainCommand,signal:t}){const i=p(e);if(e!==i)throw new Error(`Downloaded Node toolchain version must use canonical x.y.z form; received ${JSON.stringify(e)}`);const s=H(i);return R({commandExecutor:r,fetchImpl:o,productDir:n,release:s,signal:t})}function S(n){return _.createHash("sha256").update(JSON.stringify({kind:"node",...n})).digest("hex")}async function X({command:n,args:e,cwd:o,env:r,commandExecutor:t=executeToolchainCommand,signal:i}){const s=await t(n,e,{cwd:o,env:r,signal:i,stdio:"pipe",timeoutMs:$,windowsHide:!0});return s.stdout==null?"":typeof s.stdout=="string"?s.stdout.trim():Buffer.from(s.stdout).toString().trim()}function Y(n){const e=d(n);if(!e)return null;const o=e.lastIndexOf("@");return o<=0||o===e.length-1?null:{name:e.slice(0,o),version:e.slice(o+1)}}function Z(n){if(!f.existsSync(n))return null;try{return JSON.parse(f.readFileSync(n,"utf8"))}catch{return null}}function b(n){if(!f.existsSync(n))return null;const o=f.readFileSync(n,"utf8").split(/\r?\n/).find(r=>r.trim().length>0);return o?o.trim():null}function ee(n){if(!f.existsSync(n))return{};const e={};for(const o of f.readFileSync(n,"utf8").split(/\r?\n/)){const r=o.trim();if(!r||r.startsWith("#"))continue;const[t,i]=r.split(/\s+/,2);t&&i&&(e[t]=i.trim())}return e}function ne(n,e){const o=d(n);if(!o)return e;const r=(e||"").split(u.delimiter).filter(Boolean).filter(t=>t!==o);return[o,...r].join(u.delimiter)}function d(n){if(typeof n!="string")return null;const e=n.trim();return e.length>0?e:null}export async function fetchToolchain(n,e={}){const o=AbortSignal.timeout(U),r=await fetch(n,{signal:e.signal===void 0?o:AbortSignal.any([e.signal,o])});return{arrayBuffer:()=>r.arrayBuffer(),body:r.body===null?null:oe(r.body),ok:r.ok,status:r.status}}async function*oe(n){const e=n.getReader();let o=!1;try{for(;;){const r=await e.read();if(r.done){o=!0;return}yield r.value}}finally{o||await e.cancel(),e.releaseLock()}}export function prepareToolchainCommandForManagedHost(n,e,o={}){const r={env:o.env||process.env,platform:o.platform},t=A(n,r),i=I(t,e,r);return i.windowsVerbatimArguments?(re(t,e),{executable:o.hostNodeExecutable||process.execPath,args:["--input-type=commonjs","--eval",B,"--",i.command,...i.args]}):{executable:i.command,args:i.args}}function re(n,e){if(/[%!"\0\r\n]/u.test(n))throw new Error(`Windows batch toolchain commands cannot safely preserve command path ${JSON.stringify(n)}`);const o=e.find(r=>/[%!"\0\r\n]/u.test(r)||r.endsWith("\\"));if(o!==void 0)throw new Error(`Windows batch toolchain commands cannot safely preserve argument ${JSON.stringify(o)}`)}export async function executeToolchainCommand(n,e,o={}){const r=te(o.timeoutMs),t=u.resolve(o.cwd||process.cwd()),i=prepareToolchainCommandForManagedHost(n,e,{env:o.env||process.env}),s=await j({args:i.args,cwd:t,displayLabel:`Toolchain command ${n}`,env:o.env||process.env,executable:i.executable,signal:o.signal,timeoutMs:r}),a=M(`Toolchain command ${n}`,s);if(a)throw a;if(s.exitCode!==0)throw new Error(`Toolchain command ${n} exited with code ${String(s.exitCode)}${ie(s.stdout,s.stderr)}`);return{stdout:s.stdout}}function te(n){const e=n??$;if(!Number.isSafeInteger(e)||e<=0)throw new Error("Toolchain command timeout must be a positive safe integer in milliseconds");return e}function ie(n,e){const o=[n,e].map(r=>r.trim()).filter(Boolean).join(`
+`);return o?`
+${o.slice(-4e3)}`:""}function w(n,...e){let o=n;for(const r of e){if(!N(o))return;o=o[r]}return o}function N(n){return n!==null&&typeof n=="object"&&!Array.isArray(n)}