@gfdelarue/testkit 0.3.0

package/bin/testkit.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { hostNodeIsSupported, TESTKIT_SUPPORTED_HOST_NODE_RANGE } from "../dist/toolchains/host-node-support.js";
+
+const HOST_NODE_ERROR_CODE = "TESTKIT_HOST_NODE_UNSUPPORTED";
+
+class UnsupportedTestkitHostNodeError extends Error {
+  code = HOST_NODE_ERROR_CODE;
+
+  constructor(actualVersion) {
+    super(
+      `Testkit requires Node ${TESTKIT_SUPPORTED_HOST_NODE_RANGE}; current host is Node ${actualVersion}. Upgrade the Node executable used to launch testkit and rerun the command.`,
+    );
+    this.name = "UnsupportedTestkitHostNodeError";
+  }
+}
+
+if (!hostNodeIsSupported(process.versions.node)) {
+  const error = new UnsupportedTestkitHostNodeError(process.versions.node);
+  const json = hasControlFlag(process.argv.slice(2), "--json");
+  process.stderr.write(
+    json
+      ? `${JSON.stringify({ code: error.code, message: error.message, name: error.name })}\n`
+      : `[${error.code}] ${error.message}\n`,
+  );
+  process.exitCode = 1;
+} else {
+  const [{ normalizeCliArgs }, versionDrift] = await Promise.all([
+    import("../dist/cli/entrypoint.js"),
+    import("../dist/cli/version-drift.js"),
+  ]);
+  const effectiveArgs = normalizeCliArgs(process.argv.slice(2));
+  const versionMismatch = versionDrift.checkCliVersionDrift(effectiveArgs, {
+    binUrl: import.meta.url,
+  });
+  if (
+    !versionDrift.emitCliVersionDriftAndExit(versionMismatch, {
+      json: versionDrift.isJsonMode(effectiveArgs),
+    })
+  ) {
+    const { executeCli } = await import("../dist/cli/index.js");
+    await executeCli(
+      effectiveArgs,
+      process.platform === "win32"
+        ? {
+            async beforeAction(id) {
+              if (id[0] === "guard") return;
+              const { ensureWindowsCliOwnership } = await import("../dist/process/windows-cli-owner.js");
+              await ensureWindowsCliOwnership();
+            },
+          }
+        : {},
+    );
+  }
+}
+
+function hasControlFlag(arguments_, flag) {
+  const separatorIndex = arguments_.indexOf("--");
+  const controls = separatorIndex < 0 ? arguments_ : arguments_.slice(0, separatorIndex);
+  return controls.includes(flag);
+}

package/dist/app/cleanup/index.d.ts

@@ -0,0 +1,52 @@
+import type { NormalizedServiceConfig } from "../../config/loader/index.js";
+import { type BundleCleanupTarget } from "../../engines/bundle-cache.js";
+import { type ResourceCleanupSummary, type RuntimeCleanupTarget, type RunManifest } from "../../environment/maintenance.js";
+export interface MaintenanceCleanupOptions {
+    allConfigs?: readonly NormalizedServiceConfig[];
+    cache?: unknown;
+    dryRun?: unknown;
+    resources?: unknown;
+    serviceName?: null | string;
+}
+export interface CleanupTargets {
+    bundles: BundleCleanupTarget[];
+    runtime: RuntimeCleanupTarget[];
+}
+export interface MaintenanceCleanupResult {
+    bundleCleaned: BundleCleanupTarget[];
+    cleaned: RunManifest[];
+    dryRun: boolean;
+    automaticResourceCleanup: ResourceCleanupSummary[];
+    resourceCleanup: ResourceCleanupSummary;
+    runtimeCleaned: RuntimeCleanupTarget[];
+    skippedActive: RunManifest[];
+    stoppedActive: RunManifest[];
+    targets: CleanupTargets;
+}
+export type CleanupRunSummaries = Awaited<ReturnType<typeof cleanupEnvironment>>["runSummaries"];
+export interface CleanupOptions {
+    cache: unknown;
+    dir?: string;
+    dryRun: boolean;
+    resources: boolean;
+    service?: string;
+}
+export declare function cleanupEnvironment(options: Readonly<CleanupOptions>): Promise<{
+    productDir: string;
+    result: MaintenanceCleanupResult;
+    runSummaries: {
+        cleaned: {
+            runId: string;
+            summary: string;
+        }[];
+        stoppedActive: {
+            runId: string;
+            summary: string;
+        }[];
+        skippedActive: {
+            runId: string;
+            summary: string;
+        }[];
+    };
+}>;
+export declare function cleanup(productDir: string, options?: Readonly<MaintenanceCleanupOptions>): Promise<MaintenanceCleanupResult>;

package/dist/app/cleanup/index.js

@@ -0,0 +1 @@
+import{formatRunSummary as m}from"../../process/runs/manifest.js";import d from"path";import{pruneEmptyDir as p}from"../../process/files/directory-status.js";import f from"fs";import{loadManagedConfigs as v}from"../../config/loader/managed-configs.js";import{collectBundleCleanupTargets as g}from"../../engines/bundle-cache.js";import{createEnvironmentMaintenance as y}from"../../environment/maintenance.js";import{runtimePlanning as h}from"../../environment/runtime-planning.js";export async function cleanupEnvironment(e){const{allConfigs:r}=await v({dir:e.dir,service:e.service}),n=r[0]?.productDir||process.cwd(),t=await cleanup(n,{allConfigs:r,serviceName:e.service||null,dryRun:e.dryRun,cache:e.cache,resources:e.resources}),a={cleaned:s(t.cleaned),stoppedActive:s(t.stoppedActive),skippedActive:s(t.skippedActive)};return{productDir:n,result:t,runSummaries:a}}export async function cleanup(e,r={}){const n=r.allConfigs??[],t=r.serviceName||null,a=C(r.cache),{environment:c,otherCaches:u}=await y(e).maintain({kind:"cleanup",desiredGraphs:h.collectDesiredRuntimeGraphs(n),serviceName:t,dryRun:!!r.dryRun,resources:!!r.resources},()=>{const i=a.includes("bundles")?g(e,{allConfigs:n,serviceName:t}):[],o=[];return{result:{targets:i,cleaned:o},prune(){for(const l of i)f.rmSync(l.path,{force:!0}),o.push(l);p(d.join(e,".testkit","_bundles"))}}});return{...c,targets:{runtime:c.targets,bundles:u.targets},bundleCleaned:u.cleaned}}function C(e){const n=(Array.isArray(e)?e:e?[e]:[]).filter(Boolean).map(String);return n.includes("all")?["runtime","bundles"]:n}function s(e){return e.map(r=>({runId:r.runId,summary:m(r)}))}

package/dist/app/cloud/campaigns.d.ts

@@ -0,0 +1,6 @@
+import { CloudClient, type CloudReceipt } from "../../cloud/client.js";
+import { type CampaignReport, type CampaignResult } from "../../cloud/campaigns.js";
+export declare function readCampaignReportFile(file: string): unknown;
+export declare function requiresVerificationPreflight(currentVersion: number, expectedVersion: number): boolean;
+export declare function checkVerificationSubmission(client: CloudClient, report: CampaignReport, productDir: string): Promise<void>;
+export declare function associateReceipt(client: CloudClient, receipt: CloudReceipt, campaignId: string): Promise<CampaignResult>;

package/dist/app/cloud/campaigns.js

@@ -0,0 +1 @@
+import c from"node:fs";import u from"node:path";import p from"node:crypto";import{CloudResponseError as m}from"../../cloud/client.js";import{campaignError as f}from"../../cloud/campaigns.js";import{loadTestkitConfig as l,minimumConfirmingRuns as g}from"../../config/loader/index.js";import{attachErrorDiagnostics as d}from"../../kernel/error-serialization.js";import{shellQuote as h}from"../../process/host/platform.js";export function readCampaignReportFile(r){const e=c.openSync(u.resolve(r),"r");try{if(!c.fstatSync(e).isFile())throw f("file","report must be a regular file");const n=Buffer.alloc(65537);let t=0;for(;t<n.length;){const i=c.readSync(e,n,t,n.length-t,null);if(!i)break;t+=i}if(t>65536)throw f("file","report exceeds 65,536 bytes");try{return JSON.parse(new TextDecoder("utf-8",{fatal:!0}).decode(n.subarray(0,t)))}catch{throw f("file","report must contain valid UTF-8 JSON")}}finally{c.closeSync(e)}}export function requiresVerificationPreflight(r,e){if(r<e)throw d(Object.assign(new Error("Verification report names a future campaign version; read current state before submitting"),{code:"campaign_version_conflict",status:409}),{source:"local",currentVersion:r,expectedVersion:e});return r===e}export async function checkVerificationSubmission(r,e,n){if(e.command.type==="finding.verify"&&requiresVerificationPreflight((await r.campaign(e.campaignId)).version,e.expectedVersion))try{const t=await r.finding(e.campaignId,e.command.findingId);if(!requiresVerificationPreflight(t.campaignVersion,e.expectedVersion))return;const i=g((await l(n)).config),o=new Set(t.evidence.filter(a=>a.available).map(a=>a.receiptId)),s=new Set;for(const a of o)s.add((await r.receipt(a)).runId);if(s.size<i)throw d(Object.assign(new Error(`Local verification submission requires ${String(i)} distinct confirming runs; ${String(s.size)} eligible`),{code:"local_insufficient_confirmations"}),{source:"local",required:i,eligible:s.size})}catch(t){if((await r.campaign(e.campaignId)).version>e.expectedVersion)return;throw t}}export async function associateReceipt(r,e,n){let t;try{const i=await r.campaign(n),o="link:"+p.createHash("sha256").update(JSON.stringify([r.projectId,n,e.id,i.version])).digest("hex");return t={schemaVersion:1,projectId:r.projectId,campaignId:n,expectedVersion:i.version,idempotencyKey:o,command:{type:"receipt.link",receiptId:e.id}},await r.report(t)}catch(i){const o=t?i instanceof m&&i.status<500?"rejected":"unknown":"not_attempted";throw i instanceof Error&&(i.message=`Published run ${e.runId} (${e.id}); campaign association did not return a confirmed result. ${i.message}. Use --json for receipt and report recovery details.`),d(i,{publication:{status:"accepted",receipt:e},association:{campaignId:n,status:o,...t?{report:t}:{}},recovery:o==="rejected"?"Resolve the rejection, then repeat publication to read the current campaign version and reuse the accepted receipt: testkit cloud publish --run "+h(e.runId)+" --campaign "+n+" --json":t?"Save association.report as JSON and retry: testkit cloud apply --campaign "+n+" --file report.json --json":"Read the campaign version, then submit receipt.link for accepted receipt "+e.id})}}

package/dist/app/cloud/control-actions.d.ts

@@ -0,0 +1,12 @@
+import { type ControlOptions } from "./control.js";
+export declare function createCloudCampaign(options: ControlOptions & {
+    requestKey?: string;
+    focus?: string;
+    targetBugCount?: number;
+}): Promise<unknown>;
+export declare function previewCloudPolicy(policy: string, file: string, options: ControlOptions): Promise<unknown>;
+export declare function downloadCloudArtifact(receipt: string, artifactPath: string, output: string, options: ControlOptions): Promise<unknown>;
+export declare function revokeCloudSession(id: string, options: ControlOptions): Promise<{
+    id: string;
+    revoked: true;
+}>;

package/dist/app/cloud/control-actions.js

@@ -0,0 +1,2 @@
+import p from"node:fs";import f from"node:path";import{randomUUID as d}from"node:crypto";import{controlClient as c,resolveOrganisation as w,resolveProject as h}from"./control.js";import{allItems as y,createdResourceDashboardLink as g}from"./control-links.js";import{invalidResponse as v}from"../../cloud/transport.js";export async function createCloudCampaign(e){const t=await c(e),r=await h(t,e),n=e.requestKey??d();e.notify?.(`Request key: ${n}. Reuse --request-key ${n} to retry the same campaign creation.
+`);const a=await t.request("POST",`/api/v1/projects/${encodeURIComponent(r)}/campaigns`,{schemaVersion:1,projectId:r,idempotencyKey:n,focus:e.focus??"",...e.targetBugCount!==void 0?{targetBugCount:e.targetBugCount}:{}});return g(t,"campaign",a,e.env??process.env)}export async function previewCloudPolicy(e,t,r){const n=await c(r),a=await w(n,r.organisation,r.choose),i=p.statSync(t);if(!i.isFile()||i.size>256*1024)throw new Error("Policy preview input must be a JSON file no larger than 256 KiB.");const l=JSON.parse(p.readFileSync(t,"utf8"));return n.request("POST",`/api/v1/organisations/${encodeURIComponent(a)}/policies/${encodeURIComponent(e)}/preview`,l)}export async function downloadCloudArtifact(e,t,r,n){const a=await c(n);if(t.split("/").some(s=>!s||s==="."||s==="..")||t.includes("\\"))throw new Error("Artifact path must be a normalized relative path.");const i=`/api/v1/receipts/${encodeURIComponent(e)}/artifacts`,o=(await y(a,i)).find(s=>s.path===t);if(!o)throw new Error("This receipt has no artifact at the requested path.");if(o.available!==!0)throw new Error("Artifact evidence has expired. Its manifest metadata is still available.");if(typeof o.bytes!="number"||typeof o.sha256!="string")throw v("artifact manifest");const u=f.resolve(r);if(p.existsSync(u))throw new Error("Output file already exists. Choose a new path.");const m=new URL(`${i}/${t.split("/").map(encodeURIComponent).join("/")}`,a.origin);return await a.downloadArtifact(m,u,{bytes:o.bytes,sha256:o.sha256}),{receiptId:e,path:t,output:u,bytes:o.bytes,sha256:o.sha256}}export async function revokeCloudSession(e,t){if(!e.trim())throw new Error("Session ID is required");return await(await c(t,!1)).request("DELETE",`/api/v1/auth/cli/sessions/${encodeURIComponent(e)}`),{id:e,revoked:!0}}

package/dist/app/cloud/control-links.d.ts

@@ -0,0 +1,5 @@
+import { type CloudAccountClient } from "../../cloud/account.js";
+export declare function allItems(client: CloudAccountClient, target: string): Promise<Record<string, unknown>[]>;
+export declare function resourceDashboardLinks(client: CloudAccountClient, resource: string, value: unknown, env: NodeJS.ProcessEnv): Promise<unknown>;
+export declare function cloudDashboardUrl(origin: string, organisation: string, project: string, campaign?: string): string;
+export declare function createdResourceDashboardLink(client: CloudAccountClient, resource: "project" | "campaign", result: unknown, env: NodeJS.ProcessEnv): Promise<unknown>;

package/dist/app/cloud/control-links.js

@@ -0,0 +1 @@
+import{isCloudAccountToken as y}from"../../cloud/account.js";import{isUnknownRecord as t}from"../../kernel/unknown-values.js";import{invalidResponse as c}from"../../cloud/transport.js";export async function allItems(i,s){const r=[],e=new Set;let o="";do{const a=new URL(s,i.origin);a.searchParams.set("limit","100"),o&&a.searchParams.set("cursor",o);const n=await i.request("GET",a.href);if(!t(n)||!Array.isArray(n.items)||!n.items.every(t)||typeof n.nextCursor!="string")throw c("resource page");if(r.push(...n.items),o=n.nextCursor,o&&e.has(o))throw c("repeated page cursor");e.add(o)}while(o);return r}export async function resourceDashboardLinks(i,s,r,e){if(!["project","projects","campaign","campaigns"].includes(s)||!t(r))return r;const o=e.TESTKIT_CLOUD_TOKEN;if(o!==void 0&&!y(o))return r;const a=await allItems(i,"/api/v1/organisations"),n=s==="campaign"||s==="campaigns",d=Array.isArray(r.items)?r.items[0]:r;if(n&&d===void 0)return r;if(n&&(!t(d)||typeof d.projectId!="string"))throw c("campaign project");const u=n&&t(d)?await i.request("GET",`/api/v1/projects/${encodeURIComponent(String(d.projectId))}`):void 0;function m(p){if(!t(p))throw c("dashboard resource");const g=n?u:p;if(!t(g)||typeof g.slug!="string")throw c("project slug");const f=a.find(h=>t(h.organisation)&&h.organisation.id===g.organisationId);if(!f||!t(f.organisation)||typeof f.organisation.slug!="string")throw c("organisation slug");if(n&&typeof p.id!="string")throw c("campaign identity");return{...p,dashboardUrl:cloudDashboardUrl(i.origin,f.organisation.slug,g.slug,n?p.id:void 0)}}return Array.isArray(r.items)?{...r,items:r.items.map(m)}:m(r)}export function cloudDashboardUrl(i,s,r,e){const o=`/dashboard/${encodeURIComponent(s)}/${encodeURIComponent(r)}`;return new URL(e?`${o}/campaigns/${encodeURIComponent(e)}`:o,i).href}export async function createdResourceDashboardLink(i,s,r,e){if(!t(r))return r;const o=s==="project"?r.project:{...r,id:r.campaignId};try{const a=await resourceDashboardLinks(i,s,o,e);return t(a)&&typeof a.dashboardUrl=="string"?{...r,dashboardUrl:a.dashboardUrl}:r}catch{return r}}

package/dist/app/cloud/control-read.d.ts

@@ -0,0 +1,24 @@
+export { cloudDashboardUrl } from "./control-links.js";
+import { type ControlOptions } from "./control.js";
+export interface ReadOptions extends ControlOptions {
+    limit?: number;
+    cursor?: string;
+    branch?: string;
+    decision?: string;
+    pr?: number;
+    sort?: string;
+    direction?: string;
+    flaky?: boolean;
+    receipt?: string;
+    caseId?: string;
+    testPath?: string;
+    page?: number;
+    campaign?: string;
+    filePath?: string;
+    rootCauseKey?: string;
+    issueReference?: string;
+    view?: string;
+    order?: string;
+}
+export declare function listCloudResources(resource: string, options: ReadOptions): Promise<unknown>;
+export declare function showCloudResource(resource: string, id: string | undefined, options: ReadOptions): Promise<unknown>;

package/dist/app/cloud/control-read.js

@@ -0,0 +1 @@
+import{resourceDashboardLinks as p}from"./control-links.js";export{cloudDashboardUrl}from"./control-links.js";import{validateCloudListFilters as w}from"./control-resources.js";import{controlClient as m,resolveOrganisation as t,resolveProject as n}from"./control.js";export async function listCloudResources(i,e){w(i,{...e});const a=await m(e,i!=="sessions");let r;switch(i){case"artifacts":if(!e.receipt)throw new Error("Artifact listing requires --receipt");r=`/api/v1/receipts/${encodeURIComponent(e.receipt)}/artifacts`;break;case"metrics":r=`/api/v1/projects/${encodeURIComponent(await n(a,e))}/metrics`;break;case"case-occurrences":case"case-history":if(!e.caseId)throw new Error("Case history requires --case");r=`/api/v1/projects/${encodeURIComponent(await n(a,e))}/cases/${encodeURIComponent(e.caseId)}/${i==="case-history"?"history":"occurrences"}`;break;case"file-history":if(!e.testPath)throw new Error("File history requires --path");r=`/api/v1/projects/${encodeURIComponent(await n(a,e))}/file-history`;break;case"sessions":r="/api/v1/auth/cli/sessions";break;case"organisations":r="/api/v1/organisations";break;case"projects":r="/api/v1/projects";break;case"members":case"invitations":case"providers":case"policies":case"audit":r=`/api/v1/organisations/${encodeURIComponent(await t(a,e.organisation,e.choose))}/${i}`;break;case"notifications":case"tokens":case"campaigns":case"runs":case"tests":r=`/api/v1/projects/${encodeURIComponent(await n(a,e))}/${i}`;break;case"findings":r=`/api/v1/projects/${encodeURIComponent(await n(a,e))}/campaigns/${e.campaign?`${encodeURIComponent(e.campaign)}/`:""}findings`;break;case"cases":r=`/api/v1/projects/${encodeURIComponent(await n(a,e))}/cases`;break;default:throw new Error(`Unknown resource: ${i}`)}const s=new URL(r,a.origin),c={limit:e.limit,cursor:e.cursor,branch:e.branch,decision:e.decision,pr:e.pr,sort:e.sort,direction:e.direction,flaky:e.flaky,path:e.testPath,page:e.page,rootCauseKey:e.rootCauseKey,issueReference:e.issueReference,view:e.view,order:e.order};for(const[d,o]of Object.entries(c))o!==void 0&&s.searchParams.set(d,String(o));return i==="projects"&&e.organisation&&s.searchParams.set("organisationId",await t(a,e.organisation,e.choose)),p(a,i,await a.request("GET",s.href),e.env??process.env)}export async function showCloudResource(i,e,a){const r=await m(a),s=()=>{if(!e)throw new Error(`cloud show ${i} requires an ID`);return encodeURIComponent(e)};let c;switch(i){case"account":c="/api/v1/account";break;case"organisation":c=`/api/v1/organisations/${encodeURIComponent(await t(r,e??a.organisation,a.choose))}`;break;case"project":c=`/api/v1/projects/${encodeURIComponent(await n(r,{...a,project:e??a.project}))}`;break;case"policy":c=`/api/v1/organisations/${encodeURIComponent(await t(r,a.organisation,a.choose))}/policies/${s()}`;break;case"campaign":c=`/api/v1/projects/${encodeURIComponent(await n(r,a))}/campaigns/${s()}`;break;case"finding":if(!a.campaign)throw new Error("Finding detail requires --campaign");c=`/api/v1/projects/${encodeURIComponent(await n(r,a))}/campaigns/${encodeURIComponent(a.campaign)}/findings/${s()}`;break;case"receipt":c=`/api/v1/receipts/${s()}`;break;case"run":c=`/api/v1/runs/${s()}`;break;case"case":c=`/api/v1/projects/${encodeURIComponent(await n(r,a))}/cases/${s()}`;break;case"test-file":c=`/api/v1/projects/${encodeURIComponent(await n(r,a))}/test-file?path=${s()}`;break;case"project-policy":c=`/api/v1/projects/${encodeURIComponent(await n(r,a))}/policy`;break;case"performance":c=`/api/v1/projects/${encodeURIComponent(await n(r,a))}/performance`;break;case"connection":c=`/api/v1/project-connections/${s()}`;break;default:throw new Error(`Unknown resource: ${i}`)}return p(r,i,await r.request("GET",c),a.env??process.env)}

package/dist/app/cloud/control-resources.d.ts

@@ -0,0 +1,3 @@
+export declare const cloudListResources: Readonly<Record<string, readonly string[]>>;
+export declare const cloudShowResources: readonly ["account", "organisation", "project", "policy", "campaign", "finding", "receipt", "run", "case", "test-file", "performance", "project-policy", "connection"];
+export declare function validateCloudListFilters(resource: string, options: Record<string, unknown>): void;

package/dist/app/cloud/control-resources.js

@@ -0,0 +1 @@
+const e=["limit","cursor"];export const cloudListResources={organisations:e,projects:e,members:e,invitations:e,providers:e,policies:e,notifications:e,tokens:e,sessions:[],campaigns:e,findings:[...e,"campaign","rootCauseKey","issueReference","view","order"],runs:["limit","branch","decision","pr","sort","direction","page"],tests:["flaky"],audit:e,cases:e,artifacts:[...e,"receipt"],"case-history":[...e,"caseId"],"file-history":[...e,"testPath"],"case-occurrences":[...e,"caseId"],metrics:[...e,"testPath"]},cloudShowResources=["account","organisation","project","policy","campaign","finding","receipt","run","case","test-file","performance","project-policy","connection"];export function validateCloudListFilters(s,n){const o=Object.hasOwn(cloudListResources,s)?cloudListResources[s]:void 0;if(!o)throw new Error(`Unknown resource: ${s}`);const c=new Set(Object.values(cloudListResources).flat()),r={caseId:"case",testPath:"path",rootCauseKey:"root-cause-key",issueReference:"issue-reference"};for(const t of c){const i=n[t];if(i!==void 0&&i!==!1&&!o.includes(t))throw new Error(`--${r[t]??t} is not supported by cloud list ${s}`)}}

package/dist/app/cloud/control.d.ts

@@ -0,0 +1,34 @@
+import { CloudAccountClient } from "../../cloud/account.js";
+export interface ControlOptions {
+    origin?: string;
+    env?: NodeJS.ProcessEnv;
+    organisation?: string;
+    project?: string;
+    browser?: boolean;
+    signal?: AbortSignal;
+    secretOutput?: string;
+    notify?: (message: string) => void;
+    choose?: (label: string, choices: readonly {
+        id: string;
+        name: string;
+    }[]) => Promise<string>;
+}
+export declare function controlClient(options?: ControlOptions, refreshCredential?: boolean): Promise<CloudAccountClient>;
+export declare function resolveOrganisation(client: CloudAccountClient, selection?: string, choose?: ControlOptions["choose"]): Promise<string>;
+export declare function resolveProject(client: CloudAccountClient, options: ControlOptions): Promise<string>;
+export declare function projectsForRepository(projects: Record<string, unknown>[], origin: string): Record<string, unknown>[];
+export declare function applyAccountCommand(command: Record<string, unknown>, options?: ControlOptions): Promise<unknown>;
+export declare function waitForConnection(client: CloudAccountClient, initial: unknown, options: ControlOptions): Promise<unknown>;
+export interface CreateProjectOptions extends ControlOptions {
+    name?: string;
+    repository?: string;
+    provider?: string;
+    host?: string;
+    publishDecisions?: boolean;
+    requestKey?: string;
+}
+export declare function createCloudProject(options: CreateProjectOptions): Promise<unknown>;
+export declare function parseRepository(value: string, host?: string): {
+    repository: string;
+    host: string;
+};

package/dist/app/cloud/control.js

@@ -0,0 +1,5 @@
+import{setTimeout as v}from"node:timers/promises";import c from"node:fs";import $ from"node:path";import{randomUUID as I}from"node:crypto";import{execFileSync as R}from"node:child_process";import{CloudAccountClient as E}from"../../cloud/account.js";import{invalidResponse as u}from"../../cloud/transport.js";import{isUnknownRecord as p}from"../../kernel/unknown-values.js";import{cloudToken as k}from"./credentials.js";import{openBrowser as C,selectedCloudOrigin as S}from"./login.js";import{allItems as l,createdResourceDashboardLink as x}from"./control-links.js";export async function controlClient(o={},r=!0){const e=S(o);return new E(e,await k(e,o.env??process.env,r))}async function m(o,r,e,n){const t=r?o.filter(a=>a.id===r||a.slug===r||a.name===r):o;if(t.length>1&&!r&&n){const a=t.map(s=>{if(typeof s.id!="string"||!s.id)throw u(`${e} identity`);return{id:s.id,name:typeof s.name=="string"?s.name:s.id}}),d=await n(e,a);if(!a.some(s=>s.id===d))throw new Error(`Invalid ${e} selection`);return d}if(t.length!==1)throw new Error(`${e} ${r?`"${r}" `:""}${t.length?"is ambiguous":"was not found"}. Select an explicit ID from cloud list ${e==="organisation"?"organisations":"projects"}.`);const i=t[0]?.id;if(typeof i!="string"||!i)throw u(`${e} identity`);return i}export async function resolveOrganisation(o,r,e){const n=await l(o,"/api/v1/organisations");return m(n.map(t=>{if(!p(t.organisation))throw u("organisation");return t.organisation}),r,"organisation",e)}export async function resolveProject(o,r){const e=r.project??(r.env??process.env).TESTKIT_CLOUD_PROJECT_ID;if(e?.startsWith("prj_"))return e;const n=r.organisation?`?organisationId=${encodeURIComponent(await resolveOrganisation(o,r.organisation,r.choose))}`:"",t=await l(o,`/api/v1/projects${n}`),i=e?void 0:g(),a=i?projectsForRepository(t,i):[];return m(a.length?a:t,e,"project",r.choose)}function g(){try{return R("git",["remote","get-url","origin"],{encoding:"utf8",stdio:["ignore","pipe","ignore"]}).trim()}catch{return}}export function projectsForRepository(o,r){let e;try{e=parseRepository(r)}catch{return[]}return o.filter(n=>{const t=n.repository;return p(t)&&t.host===e.host&&`${String(t.owner)}/${String(t.name)}`===e.repository})}export async function applyAccountCommand(o,r={}){const e=o.operation==="token.create";if(r.secretOutput!==void 0&&!e)throw new Error("--secret-output is only supported for token.create.");const n=r.secretOutput?$.resolve(r.secretOutput):void 0;if(e&&!n)throw new Error("Credential creation requires --secret-output <new-file> to save the issued token privately.");const t=n?c.openSync(n,"wx",384):void 0;let i=!1,a=!1,d=!1;try{const s=await controlClient(r);d=e;const f=await s.request("POST","/api/v1/account/commands",o);if(e&&t!==void 0&&n!==void 0){if(i=!0,!p(f)||typeof f.value!="string")throw u("issued credential");c.writeFileSync(t,`${f.value}
+`),c.fsyncSync(t);const y=c.fstatSync(t),h=c.lstatSync(n);if(!h.isFile()||h.ino!==y.ino||h.dev!==y.dev)throw new Error("Credential output was replaced while the command was running");c.closeSync(t),a=!0;const w={...f};return delete w.value,{...w,secretFile:n}}return await waitForConnection(s,f,r)}catch(s){throw d&&n!==void 0?new Error(`Cloud ${i?"issued the credential, but saving it failed":"may have issued the credential before the request failed"}. Retry the same command and idempotency key with --secret-output pointing to a new file to recover it. Output path: ${n}.`,{cause:s}):s}finally{if(t!==void 0&&!a){const s=c.fstatSync(t);c.closeSync(t),!i&&s.size===0&&n!==void 0&&O(n,s)}}}function O(o,r){try{const e=c.lstatSync(o);e.isFile()&&e.size===0&&e.ino===r.ino&&e.dev===r.dev&&c.unlinkSync(o)}catch(e){if(!p(e)||e.code!=="ENOENT")throw e}}export async function waitForConnection(o,r,e){if(!p(r)||typeof r.operationId!="string"||r.status==="complete")return r;let n=!1;for(;;){e.signal?.throwIfAborted();const t=await j(o,r.operationId);if(t.status==="complete")return t;if(t.status!=="pending"&&t.status!=="processing")throw new Error(`Repository connection ${r.operationId} is ${String(t.status)}. Inspect with cloud show connection ${r.operationId}; retry the create command with a new request key after checking access.`);if(t.status==="pending"&&!n){if(typeof t.verificationUrl!="string")throw u("repository approval link");const i=new URL(t.verificationUrl);if(i.origin!==o.origin||i.username||i.password||i.pathname!==`/cli/projects/${r.operationId}/authorize`)throw u("repository approval link");if(e.notify?.(`Open ${i.href}
+Waiting for repository authorization. Operation: ${r.operationId}
+`),(e.env??process.env).CI)throw new Error(`Repository authorization requires a person. Open ${i.href}, then retry the same request key. Operation: ${r.operationId}`);e.browser!==!1&&C(i.href),n=!0}if((e.env??process.env).CI)throw new Error(`Repository connection ${r.operationId} is processing. Inspect with cloud show connection ${r.operationId}, then retry the same request key to resume.`);if(typeof t.expiresAt!="string"||!Number.isFinite(Date.parse(t.expiresAt)))throw u("connection expiry");if(Date.now()>=Date.parse(t.expiresAt))throw new Error(`Repository connection ${r.operationId} expired. Start a new request.`);await v(2e3,void 0,{signal:e.signal})}}async function j(o,r){const e=await o.request("GET",`/api/v1/project-connections/${encodeURIComponent(r)}`);if(!p(e)||e.operationId!==r||typeof e.status!="string")throw u("repository connection");return e}export async function createCloudProject(o){const r=o.repository??g();if(!r)throw new Error("Pass --repository owner/repo when outside Git or when origin is unavailable.");const e=parseRepository(r,o.host),n=await controlClient(o),t=await resolveOrganisation(n,o.organisation,o.choose),i=o.requestKey??I();o.notify?.(`Request key: ${i}. Reuse --request-key ${i} to resume this operation.
+`);const a=await applyAccountCommand({schemaVersion:1,idempotencyKey:i,operation:"project.create",organisationId:t,input:{name:o.name??e.repository.split("/")[1],repository:e.repository,host:e.host,provider:o.provider??(e.host==="github.com"?"github":"gitea"),publishDecisions:o.publishDecisions??!1}},o);return x(n,"project",a,o.env??process.env)}export function parseRepository(o,r){let e=o.trim(),n="github.com";if(e.includes("://")){const t=new URL(e);if(!["https:","http:","ssh:","git:"].includes(t.protocol)||t.search||t.hash)throw new Error("Repository must be owner/repo or a Git remote URL.");n=t.protocol==="ssh:"||t.protocol==="git:"?t.hostname:t.host,e=t.pathname.replace(/^\//u,"")}else{const t=/^(?:[^@/]+@)?([^/:]+):(.+)$/.exec(e);t?.[1]&&t[2]&&(n=t[1].toLowerCase(),e=t[2])}if(e=e.replace(/\/+$/u,"").replace(/\.git$/u,""),!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(e)||e.split("/").some(t=>t==="."||t===".."))throw new Error("Repository must be owner/repo or a Git remote URL.");return{host:r??n,repository:e}}

package/dist/app/cloud/credentials.d.ts

@@ -0,0 +1,11 @@
+import { type AccountSession } from "../../cloud/account.js";
+export interface SavedCredential extends AccountSession {
+    origin: string;
+    token: string;
+}
+export declare function readCredential(origin: string, env?: NodeJS.ProcessEnv): SavedCredential | null;
+export declare function saveCredential(credential: SavedCredential, env?: NodeJS.ProcessEnv): void;
+export declare function removeCredential(origin: string, env?: NodeJS.ProcessEnv): void;
+export declare function cloudToken(origin: string, env?: NodeJS.ProcessEnv, refresh?: boolean): Promise<string>;
+export declare function shouldRefreshCredential(credential: AccountSession, now: number): boolean;
+export declare function canUseCredentialAfterRefreshFailure(credential: AccountSession, error: unknown, now: number): boolean;

package/dist/app/cloud/credentials.js

@@ -0,0 +1,2 @@
+import s from"node:fs";import p from"node:os";import c from"node:path";import{createHash as y,randomUUID as T}from"node:crypto";import{CloudAccountClient as w,cloudOrigin as l,isCloudAccountToken as E,parseSession as O}from"../../cloud/account.js";import{CloudResponseError as h}from"../../cloud/client.js";import{isUnknownRecord as u}from"../../kernel/unknown-values.js";function d(o,e){const r=e.XDG_CONFIG_HOME??(process.platform==="win32"?e.APPDATA:void 0);if(r&&!c.isAbsolute(r))throw new Error("Cloud credential configuration directory must be absolute");const t=r||c.join(p.homedir(),".config"),n=y("sha256").update(l(o)).digest("hex");return c.join(t,"testkit","cloud",`${n}.json`)}function m(o,e){const r=c.dirname(o),t=c.dirname(r),n=c.dirname(t);for(const i of[n,t,r]){let a;try{a=s.lstatSync(i)}catch(f){if(!u(f)||f.code!=="ENOENT")throw f;if(!e)return!1;s.mkdirSync(i,{recursive:i===n,mode:448}),a=s.lstatSync(i)}if(!a.isDirectory()||a.isSymbolicLink())throw new Error("Cloud credential directory must be a real directory, not a symlink");if(i!==n&&process.platform!=="win32"&&(a.mode&63)!==0)throw new Error("Cloud credential directory must be private (mode 0700)")}return!0}export function readCredential(o,e=process.env){const r=d(o,e);if(!m(r,!1))return null;let t;try{t=s.openSync(r,s.constants.O_RDONLY|s.constants.O_NOFOLLOW)}catch(n){if(u(n)&&n.code==="ENOENT")return null;throw n}try{const n=s.fstatSync(t);if(!n.isFile()||n.size>16384||process.platform!=="win32"&&(n.mode&63)!==0)throw new Error("Cloud credential file must be a private regular file");const i=JSON.parse(s.readFileSync(t,"utf8"));if(!u(i)||i.origin!==l(o)||!E(i.token))throw new Error("Invalid Cloud credential file; run testkit cloud login --force");return{...O(i),origin:i.origin,token:i.token}}finally{s.closeSync(t)}}export function saveCredential(o,e=process.env){const r=d(o.origin,e);m(r,!0);const t=`${r}.${T()}.tmp`;try{s.writeFileSync(t,`${JSON.stringify(o)}
+`,{flag:"wx",mode:384}),s.renameSync(t,r)}finally{s.rmSync(t,{force:!0})}}export function removeCredential(o,e=process.env){const r=d(o,e);m(r,!1)&&s.rmSync(r,{force:!0})}export async function cloudToken(o,e=process.env,r=!0){if(e.TESTKIT_CLOUD_TOKEN!==void 0){if(!e.TESTKIT_CLOUD_TOKEN.trim())throw new Error("TESTKIT_CLOUD_TOKEN is empty");return e.TESTKIT_CLOUD_TOKEN}const t=readCredential(o,e);if(!t||Date.parse(t.expiresAt)<=Date.now())throw new Error(e.CI?"Set TESTKIT_CLOUD_TOKEN to an automation token for CI.":`Run testkit cloud login --url ${l(o)} to connect your account, or set TESTKIT_CLOUD_TOKEN for automation.`);if(r&&shouldRefreshCredential(t,Date.now())){let n;try{n=await new w(o,t.token).refresh()}catch(i){if(!canUseCredentialAfterRefreshFailure(t,i,Date.now()))throw i}n&&saveCredential({...t,...n},e)}return t.token}export function shouldRefreshCredential(o,e){const r=Date.parse(o.expiresAt);return r>e&&r-e<10080*6e4&&r<Date.parse(o.maximumExpiresAt)}export function canUseCredentialAfterRefreshFailure(o,e,r){return Date.parse(o.expiresAt)<=r?!1:e instanceof h?e.status>=500||e.status===429:u(e)&&e.code==="cloud_transport_error"}

package/dist/app/cloud/index.d.ts

@@ -0,0 +1,22 @@
+import { type CampaignSelection, type CampaignResult } from "../../cloud/campaigns.js";
+import { CloudClient, type CloudReceipt } from "../../cloud/client.js";
+import type { ControlOptions } from "./control.js";
+export interface CloudEnvironmentOptions extends Pick<ControlOptions, "browser" | "signal" | "secretOutput" | "notify"> {
+    env?: NodeJS.ProcessEnv;
+    origin?: string;
+    projectId?: string;
+    campaignId?: string;
+    productDir?: string;
+}
+export interface PublishRunToCloudOptions extends CloudEnvironmentOptions {
+    productDir: string;
+    runId?: null | string;
+}
+export declare function publishRunToCloud(options: Readonly<PublishRunToCloudOptions>): Promise<{
+    receipt: CloudReceipt;
+    association?: CampaignResult;
+    dashboardUrl: string;
+}>;
+export declare function applyCloudMutationFile(filePath: string, options?: Readonly<CloudEnvironmentOptions>): Promise<unknown>;
+export declare function readCloudSnapshot(options?: Readonly<CloudEnvironmentOptions & CampaignSelection>): Promise<unknown>;
+export declare function cloudClientFromEnvironment(options?: Readonly<CloudEnvironmentOptions>): Promise<CloudClient>;

package/dist/app/cloud/index.js

@@ -0,0 +1,2 @@
+import{associateReceipt as s,checkVerificationSubmission as m,readCampaignReportFile as l}from"./campaigns.js";import{requireCloudId as u,parseCampaignReport as f}from"../../cloud/campaigns.js";import{isUnknownRecord as I}from"../../kernel/unknown-values.js";import c from"node:fs";import a from"node:path";import{prepareVerifiedRunBundleUpload as w}from"../../evidence/index.js";import{CloudClient as g}from"../../cloud/client.js";import{applyAccountCommand as y}from"./control.js";import{selectedCloudOrigin as C}from"./login.js";import{cloudToken as h}from"./credentials.js";export async function publishRunToCloud(e){if(e.campaignId!==void 0&&(u(e.campaignId,"campaignId"),!e.runId))throw new Error("Campaign publication requires an explicit --run ID");const r=w(e.productDir,e.runId??null),n=await cloudClientFromEnvironment(e),t=await n.publish(r,i=>{e.notify?.(i)});j(e.productDir,r.runId,t);const o=e.campaignId===void 0?void 0:await s(n,t,e.campaignId);return{receipt:t,dashboardUrl:new URL(`/receipts/${encodeURIComponent(t.id)}`,n.origin).href,...o?{association:o}:{}}}export async function applyCloudMutationFile(e,r={}){if(r.campaignId!==void 0){if(r.secretOutput!==void 0)throw new Error("--secret-output is only supported for token.create.");const d=await cloudClientFromEnvironment(r),p=f(l(e),d.projectId,u(r.campaignId,"campaignId"));return await m(d,p,a.resolve(r.productDir??process.cwd())),d.report(p)}const n=a.resolve(e),t=JSON.parse(c.readFileSync(n,"utf8"));if(!I(t))throw new Error("Cloud mutation file must contain a JSON object");if(typeof t.operation=="string")return y(t,r);if(r.secretOutput!==void 0)throw new Error("--secret-output is only supported for token.create.");const o=await cloudClientFromEnvironment(r),i={...t,projectId:typeof t.projectId=="string"?t.projectId:o.projectId};if(i.projectId!==o.projectId)throw new Error("Cloud mutation file projectId does not match TESTKIT_CLOUD_PROJECT_ID");return o.apply(i)}export async function readCloudSnapshot(e={}){return(await cloudClientFromEnvironment(e)).snapshot(e)}export async function cloudClientFromEnvironment(e={}){const r=e.env??process.env,n=C(e);return new g({origin:n,projectId:e.projectId??r.TESTKIT_CLOUD_PROJECT_ID??"",token:await h(n,r)})}function j(e,r,n){const t=a.join(e,".testkit","cloud","receipts");c.mkdirSync(t,{recursive:!0});const o=a.join(t,`${r}.json`),i=`${o}.${String(process.pid)}.${String(Date.now())}.tmp`;c.writeFileSync(i,`${JSON.stringify(n,null,2)}
+`,{mode:384}),c.renameSync(i,o)}

package/dist/app/cloud/login.d.ts

@@ -0,0 +1,63 @@
+export interface LoginOptions {
+    origin?: string;
+    env?: NodeJS.ProcessEnv;
+    force?: boolean;
+    browser?: boolean;
+    signal?: AbortSignal;
+    notify: (message: string) => void;
+}
+export declare function selectedCloudOrigin(options: {
+    origin?: string;
+    env?: NodeJS.ProcessEnv;
+}): string;
+export declare function loginToCloud(options: LoginOptions): Promise<{
+    reused: boolean;
+    user: {
+        id: string;
+        email: string;
+        name: string;
+    };
+    expiresAt: string;
+    maximumExpiresAt: string;
+    origin: string;
+}>;
+export declare function cloudLoginStatus(options: {
+    origin?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<{
+    origin: string;
+    source: "environment";
+    authenticated: null;
+    message: string;
+} | {
+    origin: string;
+    source: "none";
+    authenticated: boolean;
+    message?: undefined;
+} | {
+    user: {
+        id: string;
+        email: string;
+        name: string;
+    };
+    expiresAt: string;
+    maximumExpiresAt: string;
+    origin: string;
+    source: "account";
+    authenticated: boolean;
+    message?: undefined;
+} | {
+    origin: string;
+    source: "account";
+    authenticated: boolean;
+    message?: undefined;
+}>;
+export declare function logoutOfCloud(options: {
+    origin?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<{
+    origin: string;
+    loggedOut: boolean;
+    environmentTokenActive: boolean;
+}>;
+export declare function openBrowser(url: string): void;

package/dist/app/cloud/login.js

@@ -0,0 +1,2 @@
+import{spawn as p}from"node:child_process";import{setTimeout as w}from"node:timers/promises";import{CloudAccountClient as c,cloudOrigin as v}from"../../cloud/account.js";import{CloudResponseError as l}from"../../cloud/client.js";import{readCredential as u,removeCredential as g,saveCredential as h,canUseCredentialAfterRefreshFailure as C}from"./credentials.js";import{isUnknownRecord as x}from"../../kernel/unknown-values.js";export function selectedCloudOrigin(e){return v(e.origin??(e.env??process.env).TESTKIT_CLOUD_URL??"https://testkit.cloud")}export async function loginToCloud(e){const t=selectedCloudOrigin(e),o=e.env??process.env;let n;try{n=u(t,o)}catch(r){if(!e.force)throw r;n=null}if(n&&!e.force)try{const r=new c(t,n.token),m=Date.parse(n.expiresAt)===Date.parse(n.maximumExpiresAt)?await r.session():await r.refresh();return h({...n,...m},o),{origin:t,...m,reused:!0}}catch(r){if(C(n,r,Date.now()))return e.notify("Cloud session refresh is temporarily unavailable. Using the saved, unexpired session."),{origin:t,user:n.user,expiresAt:n.expiresAt,maximumExpiresAt:n.maximumExpiresAt,reused:!0};if(!(r instanceof l)||r.status!==401)throw r}const i=new c(t),a=await i.login();e.notify(`Open ${a.verificationUrl}
+Check code ${a.userCode}, then choose Allow CLI access. Waiting for approval...`),e.browser!==!1&&!o.CI&&openBrowser(a.verificationUrl);const d=Date.now()+a.expiresIn*1e3;let s=a.interval*1e3,f=!1;try{for(;Date.now()<d;){e.signal?.throwIfAborted();try{const r=await i.poll(a.deviceCode);return e.signal?.throwIfAborted(),h({...r,origin:t,token:a.deviceCode},o),f=!0,n&&await i.revoke(n.token).catch(()=>{e.notify("The previous Cloud session could not be revoked. It will expire automatically.")}),{origin:t,...r,reused:!1}}catch(r){if(r instanceof l&&r.status>=500||x(r)&&r.code==="cloud_transport_error"){await w(Math.min(s,Math.max(1,d-Date.now())),void 0,{signal:e.signal});continue}if(!(r instanceof l)||!["authorization_pending","slow_down"].includes(r.code??""))throw r;r.code==="slow_down"&&(s=Math.min(s+1e3,3e4))}await w(Math.min(s,Math.max(1,d-Date.now())),void 0,{signal:e.signal})}throw new Error("CLI login expired. Run testkit cloud login again.")}finally{f||await i.revoke(a.deviceCode).catch(()=>{})}}export async function cloudLoginStatus(e){const t=selectedCloudOrigin(e),o=e.env??process.env;if(o.TESTKIT_CLOUD_TOKEN!==void 0)return{origin:t,source:"environment",authenticated:null,message:"Commands use TESTKIT_CLOUD_TOKEN. Select a project to check its permissions."};const n=u(t,o);if(!n)return{origin:t,source:"none",authenticated:!1};try{return{origin:t,source:"account",authenticated:!0,...await new c(t,n.token).session()}}catch(i){if(!(i instanceof l)||i.status!==401)throw i;return{origin:t,source:"account",authenticated:!1}}}export async function logoutOfCloud(e){const t=selectedCloudOrigin(e),o=e.env??process.env,n=u(t,o);return n&&(await new c(t).revoke(n.token),g(t,o)),{origin:t,loggedOut:!0,environmentTokenActive:o.TESTKIT_CLOUD_TOKEN!==void 0}}export function openBrowser(e){const t=process.platform==="darwin"?"open":process.platform==="win32"?"rundll32":"xdg-open",o=process.platform==="win32"?["url.dll,FileProtocolHandler",e]:[e],n=p(t,o,{detached:!0,stdio:"ignore",shell:!1});n.on("error",()=>{}),n.unref()}

package/dist/app/cloud/migration/archive.d.ts

@@ -0,0 +1,13 @@
+import type { MigrationPlan, PlannedRun } from "./model.js";
+interface ArchiveIdentity {
+    bytes: number;
+    sha256: string;
+}
+/** The migration output lock and sequential run transfer own this single archive slot. */
+export declare function prepareMigrationArchive(plan: MigrationPlan, run: PlannedRun, maxBytes: number, expected?: ArchiveIdentity): Promise<{
+    path: string;
+    bytes: number;
+    sha256: string;
+}>;
+export declare function removeMigrationArchive(plan: MigrationPlan, runId: string): Promise<void>;
+export {};

package/dist/app/cloud/migration/archive.js

@@ -0,0 +1 @@
+import p from"node:crypto";import r from"node:fs";import a from"node:path";import{writeUploadArchive as l}from"../../../cloud/archive.js";import{canonicalHistoricalJson as w}from"../../../cloud/historical-json.js";import{digest as S}from"./files.js";function u(o,t){const n=r.lstatSync(o.outputDir);if(!n.isDirectory()||n.isSymbolicLink())throw new Error("Migration output directory is unsafe");const i=a.join(o.outputDir,"archives");r.existsSync(i)||r.mkdirSync(i,{mode:448});const e=r.lstatSync(i);if(!e.isDirectory()||e.isSymbolicLink())throw new Error("Migration archive directory is unsafe");return a.join(i,`${S(t)}.zip`)}function m(o){if(process.platform==="win32")return;const t=r.openSync(o,"r");try{r.fsyncSync(t)}finally{r.closeSync(t)}}async function d(o,t,n){if(t.bytes>n)throw new Error("Journaled migration archive exceeds the upload limit");try{const i=r.lstatSync(o);if(!i.isFile()||i.isSymbolicLink()||i.size!==t.bytes)throw new Error("Archive size or file type changed");const e=r.openSync(o,r.constants.O_RDONLY|r.constants.O_NOFOLLOW),f=r.createReadStream(o,{fd:e}),c=p.createHash("sha256");let s=0;for await(const y of f){const h=y;if(s+=h.length,s>t.bytes)throw new Error("Archive grew during verification");c.update(h)}if(s!==t.bytes||c.digest("hex")!==t.sha256)throw new Error("Archive SHA-256 or size changed")}catch(i){throw new Error("Journaled migration archive is missing or corrupt; restore the original archive before resuming",{cause:i})}}export async function prepareMigrationArchive(o,t,n,i){const e=u(o,t.runId),f=a.dirname(e),c=`${e}.tmp`;if(r.readdirSync(f).some(s=>s!==a.basename(e)&&s!==a.basename(c)))throw new Error("Another migration archive occupies the active run slot; resume its run before packaging another");if(i)return await d(e,i,n),{path:e,...i};r.rmSync(e,{force:!0}),r.rmSync(c,{force:!0});try{const s=await l({manifest:t.request.manifest,files:t.files},n,c,w),y=r.openSync(c,r.constants.O_RDWR|r.constants.O_NOFOLLOW);try{r.fsyncSync(y)}finally{r.closeSync(y)}return r.renameSync(c,e),m(f),m(o.outputDir),{path:e,...s}}finally{r.rmSync(c,{force:!0})}}export async function removeMigrationArchive(o,t){const n=u(o,t);await r.promises.rm(n,{force:!0}),await r.promises.rm(`${n}.tmp`,{force:!0}),m(a.dirname(n))}

package/dist/app/cloud/migration/commands.d.ts

@@ -0,0 +1,8 @@
+import { type HistoricalBegin, type HistoricalRecord } from "../../../cloud/historical-contract.js";
+import type { MigrationPlan, PlannedRecord } from "./model.js";
+import type { MigrationJournal } from "./state.js";
+export declare function dependencyOrder(records: PlannedRecord[]): PlannedRecord[];
+/** The upper version bound makes chunk boundaries independent of resumed state. */
+export declare function batchRecords(records: HistoricalRecord[]): HistoricalRecord[][];
+export declare function beginCommand(plan: MigrationPlan, planDigest: string): HistoricalBegin;
+export declare function plannedRecords(plan: MigrationPlan, journal: MigrationJournal, kind: "case" | "finding"): HistoricalRecord[];

package/dist/app/cloud/migration/commands.js

@@ -0,0 +1 @@
+import{HISTORICAL_BODY_LIMIT as u}from"../../../cloud/historical-contract.js";import{canonicalHistoricalJson as f,historicalDigest as p}from"../../../cloud/historical-json.js";import{expectedFindingData as h}from"./reconcile.js";export function dependencyOrder(i){const s=new Map(i.map(o=>[o.source.id,o])),n=new Set,t=new Set,e=[],c=o=>{const r=o.source.id;if(n.has(r))return;if(t.has(r))throw new Error(`Cyclic finding relationship: ${r}`);t.add(r);const a=o.relationship?.targetId,d=a?s.get(a):void 0;d&&c(d),t.delete(r),n.add(r),e.push(o)};return i.forEach(c),e}export function batchRecords(i){const s=[];let n=[];const t=e=>e.length<=25&&Buffer.byteLength(f({schemaVersion:1,idempotencyKey:"x".repeat(128),expectedVersion:Number.MAX_SAFE_INTEGER,records:e}))<=u;for(const e of i){if(!t([e]))throw new Error(`Record cannot fit a historical batch: ${e.source.id}`);t([...n,e])||(s.push(n),n=[]),n.push(e)}return n.length&&s.push(n),s}export function beginCommand(i,s){const n=[...i.runs.filter(t=>!Object.hasOwn(i.reusedRuns,t.runId)).map(t=>t.request.source),...i.records.map(t=>t.source)];return{schemaVersion:1,idempotencyKey:`migration-${s}`,namespace:i.namespace,inventoryDigest:p(n),inventory:n}}export function plannedRecords(i,s,n){const t=i.records.filter(e=>e.source.kind===n);return(n==="finding"?dependencyOrder(t):t).map(e=>({source:e.source,sourceRecord:e.sourceRecord,observedAt:e.observedAt,...e.case?{case:e.case}:{finding:h(e,s)},...e.relationship?{relationship:e.relationship}:{},...e.verify!==void 0?{verify:e.verify}:{}}))}

package/dist/app/cloud/migration/evidence.d.ts

@@ -0,0 +1,13 @@
+import type { MigrationMapping, PlannedRun, SourceFile } from "./model.js";
+export declare function referencedRuns(...documents: unknown[]): string[];
+export declare function verifyCitedHashes(value: unknown, sourceFiles: SourceFile[]): void;
+export declare function prepareHistoricalRun(options: {
+    sourceDir: string;
+    outputDir: string;
+    runId: string;
+    mapping: MigrationMapping;
+    sourceFiles: SourceFile[];
+    env: NodeJS.ProcessEnv;
+}): PlannedRun;
+/** Keep a cited source manifest distinct from the manifest describing derived files. */
+export declare function includeOriginalManifest(run: PlannedRun, sourceDir: string, outputDir: string, sourceFiles: SourceFile[], env: NodeJS.ProcessEnv): void;

package/dist/app/cloud/migration/evidence.js

@@ -0,0 +1,2 @@
+import $ from"node:fs";import H from"node:path";import{canonicalHistoricalJson as R,historicalDigest as F,HistoricalJsonNumber as Z,parseHistoricalJson as J}from"../../../cloud/historical-json.js";import"../../../cloud/historical-contract.js";import{stableJson as q}from"../../../evidence/storage.js";import{array as O,digest as w,object as f,readSource as P,readSourceJson as W,sanitize as U,text as b}from"./files.js";export function referencedRuns(...e){const i=new Set;function n(t){if(typeof t=="string")for(const c of t.matchAll(/\.testkit\/results\/runs\/([A-Za-z0-9._-]+)\//gu))i.add(c[1]);else if(Array.isArray(t))t.forEach(n);else if(t&&typeof t=="object")for(const[c,m]of Object.entries(t)){if(c==="runId")i.add(b(m,"runId",256));else if(c.toLowerCase().endsWith("runids"))for(const l of O(m,c))i.add(b(l,c,256));n(m)}}if(e.forEach(n),i.size>1e4)throw new Error("Referenced run inventory exceeds 10,000 entries");for(const t of i)if(!/^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/u.test(t))throw new Error("Unsafe original run identity");return[...i].sort()}function B(e,i){if(e instanceof Z){if(!/^(?:0|[1-9]\d*)$/u.test(e.lexeme))throw new Error(`${i} must be an integer`);e=Number(e.lexeme)}if(typeof e!="number"||!Number.isSafeInteger(e)||e<0)throw new Error(`${i} must be a bounded integer`);return e}function z(e,i){const n=b(e,i,128);if(!/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,9})?(?:Z|[+-]\d\d:\d\d)$/u.test(n)||!Number.isFinite(Date.parse(n)))throw new Error(`Invalid historical ${i}`);return n}export function verifyCitedHashes(e,i){if(Array.isArray(e)){e.forEach(t=>{verifyCitedHashes(t,i)});return}if(!e||typeof e!="object")return;const n=e;if(typeof n.path=="string"&&n.path.startsWith(".testkit/results/runs/")&&typeof n.sha256=="string"&&i.find(t=>t.path===n.path)?.sha256!==n.sha256)throw new Error(`Cited artifact hash does not match retained evidence: ${n.path}`);Object.values(n).forEach(t=>{verifyCitedHashes(t,i)})}function T(e,i){let n;if(e.repository)n=f(e.repository,"git.repository");else{const t=new URL(b(e.remoteUrl,"git.remoteUrl"));if(!["https:","http:"].includes(t.protocol)||t.search||t.hash)throw new Error("Historical remote URL requires explicit repository mapping");const c=t.pathname.replace(/\.git$/u,"").split("/").filter(Boolean);if(c.length!==2)throw new Error("Historical repository path is ambiguous");n={host:t.host,owner:c[0],name:c[1]}}for(const t of["host","owner","name"])if(b(n[t],`git.repository.${t}`).toLowerCase()!==i[t].toLowerCase())throw new Error("Historical repository does not match the selected repository mapping");e.repository=i,delete e.remoteUrl,delete e.repoRoot,delete e.worktreePath}export function prepareHistoricalRun(e){const{sourceDir:i,outputDir:n,runId:t,mapping:c,sourceFiles:m,env:l}=e,j=`.testkit/results/runs/${t}`,I=W(i,`${j}/manifest.json`,m,8*1024**2),x=f(I,"manifest"),a={...x,schemaVersion:B(x.schemaVersion,"manifest schemaVersion")};if(a.runId!==t||a.algorithm!=="sha256"||![1,2].includes(a.schemaVersion))throw new Error("Unsupported historical manifest schema or identity");const p=O(a.files,"manifest.files").map(r=>{const s=f(r,"manifest entry"),d=b(s.path,"manifest path"),D=B(s.bytes,"manifest entry bytes");if(d==="manifest.json"||!/^[a-f0-9]{64}$/u.test(String(s.sha256)))throw new Error("Invalid manifest entry");return{path:d,bytes:D,sha256:String(s.sha256)}});if(p.length<2||p.length>1e4||new Set(p.map(r=>r.path)).size!==p.length)throw new Error("Invalid or duplicate manifest entries");if(w(q(p))!==a.digest)throw new Error("Original manifest file-list digest mismatch");if(p.reduce((r,s)=>r+s.bytes,0)>2*1024**3)throw new Error("Historical bundle exceeds 2 GiB");const u=[],V=[];let E="",g;for(const r of p.sort((s,d)=>s.path==="run.json"?-1:d.path==="run.json"?1:s.path.localeCompare(d.path))){const s=P(i,`${j}/${r.path}`,m);if(s.length!==r.bytes||w(s)!==r.sha256)throw new Error(`Evidence hash/size mismatch: ${r.path}`);let d=s;const D=[];if(r.path==="run.json"||r.path==="provenance.json"){if(s.length>8*1024**2)throw new Error("Historical run/provenance exceeds 8 MiB");const o=f(J(new TextDecoder("utf-8",{fatal:!0}).decode(s)),r.path);if(r.path==="run.json"){const h=f(o.run,"run");if(h.id!==t||B(o.schemaVersion,"run schemaVersion")!==(a.schemaVersion===1?16:19))throw new Error("Unsupported historical run schema or identity");const v=z(h.startedAt,"startedAt"),S=h.finishedAt==null?v:z(h.finishedAt,"finishedAt"),A=Date.parse(v),L=Date.parse(S);if(o.generatedAt!==void 0&&o.generatedAt!==""&&z(o.generatedAt,"generatedAt"),!Number.isFinite(A)||!Number.isFinite(L)||L<A||A>Date.now())throw new Error("Invalid historical observation times");if(!["passed","failed","cancelled","interrupted","incomplete"].includes(String(h.status)))throw new Error("Unsupported historical run status");E=S;const N=f(o.git,"run.git");T(N,c.repository),g=N,o.product&&delete f(o.product,"product").directory,delete o.host}else{if(o.runId!==t||B(o.schemaVersion,"provenance schemaVersion")!==(a.schemaVersion===1?1:3))throw new Error("Unsupported historical provenance schema or identity");const h=f(o.source,"provenance.source");if(delete h.root,h.git){const S=f(h.git,"provenance.source.git");T(S,c.repository);for(const A of["branch","commitSha"])if(S[A]!=null&&S[A]!==g?.[A])throw new Error("Historical provenance disagrees with run identity")}const v=o.runtime?f(o.runtime,"runtime"):void 0;v&&delete v.hostname,v?.controller&&delete f(v.controller,"controller").hostname}if(d=Buffer.from(R(U(o,l))+`
+`),d.length>8*1024**2)throw new Error("Derived run/provenance exceeds 8 MiB");D.push("Normalize repository from original metadata; remove machine paths and hostname; sanitize text; canonical JSON; preserve original schema, run identity and observation times")}else try{const o=new TextDecoder("utf-8",{fatal:!0}).decode(s);if(!o.includes("\0")){const h=String(U(o,l));h!==o&&(d=Buffer.from(h),D.push("Redact sensitive text and the configured Cloud credential"))}}catch{}const M=H.join(n,"evidence",t,r.path);let k=n;for(const o of["evidence",t,...r.path.split("/").slice(0,-1)]){k=H.join(k,o),$.existsSync(k)||$.mkdirSync(k,{mode:448});const h=$.lstatSync(k);if(h.isSymbolicLink()||!h.isDirectory())throw new Error("Derived evidence directory must not contain symlinks or files")}$.writeFileSync(M,d,{mode:384,flag:"wx"}),u.push({path:r.path,absolutePath:M,bytes:d.length,sha256:w(d)}),V.push({path:r.path,originalPath:`${j}/${r.path}`,originalBytes:r.bytes,originalSha256:r.sha256,...d.equals(s)?{}:{transformation:D.join("; ")}})}if(!u.some(r=>r.path==="run.json")||!u.some(r=>r.path==="provenance.json"))throw new Error("Historical bundle lacks run.json or provenance.json");const y={runId:t,observedAt:E,originalManifestSha256:b(m.find(r=>r.path===`${j}/manifest.json`)?.sha256,"original manifest SHA256",64),originalManifestDigest:b(a.digest,"manifest.digest",64),converterVersion:"testkit-legacy-v1",schemaTuple:{manifest:B(a.schemaVersion,"manifest.schemaVersion"),run:a.schemaVersion===1?16:19,provenance:a.schemaVersion===1?1:3}},C=u.map(({path:r,bytes:s,sha256:d})=>({path:r,bytes:s,sha256:d})).sort((r,s)=>r.path.localeCompare(s.path)),_={algorithm:"sha256",schemaVersion:a.schemaVersion,runId:t,createdAt:b(a.createdAt,"manifest.createdAt"),files:C,digest:w(q(C)),redaction:U(a.redaction??{},l),storage:{fileCount:u.length,logicalBytes:u.reduce((r,s)=>r+s.bytes,0),deduplicatedBytes:0,objectBytesWritten:0}};return{runId:t,observedAt:E,request:{schemaVersion:1,source:{kind:"run",id:Buffer.byteLength(t)<=128?t:`run_${w(t)}`,digest:F(y)},sourceRecord:y,manifest:_,artifacts:V},files:u}}export function includeOriginalManifest(e,i,n,t,c){const m=`.testkit/results/runs/${e.runId}/manifest.json`,l=P(i,m,t,8*1024**2);if(w(l)!==e.request.sourceRecord.originalManifestSha256)throw new Error(`Original manifest changed during planning: ${e.runId}`);const j=J(new TextDecoder("utf-8",{fatal:!0}).decode(l)),I=U(j,c),x=R(j)!==R(I),a=x?Buffer.from(R(I)):l;if(e.files.length>=1e4||e.files.reduce((g,y)=>g+y.bytes,a.length)>2*1024**3)throw new Error(`Cited original manifest exceeds derived evidence limits: ${e.runId}`);const p=H.join(n,"evidence",e.runId),u=$.lstatSync(p);if(!u.isDirectory()||u.isSymbolicLink())throw new Error("Derived evidence directory is unsafe");const V=H.join(p,"manifest.json");$.writeFileSync(V,a,{mode:384,flag:"wx"}),e.files.push({path:"manifest.json",absolutePath:V,bytes:a.length,sha256:w(a)}),e.request.artifacts.push({path:"manifest.json",originalPath:m,originalBytes:l.length,originalSha256:w(l),...x?{transformation:"Redact sensitive original manifest fields and Cloud credential"}:{}});const E=e.files.map(({path:g,bytes:y,sha256:C})=>({path:g,bytes:y,sha256:C})).sort((g,y)=>g.path.localeCompare(y.path));e.request.manifest.files=E,e.request.manifest.digest=w(q(E)),e.request.manifest.storage={...f(e.request.manifest.storage,"derived manifest storage"),fileCount:E.length,logicalBytes:E.reduce((g,y)=>g+y.bytes,0)}}

package/dist/app/cloud/migration/files.d.ts

@@ -0,0 +1,16 @@
+import crypto from "node:crypto";
+import type { SourceFile } from "./model.js";
+export declare const digest: (bytes: crypto.BinaryLike) => string;
+export declare function object(value: unknown, label: string): Record<string, unknown>;
+export declare function text(value: unknown, label: string, max?: number): string;
+export declare function array(value: unknown, label: string): unknown[];
+export declare function plain(value: unknown): unknown;
+export declare function contained(root: string, relative: string): string;
+export declare function readBoundedFile(filename: string, maxBytes?: number): Buffer;
+export declare function readSource(root: string, relative: string, inventory: SourceFile[], maxBytes?: number): Buffer;
+export declare function readSourceJson(root: string, relative: string, inventory: SourceFile[], maxBytes?: number): unknown;
+export declare function sanitize(value: unknown, env: NodeJS.ProcessEnv): unknown;
+export declare function writeDocument(filename: string, value: unknown): void;
+export declare function readDocument(filename: string): unknown;
+export declare function separateOutput(source: string, output: string): void;
+export declare function withOutputLock<T>(output: string, work: () => Promise<T>): Promise<T>;

package/dist/app/cloud/migration/files.js

@@ -0,0 +1,2 @@
+import y from"node:crypto";import i from"node:fs";import d from"node:os";import u from"node:path";import{canonicalHistoricalJson as m,parseHistoricalJson as h,HistoricalJsonNumber as l}from"../../../cloud/historical-json.js";import{redactSensitiveText as w}from"../../../kernel/redaction.js";export const digest=r=>y.createHash("sha256").update(r).digest("hex");export function object(r,n){if(!r||typeof r!="object"||Array.isArray(r))throw new Error(`${n} must be an object`);return r}export function text(r,n,e=4096){if(typeof r!="string"||!r.trim()||r.includes("\0")||Buffer.byteLength(r)>e)throw new Error(`${n} must be a nonblank string of at most ${String(e)} bytes`);return r}export function array(r,n){if(!Array.isArray(r))throw new Error(`${n} must be an array`);return r}export function plain(r){if(r instanceof l){const n=Number(r.lexeme);if(!Number.isFinite(n)||Number.isInteger(n)&&!Number.isSafeInteger(n))throw new Error("Numeric field exceeds supported range");return n}return Array.isArray(r)?r.map(plain):r&&typeof r=="object"?Object.fromEntries(Object.entries(r).map(([n,e])=>[n,plain(e)])):r}export function contained(r,n){if(u.isAbsolute(n)||u.win32.isAbsolute(n)||/[\\:\0]/u.test(n)||n.split("/").some(o=>!o||o==="."||o===".."))throw new Error("Source reference must be a normalized relative path");const e=u.resolve(r,n);let t=r;for(const o of n.split("/"))if(t=u.join(t,o),i.lstatSync(t).isSymbolicLink())throw new Error(`Symlink is not allowed: ${n}`);if(!i.statSync(e).isFile())throw new Error(`Source reference is not a file: ${n}`);return e}export function readBoundedFile(r,n=128*1024**2){const e=i.lstatSync(r);if(!e.isFile()||e.isSymbolicLink()||e.size>n)throw new Error("File must be regular and within its byte limit");const t=i.openSync(r,i.constants.O_RDONLY|i.constants.O_NOFOLLOW);try{const o=i.fstatSync(t);if(!o.isFile()||o.ino!==e.ino||o.dev!==e.dev||o.size!==e.size)throw new Error("Source changed during read");const s=Buffer.alloc(e.size+1);let c=0;for(;c<s.length;){const f=i.readSync(t,s,c,s.length-c,null);if(!f)break;c+=f}const a=i.fstatSync(t);if(c!==e.size||a.size!==e.size||a.mtimeMs!==e.mtimeMs||a.ctimeMs!==e.ctimeMs)throw new Error("Source changed during read");return s.subarray(0,c)}finally{i.closeSync(t)}}export function readSource(r,n,e,t=128*1024**2){const o=contained(r,n),s=readBoundedFile(o,t),c={path:n,bytes:s.length,sha256:digest(s)},a=e.find(f=>f.path===n);if(a&&(a.sha256!==c.sha256||a.bytes!==c.bytes))throw new Error(`Source changed during inventory: ${n}`);return a||e.push(c),s}export function readSourceJson(r,n,e,t=32*1024**2){return h(new TextDecoder("utf-8",{fatal:!0}).decode(readSource(r,n,e,t)),{maxBytes:t})}export function sanitize(r,n){const e=n.TESTKIT_CLOUD_TOKEN;function t(o){if(typeof o=="string"){const s=o.replace(/[a-z][a-z0-9+.-]*:\/\/[^\s"'<>]+/giu,a=>{try{const f=new URL(a);return f.username="",f.password="",f.search="",f.hash="",f.toString()}catch{return"<redacted-url>"}});let c=w(s).replace(/\bBearer\s+[^\s"']+/giu,"Bearer <redacted>").replace(/\btkc_cli_[A-Za-z0-9_-]{43}\b/gu,"<redacted>");return e&&(e.length>=12?c=c.replaceAll(e,"<redacted>"):c===e&&(c="<redacted>")),c}return o instanceof l?o:Array.isArray(o)?o.map(t):o&&typeof o=="object"?Object.fromEntries(Object.entries(o).map(([s,c])=>[s,/^(?:password|(?:access[_-]?|refresh[_-]?)?token|(?:client[_-]?)?secret|private[_-]?key|authorization|cookie|session|api[_-]?key)$/iu.test(s)?"<redacted>":t(c)])):o}return t(r)}export function writeDocument(r,n){const e=m(n)+`
+`;if(Buffer.byteLength(e)>128*1024**2)throw new Error("Migration document exceeds 128 MiB");i.mkdirSync(u.dirname(r),{recursive:!0,mode:448});const t=`${r}.${y.randomUUID()}.tmp`,o=i.openSync(t,"wx",384);try{try{i.writeFileSync(o,e),i.fsyncSync(o)}finally{i.closeSync(o)}i.renameSync(t,r)}finally{i.rmSync(t,{force:!0})}if(process.platform!=="win32"){const s=i.openSync(u.dirname(r),"r");try{i.fsyncSync(s)}finally{i.closeSync(s)}}}export function readDocument(r){const n=h(new TextDecoder("utf-8",{fatal:!0}).decode(readBoundedFile(r)),{maxBytes:134217728});function e(t,o=""){return o==="sourceRecord"||o==="record"?t:t instanceof l?plain(t):Array.isArray(t)?t.map(s=>e(s)):t&&typeof t=="object"?Object.fromEntries(Object.entries(t).map(([s,c])=>[s,e(c,s)])):t}return e(n)}export function separateOutput(r,n){const e=i.realpathSync(r);let t=u.resolve(n);const o=[];for(;!i.existsSync(t);)o.unshift(u.basename(t)),t=u.dirname(t);const s=u.join(i.realpathSync(t),...o);for(const[c,a]of[[e,s],[s,e]]){const f=u.relative(c,a);if(!f||!f.startsWith(`..${u.sep}`)&&f!==".."&&!u.isAbsolute(f))throw new Error("Migration output must be outside and separate from the source root")}}export async function withOutputLock(r,n){i.mkdirSync(r,{recursive:!0,mode:448});const e=u.join(r,".migration-lock"),t=u.join(r,".migration-lock-acquire");let o;try{o=i.openSync(t,"wx",384)}catch(a){throw object(a,"lock acquisition error").code==="EEXIST"?new Error("Migration lock acquisition is already running. If its process crashed, verify no migration is acquiring this directory before manually removing .migration-lock-acquire",{cause:a}):a}const s=i.fstatSync(o),c=y.randomUUID();try{if(i.writeFileSync(o,JSON.stringify({pid:process.pid,host:d.hostname(),owner:c})),i.existsSync(e)){const f=object(JSON.parse(readBoundedFile(e,4096).toString("utf8")),"lock");let p=!1;if(f.host===d.hostname()&&Number.isSafeInteger(f.pid)&&Number(f.pid)>0)try{process.kill(Number(f.pid),0)}catch(S){p=object(S,"process error").code==="ESRCH"}if(!p)throw new Error("Migration output is locked by another process");i.unlinkSync(e)}const a=i.openSync(e,"wx",384);try{i.writeFileSync(a,JSON.stringify({pid:process.pid,host:d.hostname(),owner:c}))}finally{i.closeSync(a)}}finally{if(i.closeSync(o),i.existsSync(t)){const a=i.lstatSync(t);a.ino===s.ino&&a.dev===s.dev&&i.unlinkSync(t)}}try{return await n()}finally{i.existsSync(e)&&object(JSON.parse(readBoundedFile(e,4096).toString("utf8")),"lock").owner===c&&i.unlinkSync(e)}}

package/dist/app/cloud/migration/index.d.ts

@@ -0,0 +1,6 @@
+import { type MigrationProgressCallback } from "./progress.js";
+export type { MigrationProgress, MigrationProgressCallback } from "./progress.js";
+import type { MigrationResult } from "./model.js";
+export { planMigration } from "./plan.js";
+export declare function applyMigration(planPath: string, env?: NodeJS.ProcessEnv, onProgress?: MigrationProgressCallback): Promise<MigrationResult>;
+export declare function reconcileMigration(planPath: string, env?: NodeJS.ProcessEnv, onProgress?: MigrationProgressCallback): Promise<MigrationResult>;

package/dist/app/cloud/migration/index.js

@@ -0,0 +1 @@
+import w from"node:path";import{cloudToken as v}from"../credentials.js";import{HistoricalClient as O}from"../../../cloud/historical.js";import{sanitize as h,withOutputLock as $,writeDocument as j}from"./files.js";import{reconcileState as E}from"./reconcile.js";import{loadPlan as M,openJournal as k,performOperation as q,verifyPlanFiles as P,upgradeJournal as x}from"./state.js";import{transfer as R}from"./transfer.js";import{operationIs as V}from"./journal.js";import{createMigrationProgress as C}from"./progress.js";export{planMigration}from"./plan.js";export function applyMigration(m,i=process.env,c){return S(m,i,!0,c)}export function reconcileMigration(m,i=process.env,c){return S(m,i,!1,c)}async function S(m,i,c,r){const n=C(r,i),u=w.resolve(m),a=w.join(w.dirname(u),"report.json"),o={complete:!1,planPath:u,reportPath:a,problems:[]};try{n.emit("source-verification",{operation:"source-verification"});const{plan:t,planDigest:y}=M(u);return n.emit("source-verification",{totalRuns:t.runs.length,operation:"source-verification"}),await $(t.outputDir,async()=>{let d={planDigest:y,target:t.target,sourceSummary:t.sourceSummary,dispositions:t.dispositions??[]};try{if(P(t),!t.ready||t.problems.length)throw o.problems=t.problems,new Error("Migration plan has unresolved decisions");const e=k(t,y),s=new O({...t.target,token:await v(t.target.origin,i)});if(n.emit("source-verification",{completedRuns:Object.keys(e.receiptIds).length,operation:"source-verification"}),c){const l=e.schemaVersion===1;x(t,e),l&&e.upgradedFrom===1&&n.emit("journal-upgrade",{operation:"journal-upgrade",detail:"Schema 1 to schema 2; saved requests retained"}),await R(t,e,s,i,n)}e.importId&&(o.importId=e.importId),n.emit("reconciliation",{completedRuns:Object.keys(e.receiptIds).length,operation:"reconcile"});let I=0,p=await E(t,e,s,{onVerified(l){I+=l,n.emit("reconciliation",{verifiedBytes:I,operation:"reconcile"})}});if(c&&p.complete&&e.importId){const l=e.importId,b=e.operations.some(g=>g.key==="complete"&&g.state!=="accepted");n.emit("reconciliation",{operation:"complete-import",retries:n.current.retries+(b?1:0)}),await q(t,e,"complete","complete",{importId:l},()=>s.complete(l),i),n.emit("reconciliation",{operation:"verify-completion"}),p=await p.verifyCompletion()}o.problems.push(...p.problems);const f=e.importId?!!(await s.page(e.importId)).import.completedAt:!1;f||o.problems.push({kind:"import",id:e.importId??"missing",field:"completion",detail:"Server import is not complete"}),o.complete=p.complete&&f,n.emit(o.complete?"completion":"failed",{...o.problems[0]?{operation:"reconcile",detail:o.problems[0].detail}:{}}),d={...d,items:p.items,counts:p.counts,campaignVersion:p.campaignVersion,receiptIds:e.receiptIds,caseIds:e.caseIds,operations:e.operations.map(({key:l,state:b,error:g})=>({key:l,state:b,...g?{error:g}:{}}))}}catch(e){n.fail(e),o.problems.push({kind:"migration",id:"operation",field:c?"apply":"reconcile",detail:String(h(e instanceof Error?e.message:String(e),i))});try{const s=k(t,y);s.importId&&(o.importId=s.importId),d={...d,localOutcomes:D(t,s),receiptIds:s.receiptIds,caseIds:s.caseIds,operations:s.operations.map(({key:I,state:p,error:f})=>({key:I,state:p,...f?{error:f}:{}}))}}catch(s){d.journalError=String(h(s instanceof Error?s.message:String(s),i))}}return j(a,h({...d,...o},i)),o})}catch(t){return n.fail(t),o.problems.push({kind:"migration",id:"plan",field:"preflight",detail:String(h(t instanceof Error?t.message:String(t),i))}),o}}function D(m,i){const c=new Map;for(const r of m.runs)c.set(`run:${r.request.source.id}`,{...r.request.source,status:i.receiptIds[r.runId]?Object.hasOwn(m.reusedRuns,r.runId)?"reused":"accepted":"pending",...i.receiptIds[r.runId]?{cloudId:i.receiptIds[r.runId]}:{}});for(const r of m.records)c.set(`${r.source.kind}:${r.source.id}`,{...r.source,originalId:r.originalId,status:"pending"});for(const r of i.operations){const n=JSON.parse(r.request);for(const a of n.records??[]){const o=c.get(`${a.source.kind}:${a.source.id}`);o&&(o.status=r.state==="accepted"?"accepted":r.state)}const u=V(r,"batch")?r.result:void 0;for(const a of u?.items??[]){const o=c.get(`${a.kind}:${a.id}`);o&&c.set(`${a.kind}:${a.id}`,{...o,...a})}}return[...c.values()]}