@gfdelarue/testkit 0.3.6 → 0.4.0

package/dist/cloud/historical.d.ts

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

package/dist/cloud/historical.js

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

package/dist/cloud/pagination.d.ts

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

package/dist/cloud/pagination.js

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

package/dist/cloud/transport.d.ts

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

package/dist/cloud/transport.js

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

package/dist/config/loader/cloud.d.ts

@@ -1,2 +0,0 @@
-/** Local submission policy only. Cloud independently owns acceptance. */
-export declare function minimumConfirmingRuns(config: object): number;

package/dist/config/loader/cloud.js

@@ -1 +0,0 @@
-import{isUnknownRecord as e}from"../../kernel/unknown-values.js";import{attachErrorDiagnostics as t}from"../../kernel/error-serialization.js";export function minimumConfirmingRuns(o){let i=o;for(const r of["cloud","verification","minimumConfirmingRuns"]){if(!e(i))throw n();if(i=i[r],i===void 0)return 2}if(typeof i!="number"||!Number.isSafeInteger(i)||i<1||i>64)throw n();return i}function n(){return t(Object.assign(new Error("cloud.verification.minimumConfirmingRuns must be an integer from 1 through 64"),{code:"invalid_cloud_verification_config"}),{source:"local",field:"cloud.verification.minimumConfirmingRuns"})}

package/docs/cloud-control.md

@@ -1,108 +0,0 @@
-# Cloud command reference
-
-The `testkit cloud` commands are deprecated. See the
-[Cloud boundary](testkit-cloud-boundary.md) for the direction.
-
-`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.