@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/cli/commands/init-config.js

@@ -0,0 +1,233 @@
+import { SIGN_IN } from "../../spec/sign-in.js";
+import { rootsOf } from "../../report/console/roots.js";
+import { prefixRoots } from "../../spec/graph/roots.js";
+import { buildModel } from "../../spec/graph/build.js";
+import { listEndpoints } from "../../spec/endpoints.js";
+import { placementOf } from "../../spec/security/placement.js";
+import { resolveSecurity } from "../../spec/security/requirements.js";
+import { readSchemes } from "../../spec/security/schemes.js";
+import { fieldLines, quote } from "./init-code.js";
+const UNTESTED = "Operations that need only it are reported untested.";
+const OWNED_GRANTS = "The API tester performs only clientCredentials and password grants; supply a token obtained elsewhere";
+const HOLDS = "the scopes this credential carries; operations needing scopes it lacks are untested";
+/** Each scheme's env var stem, `TESTING_API_<NAME>`, with `_2`, `_3` for a later scheme whose stem is taken. */
+function envStems() {
+    const taken = new Set();
+    return (scheme) => {
+        const words = scheme
+            .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+            .replace(/[^A-Za-z0-9]+/g, "_")
+            .replace(/^_|_$/g, "");
+        const base = `TESTING_API_${words.toUpperCase() || "SCHEME"}`;
+        let stem = base;
+        for (let n = 2; taken.has(stem); n++)
+            stem = `${base}_${n}`;
+        taken.add(stem);
+        return stem;
+    };
+}
+function usageOf(doc) {
+    const endpoints = listEndpoints(doc).map((endpoint) => ({ endpoint, security: resolveSecurity(endpoint.op, doc) }));
+    const required = endpoints.flatMap(({ security }) => security.alternatives.flat());
+    const signIn = endpoints.find(({ endpoint, security }) => endpoint.method === "post" &&
+        endpoint.op.operationId !== undefined &&
+        SIGN_IN.test(endpoint.path) &&
+        security.alternatives.some((alternative) => alternative.length === 0))?.endpoint.op.operationId;
+    const scopes = (scheme) => [...new Set(required.filter((need) => need.scheme === scheme).flatMap((need) => need.scopes))].toSorted();
+    return signIn === undefined ? { scopes } : { scopes, signIn };
+}
+const env = (name) => `env(${quote(name)})`;
+/** Where a scheme's credential goes, as its placement says: `in header Authorization: Bearer {credential}`. */
+function placed(scheme) {
+    const place = placementOf(scheme);
+    const where = `in ${place.in} ${place.name}`;
+    if (place.template === "{credential}")
+        return where;
+    const filled = place.encode === "base64" ? place.template.replace("{credential}", "base64(username:password)") : place.template;
+    return `${where}: ${filled}`;
+}
+/* An API key in the header a bearer token goes in: the server may expect a prefix there, as it does for the token. */
+function inPrefixedHeader(scheme) {
+    const own = placementOf(scheme);
+    const bearer = placementOf({ deprecated: false, kind: "bearer", name: scheme.name });
+    return own.in === bearer.in && own.name.toLowerCase() === bearer.name.toLowerCase();
+}
+/* A static token or key: what most schemes take, with the scopes it must hold when operations ask for some. */
+function staticRecipe(name, comments, scopes) {
+    const holds = scopes.length === 0 ? [] : [`holds: [${scopes.map(quote).join(", ")}], // ${HOLDS}`];
+    return { comments: [...comments, ...holds], env: [name], value: [{ key: "static", value: env(name) }] };
+}
+function oauth2Recipe(scheme, stem, scopes) {
+    const grant = ["clientCredentials", "password"].find((flow) => scheme.flows[flow]?.tokenUrl !== undefined);
+    if (grant === undefined) {
+        const flows = Object.keys(scheme.flows);
+        const kind = `oauth2${flows.length === 0 ? "" : ` ${flows.join(", ")}`} ${placed(scheme)}`;
+        return staticRecipe(`${stem}_TOKEN`, [kind, OWNED_GRANTS], scopes);
+    }
+    const [id, secret, username, password] = ["CLIENT_ID", "CLIENT_SECRET", "USERNAME", "PASSWORD"].map((suffix) => `${stem}_${suffix}`);
+    const credentials = grant === "password"
+        ? [
+            { comment: `clientSecret: ${env(secret)},` },
+            { key: "username", value: env(username) },
+            { key: "password", value: env(password) },
+        ]
+        : [{ key: "clientSecret", value: env(secret) }];
+    const fields = [
+        { key: "flow", value: quote(grant) },
+        { key: "clientId", value: env(id) },
+        ...credentials,
+        ...(scopes.length === 0 ? [] : [{ key: "scopes", value: scopes.map(quote) }]),
+    ];
+    return {
+        comments: [`oauth2 ${grant}, token from ${scheme.flows[grant]?.tokenUrl}`],
+        env: grant === "password" ? [id, username, password] : [id, secret],
+        value: [{ key: "oauth2", value: fields }],
+    };
+}
+/** The recipe a supported scheme gets, with the comments that say where its credential goes. */
+function recipeOf(scheme, stem, usage) {
+    const scopes = usage.scopes(scheme.name);
+    switch (scheme.kind) {
+        case "bearer": {
+            const format = scheme.bearerFormat === undefined ? "" : ` (${scheme.bearerFormat})`;
+            const login = usage.signIn === undefined ? [] : [signInComment(usage.signIn)];
+            return staticRecipe(`${stem}_TOKEN`, [`http bearer${format} ${placed(scheme)}`, ...login], scopes);
+        }
+        case "basic": {
+            const pair = [
+                { key: "username", value: env(`${stem}_USERNAME`) },
+                { key: "password", value: env(`${stem}_PASSWORD`) },
+            ];
+            return {
+                comments: [`http basic ${placed(scheme)}`],
+                env: [`${stem}_USERNAME`, `${stem}_PASSWORD`],
+                value: [{ key: "static", value: pair }],
+            };
+        }
+        case "apiKey": {
+            const prefix = inPrefixedHeader(scheme)
+                ? ['add format: "<Prefix> {credential}" if the server expects a prefix']
+                : [];
+            return staticRecipe(`${stem}_KEY`, [`apiKey ${placed(scheme)}`, ...prefix], scopes);
+        }
+        case "openIdConnect":
+            return staticRecipe(`${stem}_TOKEN`, [`openIdConnect ${placed(scheme)}`, `a token from ${scheme.openIdConnectUrl}`], scopes);
+        case "oauth2":
+            return oauth2Recipe(scheme, stem, scopes);
+    }
+}
+const signInComment = (operationId) => `or sign in: login: { steps: [{ operationId: ${quote(operationId)}, body: {} }], from: "$.access_token" }`;
+/** The declared type of a scheme the API tester cannot send, as the document writes it: `mutualTLS`, `http digest`. */
+function declaredType(raw) {
+    const declared = (raw ?? {});
+    if (typeof declared.type !== "string")
+        return "no type";
+    return declared.type === "http" ? `http ${String(declared.scheme ?? "")}`.trim() : declared.type;
+}
+/** The first description line of a scheme, as a sentence after its placement. */
+function described(raw) {
+    const description = raw?.description;
+    const first = typeof description === "string" ? description.split("\n")[0]?.trim() : undefined;
+    return first === undefined || first === "" ? "" : `. ${first}`;
+}
+/** The first absolute http(s) server URL, its variables filled with their defaults. */
+/**
+ * The first server the API tester can call: absolute once its variables take their defaults, or relative and
+ * resolved against the document's own URL, as OpenAPI says. A document read from a file gives a
+ * relative server no base, so the config asks for one.
+ */
+function serverUrl(doc, spec) {
+    const base = /^https?:\/\//.test(spec) ? spec : undefined;
+    for (const server of doc.servers ?? []) {
+        const variables = (server.variables ?? {});
+        const filled = server.url.replace(/\{([^}]*)\}/g, (whole, name) => {
+            const fill = variables[name]?.default;
+            return typeof fill === "string" ? fill : whole;
+        });
+        const url = /^https?:\/\//.test(filled) || base === undefined ? filled : new URL(filled, base).href;
+        if (/^https?:\/\/[^{}]+$/.test(url))
+            return url.replace(/\/$/, "");
+    }
+    return undefined;
+}
+const NO_SCHEME = [
+    { comment: "The document declares no security scheme. If the API needs a credential, declare it:" },
+    {
+        comment: 'overlay: { securitySchemes: { bearer: { type: "http", scheme: "bearer" } }, security: [{ bearer: [] }] },',
+    },
+    { comment: 'security: { bearer: { static: env("TESTING_API_BEARER_TOKEN") } },' },
+];
+const PRINCIPAL = "one principal; a second with a different tenant enables the isolation checks";
+const NAMED = 4;
+/*
+ * The principal's body: a commented `scope` for each prefix root no create operation makes, and the
+ * operations each one unlocks. Ids a flow yields (an invite's token) are a run's to pick up, not the config's.
+ */
+function principalStub(doc) {
+    const model = buildModel(doc);
+    const prefix = prefixRoots(model);
+    const roots = rootsOf(model).required;
+    if (roots.length === 0)
+        return [];
+    const unlocks = roots.map((root) => {
+        /* A required root is a prefix root, so its operations are always there. */
+        const operations = prefix.get(root);
+        const more = operations.length > NAMED ? ` and ${operations.length - NAMED} more` : "";
+        return { comment: `${root} unlocks ${operations.slice(0, NAMED).join(", ")}${more}` };
+    });
+    return [
+        { comment: "no create operation makes these path parameters; set each to one this principal can reach:" },
+        { comment: `scope: { ${roots.map((root) => `${root}: ""`).join(", ")} },` },
+        ...unlocks,
+    ];
+}
+/** The config `testing api init` writes for `doc`, read from `spec` and written to `out`. */
+export function renderInitConfig(doc, where) {
+    const declared = doc.components?.securitySchemes ?? {};
+    const schemes = readSchemes(doc);
+    const usage = usageOf(doc);
+    const stemOf = envStems();
+    const base = serverUrl(doc, where.spec);
+    const names = base === undefined ? ["TESTING_API_BASE_URL"] : [];
+    const unsupported = [];
+    const security = [];
+    for (const scheme of schemes.values()) {
+        if (scheme.kind === "unsupported") {
+            const type = declaredType(declared[scheme.name]);
+            unsupported.push({ name: scheme.name, type, why: scheme.unsupported });
+            security.push({
+                comment: `${scheme.name}: ${type}, not sent by the API tester — ${scheme.unsupported}. ${UNTESTED}`,
+            });
+            continue;
+        }
+        const recipe = recipeOf(scheme, stemOf(scheme.name), usage);
+        const [kind = "", ...rest] = recipe.comments;
+        names.push(...recipe.env);
+        security.push({
+            comments: [`${kind}${described(declared[scheme.name])}`, ...rest],
+            key: scheme.name,
+            value: recipe.value,
+        });
+    }
+    const fields = [
+        { key: "spec", value: quote(where.spec) },
+        { key: "baseUrl", value: base === undefined ? env("TESTING_API_BASE_URL") : quote(base) },
+        ...(schemes.size === 0 ? NO_SCHEME : [{ key: "security", value: security }]),
+        { key: "principals", value: [{ comments: [PRINCIPAL], key: "alpha", value: principalStub(doc) }] },
+    ];
+    const next = `testing api doctor --config ${where.out}`;
+    const header = names.length === 0
+        ? `// Written by testing api init from ${where.spec}. Run: ${next}`
+        : `// Written by testing api init from ${where.spec}. Set each env() variable, then run: ${next}`;
+    const text = [
+        header,
+        `import { ${names.length === 0 ? "defineConfig" : "defineConfig, env"} } from "@workerstack/testing/api"`,
+        "",
+        "export default defineConfig({",
+        ...fieldLines(fields, 1),
+        "})",
+        "",
+    ].join("\n");
+    return { env: names, schemes: schemes.size - unsupported.length, text, unsupported };
+}
+//# sourceMappingURL=init-config.js.map

package/dist/api/cli/commands/init.d.ts

@@ -0,0 +1,13 @@
+import { type Args } from "../flags.ts";
+import type { Writer } from "../writer.ts";
+/**
+ * The `spec` a config written to `out` holds: a relative path rebased onto `out`'s folder, which is
+ * where a config's relative paths resolve from. A URL and an absolute path stay as given.
+ */
+export declare function specFromConfig(spec: string, out: string): string;
+/**
+ * `testing api init --spec <url|file> [--out file] [--force]`: writes a starter config from the document's
+ * security schemes, and prints the env vars it reads. An existing file is kept unless `--force`.
+ */
+export declare function commandInit(writer: Writer, flags: Args["flags"]): Promise<number>;
+//# sourceMappingURL=init.d.ts.map

package/dist/api/cli/commands/init.js

@@ -0,0 +1,68 @@
+import { writeFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, relative, resolve, sep } from "node:path";
+import { UsageError } from "../../errors/usage-error.js";
+import { EXIT } from "../../runtime/exit.js";
+import { fetchSpecText } from "../../runtime/network/fetch.js";
+import { dereference } from "../../spec/load/dereference.js";
+import { loadSpec } from "../../spec/load/source.js";
+import { str, USAGE } from "../flags.js";
+import { renderInitConfig } from "./init-config.js";
+/* A config the API tester can import: one module, never JSON, which cannot call env(). */
+const MODULES = /* @__PURE__ */ new Set([".ts", ".mts", ".js", ".mjs"]);
+/**
+ * The `spec` a config written to `out` holds: a relative path rebased onto `out`'s folder, which is
+ * where a config's relative paths resolve from. A URL and an absolute path stay as given.
+ */
+export function specFromConfig(spec, out) {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(spec) || isAbsolute(spec))
+        return spec;
+    return relative(dirname(resolve(out)), resolve(spec))
+        .split(sep)
+        .join("/");
+}
+/**
+ * `testing api init --spec <url|file> [--out file] [--force]`: writes a starter config from the document's
+ * security schemes, and prints the env vars it reads. An existing file is kept unless `--force`.
+ */
+export async function commandInit(writer, flags) {
+    const spec = str(flags, "spec");
+    if (spec === undefined) {
+        writer.err(`testing api: init requires --spec\n\n${USAGE}`);
+        return EXIT.usage;
+    }
+    const out = str(flags, "out") ?? "testing.api.config.ts";
+    if (!MODULES.has(extname(out))) {
+        writer.err(`testing api: init writes a module config (.ts, .mts, .js or .mjs), got ${out}\n`);
+        return EXIT.usage;
+    }
+    let doc;
+    try {
+        doc = dereference(await loadSpec(spec, { fetchText: fetchSpecText })).doc;
+    }
+    catch (error) {
+        if (!(error instanceof UsageError))
+            throw error;
+        writer.err(`${error.message}\n`);
+        return EXIT.usage;
+    }
+    const config = renderInitConfig(doc, { out, spec: specFromConfig(spec, out) });
+    try {
+        await writeFile(out, config.text, { flag: flags.force === true ? "w" : "wx" });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        writer.err(`testing api: ${out} exists; --force overwrites it\n`);
+        return EXIT.usage;
+    }
+    const schemes = `${config.schemes} scheme${config.schemes === 1 ? "" : "s"}`;
+    writer.out([
+        `  wrote ${out} — ${schemes}, 1 principal`,
+        ...(config.env.length === 0 ? [] : [`    set ${config.env.join(", ")}`]),
+        ...config.unsupported.map(({ name, type, why }) => `    ${name} (${type}) is not sent by testing api: ${why}`),
+        `    next: testing api doctor --config ${out}`,
+        "",
+    ].join("\n"));
+    return 0;
+}
+//# sourceMappingURL=init.js.map

package/dist/api/cli/commands/plan.d.ts

@@ -0,0 +1,11 @@
+import type { SpecModel } from "../../spec/graph/types.ts";
+import { planScope } from "../../runtime/scope/plan.ts";
+import { resolveTargetScope } from "../../runtime/scope/target.ts";
+import { ScopeError } from "../../runtime/scope/scope-error.ts";
+import { type Args } from "../flags.ts";
+import type { Writer } from "../writer.ts";
+/** `testing api plan`: the test model derived from the document, offline; targeted when `--ops` or `--only` says. */
+export declare function commandPlan(writer: Writer, flags: Args["flags"]): Promise<number>;
+/** The run's scope over `model`, or the caller's mistake in naming it. Any other error is a bug, and propagates. */
+export declare function targetedScope(model: SpecModel, input: Parameters<typeof resolveTargetScope>[1]): ReturnType<typeof planScope> | ScopeError;
+//# sourceMappingURL=plan.d.ts.map

package/dist/api/cli/commands/plan.js

@@ -0,0 +1,64 @@
+import { unsetEnvLines } from "../../report/console/doctor.js";
+import { report } from "../../report/console/report.js";
+import { EXIT } from "../../runtime/exit.js";
+import { authStepOperationIds } from "../../runtime/scope/entities.js";
+import { planScope } from "../../runtime/scope/plan.js";
+import { resolveTargetScope } from "../../runtime/scope/target.js";
+import { ScopeError } from "../../runtime/scope/scope-error.js";
+import { list } from "../flags.js";
+import { modeled } from "./spec.js";
+/* What of the config the plan reads: its recipes and principals, and the hook that supplies roots. */
+function configView(config) {
+    if (config === undefined)
+        return {};
+    return {
+        credentials: {
+            principals: config.principals ?? {},
+            security: config.security ?? {},
+            ...(config.writer === undefined ? {} : { writer: config.writer }),
+        },
+        hooks: config.hooks,
+    };
+}
+/** `testing api plan`: the test model derived from the document, offline; targeted when `--ops` or `--only` says. */
+export async function commandPlan(writer, flags) {
+    const read = await modeled(writer, flags);
+    if (typeof read === "number")
+        return read;
+    const { model, config, unsetEnv } = read;
+    const ops = list(flags, "ops") ?? config?.ops;
+    const only = list(flags, "only") ?? config?.only;
+    const authCreates = authStepOperationIds(config ?? {});
+    const scope = targetedScope(model, {
+        ...(ops === undefined ? {} : { ops }),
+        ...(only === undefined ? {} : { only }),
+        authCreates,
+    });
+    if (scope instanceof ScopeError) {
+        writer.err(`${scope.message}\n`);
+        return EXIT.usage;
+    }
+    /* A diagnostic beside the plan, so the plan on stdout stays the plan, as text or JSON. */
+    const [note] = unsetEnvLines(unsetEnv);
+    if (note !== undefined)
+        writer.err(`${note}\n`);
+    writer.out(report.plan(model, flags.json === true, {
+        authCreates,
+        ...configView(config),
+        scope: scope.mode === "targeted" ? scope : undefined,
+        unsetEnv,
+    }));
+    return 0;
+}
+/** The run's scope over `model`, or the caller's mistake in naming it. Any other error is a bug, and propagates. */
+export function targetedScope(model, input) {
+    try {
+        return planScope(model, resolveTargetScope(model, input));
+    }
+    catch (error) {
+        if (error instanceof ScopeError)
+            return error;
+        throw error;
+    }
+}
+//# sourceMappingURL=plan.js.map

package/dist/api/cli/commands/run-options.d.ts

@@ -0,0 +1,29 @@
+import type { ApiConfig } from "../../config/types/config.ts";
+import type { BaselineFile } from "../../runtime/baseline.ts";
+import type { ProgressHandler } from "../../runtime/progress/types.ts";
+import type { RunOptions } from "../../runtime/run/index.ts";
+import { type Args } from "../flags.ts";
+/** What the command decided around the config: where it writes, how it reports, how it stops. */
+export interface RunSetting {
+    configPath: string;
+    baseline: BaselineFile | undefined;
+    signal: AbortSignal;
+    onProgress: ProgressHandler;
+    warn: (message: string) => void;
+    /** The run folder, when its exchanges are journaled. */
+    exchangeDir: string | undefined;
+    /** Where the run keeps its account ledger: `accounts.json` in the run folder. */
+    accountsFile?: string;
+}
+/** The flags that override the config, as the run reads them. */
+export interface Overrides {
+    baseUrl: string;
+    only: string[] | undefined;
+    ops: string[] | undefined;
+    profile: string | undefined;
+}
+/** The flags over the config: a flag says what the config would, for this run only. */
+export declare function overridesOf(config: ApiConfig, flags: Args["flags"]): Overrides;
+/** The run's options, from the config, the flags over it, and what the command set up. */
+export declare function runOptionsOf(config: ApiConfig, flags: Args["flags"], setting: RunSetting): RunOptions;
+//# sourceMappingURL=run-options.d.ts.map

package/dist/api/cli/commands/run-options.js

@@ -0,0 +1,79 @@
+import { dirname, resolve } from "node:path";
+import { list, str } from "../flags.js";
+/** Config fields a run takes as they are written. */
+const AS_WRITTEN = [
+    "writer",
+    "globalHeaders",
+    "cache",
+    "hooks",
+    "uploads",
+    "security",
+    "redact",
+    "cohortSize",
+    "profiles",
+    "rateLimits",
+    "maxRps",
+    "origins",
+    "overlay",
+    "allow",
+    "fence",
+    "teardown",
+    "targetVersion",
+    "scenarios",
+    "externals",
+    "outOfBand",
+    "payloads",
+    "checks",
+    "query",
+    "entities",
+    "network",
+];
+/** The flags over the config: a flag says what the config would, for this run only. */
+export function overridesOf(config, flags) {
+    return {
+        baseUrl: str(flags, "base-url") ?? config.baseUrl,
+        only: list(flags, "only") ?? config.only?.filter((name) => name.trim() !== ""),
+        ops: list(flags, "ops") ?? config.ops?.filter((name) => name.trim() !== ""),
+        profile: str(flags, "profile") ?? config.profile,
+    };
+}
+/** The run's options, from the config, the flags over it, and what the command set up. */
+export function runOptionsOf(config, flags, setting) {
+    const { baseUrl, only, ops, profile } = overridesOf(config, flags);
+    const seed = str(flags, "seed");
+    return {
+        ...asWritten(config),
+        baseUrl,
+        configDir: dirname(resolve(setting.configPath)),
+        keepFixtures: flags["keep-fixtures"] === true || config.keepFixtures === true,
+        maxInFlight: Number.parseInt(str(flags, "max-in-flight") ?? "", 10) || config.maxInFlight || 4,
+        onProgress: setting.onProgress,
+        principals: config.principals ?? {},
+        seed: seed === undefined ? (config.seed ?? 1) : Number.parseInt(seed, 10),
+        signal: setting.signal,
+        spec: config.spec,
+        warn: setting.warn,
+        ...(flags["keep-credentials"] === true ? { keepCredentials: true } : {}),
+        ...(only === undefined || only.length === 0 ? {} : { only }),
+        ...(ops === undefined || ops.length === 0 ? {} : { ops }),
+        ...(profile === undefined ? {} : { profile }),
+        ...setUp(setting),
+    };
+}
+/* What the command set up that a run takes only when it is set: a baseline, and where to journal. */
+function setUp(setting) {
+    return {
+        ...(setting.baseline === undefined ? {} : { baseline: setting.baseline }),
+        ...(setting.exchangeDir === undefined ? {} : { exchangeDir: setting.exchangeDir }),
+        ...(setting.accountsFile === undefined ? {} : { accountsFile: setting.accountsFile }),
+    };
+}
+function asWritten(config) {
+    const picked = {};
+    for (const key of AS_WRITTEN) {
+        if (config[key] !== undefined)
+            picked[key] = config[key];
+    }
+    return picked;
+}
+//# sourceMappingURL=run-options.js.map

package/dist/api/cli/commands/run-progress.d.ts

@@ -0,0 +1,19 @@
+import type { ProgressSnapshot } from "../../runtime/progress/types.ts";
+import type { Writer } from "../writer.ts";
+/** Where a run's live status goes, and how it is closed once the run ends. */
+export interface RunProgressOut {
+    onProgress(snap: ProgressSnapshot): void;
+    /** Stops the status and shuts the files: resolved once every one is written, however often it is called. */
+    close(): Promise<void>;
+}
+/**
+ * The run's status: a line on stderr unless `quiet`, and in the run folder `progress.log` (with
+ * its glossary), `progress.tsv`, `progress.jsonl`, and `progress.json` for what is happening now.
+ */
+/** When the run started, and whether its stderr line stays quiet. */
+export interface ProgressOptions {
+    startedAt: number;
+    quiet: boolean;
+}
+export declare function runProgress(writer: Writer, outDir: string, { quiet, startedAt }: ProgressOptions): RunProgressOut;
+//# sourceMappingURL=run-progress.d.ts.map

package/dist/api/cli/commands/run-progress.js

@@ -0,0 +1,47 @@
+import { createWriteStream, writeFileSync } from "node:fs";
+import { finished } from "node:stream/promises";
+import { resolve } from "node:path";
+import { createProgressPrinter, createProgressPump } from "../../runtime/progress/pump.js";
+import { formatProgressJsonl, formatProgressLine, formatProgressTsv } from "../../runtime/progress/format.js";
+import { PROGRESS_GLOSSARY, PROGRESS_TSV_HEADER } from "../../runtime/progress/columns.js";
+/** How often `progress.json`, the one file read while the run goes on, is rewritten. */
+const JSON_EVERY_MS = 1_000;
+export function runProgress(writer, outDir, { quiet, startedAt }) {
+    const stderr = quiet ? undefined : createProgressPrinter(writer.err, startedAt);
+    const log = createWriteStream(resolve(outDir, "progress.log"));
+    const tsv = createWriteStream(resolve(outDir, "progress.tsv"));
+    const jsonl = createWriteStream(resolve(outDir, "progress.jsonl"));
+    log.write(`${PROGRESS_GLOSSARY}\n`);
+    tsv.write(`${PROGRESS_TSV_HEADER}\n`);
+    let lastJsonAt = 0;
+    const files = createProgressPump(startedAt, (snap, now) => {
+        log.write(`${formatProgressLine(snap, now)}\n`);
+        tsv.write(`${formatProgressTsv(snap, now)}\n`);
+        jsonl.write(`${formatProgressJsonl(snap, now)}\n`);
+        if (now - lastJsonAt < JSON_EVERY_MS && snap.phase !== "done")
+            return;
+        lastJsonAt = now;
+        writeFileSync(resolve(outDir, "progress.json"), `${JSON.stringify(current(snap, now), null, 2)}\n`);
+    });
+    let closing;
+    return {
+        close: () => {
+            closing ??= (() => {
+                stderr?.stop();
+                files.stop();
+                return Promise.all([log, tsv, jsonl].map((stream) => finished(stream.end()))).then(() => undefined);
+            })();
+            return closing;
+        },
+        onProgress: (snap) => {
+            stderr?.emit(snap);
+            files.emit(snap);
+        },
+    };
+}
+/** The status as `progress.json` states it: how long since the run last heard anything, and when. */
+function current(snap, now) {
+    const ageFrom = snap.inflight?.at ?? snap.last?.at;
+    return { ...snap, lastAgoMs: ageFrom === undefined ? null : now - ageFrom, updatedAt: new Date(now).toISOString() };
+}
+//# sourceMappingURL=run-progress.js.map

package/dist/api/cli/commands/run-report.d.ts

@@ -0,0 +1,42 @@
+import type { ReportInput } from "../../report/render/input.ts";
+import type { RunResult } from "../../runtime/run/index.ts";
+import type { Writer } from "../writer.ts";
+/** A report `--report` can add to the run folder. */
+export type ReportFormat = "junit";
+export declare const REPORT_FORMATS: readonly ReportFormat[];
+/** What a finished run reports: the result, and where and when it ran. */
+export interface Finished {
+    result: RunResult;
+    baseUrl: string;
+    startedAt: Date;
+    durationMs: number;
+    outDir: string;
+    /** The reports `--report` asked for beside the run's own; absent, none. */
+    formats?: readonly ReportFormat[];
+}
+/** The report's input: the result as the renderers read it. */
+export declare function reportInput({ result, baseUrl, startedAt, durationMs }: Finished): ReportInput;
+/** Where `--keep-credentials` writes, from the working directory: beside the default runs root, never in a run folder. */
+export declare const KEPT_CREDENTIALS = ".testing/api/credentials.json";
+/**
+ * The credential values a run kept (`--keep-credentials`), written to `path`, which is never under
+ * the output directory: a report is shared, and holds no credential. False when the run kept none.
+ */
+export declare function keepCredentials(result: RunResult, path: string): Promise<boolean>;
+/**
+ * Every file of the run folder: the principals as they stood, holding no credential value, the reports in markdown and JSON,
+ * JUnit XML when `--report junit` asked for it, the matrix (one graph, drawn as the poster and written as JSON), the
+ * confidence page over the journaled exchanges, and a repro script per finding.
+ */
+export declare function writeReports(finished: Finished, input: ReportInput): Promise<void>;
+/**
+ * The run's job summary, appended to `path`: the file `GITHUB_STEP_SUMMARY` names inside GitHub
+ * Actions. Nothing without one. A summary that cannot be written is a warning, never a different exit.
+ */
+export declare function appendStepSummary(writer: Writer, input: ReportInput, where: {
+    path: string | undefined;
+    runDir: string;
+}): Promise<void>;
+/** The console summary: the report, teardown, and where every file is. */
+export declare function printSummary(writer: Writer, finished: Finished, input: ReportInput): void;
+//# sourceMappingURL=run-report.d.ts.map