@gfdelarue/testkit 0.3.0

package/dist/process/process-identity.d.ts

@@ -0,0 +1,27 @@
+interface BoundedProcessIdentityQuery {
+    readonly args: readonly string[];
+    readonly environment: Readonly<Record<string, string>>;
+    readonly executable: string;
+    readonly timeoutMs: number;
+    readonly windowsHide: boolean;
+}
+export type ProcessCreationIdentityObservation = "different" | "matches" | "unknown";
+export interface ProcessCreationIdentityObservationOptions {
+    captureIdentity?(pid: number): string | null;
+    inspectLiveness?(pid: number): "absent" | "alive" | "unknown";
+}
+export declare function captureProcessCreationIdentity(pid: unknown): string | null;
+export declare function processCreationIdentityMatches(pid: unknown, expectedIdentity: unknown): boolean;
+export declare function observeProcessCreationIdentity(pid: unknown, expectedIdentity: unknown, options?: Readonly<ProcessCreationIdentityObservationOptions>): ProcessCreationIdentityObservation;
+export declare function parseWindowsProcessCreationIdentity(identity: string): string | null;
+export declare function parseLinuxProcessCreationIdentity(pid: number, stat: string): string;
+/**
+ * Parses the C-locale `ps -o pid=,lstart=` representation used by both the
+ * single-process identity boundary and the bounded Darwin process-table
+ * snapshot. Whitespace is canonicalized so the two producers cannot drift.
+ */
+export declare function parseDarwinProcessCreationIdentity(pid: number, output: string): string;
+export declare function windowsProcessCreationIdentityScript(pid: number): string;
+export declare function runBoundedProcessIdentityQuery(query: Readonly<BoundedProcessIdentityQuery>): string;
+export declare function inspectProcessLiveness(pid: number): "absent" | "alive" | "unknown";
+export {};

package/dist/process/process-identity.js

@@ -0,0 +1 @@
+import{execFileSync as c}from"node:child_process";import a from"node:fs";import{DARWIN_PS_EXECUTABLE as d,HOST_POSIX_INSPECTION_ENVIRONMENT as l,requireWindowsHostPowerShellCommand as f}from"./host-inspection-command.js";import{formatWindowsKernelProcessIdentity as m,parseWindowsKernelProcessIdentity as p}from"./windows-process-identity.js";const w=3e3,I=16*1024,S=8e3;export function captureProcessCreationIdentity(e){const t=Number(e);if(!Number.isSafeInteger(t)||t<=0)return null;try{if(process.platform==="linux")return E(t);if(process.platform==="darwin")return T(t);if(process.platform==="win32")return P(t)}catch{return null}return null}export function processCreationIdentityMatches(e,t){return observeProcessCreationIdentity(e,t)==="matches"}export function observeProcessCreationIdentity(e,t,n={}){const r=Number(e);if(!Number.isSafeInteger(r)||r<=0||typeof t!="string"||t.length===0)return"unknown";const i=(n.captureIdentity??captureProcessCreationIdentity)(r);return i!==null?i===t?"matches":"different":(n.inspectLiveness??inspectProcessLiveness)(r)==="absent"?"different":"unknown"}export function parseWindowsProcessCreationIdentity(e){return p(e)}function E(e){return parseLinuxProcessCreationIdentity(e,a.readFileSync(`/proc/${e.toString()}/stat`,"utf8"))}export function parseLinuxProcessCreationIdentity(e,t){if(!Number.isSafeInteger(e)||e<=0)throw new Error("Linux process stat identity requires a positive pid");const n=t.trim(),r=n.lastIndexOf(")"),i=n.indexOf(" ");if(r<0||i<1||Number(n.slice(0,i))!==e)throw new Error("Linux process stat identity is malformed");const o=n.slice(r+1).trim().split(/\s+/u)[19];if(!/^\d+$/u.test(o))throw new Error("Linux process stat start time is malformed");return`linux-proc-start:${o}`}function T(e){const t=runBoundedProcessIdentityQuery({args:["-p",e.toString(),"-o","pid=,lstart="],environment:l,executable:d,timeoutMs:w,windowsHide:!1});return parseDarwinProcessCreationIdentity(e,t)}export function parseDarwinProcessCreationIdentity(e,t){if(!Number.isSafeInteger(e)||e<=0)throw new Error("Darwin process start identity requires a positive pid");const n=t.trim().replace(/\s+/gu," "),r=/^(\d+) ((?:Sun|Mon|Tue|Wed|Thu|Fri|Sat) (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (?:[1-9]|[12]\d|3[01]) (?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d \d{4})$/u.exec(n);if(r===null||Number(r[1])!==e)throw new Error("Darwin process start identity is malformed");return`darwin-ps-start:${r[2]}`}function P(e){const t=f(),n=windowsProcessCreationIdentityScript(e),r=runBoundedProcessIdentityQuery({args:["-NoLogo","-NoProfile","-NonInteractive","-Command",n],environment:t.environment,executable:t.executable,timeoutMs:S,windowsHide:!0});if(!/^\d+$/u.test(r))throw new Error("Windows process creation identity is malformed");return m(r)}export function windowsProcessCreationIdentityScript(e){if(!Number.isSafeInteger(e)||e<=0)throw new Error("Windows process creation identity script requires a positive pid");return`$ErrorActionPreference = "Stop"; $p = [Diagnostics.Process]::GetProcessById(${e.toString()}); try { $fileTime = [Int64]$p.StartTime.ToUniversalTime().ToFileTimeUtc(); if ($fileTime -le 0) { exit 3 }; [Console]::Write($fileTime.ToString([Globalization.CultureInfo]::InvariantCulture)) } finally { $p.Dispose() }`}export function runBoundedProcessIdentityQuery(e){if(!Number.isSafeInteger(e.timeoutMs)||e.timeoutMs<=0)throw new Error("Process identity query timeout must be a positive safe integer in milliseconds");return c(e.executable,[...e.args],{encoding:"utf8",env:e.environment,killSignal:"SIGKILL",maxBuffer:I,stdio:["ignore","pipe","ignore"],timeout:e.timeoutMs,windowsHide:e.windowsHide}).trim()}export function inspectProcessLiveness(e){try{return process.kill(e,0),"alive"}catch(t){return s(t,"ESRCH")?"absent":s(t,"EPERM")?"alive":"unknown"}}function s(e,t){return typeof e=="object"&&e!==null&&Reflect.get(e,"code")===t}

package/dist/process/process-limits.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Maximum combined stdout and stderr bytes retained by supervised process
+ * capture. Process supervision owns this resource limit independently of any
+ * engine request or result protocol.
+ */
+export declare const MAX_SUPERVISED_PROCESS_CAPTURE_BYTES: number;

package/dist/process/process-limits.js

@@ -0,0 +1 @@
+export const MAX_SUPERVISED_PROCESS_CAPTURE_BYTES=8388608;

package/dist/process/process.d.ts

@@ -0,0 +1,11 @@
+import { type ManagedProcessRequest, type ManagedProcessResult, type SupervisedProcessHandle, type SupervisedProcessRequest } from "./process-contracts.js";
+export { type AttributedProcessLineageTerminationRequest, type ManagedProcessCancellationSignal, type ManagedProcessRequest, type ManagedProcessResult, type OwnedPosixProcessGroupTerminationRequest, type SupervisedProcessHandle, type SupervisedProcessOutputMode, type SupervisedProcessRecoveryIdentity, type SupervisedProcessReady, type SupervisedProcessRequest, } from "./process-contracts.js";
+export { terminateAttributedProcessLineage, terminateOwnedPosixProcessGroup } from "./recovery.js";
+export { cleanupExitedProcessGroup } from "./process-group.js";
+export declare function runManagedProcess(request: Readonly<ManagedProcessRequest>): Promise<ManagedProcessResult>;
+export declare class ProcessExitedBeforeReadyError extends Error {
+    readonly exitCode: number | null;
+    readonly exitSignal: NodeJS.Signals | null;
+    constructor(exitCode: number | null, exitSignal: NodeJS.Signals | null);
+}
+export declare function startSupervisedProcess(request: Readonly<SupervisedProcessRequest>): SupervisedProcessHandle;

package/dist/process/process.js

@@ -0,0 +1 @@
+import{execa as v}from"execa";import{accessSync as O}from"node:fs";import{isAbsolute as D}from"node:path";import"./process-contracts.js";import{captureProcessCreationIdentity as G,inspectProcessLiveness as _}from"./process-identity.js";import{MAX_SUPERVISED_PROCESS_CAPTURE_BYTES as B}from"./process-limits.js";export{}from"./process-contracts.js";export{terminateAttributedProcessLineage,terminateOwnedPosixProcessGroup}from"./recovery.js";import{cleanupExitedProcessGroup as E,processGroupExists as S}from"./process-group.js";import{createShutdownDeadline as R,DEFAULT_SHUTDOWN_TIMEOUT_MS as c}from"./shutdown.js";export{cleanupExitedProcessGroup}from"./process-group.js";export function runManagedProcess(e){if(C(e,!1),e.signal.aborted)return Promise.resolve(A());try{const t=y(e,"bounded-capture",{cancelSignal:e.signal,forceKillAfterDelay:c});return k(t)}catch(t){return Promise.resolve(U(t))}}export class ProcessExitedBeforeReadyError extends Error{exitCode;exitSignal;constructor(t,n){super("Process exited before becoming ready"),this.exitCode=t,this.exitSignal=n}}export function startSupervisedProcess(e){if(C(e,!0),e.signal.aborted)throw new Error(`${e.displayLabel} was cancelled before its process could start`);const t=y(e,e.outputMode,{forceKillAfterDelay:e.shutdownTimeoutMs===void 0?c:!1}),n=t.pid;if(n===void 0)throw t.kill("SIGKILL"),new Error(`${e.displayLabel} could not start ${JSON.stringify(e.executable)}`);let i=!1,m=!1,f=!1;const l=R(e.shutdownTimeoutMs??c);let a=null;const o={failure:null,cleanup:null},w=()=>{if(o.failure=null,l.deadlineAt!==null)try{a?.(l.deadlineAt)}catch(r){o.failure=p(r)}},d=r=>{f||(l.begin(r)&&w(),!i&&(i=!0,t.kill("SIGTERM"),o.cleanup=E(n,{remainingMs:l.remainingMs,initialSignalSent:!0,sendSignal:(s,u)=>{t.kill(u)}})))},g=()=>{!i&&!f&&t.nodeChildProcess.exitCode===null&&t.nodeChildProcess.signalCode===null&&(m=!0),d()};for(const r of[t.stdout,t.stderr])r.once("close",()=>{!r.readableEnded&&t.nodeChildProcess.exitCode===null&&t.nodeChildProcess.signalCode===null&&d()});e.signal.addEventListener("abort",g,{once:!0});const b=e.timeoutMs!==null?setTimeout(d,e.timeoutMs):null;t.nodeChildProcess.once("exit",()=>{process.platform!=="win32"&&S(n)&&d()});const x=new Promise((r,s)=>{t.nodeChildProcess.once("error",s),t.nodeChildProcess.once("spawn",()=>{const u=G(n);if(u===null){const L=new Error(`${e.displayLabel} process creation identity could not be captured`);_(n)==="absent"?t.nodeChildProcess.once("exit",(T,I)=>{s(new ProcessExitedBeforeReadyError(T,I))}):(t.kill("SIGKILL"),s(L));return}r({pid:n,recovery:{creationIdentity:u,processGroupId:process.platform==="win32"?null:n}})})});x.catch(()=>{});const h=(async()=>{const r=await t;process.platform!=="win32"&&S(n)&&d();const s=o.cleanup===null?null:await o.cleanup;return{...M(r,e.outputMode==="bounded-capture",s??o.failure),cancelled:m}})().finally(()=>{f=!0,e.signal.removeEventListener("abort",g),b!==null&&clearTimeout(b),o.failure===null&&(a=null)});return{completion:h,ready:x,stderr:t.stderr,stdin:t.stdin,stdout:t.stdout,pid:n,shutdownTimeoutMs:e.shutdownTimeoutMs??c,get shutdownDeadlineAt(){return l.deadlineAt},onShutdownStarted(r){return a=r,l.deadlineAt!==null&&r(l.deadlineAt),()=>{a===r&&(a=null)}},async stop(r){return o.failure!==null&&w(),d(r),{...await h,terminationError:await o.cleanup??o.failure}}}}async function k(e){const t=e.pid,n=await e,i=t===void 0?null:await E(t);return M(n,!0,i)}function y(e,t,n){return process.platform==="win32"&&D(e.executable)&&O(e.executable),v(e.executable,[...e.args],{buffer:t==="bounded-capture",maxBuffer:B/2,...n,cleanup:!0,cwd:e.cwd,encoding:"utf8",env:e.env,extendEnv:!1,killDescendants:!0,reject:!1,stderr:"pipe",stdin:"pipe",stdout:"pipe",stripFinalNewline:!1,...e.timeoutMs===null?{}:{timeout:e.timeoutMs},windowsHide:!0,windowsVerbatimArguments:e.windowsVerbatimArguments})}function M(e,t,n){const i=e.failed&&e.exitCode===void 0&&e.signal===void 0&&!e.timedOut&&!e.isCanceled&&!e.isMaxBuffer?p(e):null;return{cancelled:e.isCanceled,error:i,exitCode:e.exitCode??null,exitSignal:e.signal??null,outputLimitExceeded:e.isMaxBuffer,stderr:t?P(e.stderr):"",stdout:t?P(e.stdout):"",terminationError:n,timedOut:e.timedOut}}function P(e){return typeof e=="string"?e:e instanceof Uint8Array?Buffer.from(e).toString("utf8"):""}function C(e,t){if(e.executable.length===0)throw new Error("Managed process executable must be non-empty");if(e.cwd.length===0)throw new Error("Managed process working directory must be non-empty");if(e.displayLabel.trim().length===0)throw new Error("Managed process display label must be non-empty");if(e.timeoutMs!==null&&(!Number.isSafeInteger(e.timeoutMs)||e.timeoutMs<=0))throw new Error("Managed process timeout must be a positive safe integer");if(t&&"outputMode"in e&&!["bounded-capture","caller-drained"].includes(e.outputMode))throw new Error("Supervised process output mode must be bounded-capture or caller-drained")}function A(){return{cancelled:!0,error:null,exitCode:null,exitSignal:null,outputLimitExceeded:!1,stderr:"",stdout:"",terminationError:null,timedOut:!1}}function U(e){return{...A(),cancelled:!1,error:p(e)}}function p(e){return e instanceof Error?e:new Error(String(e))}

package/dist/process/readiness.d.ts

@@ -0,0 +1,37 @@
+import type { RuntimeSocket } from "./runtime-socket.js";
+export interface ReadyProcess {
+    completion: PromiseLike<ReadyProcessCompletion>;
+}
+export interface ReadyProcessCompletion {
+    error?: Error | null;
+    exitCode: null | number;
+    exitSignal?: NodeJS.Signals | null;
+    terminationError?: Error | null;
+}
+export interface WaitForReadyOptions {
+    name: string;
+    process: ReadyProcess;
+    signal?: AbortSignal | null;
+    timeoutMs: number;
+    url: string;
+}
+export declare const DEFAULT_READY_TIMEOUT_MS = 120000;
+export declare function waitForReady({ name, url, timeoutMs, process, signal, }: Readonly<WaitForReadyOptions>): Promise<void>;
+export declare function serviceCompletionError(name: string, result: Readonly<ReadyProcessCompletion>, phase?: "before becoming ready" | "unexpectedly"): Error;
+export declare function isPortInUse({ host, port }: Readonly<RuntimeSocket>): Promise<boolean>;
+export interface EndpointReadinessSuccessfulAttempt {
+    durationMs: number;
+    error?: undefined;
+    host: string;
+    ok: true;
+    port: number;
+}
+export interface EndpointReadinessFailedAttempt {
+    durationMs: number;
+    error: string;
+    host: string;
+    ok: false;
+    port: number;
+}
+export type EndpointReadinessAttempt = EndpointReadinessFailedAttempt | EndpointReadinessSuccessfulAttempt;
+export declare function connectEndpoint(endpoint: Readonly<RuntimeSocket>, timeoutMs: number, signal?: AbortSignal): Promise<EndpointReadinessAttempt>;

package/dist/process/readiness.js

@@ -0,0 +1 @@
+import u from"net";import{setTimeout as w}from"node:timers/promises";export const DEFAULT_READY_TIMEOUT_MS=12e4;export async function waitForReady({name:e,url:t,timeoutMs:r,process:s,signal:o}){const c=Date.now(),a=Promise.resolve(s.completion).then(i=>({kind:"completion",result:i})),n=b(o);try{for(;Date.now()-c<r;){const i=Math.max(1,r-(Date.now()-c)),f=Promise.resolve(w(Math.min(1e3,i))).then(()=>({kind:"interval"})),l=new AbortController,m=fetch(t,{signal:l.signal}).then(p=>({kind:"endpoint",ready:p.ok}),()=>({kind:"endpoint",ready:!1}));let d=await Promise.race([a,...n?[n.promise]:[],m,f]).finally(()=>{l.abort()});if(d.kind==="endpoint"){if(d.ready)return;d=await Promise.race([a,...n?[n.promise]:[],f])}if(d.kind==="completion")throw serviceCompletionError(e,d.result);if(d.kind==="abort")throw d.reason}}finally{n?.dispose()}throw new Error(`Timed out waiting for "${e}" to become ready at ${t}`)}export function serviceCompletionError(e,t,r="before becoming ready"){const s=r==="unexpectedly"?"Local service":"Service",o=t.error||t.terminationError||null,c=t.exitCode!==null?`exit code ${t.exitCode.toString()}`:t.exitSignal?`signal ${t.exitSignal}`:"no exit status";return new Error(`${s} "${e}" exited ${r} with ${c}${o?`: ${o.message}`:""}`,o?{cause:o}:void 0)}function b(e){if(!e)return null;let t=()=>{};const r=new Promise(s=>{t=()=>{s({kind:"abort",reason:e.reason||new Error("Service startup aborted")})},e.aborted?t():e.addEventListener("abort",t,{once:!0})});return{dispose(){e.removeEventListener("abort",t)},promise:r}}export async function isPortInUse({host:e,port:t}){return new Promise((r,s)=>{const o=new u.Socket;let c=!1;const a=(n,i=null)=>{if(!c){if(c=!0,o.destroy(),i){s(i);return}r(n)}};o.setTimeout(1e3),o.once("connect",()=>{a(!0)}),o.once("timeout",()=>{a(!1)}),o.once("error",n=>{const i=y(n,"code");if(typeof i=="string"&&["ECONNREFUSED","EHOSTUNREACH","ENOTFOUND"].includes(i)){a(!1);return}a(!1,n)}),o.connect(t,e)})}function y(e,t){if(!((typeof e!="object"||e===null)&&typeof e!="function"))return Reflect.get(e,t)}export function connectEndpoint(e,t,r){return new Promise(s=>{const o=u.createConnection({host:e.host,port:e.port});let c=!1;const a=Date.now(),n=f=>{c||(c=!0,r?.removeEventListener("abort",i),o.destroy(),s({host:e.host,port:e.port,durationMs:Math.max(0,Date.now()-a),...f}))};function i(){n({ok:!1,error:"connection cancelled"})}o.setTimeout(t),o.once("connect",()=>{n({ok:!0})}),o.once("timeout",()=>{n({ok:!1,error:`connect timed out after ${t.toString()}ms`})}),o.once("error",f=>{n({ok:!1,error:f.message})}),r?.addEventListener("abort",i,{once:!0}),r?.aborted&&i()})}

package/dist/process/recovery.d.ts

@@ -0,0 +1,3 @@
+import type { AttributedProcessLineageTerminationRequest, OwnedPosixProcessGroupTerminationRequest } from "./process-contracts.js";
+export declare function terminateAttributedProcessLineage(request: Readonly<AttributedProcessLineageTerminationRequest>): Promise<void>;
+export declare function terminateOwnedPosixProcessGroup(request: Readonly<OwnedPosixProcessGroupTerminationRequest>): Promise<void>;

package/dist/process/recovery.js

@@ -0,0 +1 @@
+import{execFile as c}from"node:child_process";import p from"node:path";import{promisify as d}from"node:util";import{processCreationIdentityMatches as l}from"./process-identity.js";import{cleanupExitedProcessGroup as f,processGroupExists as m}from"./process-group.js";const u=d(c);export async function terminateAttributedProcessLineage(e){if(i(e.pid),t(e.displayLabel),s(e.pid,e.expectedCreationIdentity),process.platform==="win32"){await g(e.pid,e.displayLabel);return}w(e.pid,e.signal)}export async function terminateOwnedPosixProcessGroup(e){if(process.platform==="win32")throw new Error("POSIX process-group recovery is unavailable on Windows");if(i(e.leaderPid),i(e.processGroupId),t(e.displayLabel),e.leaderPid!==e.processGroupId)throw new Error("Owned POSIX process-group leader pid must equal its process-group id");if(!Number.isFinite(e.graceMs)||!Number.isInteger(e.graceMs)||e.graceMs<0)throw new Error("Owned POSIX process-group grace must be non-negative");if(!m(e.processGroupId))return;s(e.leaderPid,e.leaderCreationIdentity);const r=await f(e.processGroupId,{graceMs:e.graceMs});if(r!==null)throw new Error(`${e.displayLabel}: ${r.message}`,{cause:r})}function i(e){if(!Number.isSafeInteger(e)||e<=0)throw new Error("Process pid must be a positive safe integer")}function t(e){if(e.trim().length===0)throw new Error("Process display label must be non-empty")}function s(e,r){if(r!==void 0&&!l(e,r))throw new Error(`Process creation identity no longer matches pid ${e.toString()}; refusing unsafe cleanup`)}function w(e,r){try{process.kill(e,r)}catch(o){if(!a(o,"ESRCH"))throw o}}async function g(e,r){const o=p.join(process.env.SystemRoot||"C:\\Windows","System32","taskkill.exe");try{await u(o,["/pid",e.toString(),"/t","/f"],{timeout:1e4,windowsHide:!0})}catch(n){if(a(n,"ESRCH"))return;throw new Error(`Could not terminate ${r} process tree`,{cause:n})}}function a(e,r){return typeof e=="object"&&e!==null&&Reflect.get(e,"code")===r}

package/dist/process/runs/manifest.d.ts

@@ -0,0 +1,85 @@
+import type { RuntimeSocket } from "../runtime-socket.js";
+import { RUN_MAINTENANCE_STOP_REQUEST_SCHEMA_VERSION, RUN_MANIFEST_SCHEMA_VERSION } from "./schema.js";
+export { RUN_MAINTENANCE_STOP_REQUEST_SCHEMA_VERSION, RUN_MANIFEST_SCHEMA_VERSION };
+export interface RunManifestController {
+    [key: string]: null | string;
+}
+export interface RunManifestPort extends RuntimeSocket {
+    [key: string]: unknown;
+}
+export interface RunManifestService {
+    shutdownTimeoutMs?: number;
+    shutdownDeadlineAt?: number | null;
+    [key: string]: unknown;
+    command?: null | string;
+    cwd?: string;
+    pid: number;
+    processIdentity: string;
+    ports: RunManifestPort[];
+    processGroupId: null | number;
+    runtimeLabel?: string;
+    serviceName?: string;
+    startedAt?: string;
+}
+export interface RunManifest {
+    [key: string]: unknown;
+    controller?: null | RunManifestController;
+    finishedAt?: string;
+    heartbeatAt?: null | string;
+    incarnationId: string;
+    interruptReason?: null | string;
+    pid: number;
+    processIdentity: null | string;
+    runId: string;
+    runtimeDirs: string[];
+    schemaVersion: typeof RUN_MANIFEST_SCHEMA_VERSION;
+    services: RunManifestService[];
+    session?: null | Record<string, unknown>;
+    startedAt?: string;
+    status?: string;
+}
+export interface WritableRunManifest extends RunManifest {
+    controller: null | RunManifestController;
+    heartbeatAt: null | string;
+    interruptReason: null | string;
+    pid: number;
+    processIdentity: null | string;
+    runId: string;
+    schemaVersion: typeof RUN_MANIFEST_SCHEMA_VERSION;
+    startedAt: string;
+    status: string;
+}
+export interface RunMaintenanceStopRequest {
+    coordinatorPid: number;
+    coordinatorProcessIdentity: string;
+    reason: string;
+    requestedAt: string;
+    runId: string;
+    schemaVersion: typeof RUN_MAINTENANCE_STOP_REQUEST_SCHEMA_VERSION;
+    targetIncarnationId: string;
+    targetPid: number;
+    targetProcessIdentity: string;
+}
+export declare class RunManifestCollisionError extends Error {
+    readonly code = "TESTKIT_RUN_MANIFEST_COLLISION";
+    readonly manifestPath: string;
+    constructor(manifestPath: string, options?: ErrorOptions);
+}
+export declare class RunManifestInventoryError extends Error {
+    readonly code = "TESTKIT_RUN_MANIFEST_INVENTORY_FAILED";
+    readonly manifestPath: string;
+    constructor(manifestPath: string, reason: string, options?: ErrorOptions);
+}
+export declare function runManifestPath(productDir: string, runId: unknown): string;
+export declare function writeRunManifest(productDir: string, manifest: Readonly<WritableRunManifest>): void;
+export declare function prepareRunShutdownDeadlines(manifest: Readonly<RunManifest>, requestedAt: string): RunManifest;
+export declare function persistRunShutdownDeadlines(productDir: string, manifest: Readonly<RunManifest>): void;
+export declare function createRunManifest(productDir: string, manifest: Readonly<WritableRunManifest>): void;
+export declare function writeRunMaintenanceStopRequest(productDir: string, request: Readonly<RunMaintenanceStopRequest>): void;
+export declare function readRunMaintenanceStopRequest(productDir: string, runId: unknown): RunMaintenanceStopRequest | null;
+export declare function removeRunMaintenanceStopRequest(productDir: string, runId: unknown): void;
+export declare function removeRunManifestFile(productDir: string, runId: unknown): void;
+export declare function listRunManifests(productDir: string): RunManifest[];
+export declare function requireSafeRunId(value: unknown, label: string): string;
+export declare function normalizeRunManifest(value: unknown): RunManifest | null;
+export declare function formatRunSummary(manifest: unknown): string;

package/dist/process/runs/manifest.js

@@ -0,0 +1 @@
+import i from"node:fs";import l from"node:path";import{randomUUID as _}from"node:crypto";import{publishWindowsFile as P}from"../windows-native.js";import{serializeJson as x,writeJsonFileAtomicWithRetry as h}from"../files/json-file.js";import{RUN_MAINTENANCE_STOP_REQUEST_SCHEMA_VERSION as S,RUN_MANIFEST_SCHEMA_VERSION as I}from"./schema.js";export{S as RUN_MAINTENANCE_STOP_REQUEST_SCHEMA_VERSION,I as RUN_MANIFEST_SCHEMA_VERSION};const $=l.join(".testkit","_runs"),D=".maintenance-stop",E=128,U=/^[A-Za-z0-9][A-Za-z0-9._-]*$/u,F=/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u,O=/^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)/iu;export class RunManifestCollisionError extends Error{code="TESTKIT_RUN_MANIFEST_COLLISION";manifestPath;constructor(t,e){super(`Testkit run manifest already exists at ${t}`,e),this.name="RunManifestCollisionError",this.manifestPath=t}}export class RunManifestInventoryError extends Error{code="TESTKIT_RUN_MANIFEST_INVENTORY_FAILED";manifestPath;constructor(t,e,r){super(`Cannot inventory Testkit run manifest ${t}: ${e}`,r),this.name="RunManifestInventoryError",this.manifestPath=t}}export function runManifestPath(n,t){const e=requireSafeRunId(t,"Testkit run id");return l.join(p(n),`${e}.json`)}export function writeRunManifest(n,t){const e=runManifestPath(n,t.runId);i.mkdirSync(p(n),{recursive:!0}),h(e,t)}export function prepareRunShutdownDeadlines(n,t){return{...n,services:n.services.map(e=>e.shutdownTimeoutMs===void 0?e:{...e,shutdownDeadlineAt:Math.min(e.shutdownDeadlineAt??Number.MAX_VALUE,Date.parse(t)+e.shutdownTimeoutMs)})}}export function persistRunShutdownDeadlines(n,t){h(runManifestPath(n,t.runId),t)}export function createRunManifest(n,t){const e=runManifestPath(n,t.runId),r=p(n);i.mkdirSync(r,{recursive:!0});const o=l.join(r,`.${l.basename(e)}.${process.pid.toString()}.${_()}.tmp`);i.writeFileSync(o,x(t,`run manifest ${t.runId}`),{flag:"wx"});try{process.platform==="win32"?P(o,e):i.linkSync(o,e)}catch(s){throw J(s,"EEXIST")?new RunManifestCollisionError(e,{cause:s}):s}finally{i.rmSync(o,{force:!0})}}export function writeRunMaintenanceStopRequest(n,t){const e=g(n,t.runId);i.mkdirSync(p(n),{recursive:!0}),h(e,t)}export function readRunMaintenanceStopRequest(n,t){const e=requireSafeRunId(t,"Testkit run id"),r=g(n,e);let o;try{o=JSON.parse(i.readFileSync(r,"utf8"))}catch{return null}const s=j(o);return s?.runId===e?s:null}export function removeRunMaintenanceStopRequest(n,t){i.rmSync(g(n,t),{force:!0})}export function removeRunManifestFile(n,t){const e=runManifestPath(n,t),r=p(n);i.rmSync(e,{force:!0}),removeRunMaintenanceStopRequest(n,t),i.existsSync(r)&&i.readdirSync(r).length===0&&i.rmSync(r,{recursive:!0,force:!0})}export function listRunManifests(n){const t=p(n);return i.existsSync(t)?i.readdirSync(t,{withFileTypes:!0}).filter(e=>e.name.endsWith(".json")).map(e=>{const r=l.join(t,e.name);if(!e.isFile())throw new RunManifestInventoryError(r,"manifest path is not a regular file");return C(r)}).sort((e,r)=>(e.startedAt||"").localeCompare(r.startedAt||"")):[]}export function requireSafeRunId(n,t){const e=R(n);if(e!==null)return e;throw new Error(`${t} must be 1-${E.toString()} characters using only ASCII letters, digits, dot, underscore, or hyphen, must start with a letter or digit, and must not use a reserved Windows device name`)}export function normalizeRunManifest(n){if(!m(n)||n.schemaVersion!==I)return null;const t=R(n.runId);if(t===null)return null;const e=n.controller,r=n.finishedAt,o=n.heartbeatAt,s=T(n.incarnationId),u=n.interruptReason,a=n.pid,d=n.processIdentity,c=n.session,f=n.startedAt,y=n.status,b=z(n.services),w=V(n.runtimeDirs);return typeof a!="number"||!Number.isSafeInteger(a)||a<0||s===null||b===null||w===null||a===0&&d!==null||a>0&&(typeof d!="string"||d.length===0)?null:{incarnationId:s,runId:t,runtimeDirs:w,schemaVersion:I,services:b,pid:a,processIdentity:typeof d=="string"?d:null,...W(e)?{controller:e}:{},...typeof r=="string"?{finishedAt:r}:{},...N(o)?{heartbeatAt:o}:{},...N(u)?{interruptReason:u}:{},...q(c)?{session:c}:{},...typeof f=="string"?{startedAt:f}:{},...typeof y=="string"?{status:y}:{}}}function g(n,t){const e=requireSafeRunId(t,"Testkit run id");return l.join(p(n),`${e}${D}`)}function j(n){if(!m(n)||n.schemaVersion!==S)return null;const t=R(n.runId),e=T(n.targetIncarnationId);return t===null||e===null||!M(n.coordinatorPid)||typeof n.coordinatorProcessIdentity!="string"||n.coordinatorProcessIdentity.length===0||typeof n.reason!="string"||n.reason.length===0||typeof n.requestedAt!="string"||!Number.isFinite(Date.parse(n.requestedAt))||!M(n.targetPid)||typeof n.targetProcessIdentity!="string"||n.targetProcessIdentity.length===0?null:{coordinatorPid:n.coordinatorPid,coordinatorProcessIdentity:n.coordinatorProcessIdentity,reason:n.reason,requestedAt:n.requestedAt,runId:t,schemaVersion:S,targetIncarnationId:e,targetPid:n.targetPid,targetProcessIdentity:n.targetProcessIdentity}}function C(n){let t;try{t=i.readFileSync(n,"utf8")}catch(u){throw new RunManifestInventoryError(n,"file could not be read",{cause:u})}let e;try{e=JSON.parse(t)}catch(u){throw new RunManifestInventoryError(n,"file is not valid JSON",{cause:u})}const r=normalizeRunManifest(e);if(r!==null){const u=l.basename(n,".json");if(r.runId!==u)throw new RunManifestInventoryError(n,"embedded runId does not match the manifest filename");return r}const o=m(e)?e.schemaVersion:void 0,s=o===I?`schema-v${I.toString()} record is invalid`:`unsupported schema version ${typeof o=="number"?o.toString():"missing"}`;throw new RunManifestInventoryError(n,s)}function R(n){return typeof n=="string"&&n.length<=E&&U.test(n)&&!O.test(n)?n:null}function T(n){return typeof n=="string"&&F.test(n)?n:null}function z(n){if(!Array.isArray(n))return null;const t=[];for(const e of n){const r=k(e);if(r===null)return null;t.push(r)}return t}function k(n){if(!m(n))return null;const t=n.command,e=n.cwd,r=n.pid,o=n.processIdentity,s=n.processGroupId,u=n.runtimeLabel,a=n.serviceName,d=n.startedAt,c=n.shutdownTimeoutMs,f=n.shutdownDeadlineAt;if(c!==void 0&&(typeof c!="number"||!Number.isFinite(c)||!Number.isInteger(c)||c<=0)||f!=null&&(c===void 0||typeof f!="number"||!Number.isFinite(f)||f<0))return null;const y=L(n.ports);return typeof r!="number"||!Number.isSafeInteger(r)||r<=0||s!==null&&(typeof s!="number"||!Number.isSafeInteger(s)||s!==r)||typeof o!="string"||o.length===0||y===null?null:{...c===void 0?{}:{shutdownTimeoutMs:c},...f===void 0?{}:{shutdownDeadlineAt:f},ports:y,pid:r,processGroupId:s,processIdentity:o,...N(t)?{command:t}:{},...typeof e=="string"?{cwd:e}:{},...typeof u=="string"?{runtimeLabel:u}:{},...typeof a=="string"?{serviceName:a}:{},...typeof d=="string"?{startedAt:d}:{}}}function L(n){if(!Array.isArray(n))return null;const t=[];for(const e of n){if(!m(e))return null;const r=e.host,o=e.port;if(typeof r!="string"||typeof o!="number"||!Number.isSafeInteger(o)||o<=0||o>65535)return null;t.push({...e,host:r,port:o})}return t}function V(n){return!Array.isArray(n)||!n.every(t=>typeof t=="string")?null:n}function M(n){return typeof n=="number"&&Number.isSafeInteger(n)&&n>0}function p(n){return l.join(n,$)}function m(n){return typeof n=="object"&&n!==null&&!Array.isArray(n)}function q(n){return n===null||m(n)}function W(n){return n===null?!0:m(n)?Object.values(n).every(t=>t===null||typeof t=="string"):!1}function N(n){return n===null||typeof n=="string"}function J(n,t){return(typeof n=="object"||typeof n=="function")&&n!==null&&Reflect.get(n,"code")===t}const A=String;export function formatRunSummary(n){const t=normalizeRunManifest(n);if(!t)return A(n);const e=[...new Set(t.services.map(r=>r.runtimeLabel).filter(r=>!!r))];return`${A(t.runId)} pid=${A(t.pid)}${e.length>0?` runtimes=${e.join(",")}`:""}`}

package/dist/process/runs/ownership.d.ts

@@ -0,0 +1,11 @@
+import { observeProcessCreationIdentity } from "../index.js";
+export interface TerminalRunDatabaseCleanupAuthority {
+    finishedAt: string;
+    incarnationId: string;
+    pid: number;
+    processIdentity: null | string;
+    runId: string;
+    status: "failed" | "finished" | "interrupted";
+}
+export declare function hasActiveRunManifest(productDir: string, observeIdentity?: typeof observeProcessCreationIdentity): boolean;
+export declare function hasActiveRunManifestWithTerminalAuthority(productDir: string, observeIdentity: typeof observeProcessCreationIdentity, terminalRunAuthority?: Readonly<TerminalRunDatabaseCleanupAuthority>): boolean;

package/dist/process/runs/ownership.js

@@ -0,0 +1 @@
+import c from"node:fs";import l from"node:path";import{observeProcessCreationIdentity as p}from"../index.js";import{isTerminalRunStatus as m,RUN_MANIFEST_SCHEMA_VERSION as d}from"./schema.js";export function hasActiveRunManifest(e,n=p){return hasActiveRunManifestWithTerminalAuthority(e,n)}export function hasActiveRunManifestWithTerminalAuthority(e,n,i){const u=l.join(e,".testkit","_runs"),a=I(u);let f=null;if(i!==void 0){const o=`${i.runId}.json`,r=a.filter(s=>s.fileName===o&&y(s.value,i));if(r.length!==1)return!0;f=r[0]}for(const o of a){if(o===f)continue;if(t(o.value,"schemaVersion")!==d)return!0;const r=t(o.value,"pid"),s=t(o.value,"processIdentity");if(!(r===0&&s===null)&&(typeof r!="number"||!Number.isSafeInteger(r)||r<=0||typeof s!="string"||s.length===0||n(r,s)!=="different"))return!0}return!1}function y(e,n){const i=t(e,"status"),u=t(e,"services");return t(e,"schemaVersion")===d&&t(e,"runId")===n.runId&&t(e,"incarnationId")===n.incarnationId&&t(e,"pid")===n.pid&&t(e,"processIdentity")===n.processIdentity&&t(e,"finishedAt")===n.finishedAt&&i===n.status&&m(i)&&Array.isArray(u)&&u.length===0}function I(e){return c.existsSync(e)?c.readdirSync(e,{withFileTypes:!0}).filter(n=>n.name.endsWith(".json")).map(n=>({fileName:n.name,value:n.isFile()?h(l.join(e,n.name)):null})):[]}function h(e){try{return JSON.parse(c.readFileSync(e,"utf8"))}catch{return null}}function t(e,n){return typeof e!="object"&&typeof e!="function"||e===null?void 0:Reflect.get(e,n)}

package/dist/process/runs/product-state.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveContainedTestkitStateDirectory(productDir: string, ...segments: readonly string[]): string;
+export declare function requireContainedTestkitStateDirectory(productDir: string, candidateDirectory: string, label?: string): string;

package/dist/process/runs/product-state.js

@@ -0,0 +1 @@
+import l from"node:fs";import e from"node:path";export function resolveContainedTestkitStateDirectory(t,...r){for(const n of r)h(n);const o=l.realpathSync.native(e.resolve(t)),s=l.lstatSync(o);if(!s.isDirectory()||s.isSymbolicLink())throw new Error(`Testkit product path is not a directory: ${t}`);let i=o;for(const n of[".testkit",...r]){i=e.join(i,n);let a;try{a=l.lstatSync(i)}catch(c){if(d(c,"ENOENT"))break;throw c}if(a.isSymbolicLink())throw u(i,"symlink");if(!a.isDirectory())throw u(i,"non-directory node")}return e.join(o,".testkit",...r)}export function requireContainedTestkitStateDirectory(t,r,o="Testkit state directory"){const s=e.resolve(t),i=l.realpathSync.native(s),n=e.resolve(r),a=f(s,n)??f(i,n);if(a===null)throw new Error(`${o} must resolve within the Testkit product`);const c=a.split(e.sep);if(c.shift()!==".testkit")throw new Error(`${o} must resolve below the .testkit state root`);return resolveContainedTestkitStateDirectory(t,...c)}function f(t,r){const o=e.relative(t,r);return o===".."||o.startsWith(`..${e.sep}`)||e.isAbsolute(o)?null:o}function h(t){if(!t||t==="."||t===".."||e.basename(t)!==t||e.posix.basename(t)!==t||e.win32.basename(t)!==t)throw new Error(`Unsafe Testkit state path segment: ${t}`)}function u(t,r){return new Error(`Refusing unsafe Testkit state ${r} at ${t}`)}function d(t,r){return typeof t=="object"&&t!==null&&"code"in t&&Reflect.get(t,"code")===r}

package/dist/process/runs/schema.d.ts

@@ -0,0 +1,3 @@
+export declare const RUN_MANIFEST_SCHEMA_VERSION: 3;
+export declare const RUN_MAINTENANCE_STOP_REQUEST_SCHEMA_VERSION: 2;
+export declare function isTerminalRunStatus(status: unknown): status is "failed" | "finished" | "interrupted";

package/dist/process/runs/schema.js

@@ -0,0 +1 @@
+export const RUN_MANIFEST_SCHEMA_VERSION=3,RUN_MAINTENANCE_STOP_REQUEST_SCHEMA_VERSION=2;export function isTerminalRunStatus(e){return e==="failed"||e==="finished"||e==="interrupted"}

package/dist/process/runs/stop.d.ts

@@ -0,0 +1,19 @@
+import { type RunManifest, type RunManifestService } from "./manifest.js";
+export interface PreparedRunStop {
+    requestedAt: string;
+    controllerActive: boolean;
+    coordinatorProcessIdentity: null | string;
+    graceMs: number;
+    manifest: RunManifest;
+    pid: number;
+    productDir: string;
+    reason: string;
+    runId: string;
+    targetProcessIdentity: null | string;
+}
+export declare function isPidRunning(pid: unknown): boolean;
+export declare function waitForPreparedRunStop(prepared: Readonly<PreparedRunStop>): Promise<Set<string>>;
+export declare function drainRunServices(services: readonly RunManifestService[], drainedServices: Set<string>): Promise<void>;
+export declare function requestProcessStop(pid: number, expectedIdentity: null | string, signal: NodeJS.Signals | number): void;
+export declare function runManifestServiceKey(service: Readonly<RunManifestService>): string;
+export declare function sameRunManifestIncarnation(left: Readonly<RunManifest>, right: Readonly<RunManifest>): boolean;

package/dist/process/runs/stop.js

@@ -0,0 +1 @@
+import{isTerminalRunStatus as h}from"./schema.js";import{observeProcessCreationIdentity as c}from"../index.js";import{withProductLifecycleFence as a}from"../lifecycle-fence.js";import{terminateAttributedProcessLineage as f,terminateOwnedPosixProcessGroup as T}from"../service-processes.js";import{listRunManifests as d}from"./manifest.js";import{createShutdownDeadline as I,remainingShutdownMs as A,FORCE_TERMINATION_WAIT_MS as S}from"../shutdown.js";const l=5e3,E=5e3;export function isPidRunning(t){if(!Number.isInteger(Number(t))||Number(t)<=0)return!1;try{return process.kill(Number(t),0),!0}catch(n){return M(n,"EPERM")}}export async function waitForPreparedRunStop(t){if(t.controllerActive&&t.targetProcessIdentity!==null){const i=await D(t,t.targetProcessIdentity);let r=i,s=i;if(!r&&!s&&(await f(t.pid,"SIGKILL",t.targetProcessIdentity),r=await p(t.pid,l,t.targetProcessIdentity),s=!r&&await b(t)),!r&&!s)throw new Error(`Timed out stopping Testkit run process ${t.pid.toString()}`)}const n=new Set,e=await a(t.productDir,()=>d(t.productDir).find(i=>i.runId===t.runId)),o=new Map(t.manifest.services.map(i=>[runManifestServiceKey(i),i]));if(e&&sameRunManifestIncarnation(e,t.manifest))for(const i of e.services){const r=runManifestServiceKey(i),s=o.get(r);o.set(r,s?.shutdownDeadlineAt==null?i:{...i,shutdownTimeoutMs:s.shutdownTimeoutMs,shutdownDeadlineAt:Math.min(s.shutdownDeadlineAt,i.shutdownDeadlineAt??Number.MAX_VALUE)})}return await drainRunServices([...o.values()],n),n}async function D(t,n){const e=new Map,o=s=>{for(const u of s){const w=runManifestServiceKey(u),m=u.shutdownTimeoutMs??t.graceMs,g=e.get(w)??I(m+S);g.begin((u.shutdownDeadlineAt??Date.parse(t.requestedAt)+m)+S),e.set(w,g)}return Math.max(0,...s.map(u=>e.get(runManifestServiceKey(u))?.remainingMs()??0))};o(t.manifest.services);const i=I(t.graceMs);i.begin(Date.parse(t.requestedAt)+t.graceMs);let r=null;for(;;){if(c(t.pid,n)==="different")return!0;const s=await a(t.productDir,()=>d(t.productDir).find(u=>u.runId===t.runId));if(!s||!sameRunManifestIncarnation(s,t.manifest)||h(s.status))return!0;if(Math.max(i.remainingMs(),o(s.services))<=0){if(r===null){try{await f(t.pid,"SIGTERM",n)}catch{}r=performance.now()}if(performance.now()-r>=E)return!1}await y(100)}}async function b(t){return a(t.productDir,()=>{const n=d(t.productDir).find(e=>e.runId===t.runId);return n===void 0||!sameRunManifestIncarnation(n,t.manifest)||h(n.status)})}export async function drainRunServices(t,n){for(const e of[...t].reverse())await P(e),n.add(runManifestServiceKey(e))}async function P(t){const n=t.pid;if(!Number.isSafeInteger(n)||n<=0)return;const e=t.processIdentity;if(typeof e!="string"||e.length===0)throw new Error(`Application service process ${n.toString()} has no creation identity; refusing unsafe cleanup`);const o=Number(t.processGroupId);if(process.platform!=="win32"&&Number.isSafeInteger(o)&&o>0&&o===n){await T(o,e,t.shutdownTimeoutMs===void 0?l:t.shutdownDeadlineAt==null?t.shutdownTimeoutMs:A(t.shutdownTimeoutMs,t.shutdownDeadlineAt));return}if(process.platform!=="win32")throw new Error(`Application service process ${n.toString()} does not have an owned POSIX process group; refusing unsafe cleanup`);const i=c(n,e);if(i!=="matches"){if(i==="different"&&!isPidRunning(n))return;throw new Error(i==="different"?`Application service process creation identity no longer matches pid ${n.toString()}; refusing unsafe cleanup`:`Cannot establish the creation identity of application service process ${n.toString()}; refusing unsafe cleanup`)}if(await f(n,"SIGKILL",e),!await p(n,l,e))throw new Error(`Timed out stopping application service process ${n.toString()}`)}export function requestProcessStop(t,n,e){const o=c(t,n);if(o!=="matches"){if(o==="different"&&!isPidRunning(t))return;throw new Error(o==="different"?`Testkit run process creation identity no longer matches pid ${t.toString()}; refusing unsafe stop request`:`Cannot establish the creation identity of Testkit run process ${t.toString()}; refusing unsafe stop request`)}try{process.kill(t,e)}catch(i){if(!M(i,"ESRCH"))throw i}}async function p(t,n,e){const o=()=>e===void 0?isPidRunning(t):c(t,e)!=="different",i=Date.now();for(;Date.now()-i<n;){if(!o())return!0;await y(100)}return!o()}export function runManifestServiceKey(t){return`${t.pid.toString()}:${String(t.processGroupId)}:${t.processIdentity}`}export function sameRunManifestIncarnation(t,n){return t.runId===n.runId&&t.incarnationId===n.incarnationId&&t.pid===n.pid&&t.processIdentity===n.processIdentity}function y(t){return new Promise(n=>setTimeout(n,t))}function M(t,n){return(typeof t=="object"||typeof t=="function")&&t!==null&&Reflect.get(t,"code")===n}

package/dist/process/runtime-socket.d.ts

@@ -0,0 +1,4 @@
+export interface RuntimeSocket {
+    host: string;
+    port: number;
+}

package/dist/process/runtime-socket.js

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

package/dist/process/service-processes.d.ts

@@ -0,0 +1,13 @@
+import { captureProcessCreationIdentity, processCreationIdentityMatches } from "./index.js";
+export type ProcessSignal = NodeJS.Signals;
+export interface ServiceStartInvocation {
+    args: readonly string[];
+    executable: string;
+    windowsVerbatimArguments?: boolean;
+}
+export { captureProcessCreationIdentity, processCreationIdentityMatches };
+export declare function normalizeServiceStartCommand(command: string): string;
+export declare function prepareServiceStartInvocation(command: string, env: Readonly<NodeJS.ProcessEnv>, platform?: NodeJS.Platform): ServiceStartInvocation;
+export declare function terminateAttributedProcessLineage(pid: unknown, signal: ProcessSignal, expectedCreationIdentity?: string): Promise<void>;
+export declare function terminateOwnedPosixProcessGroup(processGroupId: unknown, leaderCreationIdentity: string, graceMs: number): Promise<void>;
+export declare function sleep(ms: number): Promise<void>;

package/dist/process/service-processes.js

@@ -0,0 +1 @@
+import{captureProcessCreationIdentity as a,processCreationIdentityMatches as c,resolvePosixCommandShell as m,terminateAttributedProcessLineage as d,terminateOwnedPosixProcessGroup as u}from"./index.js";export{a as captureProcessCreationIdentity,c as processCreationIdentityMatches};export function normalizeServiceStartCommand(t){const r=t.trim();if(r.length===0)throw new Error("Service start command must not be empty");return r}export function prepareServiceStartInvocation(t,r,o=process.platform){const e=normalizeServiceStartCommand(t);if(o==="win32"){const n=e.replace(/^exec(?:\s+|$)/u,"").trim();if(n.length===0)throw new Error("Service start command must not contain only exec");return{executable:r.ComSpec||process.env.ComSpec||"cmd.exe",args:["/d","/s","/c",`"${n}"`],windowsVerbatimArguments:!0}}const s=m(r),i=/^exec(?:\s|$)/u.test(e)?e:`exec ${e}`;return{executable:s,args:["-lc",i]}}export async function terminateAttributedProcessLineage(t,r,o){const e=Number(t);!Number.isInteger(e)||e<=0||await d({displayLabel:"Testkit application service",...o===void 0?{}:{expectedCreationIdentity:o},pid:e,signal:r})}export async function terminateOwnedPosixProcessGroup(t,r,o){const e=Number(t);if(!Number.isSafeInteger(e)||e<=0)throw new Error("Owned POSIX process-group id must be a positive safe integer");await u({displayLabel:"Testkit application service",graceMs:o,leaderCreationIdentity:r,leaderPid:e,processGroupId:e})}export function sleep(t){return new Promise(r=>setTimeout(r,t))}

package/dist/process/shutdown.d.ts

@@ -0,0 +1,10 @@
+export declare const DEFAULT_SHUTDOWN_TIMEOUT_MS = 1000;
+export declare const FORCE_TERMINATION_WAIT_MS = 3000;
+/** Import a persisted deadline without granting more than its original allowance. */
+export declare function remainingShutdownMs(timeoutMs: number, deadlineAt: number, now?: number): number;
+/** One monotonic allowance, with a wall-clock deadline for ownership handoff. */
+export declare function createShutdownDeadline(timeoutMs: number): {
+    readonly deadlineAt: number | null;
+    remainingMs: () => number;
+    begin(importedDeadlineAt?: number): boolean;
+};

package/dist/process/shutdown.js

@@ -0,0 +1 @@
+export const DEFAULT_SHUTDOWN_TIMEOUT_MS=1e3,FORCE_TERMINATION_WAIT_MS=3e3;export function remainingShutdownMs(e,n,t=Date.now()){return Math.max(0,Math.min(e,n-t))}export function createShutdownDeadline(e){let n=null,t=0,a=e;const u=()=>n===null?e:Math.max(0,a-(performance.now()-t));return{get deadlineAt(){return n},remainingMs:u,begin(r){if(n!==null&&(r===void 0||r>=n))return!1;const o=Date.now();return a=Math.min(u(),r===void 0?e:remainingShutdownMs(e,r,o)),t=performance.now(),n=Math.min(n??Number.MAX_VALUE,r??Number.MAX_VALUE,o+a),!0}}}

package/dist/process/windows-cli-owner.d.ts

@@ -0,0 +1,2 @@
+/** CLI-only ownership: help and parser errors never start the native owner. */
+export declare function ensureWindowsCliOwnership(): Promise<void>;

package/dist/process/windows-cli-owner.js

@@ -0,0 +1,3 @@
+import{spawn as p}from"node:child_process";import{windowsOwnerExecutable as c}from"./windows-native.js";let f;export function ensureWindowsCliOwnership(){return process.platform!=="win32"?Promise.resolve():f??=h()}async function h(){const e=p(c(),[String(process.pid)],{stdio:["pipe","pipe","inherit"],detached:!0,windowsHide:!0});await new Promise((l,a)=>{let n="",d=0,i=!1,o=!1;const u=setTimeout(()=>{r(new Error("Windows CLI process ownership handshake timed out"))},1e4);function r(t){o||(o=!0,clearTimeout(u),e.stdin.destroy(),e.stdout.destroy(),e.kill(),e.unref(),a(t))}e.once("error",r),e.stdin.on("error",r),e.stdout.on("error",r),e.once("exit",(t,s)=>{r(new Error(`Windows CLI process owner exited before readiness (${String(t)}, ${String(s)})`))}),e.stdout.once("end",()=>{r(new Error("Windows CLI process owner closed its handshake before readiness"))}),e.stdout.setEncoding("utf8"),e.stdout.on("data",t=>{if(o)return;if(d+=Buffer.byteLength(t),d>32){r(new Error("Windows CLI process ownership handshake exceeded its output limit"));return}n+=t;let s;for(;(s=n.indexOf(`
+`))>=0;){const w=n.slice(0,s);if(n=n.slice(s+1),w==="PREPARED"&&!i)i=!0,e.stdin.end(`ATTACH
+`);else if(w==="READY"&&i&&n.length===0){o=!0,clearTimeout(u),e.stdout.destroy(),e.unref(),l();return}else{r(new Error("Invalid Windows CLI process ownership handshake"));return}}})})}

package/dist/process/windows-native.d.ts

@@ -0,0 +1,6 @@
+import fs from "node:fs";
+export declare function windowsOwnerExecutable(): string;
+/** Atomically publish a complete file without replacing an existing name. */
+export declare function publishWindowsFile(source: string, destination: string): void;
+/** A rename can change ctime; require stable file identity, size, and mtime. */
+export declare function sameFileAfterRename(before: Readonly<Pick<fs.BigIntStats, "dev" | "ino" | "size" | "mtimeNs">>, after: Readonly<Pick<fs.BigIntStats, "dev" | "ino" | "size" | "mtimeNs">>): boolean;

package/dist/process/windows-native.js

@@ -0,0 +1 @@
+import{execFileSync as l}from"node:child_process";import o from"node:fs";import i from"node:path";import{fileURLToPath as p}from"node:url";export function windowsOwnerExecutable(){if(!["x64","arm64"].includes(process.arch))throw new Error(`Unsupported Testkit Windows architecture: ${process.arch}`);return i.resolve(i.dirname(p(import.meta.url)),"../../bin",`testkit-windows-owner-${process.arch}.exe`)}export function publishWindowsFile(e,t){const s=o.lstatSync(e,{bigint:!0});try{l(windowsOwnerExecutable(),["publish-file",i.toNamespacedPath(i.resolve(e)),i.toNamespacedPath(i.resolve(t))],{encoding:"utf8",maxBuffer:16*1024,stdio:["ignore","pipe","pipe"],timeout:5e3,windowsHide:!0})}catch(r){if(typeof r=="object"&&r!==null&&Reflect.get(r,"status")===17)throw Object.assign(new Error("File already exists",{cause:r}),{code:"EEXIST"});try{const n={bigint:!0,throwIfNoEntry:!1},a=o.lstatSync(e,n),c=o.lstatSync(t,n);if(!a&&s.isFile()&&c?.isFile()&&sameFileAfterRename(s,c))return}catch{}throw r}}export function sameFileAfterRename(e,t){return e.ino!==0n&&e.dev===t.dev&&e.ino===t.ino&&e.size===t.size&&e.mtimeNs===t.mtimeNs}

package/dist/process/windows-process-identity.d.ts

@@ -0,0 +1,4 @@
+export declare const WINDOWS_KERNEL_PROCESS_IDENTITY_PREFIX: "windows-kernel-filetime:";
+export declare function formatWindowsKernelProcessIdentity(fileTime: string): string;
+export declare function parseWindowsKernelProcessIdentity(identity: string): string | null;
+export declare function isWindowsKernelFileTime(value: string): boolean;

package/dist/process/windows-process-identity.js

@@ -0,0 +1 @@
+export const WINDOWS_KERNEL_PROCESS_IDENTITY_PREFIX="windows-kernel-filetime:";const t=9223372036854775807n;export function formatWindowsKernelProcessIdentity(e){if(!isWindowsKernelFileTime(e))throw new Error("Windows kernel process FILETIME must be a positive signed 64-bit decimal value");return`${WINDOWS_KERNEL_PROCESS_IDENTITY_PREFIX}${e}`}export function parseWindowsKernelProcessIdentity(e){if(!e.startsWith(WINDOWS_KERNEL_PROCESS_IDENTITY_PREFIX))return null;const n=e.slice(WINDOWS_KERNEL_PROCESS_IDENTITY_PREFIX.length);return isWindowsKernelFileTime(n)?n:null}export function isWindowsKernelFileTime(e){return e.length<=19&&/^[1-9]\d*$/u.test(e)&&BigInt(e)<=t}

package/dist/repo/ci-environment.d.ts

@@ -0,0 +1,7 @@
+export interface CiGitReference {
+    readonly branch: string | null;
+    readonly pullRequest: number | null;
+}
+export declare function readCiPullRequestHeadSha(env: Readonly<NodeJS.ProcessEnv>): string | null;
+export declare function normalizePullRequestHeadSha(value: unknown): string | null;
+export declare function resolveCiGitReference(env: Readonly<NodeJS.ProcessEnv>): CiGitReference;

package/dist/repo/ci-environment.js

@@ -0,0 +1 @@
+import f from"fs";export function readCiPullRequestHeadSha(n){if(o(u(n,"GITHUB_REF"))===null)return null;const e=u(n,"GITHUB_EVENT_PATH");if(e===null)return null;try{const t=JSON.parse(f.readFileSync(e,"utf8"));if(!l(t))return null;const r=t.pull_request;if(!l(r))return null;const i=r.head;return l(i)?normalizePullRequestHeadSha(i.sha):null}catch{return null}}export function normalizePullRequestHeadSha(n){return typeof n!="string"||!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/iu.test(n)?null:n.toLowerCase()}export function resolveCiGitReference(n){const e=u(n,"GITHUB_REF"),t=c(n,["GITHUB_HEAD_REF","GITHUB_REF_NAME","GITHUB_REF","CI_COMMIT_REF_NAME"]);return{branch:s(t),pullRequest:o(e)}}function s(n){if(n===null)return null;for(const e of["refs/heads/","refs/tags/"])if(n.startsWith(e))return n.slice(e.length)||null;return n}function o(n){const e=n?.match(/^refs\/pull\/(\d+)(?:\/|$)/u);if(e==null)return null;const t=Number(e[1]);return Number.isSafeInteger(t)&&t>0?t:null}function c(n,e){for(const t of e){const r=u(n,t);if(r!==null)return r}return null}function u(n,e){const t=n[e]?.trim();return t||null}function l(n){return typeof n=="object"&&n!==null&&!Array.isArray(n)}

package/dist/repo/fingerprint-policy.d.ts

@@ -0,0 +1,15 @@
+import type { Hash } from "crypto";
+export interface FingerprintPolicy {
+    readonly exclude: readonly string[];
+    readonly include: readonly string[];
+}
+export declare function normalizeFingerprintPolicy(value?: unknown): FingerprintPolicy;
+export declare function shouldIgnoreFingerprintPath(productDir: string, absOrRelPath: string, policy?: FingerprintPolicy): boolean;
+export declare function shouldIgnoreCanonicalFingerprintPath(relativePath: string, policy?: FingerprintPolicy): boolean;
+export declare function shouldIgnoreCanonicalFingerprintPathAtPrefix(relativePath: string, addressPrefix: string, policy?: FingerprintPolicy): boolean;
+export declare function hasIncludedFingerprintDescendantAtPrefix(relativePath: string, addressPrefix: string, policy: FingerprintPolicy): boolean;
+export declare function appendFingerprintPathToHash(hash: Hash, productDir: string, absPath: string, policy?: FingerprintPolicy): void;
+export declare function normalizeRelativePath(productDir: string, absOrRelPath: string): string;
+export declare function normalizePath(value: string): string;
+export declare function appendInputToHash(hash: Hash, productDir: string, input: string, fingerprints?: unknown): void;
+export declare function appendFileToHash(hash: Hash, productDir: string, absPath: string, fingerprints?: unknown): void;

package/dist/repo/fingerprint-policy.js

@@ -0,0 +1 @@
+import y from"fs";import f from"path";import{physicalNodeMode as d,readPhysicalDirectoryEntries as b,readPhysicalNode as $}from"./physical-tree.js";const w=[".testkit",".next-testkit"],l={exclude:[],include:[]};export function normalizeFingerprintPolicy(t={}){if(t==null)return{exclude:[],include:[]};if(!S(t))throw new Error("testkit.config.ts fingerprints must be an object");return{exclude:h(t.exclude,"fingerprints.exclude"),include:h(t.include,"fingerprints.include")}}export function shouldIgnoreFingerprintPath(t,n,e=l){const r=normalizeRelativePath(t,n);return shouldIgnoreCanonicalFingerprintPath(r,e)}export function shouldIgnoreCanonicalFingerprintPath(t,n=l){return shouldIgnoreCanonicalFingerprintPathAtPrefix(t,"",n)}export function shouldIgnoreCanonicalFingerprintPathAtPrefix(t,n,e=l){const r=c(t),i=m(n,r);return!i||p(i,e.include)?!1:E(r)?!0:p(i,e.exclude)}export function hasIncludedFingerprintDescendantAtPrefix(t,n,e){const r=m(n,t);if(!r)return e.include.length>0;const i=`${r}/`;return e.include.some(s=>{const o=c(s);if(o.includes("*")){const u=A(o);return u.length===0||r.startsWith(u)||u.startsWith(i)}return P(o).startsWith(i)})}export function appendFingerprintPathToHash(t,n,e,r=l){const i=normalizeRelativePath(n,e),s=y.realpathSync.native(f.resolve(n));x(t,s,i,r)}export function normalizeRelativePath(t,n){const e=f.isAbsolute(n)?f.relative(t,n):n;return f.isAbsolute(n)?c(e.split(f.sep).join("/")):normalizePath(e)}export function normalizePath(t){return t.split(f.sep).join("/").replace(/\\/g,"/").replace(/^\.\/+/,"").replace(/\/+$/,"")}function h(t,n){if(t==null)return[];if(!F(t))throw new Error(`testkit.config.ts ${n} must be an array of paths`);return t.map((e,r)=>{if(typeof e!="string")throw new Error(`testkit.config.ts ${n}[${String(r)}] must be a string path`);const i=c(e.trim());if(!i)throw new Error(`testkit.config.ts ${n}[${String(r)}] must be a non-empty path`);if(T(i))throw new Error(`testkit.config.ts ${n}[${String(r)}] must use "/" as the path separator; a literal backslash is written doubled`);if(i.startsWith("/")||/^[a-z]:\//iu.test(i)||i.startsWith("../")||i==="..")throw new Error(`testkit.config.ts ${n}[${String(r)}] must be relative to the product directory`);return i})}function p(t,n){return n.some(e=>z(t,e))}function E(t){return p(t,w)}function z(t,n){const e=c(t),r=c(n);if(!r)return!1;const i=P(r);if(e===i||e.startsWith(`${i}/`))return!0;if(!r.includes("*"))return!1;const s=L(r);let o=e;for(;o;){if(s.test(o))return!0;const u=o.lastIndexOf("/");if(u<0)break;o=o.slice(0,u)}return!1}function c(t){return t.replace(/^\.\/+/,"").replace(/\/+$/,"")}function T(t){for(let n=0;n<t.length;n+=1)if(t[n]==="\\"){if(t[n+1]!=="\\")return!0;n+=1}return!1}function P(t){return t.replace(/\\\\/g,"\\")}function A(t){let n="";for(let e=0;e<t.length;e+=1){const r=t[e];if(r==="*")break;r==="\\"&&t[e+1]==="\\"?(n+="\\",e+=1):n+=r}return n}function x(t,n,e,r){const i=$(n,e),s=shouldIgnoreCanonicalFingerprintPath(e,r);if(!(s&&(i.kind!=="directory"||!hasIncludedFingerprintDescendantAtPrefix(e,"",r)))&&(s||I(t,e,i),i.kind==="directory"))for(const o of b(n,e))x(t,n,m(e,o),r)}function I(t,n,e){switch(t.update("node\0"),a(t,"path",n),a(t,"kind",e.kind),e.kind){case"file":a(t,"mode",d(e.mode)),g(t,"contents",e.contents);break;case"directory":a(t,"mode",d(e.mode));break;case"symlink":case"ancestor-symlink":"obstaclePath"in e&&a(t,"obstacle",e.obstaclePath),g(t,"target",e.target);break;case"ancestor-missing":a(t,"obstacle",e.obstaclePath);break;case"ancestor-non-directory":a(t,"obstacle",e.obstaclePath),a(t,"mode",d(e.mode));break;case"missing":break}}function a(t,n,e){g(t,n,Buffer.from(e))}function g(t,n,e){t.update(`${n}\0${e.byteLength.toString()}\0`),t.update(e),t.update("\0")}function m(t,n){const e=c(t),r=c(n);return e?r?`${e}/${r}`:e:r}function L(t){let n="^";for(let e=0;e<t.length;e+=1){const r=t[e],i=t[e+1];r==="\\"&&i==="\\"?(n+=k("\\"),e+=1):r==="*"&&i==="*"?(n+=".*",e+=1):r==="*"?n+="[^/]*":n+=k(r)}return n+="$",new RegExp(n)}function k(t){return t.replace(/[\\^$+?.()|[\]{}]/g,"\\$&")}function S(t){return typeof t=="object"&&t!==null&&!Array.isArray(t)}function F(t){return Array.isArray(t)}export function appendInputToHash(t,n,e,r={}){const i=f.resolve(n,e||".");appendFingerprintPathToHash(t,n,i,normalizeFingerprintPolicy(r))}export function appendFileToHash(t,n,e,r={}){appendFingerprintPathToHash(t,n,e,normalizeFingerprintPolicy(r))}

package/dist/repo/git-path.d.ts

@@ -0,0 +1,2 @@
+/** Decode one path emitted by Git with `core.quotePath=true` and no `-z`. */
+export declare function decodeGitPathRecord(value: string): string;

package/dist/repo/git-path.js

@@ -0,0 +1 @@
+import{TextDecoder as u}from"node:util";const h=new u("utf-8",{fatal:!0});export function decodeGitPathRecord(e){if(!e.startsWith('"')){let t=e.length>0;for(let n=0;n<e.length&&t;n+=1){const r=e.charCodeAt(n);t=r>=32&&r<=126&&r!==34&&r!==92}if(!t)throw new Error("Git returned an invalid unquoted path record");return e}if(e.length<2||!e.endsWith('"'))throw new Error("Git returned an unterminated quoted path record");const o=[];for(let t=1;t<e.length-1;t+=1){const n=e[t];if(n!=="\\"){const c=n.codePointAt(0);if(c===void 0||c<32||c>126)throw new Error("Git returned a non-ASCII quoted path record");o.push(c);continue}if(t+1>=e.length-1)throw new Error("Git returned a truncated path escape");const r=e[t+1],i=f(r);if(i!==null){o.push(i),t+=1;continue}const a=e.slice(t+1,t+4);if(!/^[0-7]{3}$/u.test(a))throw new Error(`Git returned an unsupported path escape: \\${r}`);o.push(Number.parseInt(a,8)),t+=3}const s=Buffer.from(o);let d;try{d=h.decode(s)}catch(t){throw new Error(`Git path is not valid UTF-8: escaped filename bytes 0x${s.toString("hex")}`,{cause:t})}if(d.includes("\0"))throw new Error("Git path records must not contain NUL bytes");return d}function f(e){switch(e){case'"':return 34;case"\\":return 92;case"a":return 7;case"b":return 8;case"t":return 9;case"n":return 10;case"v":return 11;case"f":return 12;case"r":return 13;default:return null}}

package/dist/repo/managed-git.d.ts

@@ -0,0 +1,10 @@
+import { type ManagedProcessResult } from "../process/index.js";
+export declare const DEFAULT_GIT_COMMAND_TIMEOUT_MS = 30000;
+export interface ManagedGitCommandOptions {
+    env?: Readonly<NodeJS.ProcessEnv>;
+    repositoryConfigOnly?: boolean;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export declare function runManagedGitCommand(cwd: string, args: readonly string[], options?: Readonly<ManagedGitCommandOptions>): Promise<ManagedProcessResult>;
+export declare function createManagedGitEnvironment(environment: Readonly<NodeJS.ProcessEnv>, platform?: NodeJS.Platform, repositoryConfigOnly?: boolean): NodeJS.ProcessEnv;

package/dist/repo/managed-git.js

@@ -0,0 +1 @@
+import{runManagedHostCommand as t}from"../process/index.js";export const DEFAULT_GIT_COMMAND_TIMEOUT_MS=3e4;const n=new Set(["GIT_ALTERNATE_OBJECT_DIRECTORIES","GIT_ATTR_SOURCE","GIT_COMMON_DIR","GIT_CONFIG","GIT_CONFIG_COUNT","GIT_CONFIG_GLOBAL","GIT_CONFIG_NOSYSTEM","GIT_CONFIG_PARAMETERS","GIT_CONFIG_SYSTEM","GIT_DIFF_OPTS","GIT_DIR","GIT_EXTERNAL_DIFF","GIT_GLOB_PATHSPECS","GIT_ICASE_PATHSPECS","GIT_IMPLICIT_WORK_TREE","GIT_INDEX_FILE","GIT_LITERAL_PATHSPECS","GIT_NAMESPACE","GIT_NOGLOB_PATHSPECS","GIT_NO_REPLACE_OBJECTS","GIT_OBJECT_DIRECTORY","GIT_PREFIX","GIT_QUARANTINE_PATH","GIT_REPLACE_REF_BASE","GIT_SHALLOW_FILE","GIT_WORK_TREE"]),C=new Set(["GIT_OPTIONAL_LOCKS"]);export function runManagedGitCommand(G,T,I={}){return t({args:T,cwd:G,displayLabel:L(T),env:createManagedGitEnvironment(I.env??process.env,process.platform,I.repositoryConfigOnly??!1),executable:"git",signal:I.signal,timeoutMs:I.timeoutMs??DEFAULT_GIT_COMMAND_TIMEOUT_MS})}export function createManagedGitEnvironment(G,T=process.platform,I=!1){const _={};for(const[E,O]of Object.entries(G)){const e=T==="win32"?E.toUpperCase():E;n.has(e)||/^GIT_CONFIG_(?:KEY|VALUE)_\d+$/u.test(e)||C.has(e)||e==="LANG"||e==="LC_ALL"||(_[E]=O)}if(_.LANG="C",_.LC_ALL="C",_.GIT_NO_REPLACE_OBJECTS="1",_.GIT_OPTIONAL_LOCKS="0",I){const E=T==="win32"?"NUL":"/dev/null";_.GIT_CONFIG_GLOBAL=E,_.GIT_CONFIG_NOSYSTEM="1",_.GIT_CONFIG_SYSTEM=E}return _}function L(G){const T=G.find(I=>!I.startsWith("-"));return T?`Git ${T}`:"Git command"}

package/dist/repo/metadata.d.ts

@@ -0,0 +1,3 @@
+import { type RepoState } from "./state.js";
+export type GitMetadata = Pick<RepoState, "branch" | "commitSha" | "detached" | "dirty" | "dirtyFingerprint" | "pullRequest" | "pullRequestHeadSha" | "remoteUrl" | "repository" | "repoRoot" | "worktreePath">;
+export declare function collectGitMetadata(productDir: string): Promise<GitMetadata>;

package/dist/repo/metadata.js

@@ -0,0 +1 @@
+import{collectRepoState as r}from"./state.js";export async function collectGitMetadata(e){const t=await r(e);return{branch:t.branch,commitSha:t.commitSha,pullRequest:t.pullRequest,pullRequestHeadSha:t.pullRequestHeadSha,repoRoot:t.repoRoot,remoteUrl:t.remoteUrl,repository:t.repository,detached:t.detached,dirty:t.dirty,dirtyFingerprint:t.dirtyFingerprint,worktreePath:t.worktreePath}}

package/dist/repo/physical-tree.d.ts

@@ -0,0 +1,37 @@
+export type PhysicalNode = {
+    readonly kind: "ancestor-missing";
+    readonly obstaclePath: string;
+} | {
+    readonly kind: "ancestor-non-directory";
+    readonly mode: bigint;
+    readonly obstaclePath: string;
+} | {
+    readonly kind: "ancestor-symlink";
+    readonly obstaclePath: string;
+    readonly target: Buffer;
+} | {
+    readonly identity: PhysicalNodeIdentity;
+    readonly kind: "directory";
+    readonly mode: bigint;
+} | {
+    readonly contents: Buffer;
+    readonly kind: "file";
+    readonly mode: bigint;
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "symlink";
+    readonly target: Buffer;
+};
+export interface PhysicalNodeIdentity {
+    readonly dev: bigint;
+    readonly ino: bigint;
+    readonly type: bigint;
+}
+export declare function physicalPathAndHandleIdentitiesEqual(pathIdentity: Readonly<PhysicalNodeIdentity>, handleIdentity: Readonly<PhysicalNodeIdentity>, platform: NodeJS.Platform): boolean;
+export type PhysicalNodeType = "block-device" | "character-device" | "directory" | "fifo" | "file" | "socket" | "symlink" | "unknown";
+export declare function readPhysicalNode(rootDir: string, canonicalRelativePath: string): PhysicalNode;
+export declare function readPhysicalDirectoryEntries(rootDir: string, canonicalRelativePath: string): readonly string[];
+export declare function physicalNodeMode(mode: bigint): string;
+export declare function physicalNodeType(mode: bigint): PhysicalNodeType;
+export declare function decodePhysicalPathSegment(encoded: Uint8Array, parentPath?: string): string;

package/dist/repo/physical-tree.js

@@ -0,0 +1 @@
+import i from"node:fs";import h from"node:path";export function physicalPathAndHandleIdentitiesEqual(t,n,e){return(t.dev===n.dev||e==="win32"&&t.dev===0n&&n.dev!==0n)&&t.ino===n.ino&&t.type===n.type}const w=61440n;export function readPhysicalNode(t,n){const e=D(t,n);try{if(e.obstacle)return e.obstacle;const r=e.finalStat;if(!r)return{kind:"missing"};if(r.isSymbolicLink())return{kind:"symlink",target:$(e,r)};if(r.isFile())return R(e,r);if(r.isDirectory())return u(e,r),{identity:a(r),kind:"directory",mode:r.mode};throw u(e,r),E(n,r.mode)}finally{g(e.ancestors)}}export function readPhysicalDirectoryEntries(t,n){const e=D(t,n);try{if(e.obstacle||!e.finalStat?.isDirectory())throw new Error(`Fingerprint directory is not a stable physical directory: ${n||"."}`);u(e,e.finalStat);const r=i.readdirSync(e.finalPath,{encoding:"buffer"});return u(e,e.finalStat),r.map(o=>decodePhysicalPathSegment(o,n)).sort(T)}finally{g(e.ancestors)}}export function physicalNodeMode(t){return(t&4095n).toString(8).padStart(4,"0")}export function physicalNodeType(t){switch(t&w){case 4096n:return"fifo";case 8192n:return"character-device";case 16384n:return"directory";case 24576n:return"block-device";case 32768n:return"file";case 40960n:return"symlink";case 49152n:return"socket";default:return"unknown"}}export function decodePhysicalPathSegment(t,n=""){const e=Buffer.from(t),r=e.toString("utf8");if(!Buffer.from(r,"utf8").equals(e))throw new Error(`Fingerprint paths must be valid UTF-8: ${n||"."} contains filename bytes 0x${e.toString("hex")}`);return r}function D(t,n){const e=i.realpathSync.native(h.resolve(t)),r=_(n),o=[];let c=e;try{const l=i.lstatSync(e,{bigint:!0});if(!l.isDirectory()||l.isSymbolicLink())throw new Error(`Fingerprint root is not a physical directory: ${t}`);o.push(F(e,l));const f=r.length===0?[]:r.slice(0,-1);for(const[v,N]of f.entries()){c=h.join(c,N);const p=r.slice(0,v+1).join("/"),s=k(c);if(!s)return{ancestors:o,finalPath:c,finalStat:null,obstacle:{kind:"ancestor-missing",obstaclePath:p}};if(s.isSymbolicLink())return{ancestors:o,finalPath:c,finalStat:s,obstacle:{kind:"ancestor-symlink",obstaclePath:p,target:C(c,s,o)}};if(!s.isDirectory()){if(!s.isFile())throw E(p,s.mode);return{ancestors:o,finalPath:c,finalStat:s,obstacle:{kind:"ancestor-non-directory",mode:s.mode,obstaclePath:p}}}const L=F(c,s);o.push(L),y(o)}const b=r.length?h.join(e,...r):e,O=k(b);return y(o),{ancestors:o,finalPath:b,finalStat:O,obstacle:null}}catch(l){throw g(o),l}}function F(t,n){let e=null;if(process.platform!=="win32"){const r=Reflect.get(i.constants,"O_DIRECTORY"),o=Reflect.get(i.constants,"O_NOFOLLOW"),c=typeof r=="number"?r:0,l=typeof o=="number"?o:0;e=i.openSync(t,i.constants.O_RDONLY|c|l);const f=i.fstatSync(e,{bigint:!0});if(!f.isDirectory()||!m(f,n))throw i.closeSync(e),d(t)}return{fileDescriptor:e,identity:a(n),path:t}}function R(t,n){const e=Reflect.get(i.constants,"O_NOFOLLOW"),r=typeof e=="number"?e:0,o=i.openSync(t.finalPath,i.constants.O_RDONLY|r);try{const c=i.fstatSync(o,{bigint:!0});if(!c.isFile()||!physicalPathAndHandleIdentitiesEqual(a(n),a(c),process.platform))throw d(t.finalPath);u(t,c,"handle");const l=i.readFileSync(o),f=i.fstatSync(o,{bigint:!0});if(!x(c,f))throw d(t.finalPath);return u(t,f,"handle"),{contents:l,kind:"file",mode:f.mode}}finally{i.closeSync(o)}}function $(t,n){u(t,n);const e=i.readlinkSync(t.finalPath,{encoding:"buffer"});return u(t,n),e}function C(t,n,e){y(e);const r=i.readlinkSync(t,{encoding:"buffer"}),o=i.lstatSync(t,{bigint:!0});if(!o.isSymbolicLink()||!m(o,n))throw d(t);return y(e),r}function u(t,n,e="path"){y(t.ancestors);const r=i.lstatSync(t.finalPath,{bigint:!0});if(!(e==="handle"?physicalPathAndHandleIdentitiesEqual(a(r),a(n),process.platform):m(r,n)))throw d(t.finalPath)}function y(t){for(const n of t){const e=i.lstatSync(n.path,{bigint:!0});if(!e.isDirectory()||!S(a(e),n.identity))throw d(n.path);if(n.fileDescriptor!==null){const r=i.fstatSync(n.fileDescriptor,{bigint:!0});if(!r.isDirectory()||!S(a(r),n.identity))throw d(n.path)}}}function k(t){try{return i.lstatSync(t,{bigint:!0})}catch(n){if(P(n,"ENOENT")||P(n,"ENOTDIR"))return null;throw n}}function _(t){const n=t.replace(/^\.\/+/,"").replace(/\/+$/,"");if(!n)return[];const e=n.split("/");if(e.some(r=>r.length===0||r==="."||r===".."))throw new Error(`Invalid canonical fingerprint path: ${t}`);return e}function a(t){return{dev:t.dev,ino:t.ino,type:t.mode&w}}function m(t,n){return S(a(t),a(n))}function S(t,n){return t.dev===n.dev&&t.ino===n.ino&&t.type===n.type}function x(t,n){return m(t,n)&&t.mode===n.mode&&t.size===n.size&&t.mtimeNs===n.mtimeNs&&t.ctimeNs===n.ctimeNs}function g(t){for(const n of[...t].reverse())n.fileDescriptor!==null&&i.closeSync(n.fileDescriptor)}function d(t){return new Error(`Fingerprint path changed while reading: ${t}`)}function E(t,n){return new Error(`Fingerprinting does not support special filesystem nodes: ${t||"."} (${physicalNodeType(n)})`)}function P(t,n){return t!==null&&typeof t=="object"&&"code"in t&&Reflect.get(t,"code")===n}function T(t,n){return t<n?-1:t>n?1:0}

package/dist/repo/remote.d.ts

@@ -0,0 +1,6 @@
+export interface GitRepository {
+    readonly host: string;
+    readonly name: string;
+    readonly owner: string;
+}
+export declare function parseGitRepository(remoteUrl: unknown): GitRepository | null;

package/dist/repo/remote.js

@@ -0,0 +1 @@
+export function parseGitRepository(e){if(typeof e!="string")return null;const n=e.trim();if(n.length===0)return null;const r=n.match(/^[^@/:\s]+@([^/:\s]+):([^/\s]+)\/([^/\s]+)$/u);if(r!==null)return s(r[1],r[2],r[3]);let t;try{t=new URL(n)}catch{return null}if(t.protocol!=="https:"&&t.protocol!=="ssh:"||t.search.length>0||t.hash.length>0)return null;const l=t.pathname.split("/").filter(Boolean);return l.length!==2?null:s(t.host,l[0],l[1])}function s(e,n,r){const t=r.replace(/\.git$/iu,"");return!e||!n||!t?null:{host:e,name:t,owner:n}}

package/dist/repo/state.d.ts

@@ -0,0 +1,25 @@
+import { type GitRepository } from "./remote.js";
+export type RepoStateKind = "commit" | "dirty" | "nogit";
+export interface RepoState {
+    branch: string | null;
+    cacheKey: string;
+    commitSha: string | null;
+    contentFingerprint: string | null;
+    detached: boolean;
+    dirty: boolean;
+    dirtyFingerprint: string | null;
+    kind: RepoStateKind;
+    pullRequest: number | null;
+    pullRequestHeadSha: string | null;
+    remoteUrl: string | null;
+    repository: GitRepository | null;
+    repoRoot: string | null;
+    worktreePath: string;
+}
+export type RepoStateMetadata = RepoState;
+export interface CollectRepoStateOptions {
+    env?: Readonly<NodeJS.ProcessEnv>;
+    fingerprints?: unknown;
+}
+export declare function collectRepoState(productDir: string, options?: Readonly<CollectRepoStateOptions>): Promise<RepoState>;
+export declare function summarizeRepoStateForMetadata(repoState: Readonly<RepoState> | null | undefined): RepoStateMetadata | null;