@gfdelarue/testkit 0.3.0

package/dist/toolchains/managed-node-releases.d.ts

@@ -0,0 +1,28 @@
+import type { ArchiveFormat } from "./archive.js";
+import { type LinuxLibc, type PlatformTarget } from "../process/host/platform.js";
+export interface ManagedNodeArchiveLock {
+    readonly entryCount: number;
+    readonly fileCount: number;
+    readonly format: ArchiveFormat;
+    readonly rootDirectory: string;
+    readonly sha256: string;
+    readonly sizeBytes: number;
+    readonly unpackedSizeBytes: number;
+    readonly url: string;
+}
+export interface ManagedNodeInstalledTreeLock {
+    readonly entryCount: number;
+    readonly fileCount: number;
+    readonly sha256: string;
+    readonly unpackedSizeBytes: number;
+}
+export interface ManagedNodeRelease {
+    readonly archive: ManagedNodeArchiveLock;
+    readonly installed: ManagedNodeInstalledTreeLock;
+    readonly target: PlatformTarget;
+    readonly version: string;
+}
+export declare const MANAGED_NODE_RELEASES: readonly ManagedNodeRelease[];
+export declare const MANAGED_NODE_VERSIONS: readonly string[];
+export declare function managedNodeRelease(version: string, platform?: string, arch?: string, linuxLibc?: LinuxLibc | null): ManagedNodeRelease;
+export declare function assertManagedNodeReleaseHost(release: Readonly<ManagedNodeRelease>, linuxLibc?: LinuxLibc | null): void;

package/dist/toolchains/managed-node-releases.js

@@ -0,0 +1 @@
+import{currentLinuxLibc as r}from"../process/host/platform.js";const d=Object.freeze([{version:"20.19.5",platform:"darwin",arch:"arm64",archiveSha256:"cfed7503d8d99fbcf2f52e408ec52f616058eb0867b34dbc3437259993ef5cba",archiveSizeBytes:41312337,archiveEntryCount:5370,archiveFileCount:4321,archiveUnpackedSizeBytes:151385784,installedSha256:"a61906f15df62ef2cfeab274b4f1e22c19c82cc7f6e1d9ba337ae403f53c41b6",installedEntryCount:5369,installedFileCount:4321,installedUnpackedSizeBytes:151385784},{version:"20.19.5",platform:"darwin",arch:"x64",archiveSha256:"f9cff058f2766d4d0631dc69b5f7f27664b3a42ff186e25ac7e1ac269af7e696",archiveSizeBytes:42581169,archiveEntryCount:5370,archiveFileCount:4321,archiveUnpackedSizeBytes:153879637,installedSha256:"3e32067d22562f71618cf4c598f143d583f1406c65287456a30c7d9afc9ccef4",installedEntryCount:5369,installedFileCount:4321,installedUnpackedSizeBytes:153879637},{version:"20.19.5",platform:"linux",arch:"arm64",archiveSha256:"a08b513de673853ca16395ec461a104a99bf0e941ebb7baedb98b30cd221d8cc",archiveSizeBytes:46755579,archiveEntryCount:5370,archiveFileCount:4321,archiveUnpackedSizeBytes:160418333,installedSha256:"60a45d378794f2c58255c1307043632938fca476bed31bb1d55a755319079af1",installedEntryCount:5369,installedFileCount:4321,installedUnpackedSizeBytes:160418333},{version:"20.19.5",platform:"linux",arch:"x64",archiveSha256:"4eba5fbe1fb10753bc06e42f001a91c5cec16798b7764a3e9257adc59af47fe1",archiveSizeBytes:47041607,archiveEntryCount:5370,archiveFileCount:4321,archiveUnpackedSizeBytes:160540914,installedSha256:"db0a82021f6512dbe5a5d98e81ff9ad94c38819c44830c3a17cdc3c70057dded",installedEntryCount:5369,installedFileCount:4321,installedUnpackedSizeBytes:160540914},{version:"20.19.5",platform:"win32",arch:"x64",archiveSha256:"c48159529572a5a947eef2d55d6485dfdc4ce8e67216402e2f6de52ad5d95695",archiveSizeBytes:29893678,archiveEntryCount:2459,archiveFileCount:1961,archiveUnpackedSizeBytes:82740458,installedSha256:"d8cffd11daeed876ed5313f6d44079006b3519e4d1a9e0e7fe2c376ab13e37f7",installedEntryCount:2458,installedFileCount:1961,installedUnpackedSizeBytes:82740458},{version:"22.15.0",platform:"darwin",arch:"arm64",archiveSha256:"92eb58f54d172ed9dee320b8450f1390db629d4262c936d5c074b25a110fed02",archiveSizeBytes:47255175,archiveEntryCount:5928,archiveFileCount:4807,archiveUnpackedSizeBytes:173878232,installedSha256:"92e788484fe388a8a5e1e916aa4c82caceb7123cfa07bd39766eb55f660967f6",installedEntryCount:5927,installedFileCount:4807,installedUnpackedSizeBytes:173878232},{version:"22.15.0",platform:"darwin",arch:"x64",archiveSha256:"f7f42bee60d602783d3a842f0a02a2ecd9cb9d7f6f3088686c79295b0222facf",archiveSizeBytes:48910168,archiveEntryCount:5928,archiveFileCount:4807,archiveUnpackedSizeBytes:176964981,installedSha256:"8df7035c583aa1a75897e3aaf43568ecd265a4b386c42ee320e978f200e06c0f",installedEntryCount:5927,installedFileCount:4807,installedUnpackedSizeBytes:176964981},{version:"22.15.0",platform:"linux",arch:"arm64",archiveSha256:"c3582722db988ed1eaefd590b877b86aaace65f68746726c1f8c79d26e5cc7de",archiveSizeBytes:53731858,archiveEntryCount:5928,archiveFileCount:4807,archiveUnpackedSizeBytes:182760293,installedSha256:"fd71287680806d108856efee4e28c15c91c425a2cdb26f048092c466b16a6eda",installedEntryCount:5927,installedFileCount:4807,installedUnpackedSizeBytes:182760293},{version:"22.15.0",platform:"linux",arch:"x64",archiveSha256:"29d1c60c5b64ccdb0bc4e5495135e68e08a872e0ae91f45d9ec34fc135a17981",archiveSizeBytes:54287190,archiveEntryCount:5928,archiveFileCount:4807,archiveUnpackedSizeBytes:185675662,installedSha256:"69eb244bca48185cdbe273dd8886b4b0f01e48dd095dca856547c273dc54717f",installedEntryCount:5927,installedFileCount:4807,installedUnpackedSizeBytes:185675662},{version:"22.15.0",platform:"win32",arch:"x64",archiveSha256:"06067d4f0d463f90ed803d5eca5b039a05dec5d70fc7b7cc254803a59bd0e27c",archiveSizeBytes:35137600,archiveEntryCount:3017,archiveFileCount:2447,archiveUnpackedSizeBytes:97767612,installedSha256:"a5378a61ddbd0f1d536e5e747164c97f07633aaf43cad737a8322a8dcf4bfc40",installedEntryCount:3016,installedFileCount:2447,installedUnpackedSizeBytes:97767612},{version:"24.14.1",platform:"darwin",arch:"arm64",archiveSha256:"25495ff85bd89e2d8a24d88566d7e2f827c6b0d3d872b2cebf75371f93fcb1fe",archiveSizeBytes:51193489,archiveEntryCount:5617,archiveFileCount:4556,archiveUnpackedSizeBytes:190084527,installedSha256:"13d3d356e0af18c69a9ff7684f71e97a04b1f3588a33919604fcba8d189f8a16",installedEntryCount:5616,installedFileCount:4556,installedUnpackedSizeBytes:190084527},{version:"24.14.1",platform:"darwin",arch:"x64",archiveSha256:"2526230ad7d922be82d4fdb1e7ee1e84303e133e3b4b0ec4c2897ab31de0253d",archiveSizeBytes:52370789,archiveEntryCount:5617,archiveFileCount:4556,archiveUnpackedSizeBytes:192410700,installedSha256:"d5887ab3ac16dafb82d9d254b1587c1dc01aaa8399124a9b81ecc54ab9ac777b",installedEntryCount:5616,installedFileCount:4556,installedUnpackedSizeBytes:192410700},{version:"24.14.1",platform:"linux",arch:"arm64",archiveSha256:"734ff04fa7f8ed2e8a78d40cacf5ac3fc4515dac2858757cbab313eb483ba8a2",archiveSizeBytes:56098426,archiveEntryCount:5617,archiveFileCount:4556,archiveUnpackedSizeBytes:190794015,installedSha256:"b83f8585b6b47163b2439da0efd5d6b36c86e760bb5493fb411d12f0db968ec4",installedEntryCount:5616,installedFileCount:4556,installedUnpackedSizeBytes:190794015},{version:"24.14.1",platform:"linux",arch:"x64",archiveSha256:"ace9fa104992ed0829642629c46ca7bd7fd6e76278cb96c958c4b387d29658ea",archiveSizeBytes:56320534,archiveEntryCount:5617,archiveFileCount:4556,archiveUnpackedSizeBytes:193418491,installedSha256:"4bf6b050c7df984136a4b05ffd643282a321158e8b5add6aa63fb0113eb26600",installedEntryCount:5616,installedFileCount:4556,installedUnpackedSizeBytes:193418491},{version:"24.14.1",platform:"win32",arch:"x64",archiveSha256:"6e50ce5498c0cebc20fd39ab3ff5df836ed2f8a31aa093cecad8497cff126d70",archiveSizeBytes:36358527,archiveEntryCount:2292,archiveFileCount:1837,archiveUnpackedSizeBytes:103281800,installedSha256:"47c36e2f1ac85270816fdef7ccd91953194601598ae51aa7b82bd628b480568a",installedEntryCount:2291,installedFileCount:1837,installedUnpackedSizeBytes:103281800}]);export const MANAGED_NODE_RELEASES=Object.freeze(d.map(l)),MANAGED_NODE_VERSIONS=Object.freeze([...new Set(MANAGED_NODE_RELEASES.map(e=>e.version))].sort());export function managedNodeRelease(e,a=process.platform,c=process.arch,t=r()){const i=MANAGED_NODE_RELEASES.find(n=>n.version===e&&n.target.platform===a&&n.target.arch===c);if(i!==void 0)return assertManagedNodeReleaseHost(i,t),i;throw new Error(`Node ${e} is not in Testkit's trusted managed-toolchain manifest for ${a}/${c}. Trusted versions: ${MANAGED_NODE_VERSIONS.join(", ")}`)}export function assertManagedNodeReleaseHost(e,a=r()){if(!(e.target.platform!=="linux"||a==="glibc"))throw new Error(`Managed Node ${e.version} is unavailable on Linux ${a??"with unknown libc"}: the trusted official Node Linux archives require glibc, and Testkit does not substitute a musl build.`)}function l(e){const a=e.platform==="win32"?"win":e.platform,c=e.platform==="win32"?"zip":"tar.gz",t=c==="zip"?".zip":".tar.gz",i=`node-v${e.version}-${a}-${e.arch}`;return Object.freeze({archive:Object.freeze({entryCount:e.archiveEntryCount,fileCount:e.archiveFileCount,format:c,rootDirectory:i,sha256:e.archiveSha256,sizeBytes:e.archiveSizeBytes,unpackedSizeBytes:e.archiveUnpackedSizeBytes,url:`https://nodejs.org/dist/v${e.version}/${i}${t}`}),installed:Object.freeze({entryCount:e.installedEntryCount,fileCount:e.installedFileCount,sha256:e.installedSha256,unpackedSizeBytes:e.installedUnpackedSizeBytes}),target:Object.freeze({arch:e.arch,platform:e.platform}),version:e.version})}

package/dist/toolchains/node-cache.d.ts

@@ -0,0 +1,20 @@
+import type { ManagedNodeRelease } from "./managed-node-releases.js";
+export declare const NODE_TOOLCHAIN_CONTENT_DIRECTORY = "content";
+export declare const NODE_TOOLCHAIN_MARKER_FILENAME = "toolchain.json";
+export interface NodeToolchainCachePaths {
+    readonly contentDirectory: string;
+    readonly installDirectory: string;
+    readonly lockPath: string;
+    readonly manifestPath: string;
+    readonly rootDirectory: string;
+}
+export declare function prepareNodeToolchainCache(productDir: string, release: Readonly<ManagedNodeRelease>): NodeToolchainCachePaths;
+export declare function nodeToolchainCacheKey(paths: Readonly<NodeToolchainCachePaths>): string;
+export declare function existingRealInstallDirectory(paths: Readonly<NodeToolchainCachePaths>): boolean;
+export declare function requireRealContentDirectory(paths: Readonly<NodeToolchainCachePaths>): void;
+export declare function readRealManifestFile(paths: Readonly<NodeToolchainCachePaths>): string | null;
+export declare function removeContainedInstallDirectory(paths: Readonly<NodeToolchainCachePaths>): void;
+export declare function createContainedTemporaryDirectory(rootDirectory: string, prefix: string): string;
+export declare function requireContainedExecutable(contentDirectory: string, relativePath: string, options: Readonly<{
+    allowSymbolicLink: boolean;
+}>): string;

package/dist/toolchains/node-cache.js

@@ -0,0 +1 @@
+import h from"node:crypto";import i from"node:fs";import c from"node:path";import{isPathWithin as u}from"../process/files/paths.js";export const NODE_TOOLCHAIN_CONTENT_DIRECTORY="content",NODE_TOOLCHAIN_MARKER_FILENAME="toolchain.json";export function prepareNodeToolchainCache(t,o){const n=E(t,"Product directory"),r=m(n,[".testkit","_toolchains","node"]),e=c.join(r,`${o.version}-${o.target.platform}-${o.target.arch}`);return{contentDirectory:c.join(e,NODE_TOOLCHAIN_CONTENT_DIRECTORY),installDirectory:e,lockPath:`${e}.lock`,manifestPath:c.join(e,NODE_TOOLCHAIN_MARKER_FILENAME),rootDirectory:r}}export function nodeToolchainCacheKey(t){return t.installDirectory}export function existingRealInstallDirectory(t){const o=s(t.installDirectory);if(o===null)return!1;if(o.isSymbolicLink()||!o.isDirectory())throw new Error(`Managed Node toolchain cache entry must be a real directory: ${t.installDirectory}`);return l(t.rootDirectory,t.installDirectory),!0}export function requireRealContentDirectory(t){const o=s(t.contentDirectory);if(o===null||o.isSymbolicLink()||!o.isDirectory())throw new Error(`Managed Node toolchain content must be a real directory: ${t.contentDirectory}`);l(t.installDirectory,t.contentDirectory)}export function readRealManifestFile(t){const o=s(t.manifestPath);if(o===null)return null;if(o.isSymbolicLink()||!o.isFile())throw new Error(`Managed Node toolchain manifest must be a regular file: ${t.manifestPath}`);return l(t.installDirectory,t.manifestPath),i.readFileSync(t.manifestPath,"utf8")}export function removeContainedInstallDirectory(t){existingRealInstallDirectory(t)&&i.rmSync(t.installDirectory,{recursive:!0,force:!1})}export function createContainedTemporaryDirectory(t,o){for(let n=0;n<10;n+=1){const r=c.join(t,`${o}-${h.randomUUID()}`);try{return i.mkdirSync(r,{mode:448}),l(t,r),r}catch(e){if(!w(e))throw e}}throw new Error("Could not allocate a unique Node toolchain directory")}export function requireContainedExecutable(t,o,n){const r=c.resolve(t,o);if(!u(t,r))throw new Error("Managed Node toolchain executable escapes its content root");const e=i.lstatSync(r);if(e.isSymbolicLink()&&!n.allowSymbolicLink)throw new Error(`Managed Node toolchain executable must not be a symbolic link: ${o}`);if(!e.isFile()&&!e.isSymbolicLink())throw new Error(`Managed Node toolchain executable must be file-backed: ${o}`);const a=i.realpathSync(t),y=i.realpathSync(r);if(!u(a,y))throw new Error(`Managed Node toolchain executable escapes its content root: ${o}`);const d=i.statSync(r);if(!d.isFile())throw new Error(`Managed Node toolchain executable is not backed by a regular file: ${o}`);if(process.platform!=="win32"&&(d.mode&73)===0)throw new Error(`Managed Node toolchain executable is not executable: ${o}`);return r}function m(t,o){let n=t;for(const r of o){const e=c.join(n,r),a=s(e);if(a===null)i.mkdirSync(e,{mode:448});else if(a.isSymbolicLink()||!a.isDirectory())throw new Error(`Managed Node toolchain cache path must be a real directory: ${e}`);l(t,e),n=e}return n}function E(t,o){const n=c.resolve(t),r=i.realpathSync(n),e=i.lstatSync(r);if(!e.isDirectory()||e.isSymbolicLink())throw new Error(`${o} must be a real directory: ${t}`);return r}function l(t,o){const n=i.realpathSync(t),r=i.realpathSync(o);if(!u(n,r))throw new Error(`Managed Node toolchain cache path escapes the product directory: ${o}`)}function s(t){try{return i.lstatSync(t)}catch(o){if(b(o))return null;throw o}}function w(t){return f(t)&&t.code==="EEXIST"}function b(t){return f(t)&&t.code==="ENOENT"}function f(t){return t instanceof Error&&"code"in t}

package/dist/toolchains/node-integrity.d.ts

@@ -0,0 +1,16 @@
+import { type ArchiveEntry } from "./archive.js";
+import type { ManagedNodeInstalledTreeLock, ManagedNodeRelease } from "./managed-node-releases.js";
+export interface InstalledNodeTreeLimits {
+    readonly maxEntries: number;
+    readonly maxFiles: number;
+    readonly maxUnpackedSizeBytes: number;
+}
+export interface InstalledNodeTreeInspection {
+    readonly entryCount: number;
+    readonly fileCount: number;
+    readonly sha256: string;
+    readonly unpackedSizeBytes: number;
+}
+export declare function validateNodeArchiveEntries(entries: readonly ArchiveEntry[], release: Readonly<ManagedNodeRelease>): void;
+export declare function inspectInstalledNodeTree(root: string, limits: Readonly<InstalledNodeTreeLimits>, signal?: AbortSignal): Promise<InstalledNodeTreeInspection>;
+export declare function verifyInstalledNodeTree(root: string, expected: Readonly<ManagedNodeInstalledTreeLock>, signal?: AbortSignal): Promise<void>;

package/dist/toolchains/node-integrity.js

@@ -0,0 +1 @@
+import O from"node:crypto";import h from"node:fs";import p from"node:path";import{normalizeArchivePath as J,portableCollisionKey as z,requireSafeMode as j,requireSafeSize as B}from"./archive.js";import{isPathWithin as x}from"../process/files/paths.js";import{throwIfSignalAborted as k}from"./shared-operation.js";const M=128,I=new Map([["bin/corepack","../lib/node_modules/corepack/dist/corepack.js"],["bin/npm","../lib/node_modules/npm/bin/npm-cli.js"],["bin/npx","../lib/node_modules/npm/bin/npx-cli.js"]]);export function validateNodeArchiveEntries(n,t){const i=t.archive;let e=0,a=0;const c=new Map,w=new Map;if(n.length!==i.entryCount)throw E(n.length,e,0,t);for(const o of n){const r=J(o.path);if(r!==i.rootDirectory&&!r.startsWith(`${i.rootDirectory}/`))throw new Error(`Node archive entry escapes its locked root: ${JSON.stringify(r)}`);j(o.mode,r),B(o.sizeBytes,r);const l=z(r),f=w.get(l);if(f!==void 0)throw new Error(`Node archive contains colliding paths ${JSON.stringify(f)} and ${JSON.stringify(r)}`);if(w.set(l,r),c.set(r,o),o.kind==="forbidden")throw new Error(`Node archive entry ${JSON.stringify(r)} has forbidden type ${JSON.stringify(o.rawType)}`);if(o.kind==="directory"){if(o.sizeBytes!==0||o.linkTarget!==void 0)throw new Error(`Node archive directory ${JSON.stringify(r)} has invalid metadata`);continue}if(o.kind==="file"){if(o.linkTarget!==void 0)throw new Error(`Node archive file ${JSON.stringify(r)} has link metadata`);e+=1,a+=o.sizeBytes,C(n.length,e,a,t);continue}const g=r.slice(i.rootDirectory.length+1),d=I.get(g);if(d===void 0||o.linkTarget!==d||o.sizeBytes!==Buffer.byteLength(d,"utf8"))throw new Error(`Node archive contains an unsupported symbolic link at ${JSON.stringify(r)}`);T(r,d,i.rootDirectory),a+=o.sizeBytes,C(n.length,e,a,t)}if(c.get(i.rootDirectory)?.kind!=="directory")throw new Error("Node archive is missing its locked root directory");for(const[o]of c)for(const r of P(o)){const l=c.get(r);if(l?.kind==="file")throw new Error(`Node archive entry ${JSON.stringify(o)} has a file ancestor`);if(l?.kind==="symlink")throw new Error(`Node archive entry ${JSON.stringify(o)} would write through a symbolic link`)}if(e!==i.fileCount||a!==i.unpackedSizeBytes)throw E(n.length,e,a,t)}export async function inspectInstalledNodeTree(n,t,i){F(t);const e=await h.promises.lstat(n);if(!e.isDirectory()||e.isSymbolicLink())throw new Error("Installed Node toolchain content must be a real directory");const a=await h.promises.realpath(n),c=[],w=new Map;let m=0,o=0;return await r(n,""),c.sort((l,f)=>L(l.path,f.path)),{entryCount:c.length,fileCount:m,sha256:O.createHash("sha256").update(JSON.stringify(c)).digest("hex"),unpackedSizeBytes:o};async function r(l,f){k(i);const g=await h.promises.readdir(l,{withFileTypes:!0});g.sort((d,S)=>L(d.name,S.name));for(const d of g){k(i);const S=f?`${f}/${d.name}`:d.name,s=J(S),b=z(s),v=w.get(b);if(v!==void 0)throw new Error(`Installed Node toolchain contains colliding paths ${JSON.stringify(v)} and ${JSON.stringify(s)}`);w.set(b,s);const y=p.join(l,d.name);if(!x(n,y))throw new Error(`Installed Node toolchain path escapes its root: ${JSON.stringify(s)}`);const u=await h.promises.lstat(y);if(u.isSymbolicLink()){const N=await h.promises.readlink(y),$=I.get(s);if($===void 0||N!==$)throw new Error(`Installed Node toolchain contains an unsupported symbolic link at ${JSON.stringify(s)}`);T(s,N,".");const _=await h.promises.realpath(y);if(!x(a,_))throw new Error(`Installed Node toolchain symbolic link escapes its root: ${JSON.stringify(s)}`);if(!(await h.promises.stat(y)).isFile())throw new Error(`Installed Node toolchain symbolic link is not file-backed: ${JSON.stringify(s)}`);o+=Buffer.byteLength(N,"utf8"),c.push({kind:"symlink",path:s,target:N})}else if(u.isDirectory()){c.push({kind:"directory",path:s}),A(c.length,m,o,t),await r(y,s);continue}else if(u.isFile()){if(u.nlink!==1)throw new Error(`Installed Node toolchain contains a multiply-linked file at ${JSON.stringify(s)}`);m+=1,o+=B(u.size,s),c.push({kind:"file",path:s,sha256:await W(y,i),sizeBytes:u.size})}else throw new Error(`Installed Node toolchain contains a special file at ${JSON.stringify(s)}`);A(c.length,m,o,t)}}}export async function verifyInstalledNodeTree(n,t,i){const e=await inspectInstalledNodeTree(n,{maxEntries:t.entryCount,maxFiles:t.fileCount,maxUnpackedSizeBytes:t.unpackedSizeBytes},i);if(e.entryCount!==t.entryCount||e.fileCount!==t.fileCount||e.unpackedSizeBytes!==t.unpackedSizeBytes||e.sha256!==t.sha256)throw new Error(`Installed Node toolchain does not match its trusted tree digest and shape: expected ${JSON.stringify(t)}, received ${JSON.stringify(e)}`)}function T(n,t,i){if(p.posix.isAbsolute(t)||p.win32.isAbsolute(t)||t.includes("\0"))throw new Error(`Node toolchain symbolic link has an absolute target at ${JSON.stringify(n)}`);const e=p.posix.normalize(p.posix.join(p.posix.dirname(n),t));if(i==="."?e===".."||e.startsWith("../"):e!==i&&!e.startsWith(`${i}/`))throw new Error(`Node toolchain symbolic link escapes its root at ${JSON.stringify(n)}`)}function P(n){const t=n.split("/");if(t.length>M)throw new Error("Node archive path has too many segments");const i=[];for(let e=1;e<t.length;e+=1)i.push(t.slice(0,e).join("/"));return i}function C(n,t,i,e){const a=e.archive;if(n>a.entryCount||t>a.fileCount||i>a.unpackedSizeBytes)throw E(n,t,i,e)}function A(n,t,i,e){if(n>e.maxEntries||t>e.maxFiles||i>e.maxUnpackedSizeBytes)throw new Error("Installed Node toolchain exceeds its locked tree shape")}function E(n,t,i,e){return new Error(`Node ${e.version} archive shape mismatch: received ${n.toString()} entries, ${t.toString()} files, and ${i.toString()} unpacked bytes`)}function F(n){for(const[t,i]of Object.entries(n))if(!Number.isSafeInteger(i)||i<0)throw new Error(`${t} must be a non-negative safe integer`)}async function W(n,t){const i=O.createHash("sha256"),e=h.createReadStream(n),a=()=>e.destroy(t?.reason);t?.addEventListener("abort",a,{once:!0});try{for await(const c of e)k(t),i.update(c);return i.digest("hex")}finally{t?.removeEventListener("abort",a)}}function L(n,t){return n<t?-1:n>t?1:0}

package/dist/toolchains/node-provisioning.d.ts

@@ -0,0 +1,29 @@
+import { type ArchiveExtractor } from "./archive.js";
+import type { ProvisionedNodeToolchain, ToolchainCommandExecutor, ToolchainCommandOptions, ToolchainEnvironment, ToolchainFetch } from "./index.js";
+import type { ManagedNodeRelease } from "./managed-node-releases.js";
+export interface ProvisionNodeToolchainWithReleaseOptions {
+    readonly archiveTimeoutMs?: number;
+    readonly commandExecutor: ToolchainCommandExecutor;
+    readonly fetchImpl: ToolchainFetch;
+    readonly productDir: string;
+    readonly release: ManagedNodeRelease;
+    readonly signal?: AbortSignal;
+    readonly zipExtractor?: ArchiveExtractor;
+}
+export interface ExtractTrustedNodeArchiveOptions {
+    readonly archivePath: string;
+    readonly commandExecutor: ToolchainCommandExecutor;
+    readonly destination: string;
+    readonly release: ManagedNodeRelease;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly zipExtractor?: ArchiveExtractor;
+}
+export declare function provisionNodeToolchainWithRelease({ archiveTimeoutMs, commandExecutor, fetchImpl, productDir, release, signal, zipExtractor, }: Readonly<ProvisionNodeToolchainWithReleaseOptions>): Promise<ProvisionedNodeToolchain>;
+export declare function extractTrustedNodeArchive({ archivePath, commandExecutor, destination, release, signal, timeoutMs, zipExtractor, }: Readonly<ExtractTrustedNodeArchiveOptions>): Promise<void>;
+export declare function renameNodeToolchainPublishDirectory(source: string, destination: string, signal?: AbortSignal): Promise<void>;
+export declare function nodeToolchainPublishRetryDelay(error: unknown, platform: NodeJS.Platform, attempt: number): number | null;
+export declare function nodeToolchainVersionInvocation(cwd: string, binDir: string, env: Readonly<ToolchainEnvironment>, prefixArgs?: readonly string[]): {
+    args: string[];
+    options: ToolchainCommandOptions;
+};

package/dist/toolchains/node-provisioning.js

@@ -0,0 +1,2 @@
+import _ from"node:crypto";import u from"node:fs";import h from"node:path";import{TarArchiveInspector as I,ZipArchiveExtractor as V}from"./archive.js";import{withProcessLock as k}from"../process/locks.js";import{createContainedTemporaryDirectory as z,existingRealInstallDirectory as M,NODE_TOOLCHAIN_CONTENT_DIRECTORY as B,NODE_TOOLCHAIN_MARKER_FILENAME as R,nodeToolchainCacheKey as $,prepareNodeToolchainCache as L,readRealManifestFile as P,removeContainedInstallDirectory as j,requireContainedExecutable as v,requireRealContentDirectory as H}from"./node-cache.js";import{validateNodeArchiveEntries as F,verifyInstalledNodeTree as S}from"./node-integrity.js";import{createSharedToolchainOperation as U,throwIfSignalAborted as m,waitForPromise as f,waitForSharedToolchainOperation as Y}from"./shared-operation.js";import{TOOLCHAIN_METADATA_TIMEOUT_MS as q}from"./timeouts.js";const w=2,g=300*1e3,J=Object.freeze([100,250,500,1e3,2e3,3e3,3e3]),y=new Map;export async function provisionNodeToolchainWithRelease({archiveTimeoutMs:e=g,commandExecutor:r,fetchImpl:t,productDir:n,release:o,signal:i,zipExtractor:a}){m(i);const c=L(n,o),l=$(c);let s=y.get(l);if(s===void 0){s=U(C=>K({archiveTimeoutMs:e,commandExecutor:r,fetchImpl:t,paths:c,productDir:n,release:o,signal:C,zipExtractor:a})),y.set(l,s);const d=s;s.promise.then(()=>{N(l,d)},()=>{N(l,d)})}return Y(s,i)}export async function extractTrustedNodeArchive({archivePath:e,commandExecutor:r,destination:t,release:n,signal:o,timeoutMs:i=g,zipExtractor:a=new V}){if(ne(i),u.existsSync(t))throw new Error(`Node archive destination already exists: ${t}`);u.mkdirSync(t,{mode:448});const c=AbortSignal.timeout(i),l=o===void 0?c:AbortSignal.any([o,c]),s=n.archive.format==="zip"?a:new I;try{const d=await s.inspect(e,n.archive.format,{maxEntries:n.archive.entryCount,maxUnpackedSizeBytes:n.archive.unpackedSizeBytes,signal:l});F(d,n),n.archive.format==="zip"?await a.extract(e,t,n.archive.format,{maxEntries:n.archive.entryCount,maxUnpackedSizeBytes:n.archive.unpackedSizeBytes,signal:l}):(await r("tar",["-xzf",e,"-C",t],{cwd:h.dirname(t),env:process.env,signal:l,timeoutMs:i}),m(l))}catch(d){throw u.rmSync(t,{recursive:!0,force:!0}),d}}async function K(e){const r=await E(e.paths,e.release,e.commandExecutor,e.signal);return r!==null?r:k(e.paths.lockPath,async()=>{const t=await E(e.paths,e.release,e.commandExecutor,e.signal);return t!==null?t:(j(e.paths),W(e))},{signal:e.signal,timeoutMs:null})}async function W(e){const r=z(e.paths.rootDirectory,`.tmp-${e.release.version}`),t=e.release.archive.format==="zip"?".zip":".tar.gz",n=h.join(r,`node${t}`),o=h.join(r,"extracted"),i=h.join(r,"publish"),a=h.join(i,B);try{const c=await f(e.fetchImpl(e.release.archive.url,{signal:e.signal}),e.signal);if(!c.ok)throw new Error(`Failed to download ${e.release.archive.url}: HTTP ${String(c.status)}`);await Z(c,n,e.release,e.signal),await extractTrustedNodeArchive({archivePath:n,commandExecutor:e.commandExecutor,destination:o,release:e.release,signal:e.signal,timeoutMs:e.archiveTimeoutMs,zipExtractor:e.zipExtractor});const l=h.join(o,e.release.archive.rootDirectory);te(o,l),await S(l,e.release.installed,e.signal),u.mkdirSync(i,{mode:448}),u.renameSync(l,a),u.rmSync(o,{recursive:!0,force:!0}),u.rmSync(n,{force:!0});const s=b(a,e.release),d=await x(a,s,e.release,e.commandExecutor,e.signal);return X(h.join(i,R),Q(e.release,d.npmVersion)),await renameNodeToolchainPublishDirectory(i,e.paths.installDirectory,e.signal),{binDir:p(e.paths.contentDirectory,e.release),nodeExecutable:h.join(e.paths.contentDirectory,s.nodeRelativePath),npmVersion:d.npmVersion,toolchainDir:e.paths.installDirectory}}finally{u.rmSync(r,{recursive:!0,force:!0})}}export async function renameNodeToolchainPublishDirectory(e,r,t){for(let n=0;;n+=1){m(t);try{await u.promises.rename(e,r);return}catch(o){const i=nodeToolchainPublishRetryDelay(o,process.platform,n);if(i===null)throw o;await f(new Promise(a=>setTimeout(a,i)),t)}}}export function nodeToolchainPublishRetryDelay(e,r,t){if(r!=="win32"||!(e instanceof Error))return null;const n=e.code;return n!=="EACCES"&&n!=="EBUSY"&&n!=="EPERM"?null:J[t]??null}async function E(e,r,t,n){if(!M(e))return null;const o=P(e);if(o===null)return null;const i=ee(o);if(i===null||!re(i,r))return null;H(e);try{await S(e.contentDirectory,r.installed,n)}catch{return m(n),null}const a=b(e.contentDirectory,r),c=await x(e.contentDirectory,a,r,t,n);return c.npmVersion!==i.npmVersion?null:{binDir:p(e.contentDirectory,r),nodeExecutable:a.nodeExecutable,npmVersion:c.npmVersion,toolchainDir:e.installDirectory}}async function Z(e,r,t,n){const o=[];let i=0;if(e.body!==void 0&&e.body!==null){const l=e.body[Symbol.asyncIterator]();for(;;){const s=await f(l.next(),n);if(s.done)break;if(!(s.value instanceof Uint8Array))throw new Error("Node toolchain download yielded a non-binary chunk");const d=Buffer.from(s.value.buffer,s.value.byteOffset,s.value.byteLength);if(i+=d.byteLength,i>t.archive.sizeBytes)throw await l.return?.(),new Error(`Node toolchain archive exceeds its trusted ${t.archive.sizeBytes.toString()} byte size`);o.push(d)}}else{const l=await f(e.arrayBuffer(),n),s=Buffer.from(l);i=s.byteLength,i<=t.archive.sizeBytes&&o.push(s)}if(i!==t.archive.sizeBytes)throw new Error(`Node toolchain archive size mismatch: expected ${t.archive.sizeBytes.toString()}, received ${i.toString()}`);const a=Buffer.concat(o,i),c=_.createHash("sha256").update(a).digest("hex");if(c!==t.archive.sha256)throw new Error(`Node toolchain archive digest mismatch: expected ${t.archive.sha256}, received ${c}`);m(n),u.writeFileSync(r,a,{flag:"wx",mode:384})}function b(e,r){const t=r.target.platform==="win32"?"node.exe":"bin/node",n=r.target.platform==="win32"?"npm.cmd":"bin/npm";return{nodeExecutable:v(e,t,{allowSymbolicLink:!1}),nodeRelativePath:t,npmCli:r.target.platform==="win32"?v(e,"node_modules/npm/bin/npm-cli.js",{allowSymbolicLink:!1}):null,npmExecutable:v(e,n,{allowSymbolicLink:r.target.platform!=="win32"})}}async function x(e,r,t,n,o){const i=p(e,t),a=await T(r.nodeExecutable,e,i,n,o);if(a!==t.version)throw new Error(`Downloaded Node toolchain version mismatch: expected ${t.version}, received ${a}`);return{npmVersion:await T(r.npmCli===null?r.npmExecutable:r.nodeExecutable,e,i,n,o,r.npmCli===null?[]:[r.npmCli])}}async function T(e,r,t,n,o,i=[]){const a=nodeToolchainVersionInvocation(r,t,process.env,i),c=await n(e,a.args,{...a.options,signal:o});return G(typeof c.stdout=="string"?c.stdout:Buffer.from(c.stdout??"").toString())}export function nodeToolchainVersionInvocation(e,r,t,n=[]){const o=(t.PATH??"").split(h.delimiter).filter(i=>i.length>0&&i!==r);return{args:[...n,"--version"],options:{cwd:e,env:{...t,PATH:[r,...o].join(h.delimiter)},stdio:"pipe",timeoutMs:q,windowsHide:!0}}}function G(e){const r=e.trim().replace(/^v/u,"");if(!/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/u.test(r))throw new Error(`Toolchain command returned an invalid version: ${JSON.stringify(e)}`);return r}function p(e,r){return r.target.platform==="win32"?e:h.join(e,"bin")}function Q(e,r){return{arch:e.target.arch,archiveSha256:e.archive.sha256,installedSha256:e.installed.sha256,npmVersion:r,platform:e.target.platform,schemaVersion:w,version:e.version}}function X(e,r){u.writeFileSync(e,`${JSON.stringify(r,null,2)}
+`,{encoding:"utf8",flag:"wx",mode:384})}function ee(e){let r;try{r=JSON.parse(e)}catch{return null}if(!ie(r))return null;const t=["arch","archiveSha256","installedSha256","npmVersion","platform","schemaVersion","version"],n=Object.keys(r).filter(o=>o!=="kind").sort();return n.length!==t.length||n.some((o,i)=>o!==t[i])||r.schemaVersion!==w||!D(r.arch)||!O(r.archiveSha256)||!O(r.installedSha256)||!A(r.npmVersion)||!D(r.platform)||!A(r.version)?null:{arch:r.arch,archiveSha256:r.archiveSha256,installedSha256:r.installedSha256,npmVersion:r.npmVersion,platform:r.platform,schemaVersion:w,version:r.version}}function re(e,r){return e.version===r.version&&e.platform===r.target.platform&&e.arch===r.target.arch&&e.archiveSha256===r.archive.sha256&&e.installedSha256===r.installed.sha256}function te(e,r){const t=u.readdirSync(e);if(t.length!==1||t[0]!==h.basename(r)||!u.lstatSync(r).isDirectory()||u.lstatSync(r).isSymbolicLink())throw new Error(`Expected Node archive to contain only ${h.basename(r)}`)}function N(e,r){y.get(e)===r&&y.delete(e)}function ne(e){if(!Number.isSafeInteger(e)||e<=0)throw new Error("Node archive timeout must be a positive safe integer")}function ie(e){return e!==null&&typeof e=="object"&&!Array.isArray(e)}function D(e){return typeof e=="string"&&e.length>0}function O(e){return typeof e=="string"&&/^[a-f0-9]{64}$/u.test(e)}function A(e){return typeof e=="string"&&/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/u.test(e)}

package/dist/toolchains/semver.d.ts

@@ -0,0 +1,13 @@
+export interface SemverVersion {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+}
+export type SemverInput = string | SemverVersion;
+export declare function normalizeSemver(input: unknown): string;
+export declare function isExactSemver(input: unknown): boolean;
+export declare function parseSemver(input: unknown): SemverVersion;
+export declare function compareSemver(left: SemverInput, right: SemverInput): number;
+export declare function formatSemver(version: SemverInput): string;
+export declare function satisfiesSemver(version: SemverInput, spec: unknown): boolean;
+export declare function deriveSemverMinimum(spec: unknown): string | null;

package/dist/toolchains/semver.js

@@ -0,0 +1 @@
+const c=String;export function normalizeSemver(r){return formatSemver(parseSemver(r))}export function isExactSemver(r){try{return parseSemver(r),!0}catch{return!1}}export function parseSemver(r){const e=c(r||"").trim().replace(/^v/iu,"").match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/u);if(!e)throw u(r);const o=Number.parseInt(e[1],10),n=Number.parseInt(e[2]||"0",10),i=Number.parseInt(e[3]||"0",10);if(!s(o)||!s(n)||!s(i))throw u(r);return{major:o,minor:n,patch:i}}export function compareSemver(r,t){const e=m(r),o=m(t);return e.major!==o.major?e.major-o.major:e.minor!==o.minor?e.minor-o.minor:e.patch-o.patch}export function formatSemver(r){const t=m(r);return`${c(t.major)}.${c(t.minor)}.${c(t.patch)}`}export function satisfiesSemver(r,t){const e=d(t);if(!e)return!0;const o=m(r);for(const n of j(e))if(S(o,n))return!0;return!1}export function deriveSemverMinimum(r){const t=d(r);if(!t)return null;const e=[];for(const o of j(t)){const n=x(o);n!==null&&e.push(n)}return e.length===0?null:(e.sort(compareSemver),formatSemver(e[0]))}function S(r,t){return l(t).every(o=>v(r,o))}function x(r){const t=l(r);if(t.length===0)return null;let e=null;for(const n of t){if(n.operator==="="||n.operator===">="){e=h(e,n.version);continue}n.operator===">"&&(e=h(e,b(n.version)))}const o=e||{major:0,minor:0,patch:0};return t.every(n=>v(o,n))?o:null}function l(r){const t=[];for(const e of w(r))t.push(...$(e));return t}function w(r){return r.trim().replace(/([<>=])\s+(?=v?\d)/giu,"$1").split(/\s+/u).filter(Boolean)}function $(r){const t=r.trim();if(!t)return[];const e=t.match(/^(<=|>=|<|>|=)?\s*(.*)$/u);if(!e)throw new Error(`Unsupported semver comparator "${t}"`);const o=I(e[1]),n=e[2];if(o!==null){if(!n)throw new Error(`Unsupported semver comparator "${t}"`);return[{operator:o,version:parseSemver(n)}]}if(n.startsWith("^")){const i=n.slice(1),a=parseSemver(i);return[{operator:">=",version:a},{operator:"<",version:y(a,g(i))}]}if(n.startsWith("~")){const i=parseSemver(n.slice(1));return[{operator:">=",version:i},{operator:"<",version:{major:i.major,minor:i.minor+1,patch:0}}]}if(/^\d+(?:\.(?:x|\*))?$/iu.test(n)){const[i]=n.split("."),a=parseSemver(i);return[{operator:">=",version:a},{operator:"<",version:{major:a.major+1,minor:0,patch:0}}]}if(/^\d+\.\d+(?:\.(?:x|\*))?$/iu.test(n)){const[i,a]=n.split("."),p=parseSemver(`${i}.${a}`);return[{operator:">=",version:p},{operator:"<",version:{major:p.major,minor:p.minor+1,patch:0}}]}return[{operator:"=",version:parseSemver(n)}]}function v(r,t){const e=compareSemver(r,t.version);switch(t.operator){case"=":return e===0;case">":return e>0;case">=":return e>=0;case"<":return e<0;case"<=":return e<=0}}function y(r,t){return r.major>0||t<=1?{major:r.major+1,minor:0,patch:0}:r.minor>0||t===2?{major:0,minor:r.minor+1,patch:0}:{major:0,minor:0,patch:r.patch+1}}function g(r){return r.trim().replace(/^v/iu,"").split(".").length}function b(r){return{major:r.major,minor:r.minor,patch:r.patch+1}}function h(r,t){return r&&compareSemver(r,t)>=0?r:t}function m(r){return typeof r=="string"?parseSemver(r):A(r)}function A(r){if(!N(r))throw u(r);const t=f(r,"major"),e=f(r,"minor"),o=f(r,"patch");if(!s(t)||!s(e)||!s(o))throw u(r);return{major:t,minor:e,patch:o}}function I(r){switch(r){case"=":case">":case">=":case"<":case"<=":return r;case void 0:return null;default:throw new Error(`Unsupported semver operator "${r}"`)}}function d(r){return c(r||"").trim()}function j(r){return r.split("||").map(t=>t.trim()).filter(Boolean)}function u(r){return new Error(`Invalid semver "${c(r)}"`)}function f(r,t){return Reflect.get(r,t)}function N(r){return r!==null&&typeof r=="object"&&!Array.isArray(r)}function s(r){return typeof r=="number"&&Number.isInteger(r)&&r>=0}

package/dist/toolchains/shared-operation.d.ts

@@ -0,0 +1,11 @@
+export interface SharedToolchainOperation<Result> {
+    readonly controller: AbortController;
+    promise: Promise<Result>;
+    settled: boolean;
+    waiters: number;
+}
+export declare function createSharedToolchainOperation<Result>(run: (signal: AbortSignal) => Promise<Result>): SharedToolchainOperation<Result>;
+export declare function waitForSharedToolchainOperation<Result>(operation: SharedToolchainOperation<Result>, signal?: AbortSignal): Promise<Result>;
+export declare function waitForPromise<Result>(promise: PromiseLike<Result>, signal?: AbortSignal): Promise<Result>;
+export declare function abortReason(signal: AbortSignal): Error;
+export declare function throwIfSignalAborted(signal?: AbortSignal): void;

package/dist/toolchains/shared-operation.js

@@ -0,0 +1 @@
+export function createSharedToolchainOperation(e){const r=new AbortController,o={controller:r,promise:Promise.resolve(void 0),settled:!1,waiters:0};return o.promise=e(r.signal).finally(()=>{o.settled=!0}),o}export async function waitForSharedToolchainOperation(e,r){e.waiters+=1;try{return await waitForPromise(e.promise,r)}finally{e.waiters-=1,!e.settled&&e.waiters===0&&e.controller.abort(new Error("Toolchain operation has no remaining callers"))}}export async function waitForPromise(e,r){return r===void 0?e:(throwIfSignalAborted(r),new Promise((o,i)=>{let t=!1;const a=()=>{t||(t=!0,i(abortReason(r)))};r.addEventListener("abort",a,{once:!0}),Promise.resolve(e).then(n=>{t||(t=!0,r.removeEventListener("abort",a),o(n))},n=>{t||(t=!0,r.removeEventListener("abort",a),i(n instanceof Error?n:new Error("Toolchain operation failed",{cause:n})))})}))}export function abortReason(e){const r=e.reason;return r instanceof Error?r:new Error("Toolchain operation was aborted")}export function throwIfSignalAborted(e){if(e?.aborted)throw abortReason(e)}

package/dist/toolchains/timeouts.d.ts

@@ -0,0 +1 @@
+export declare const TOOLCHAIN_METADATA_TIMEOUT_MS: number;

package/dist/toolchains/timeouts.js

@@ -0,0 +1 @@
+export const TOOLCHAIN_METADATA_TIMEOUT_MS=12e4;

package/dist/toolchains/vitest/index.d.ts

@@ -0,0 +1,13 @@
+type UnknownRecord = Record<string, unknown>;
+export interface VitestConfigOptions {
+    exclude?: readonly string[];
+}
+export type DefinedVitestConfig<TConfig extends UnknownRecord> = TConfig & {
+    test: UnknownRecord & {
+        exclude: string[];
+    };
+};
+export declare function defineConfig(): DefinedVitestConfig<Record<string, never>>;
+export declare function defineConfig<TConfig extends UnknownRecord>(config: TConfig, options?: VitestConfigOptions): DefinedVitestConfig<TConfig>;
+export declare function testkitExcludes(): string[];
+export {};

package/dist/toolchains/vitest/index.js

@@ -0,0 +1 @@
+const s=["**/*.int.testkit.ts","**/*.e2e.testkit.ts","**/*.contract.testkit.ts","**/*.data.testkit.ts","**/*.dal.testkit.ts","**/*.load.testkit.ts","**/*.ui.testkit.ts"];export function defineConfig(t={},r={}){const e=Reflect.get(t,"test"),n={...c(e)?e:{}},i=new Set([...o(n.exclude,"config.test.exclude"),...r.exclude??[],...s]);return{...t,test:{...n,exclude:[...i]}}}export function testkitExcludes(){return[...s]}function o(t,r){if(t===void 0)return[];if(!Array.isArray(t)||!t.every(e=>typeof e=="string"))throw new TypeError(`${r} must be an array of strings`);return t}function c(t){return t!==null&&typeof t=="object"&&!Array.isArray(t)}

package/docs/cloud-control.md

@@ -0,0 +1,105 @@
+# Cloud command reference
+
+`testkit cloud apply --help` prints the account-command envelope, every supported
+operation, its scope IDs, and its input fields. This reference ships with Testkit.
+
+## Account commands
+
+`testkit cloud apply --file command.json --json` sends one account command.
+Every command requires `schemaVersion: 1`, an `idempotencyKey`, an `operation`,
+and an `input` object. Add the scope IDs shown below. Omit unrelated scope IDs.
+The key has 1 to 128 characters without surrounding whitespace. The server
+limits files to 256 KiB and rejects unknown input fields.
+
+```json
+{
+  "schemaVersion": 1,
+  "idempotencyKey": "retention-30",
+  "operation": "project.retention",
+  "projectId": "prj_example",
+  "input": { "days": 30 }
+}
+```
+
+| Operation             | Scope fields                   | Input fields                                                                                                                       |
+| --------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `account.theme`       | None                           | `theme`: `system`, `light`, or `dark`                                                                                              |
+| `organisation.update` | `organisationId`               | `name`                                                                                                                             |
+| `invitation.create`   | `organisationId`               | `email`, `role`: `owner`, `admin`, `member`, or `viewer`                                                                           |
+| `invitation.revoke`   | `organisationId`, `resourceId` | `{}`                                                                                                                               |
+| `provider.create`     | `organisationId`               | `provider`: `gitea`, `host`: HTTPS origin, `displayName`, `oauthClientId`, `oauthClientSecret`; optional `botToken`, `caBundlePEM` |
+| `provider.delete`     | `organisationId`, `resourceId` | `{}`                                                                                                                               |
+| `project.create`      | `organisationId`               | `name`, `provider`: `github` or `gitea`, `host`, `repository`: owner/repo; optional `publishDecisions`, default false              |
+| `project.publishing`  | `projectId`                    | `enabled`: boolean                                                                                                                 |
+| `project.baseline`    | `projectId`                    | `branch`; an empty string resets the provider default                                                                              |
+| `project.retention`   | `projectId`                    | `days`: 1 to 3650                                                                                                                  |
+| `project.policy`      | `projectId`                    | `policyId`: string, or null to inherit the organisation default                                                                    |
+| `policy.create`       | `organisationId`               | `name`; optional `rules` or `sourcePolicyId`, mutually exclusive                                                                   |
+| `policy.revise`       | `organisationId`, `resourceId` | Complete `rules` array                                                                                                             |
+| `policy.default`      | `organisationId`, `resourceId` | `{}`                                                                                                                               |
+| `notification.create` | `projectId`                    | `kind`: `slack` or `email`, `displayName`, `target`, `events`                                                                      |
+| `notification.update` | `projectId`, `resourceId`      | `enabled`: boolean, `events`                                                                                                       |
+| `notification.delete` | `projectId`, `resourceId`      | `{}`                                                                                                                               |
+| `notification.test`   | `projectId`, `resourceId`      | `{}`; sends a real test notification                                                                                               |
+| `token.create`        | `projectId`                    | `name`; also requires `--secret-output NEW_FILE`                                                                                   |
+| `token.revoke`        | `projectId`, `resourceId`      | `{}`                                                                                                                               |
+
+Notification events are `baseline_hold`, `case_opened`, and `case_resolved`.
+At least one event is required. An email target is an email address. A Slack
+target is an HTTPS `hooks.slack.com` webhook URL.
+
+Policy rules have `id`, `kind`, `mode`, `branches`, and typed `params`.
+`cloud show policy ID --org ORG_ID` returns existing rules. Revisions replace the
+whole rules array. `cloud policy preview ID --org ORG_ID --file preview.json`
+accepts `{"receiptId":"rcpt_example","rules":[...]}` without saving a revision.
+
+Secrets belong in private input files. `token.create` reserves a new private
+output file before issuing the token and omits its value from terminal output.
+If saving fails after issuance, the same command and key recover the original
+token with a new `--secret-output` path.
+
+Reusing a key with a changed command conflicts. For `outcome_uncertain`, inspect
+the resource and audit history before choosing a new key. Provider publishing is
+opt-in and can require browser consent. CI returns recovery details instead of
+waiting for consent or a processing connection.
+
+## Discovery and session management
+
+`cloud list --help` and `cloud show --help` list resources and filters.
+Project discovery matches Git origin to accessible Cloud projects when no
+project is selected. A non-JSON TTY can prompt when several choices remain.
+CI and JSON commands require explicit selectors for ambiguous choices.
+
+Account project and campaign reads include `dashboardUrl`. Creation results also
+include it when the optional directory lookup succeeds; a failed lookup does not
+turn a completed creation into a failed command. Automation campaign commands
+omit this field because that credential cannot read the account directory.
+Receipt publication includes its stable dashboard link for both account and
+automation credentials.
+
+`cloud list sessions` lists your CLI sessions by ID, agent, creation time, and
+expiry. `cloud session revoke SESSION_ID` revokes one session. These commands do
+not refresh the current session's expiry. The agent label is client-supplied
+context, not proof of identity. `cloud logout` revokes the saved session and
+removes its local credential. Project tokens use `cloud list tokens` and
+`token.revoke` instead.
+
+## Case and campaign files
+
+Case envelopes contain `schemaVersion: 1`, `projectId`, `idempotencyKey`,
+`expectedVersion`, and `commands`. `cloud snapshot` supplies the project version.
+Each command has `caseId` and one of these types:
+
+| Type              | Other required fields                                                              |
+| ----------------- | ---------------------------------------------------------------------------------- |
+| `case.set_state`  | `state`: `active` or `resolved`                                                    |
+| `case.classify`   | `classification`: `untriaged`, `regression`, `flaky`, `expected`, or `quarantined` |
+| `case.link_issue` | `issueRepository`, positive `issueNumber`                                          |
+
+The [Cloud boundary](testkit-cloud-boundary.md#report-an-externally-executed-campaign)
+documents campaign report fields. `cloud snapshot --campaign ID` supplies the
+campaign version.
+`cloud apply --campaign ID --file report.json` can load product verification
+configuration from `--dir`, so it retains the product CLI version check.
+Remote-only reads, including `cloud snapshot`, do not require a matching local
+Testkit installation.