@stringsync/splates 0.0.61 → 1.13.3

package/vendor/core/ship/registry/registry.d.ts

@@ -0,0 +1,85 @@
+import type { Logger } from "../../log/index.js";
+import type { Duration } from "../../time/index.js";
+import type { CheckReport } from "../step";
+import type { Package } from "../workspace/workspace";
+/** A package a registry holds back until somebody approves it. */
+export interface StagedPackage {
+    /** What approves it, as `npm stage approve` takes it. */
+    stageId: string;
+    /** The page to approve it on. */
+    url: string;
+}
+/**
+ * What a registry took from one publish. Either way it now has the version,
+ * though it may not serve it yet: it is accepted, and live once installable.
+ */
+export interface Publication {
+    /**
+     * The registry had this version already, as npm answers a retry of one it
+     * took but is still scanning, so nothing went out this time.
+     */
+    readonly already?: boolean;
+    /** Set when the registry holds the version until somebody approves it. */
+    readonly staged?: StagedPackage;
+}
+/** The package registry, as a release touches it. */
+export interface Registry {
+    /**
+     * Whether `publish` only stages, leaving each version unavailable until a
+     * person approves it. A release then waits for `published` to turn true
+     * before it tags.
+     */
+    readonly staged?: boolean;
+    /**
+     * Whether the registry checks each version it accepts before serving it,
+     * as npm scans every publish for malware. A release then waits for
+     * `published` to turn true before it tags. A registry with no scan serves
+     * what it accepts at once.
+     */
+    readonly scans?: boolean;
+    /** Whether `version` of `name` is live: installable, not merely accepted. */
+    published(name: string, version: string): Promise<boolean>;
+    /** The version an install of `name` gets now, or `undefined` before any is out. */
+    deployed(name: string): Promise<string | undefined>;
+    /**
+     * Publishes the package in `dir`, logging in along the way if that is what
+     * publishing here takes. Throws if the registry does not take it.
+     */
+    publish(dir: string): Promise<Publication>;
+    /**
+     * Packs the package in `dir` into the directory `into`, as the registry
+     * would receive it, for a dry run. Leave it off when there is no such
+     * thing, and a dry run only says what it would publish.
+     */
+    pack?(dir: string, into: string): Promise<void>;
+    /**
+     * This registry as a CI job it trusts publishes to it, with no stage and
+     * no login. Leave it off when there is no such way to publish.
+     */
+    trusted?(): Registry;
+    /**
+     * How long `publish` and its `watch` may take before the release considers
+     * them hung; five minutes when omitted.
+     */
+    readonly publishDeadline?: Duration;
+    /**
+     * Whether what `publish` handed off has finished, when it hands off to a
+     * run elsewhere and returns before the version is accepted. The release
+     * polls it after `publish`; throwing fails the step. Leave it off when
+     * `publish` returns once the registry has the version.
+     */
+    watch?(name: string, version: string): Promise<CheckReport>;
+    /**
+     * Has the registry trust the CI job that publishes `name`, which takes a
+     * person to authenticate. Leave it off when nothing publishes from CI.
+     */
+    trust?(name: string, log: Logger): Promise<void>;
+    /**
+     * Throws, saying what to fix, when the registry would refuse `pkg`, before
+     * the release stamps a version for it. Leave it off when the registry
+     * takes whatever it is sent.
+     */
+    verify?(pkg: Package): Promise<void>;
+    /** Where a person can see `version` of `name`, and why it is not live yet. */
+    page?(name: string, version: string): string;
+}

package/vendor/core/ship/release-file.d.ts

@@ -0,0 +1,22 @@
+import { type Fs } from "../system/index.js";
+/** What RELEASE holds while a release is under way. */
+export interface ReleaseState {
+    /** The version everything goes out at. */
+    version: string;
+    /** The steps that already landed, by the keys the release gave them. */
+    done: string[];
+}
+/** What a `ReleaseFile` reads and writes through; the real filesystem by default. */
+export interface ReleaseFileOptions {
+    fs?: Fs;
+}
+/** Tracks the version and completed steps of an in-flight release in RELEASE. */
+export declare class ReleaseFile {
+    private readonly path;
+    private readonly fs;
+    constructor(root: string, opts?: ReleaseFileOptions);
+    /** The release under way, or null when the previous one finished. */
+    read(): Promise<ReleaseState | null>;
+    write(state: ReleaseState): Promise<void>;
+    clear(): Promise<void>;
+}

package/vendor/core/ship/release-options.d.ts

@@ -0,0 +1,122 @@
+import type { Logger } from "../log/index.js";
+import type { Fs, Ps } from "../system/index.js";
+import type { Timer, WallClock } from "../time/index.js";
+import type { DryRun } from "./cut";
+import type { Git } from "./git/git";
+import type { StepStage } from "./step";
+import type { Bump } from "./version";
+import type { Workspace } from "./workspace/workspace";
+/** What a release goes out through; the real system by default. */
+export interface ReleaseOptions {
+    /**
+     * How far to move the version; `patch` by default. A RELEASE file left by a
+     * run that died overrides it: that version is finished first.
+     */
+    bump?: Bump;
+    /** The packages the release stamps; the manifest workspace here by default. */
+    workspace?: Workspace;
+    /**
+     * The project folder whose packages the release stamps and publishes, with
+     * the version they stand at; every package of the workspace by default.
+     */
+    project?: string;
+    /** The repository the release commits; the workspace root's by default. */
+    git?: Git;
+    log?: Logger;
+    fs?: Fs;
+    ps?: Ps;
+    timer?: Timer;
+    wallClock?: WallClock;
+    prompt?: (message: string) => string | null;
+    /** Go ahead without asking, for a run whose caller has already approved it. */
+    yes?: boolean;
+    /**
+     * Rehearse the release without sending anything out: preflight, stamp and
+     * build run as they would, each package is packed rather than published
+     * and its pack installed and imported outside the workspace, a mirror
+     * pushes to a bare copy of its remote, and the rest says what it would
+     * have done. The stamp is undone afterwards and no RELEASE file is kept,
+     * and it asks nothing. `true` keeps what it made in a directory of its own
+     * for the run; a `DryRun` names one, which releases rehearsed one after
+     * another share, so a package installs beside the ones going out before it.
+     */
+    dryRun?: boolean | DryRun;
+}
+/** Where `Release.status()` reads the workspace version from; the real system by default. */
+export interface StatusOptions {
+    /** The workspace whose version the artifacts are held against. */
+    workspace?: Workspace;
+    /**
+     * The project folder whose packages the release stamps and publishes, with
+     * the version they stand at; every package of the workspace by default.
+     */
+    project?: string;
+    fs?: Fs;
+    ps?: Ps;
+}
+/** One artifact's live version, as `Release.status()` reads it. */
+export interface DeployedArtifact {
+    name: string;
+    /** The workspace packages the artifact publishes, if any. */
+    packages: readonly string[];
+    /** What is live now; `undefined` when nothing is out yet. */
+    deployed: string | undefined;
+}
+/** The workspace's version beside what each artifact has live. */
+export interface ReleaseStatus {
+    /** The version the workspace stands at, which the last release stamped. */
+    version: string;
+    /** Every artifact that can say what it has live, in release order. */
+    artifacts: DeployedArtifact[];
+}
+/** Where `Release.plan()` reads from; the real system by default. */
+export interface PlanOptions {
+    /** How far the version would move; `patch` by default. */
+    bump?: Bump;
+    workspace?: Workspace;
+    /**
+     * The project folder whose packages the release stamps and publishes, with
+     * the version they stand at; every package of the workspace by default.
+     */
+    project?: string;
+    git?: Git;
+    log?: Logger;
+    fs?: Fs;
+    ps?: Ps;
+}
+/** What `Release.publish()` publishes through; the real system by default. */
+export interface PublishOptions {
+    /** The packages to publish, at the version the workspace stands at. */
+    workspace?: Workspace;
+    /**
+     * The project folder whose packages the release stamps and publishes, with
+     * the version they stand at; every package of the workspace by default.
+     */
+    project?: string;
+    log?: Logger;
+    fs?: Fs;
+    ps?: Ps;
+    timer?: Timer;
+    wallClock?: WallClock;
+}
+/** One step of a release, as `Release.plan()` lists it. */
+export interface PlannedStep {
+    /** The id this step's run-time events carry. */
+    id: string;
+    name: string;
+    stage: StepStage;
+    /** The workspace packages the step publishes, if any. */
+    packages: string[];
+    /** The artifact the step belongs to, when it came from one. */
+    artifact?: string;
+    deadlineMs: number;
+}
+/** Every step a release would run, in order. `schema` grows with the shape. */
+export interface ReleasePlan {
+    schema: 1;
+    /** The version the release would go out at. */
+    version: string;
+    /** Whether a RELEASE file from a run that died fixed that version. */
+    resuming: boolean;
+    steps: PlannedStep[];
+}

package/vendor/core/ship/release.d.ts

@@ -0,0 +1,61 @@
+import { type Artifact } from "./artifact/artifact";
+import type { PlanOptions, PublishOptions, ReleaseOptions, ReleasePlan, ReleaseStatus, StatusOptions } from "./release-options";
+import type { Step } from "./step";
+import { type TrustOptions } from "./trust";
+export type { DeployedArtifact, PlannedStep, PlanOptions, PublishOptions, ReleaseOptions, ReleasePlan, ReleaseStatus, StatusOptions, } from "./release-options";
+/**
+ * Everything a release ships, ready to go out at one version. `releases`
+ * composes these; `release()` runs the whole flow as declared steps: preflight,
+ * version, artifacts in stage order, and any steps the caller added.
+ *
+ * ```ts
+ * await releases.lockstep(releases.npm("@scope/foo"), releases.git()).release();
+ * ```
+ *
+ * A release that dies partway leaves a RELEASE file behind, and the next
+ * `release()` finishes that version instead of bumping past it: every step
+ * that landed is skipped, so nothing goes out twice.
+ */
+export declare class Release {
+    /** Every artifact, in the order they will run: publish, then tag, then notes. */
+    readonly artifacts: readonly Artifact[];
+    /** Steps the caller declared beside the artifacts. */
+    readonly steps: readonly Step[];
+    constructor(artifacts: readonly Artifact[], steps?: readonly Step[]);
+    /** The workspace packages this publishes, gathered from every artifact. */
+    get packages(): readonly string[];
+    /**
+     * What every artifact that can say has live, beside the workspace's own
+     * version, so a caller can show which lags. Artifacts with no `deployed`,
+     * such as a build, are left out.
+     */
+    status(opts?: StatusOptions): Promise<ReleaseStatus>;
+    /** Releases everything, asking first. Run it again after a failure. */
+    release(opts?: ReleaseOptions): Promise<void>;
+    /**
+     * Has each registry trust the CI job that `publish()` runs in, as npm's
+     * trusted publisher entry for each package: the one setup publishing
+     * without a token or 2FA takes. Every artifact is tried, and the ones that
+     * failed are named together at the end.
+     */
+    trust(opts?: TrustOptions): Promise<void>;
+    /**
+     * Publishes what the declaration names that the registry lacks, at the
+     * version the workspace already stands at, from a checkout of a release
+     * commit. It is the half of a release a CI job npm trusts can do: only the
+     * build and publish stages run, each registry in its trusted mode, so
+     * nothing is stamped, tagged, approved or noted. A version the registry
+     * already has is skipped, so a rerun publishes nothing it did.
+     */
+    publish(opts?: PublishOptions): Promise<void>;
+    /** Every step a release runs, in order, as both `release()` and `plan()` read it. */
+    private declare;
+    /**
+     * What `release()` would run, in order, without running any of it. Reads the
+     * workspace and a RELEASE file left by a run that died, and nothing else, so
+     * the version and the step ids are the ones the run's events will carry.
+     */
+    plan(opts?: PlanOptions): Promise<ReleasePlan>;
+}
+/** What status calls an artifact that names itself nothing. */
+export declare function statusName(artifact: Artifact): string;

package/vendor/core/ship/releases.d.ts

@@ -0,0 +1,119 @@
+import { type Fs, type Ps } from "../system/index.js";
+import type { Artifact } from "./artifact/artifact";
+import type { Bundle } from "./bundle/bundle";
+import { type VendorBundleOptions } from "./bundle/vendor-bundle";
+import { type GitArtifactOptions } from "./git/git-artifact";
+import { type CliGithubOptions } from "./github/cli-github";
+import { type MirrorBuildOptions } from "./mirror/mirror-build";
+import { type MirrorOptions } from "./mirror/mirror-step";
+import { type PublishWorkflowOptions } from "./publish-workflow";
+import type { GithubActions } from "./registry/github-actions";
+import { type NpmRegistryOptions } from "./registry/npm-registry";
+import type { Registry } from "./registry/registry";
+import { Release } from "./release";
+import { type ShippedOptions } from "./shipped";
+import { type SkillArtifactOptions } from "./skill-artifact";
+import type { Step } from "./step";
+/** What `releases.workspace` reads the roster through; the real system by default. */
+export interface WorkspaceReleaseOptions {
+    /** The project folder whose public packages go out; every package of the workspace by default. */
+    project?: string;
+    fs?: Fs;
+    ps?: Ps;
+    /** Publish through GitHub Actions instead of from this machine, as `releases.npm`'s `via`. */
+    via?: GithubActions;
+}
+/**
+ * Composes a release: name each package and where it goes, add the tag and
+ * the notes, and call `release()` on the result.
+ *
+ * ```ts
+ * await releases.lockstep(
+ * 	releases.npm("@scope/foo"),
+ * 	releases.custom("@scope/baz", new S3Registry()),
+ * 	releases.git(),
+ * 	releases.github(),
+ * ).release();
+ * ```
+ */
+export declare class releases {
+    private constructor();
+    /** A package the npm registry carries. */
+    static npm(name: string, opts?: NpmRegistryOptions): Release;
+    /** A package `registry` carries, for wherever npm is not the answer. */
+    static custom(name: string, registry: Registry): Release;
+    /** A caller-defined step, composed beside artifacts and other releases. */
+    static step(step: Step): Release;
+    /**
+     * Stops the release, before it asks to go out, when the project depends on
+     * another project's package that has commits since its last release: the
+     * release would go out against the version the registry has, without them.
+     * It lists them and asks whether to go ahead anyway.
+     */
+    static shipped(opts: ShippedOptions): Release;
+    /**
+     * Pushes existing Git commits to origin during preflight. Place this before
+     * other preflight steps in lockstep to push before running their gates.
+     * This is opt-in and does not create a tag or a release commit.
+     */
+    static push(opts?: GitArtifactOptions): Release;
+    /**
+     * Keeps the generated publish workflow current: a preflight step writes it
+     * when it is missing or stale, so it lands in the release commit.
+     */
+    static publishWorkflow(opts: PublishWorkflowOptions): Release;
+    /** The tag, and the push that publishes it. */
+    static git(opts?: GitArtifactOptions): Release;
+    /**
+     * Building every package before any of them goes out, and clearing what that
+     * left once the release is over. Add it to any release whose packages
+     * publish something other than the source they were written in.
+     */
+    static build(bundle?: Bundle): Release;
+    /**
+     * `build`, for a package that depends on private workspace packages and
+     * still publishes alone: each one it reaches is built into `dist/vendor`
+     * and the imports rewritten to it, so the published package needs none of
+     * them on a registry. Use it in place of `build`, not beside it.
+     */
+    static vendor(opts?: VendorBundleOptions): Release;
+    /**
+     * Mirrors a project to its public repository so that the repository stands
+     * alone from the workspace: the project folder, with the source of the
+     * workspace package it reaches added as a private package of its own.
+     * Nothing is pushed when the mirror's tree did not change. Pair it with
+     * `vendor`, which then works unchanged in the mirror, where `core` is a
+     * private workspace package.
+     */
+    static mirror(opts: MirrorOptions): Release;
+    /**
+     * `mirror`, with the packages built in the mirror rather than the
+     * workspace: the release writes the mirror's commit to a checkout of the
+     * remote, installs it from the registry as anyone cloning it would, builds
+     * each public package of the project there and publishes that build, then
+     * pushes the commit at the tag stage. What goes out is what the public
+     * repository builds, against the releases of other projects it depends on.
+     * Use it in place of `build`, `vendor` and `mirror`.
+     */
+    static mirrored(opts: MirrorBuildOptions): Release;
+    /**
+     * An agent skill document whose frontmatter version this release stamps,
+     * given relative to the workspace root. The stamp lands in the release
+     * commit, so a skill bundled into a package says the version that bundled
+     * it rather than the one before.
+     */
+    static skill(path: string, opts?: SkillArtifactOptions): Release;
+    /** The release notes GitHub publishes for the tag. */
+    static github(opts?: CliGithubOptions): Release;
+    /**
+     * Every declaration given, at one version. Stages decide when steps run, so
+     * packages always publish before the tag that names them, and notes come last.
+     */
+    static lockstep(...declarations: Array<Artifact | Release | Step>): Release;
+    /**
+     * The workspace's own release: every public package around the working
+     * directory onto npm, tagged, with GitHub release notes. This is what
+     * `wiz dev ship` runs when nothing declares otherwise.
+     */
+    static workspace(opts?: WorkspaceReleaseOptions): Promise<Release>;
+}

package/vendor/core/ship/shipped.d.ts

@@ -0,0 +1,54 @@
+import { type Fs, type Ps } from "../system/index.js";
+import { Duration } from "../time/index.js";
+import type { Cut } from "./cut";
+import type { Step } from "./step";
+import type { Workspace } from "./workspace/workspace";
+/** What `ShippedCheck` looks at, and who it asks. */
+export interface ShippedOptions {
+    /** The project folder going out, relative to the workspace root, such as `vexml`. */
+    project: string;
+    /**
+     * Asks whether to go ahead anyway; the platform's `prompt()` by default,
+     * which a run with no terminal answers with nothing, so it stops.
+     */
+    prompt?: (message: string) => string | null;
+    /** Where the packages are found; the manifest workspace around the release's root by default. */
+    workspace?: Workspace;
+    fs?: Fs;
+    ps?: Ps;
+}
+/** A package of another project with commits since its last release. */
+export interface Unshipped {
+    name: string;
+    /** Its project folder, relative to the workspace root, which ships it. */
+    project: string;
+    /** Each commit since, as `<sha> <subject>`, newest first. */
+    commits: string[];
+}
+/**
+ * Stops a release that depends on another project's package while that
+ * project has changes it has not shipped. The release would go out against
+ * the version the registry has, so a change it came to rely on, a fix with no
+ * new types included, would be missing for everyone who installs it. The
+ * commits are listed and the person asked whether to go ahead anyway, for
+ * changes the release does not need. A dry run lists them and asks nothing.
+ *
+ * A package's last release is the last commit that changed its manifest's
+ * `version`, which is what a release's stamp commits, and only commits to the
+ * package's own folder count: the project's tooling never goes out with it.
+ */
+export declare class ShippedCheck implements Step {
+    private readonly opts;
+    readonly name = "Dependencies shipped";
+    readonly deadline: Duration;
+    readonly stage: "preflight";
+    private readonly fs;
+    private readonly ps;
+    constructor(opts: ShippedOptions);
+    run(cut: Cut): Promise<void>;
+    dryRun(cut: Cut): Promise<void>;
+    /** Every other project's package this one depends on that has commits since its release. */
+    unshipped(cut: Cut): Promise<Unshipped[]>;
+    private list;
+    private git;
+}

package/vendor/core/ship/skill-artifact.d.ts

@@ -0,0 +1,27 @@
+import { type Fs } from "../system/index.js";
+import type { Artifact, Stage } from "./artifact/artifact";
+import type { Cut } from "./cut";
+/** What a `SkillArtifact` reads and writes through; the real filesystem by default. */
+export interface SkillArtifactOptions {
+    fs?: Fs;
+}
+/**
+ * An agent skill whose frontmatter carries the version it shipped at. Its
+ * stage is what makes the number true: the stamp goes into the release commit
+ * beside every package.json, so the document a build bundles says the version
+ * that bundled it.
+ *
+ * It publishes no package of its own, so it does not appear in what a release
+ * says it will send.
+ */
+export declare class SkillArtifact implements Artifact {
+    /** The document, relative to the workspace root or absolute. */
+    private readonly path;
+    readonly packages: readonly string[];
+    readonly stage: Stage;
+    private readonly fs;
+    constructor(
+    /** The document, relative to the workspace root or absolute. */
+    path: string, opts?: SkillArtifactOptions);
+    publish(cut: Cut): Promise<void>;
+}

package/vendor/core/ship/step-events.d.ts

@@ -0,0 +1,91 @@
+import type { Fs } from "../system/index.js";
+import { type WallClock } from "../time/index.js";
+import type { CheckReport, Step, StepStage } from "./step";
+/** Check an event line's `schema` against this before reading the rest of it. */
+export declare const EVENTS_SCHEMA: 1;
+/**
+ * JSON-lines release progress. No path means no event file; `progress`, when
+ * given, also receives one `{"event":"step",...}` line per start, done, failure
+ * or skip, for a caller reading the release's own output.
+ */
+export declare class StepEvents {
+    private readonly path;
+    private readonly fs;
+    private readonly clock;
+    private readonly progress?;
+    constructor(path: string | undefined, fs: Fs, clock?: WallClock, progress?: ProgressSink | undefined);
+    declared({ id, step, packages, artifact, }: StepDeclaration): Promise<void>;
+    started({ id, step }: StepDeclaration): Promise<void>;
+    /** A package staged for approval, with where to approve it. */
+    staged({ id, step }: StepDeclaration, info: {
+        package: string;
+        version: string;
+        stageId: string;
+        url: string;
+    }): Promise<void>;
+    check(declaration: StepDeclaration, { passed, status, url }: CheckReport): Promise<void>;
+    done({ id, step }: StepDeclaration): Promise<void>;
+    /** A step a resumed release found already landed. */
+    skipped({ id, step }: StepDeclaration): Promise<void>;
+    failed({ id, step }: StepDeclaration, error: unknown): Promise<void>;
+    private report;
+    private write;
+    private at;
+}
+/** Where progress lines go; the release's own logger in practice. */
+export interface ProgressSink {
+    line(text: string): void;
+}
+interface StepEvent {
+    readonly schema: typeof EVENTS_SCHEMA;
+    readonly id: string;
+    readonly name: string;
+    readonly at: string;
+}
+export interface StepDeclaredEvent extends StepEvent {
+    readonly type: "declared";
+    readonly stage: StepStage;
+    readonly packages: string[];
+    readonly artifact?: string;
+    readonly deadlineMs: number;
+}
+export interface StepStartedEvent extends StepEvent {
+    readonly type: "started";
+}
+export interface StepStagedEvent extends StepEvent {
+    readonly type: "staged";
+    readonly package: string;
+    readonly version: string;
+    readonly stageId: string;
+    readonly url: string;
+}
+export interface StepCheckEvent extends StepEvent {
+    readonly type: "check";
+    readonly passed: boolean;
+    /** What a failed check still waits on, when its step says. */
+    readonly status?: string;
+    /** Where a person can look into it. */
+    readonly url?: string;
+}
+export interface StepDoneEvent extends StepEvent {
+    readonly type: "done";
+}
+export interface StepSkippedEvent extends StepEvent {
+    readonly type: "skipped";
+}
+export interface StepFailedEvent extends StepEvent {
+    readonly type: "failed";
+    readonly error: string;
+}
+/** One line in the release event file named by WEBAPPWIZ_SHIP_EVENTS or SPLATES_SHIP_EVENTS. */
+export type ReleaseStepEvent = StepDeclaredEvent | StepStartedEvent | StepStagedEvent | StepCheckEvent | StepDoneEvent | StepSkippedEvent | StepFailedEvent;
+/** What a step runner reports, identified independently of its display name. */
+export interface StepDeclaration {
+    readonly id: string;
+    readonly step: Step;
+    /** The artifact the step belongs to, when it came from one. */
+    readonly artifact?: string;
+    /** The workspace packages the step publishes, if any. */
+    readonly packages?: readonly string[];
+}
+export {};

package/vendor/core/ship/step-runner.d.ts

@@ -0,0 +1,16 @@
+import { type Timer } from "../time/index.js";
+import type { Cut } from "./cut";
+import type { StepDeclaration, StepEvents } from "./step-events";
+/** Runs declared work and its checks, reporting every transition. */
+export declare class StepRunner {
+    private readonly events;
+    private readonly timer;
+    constructor(events: StepEvents, timer?: Timer);
+    declare(steps: readonly StepDeclaration[]): Promise<void>;
+    run(declaration: StepDeclaration, cut: Cut, opts?: StepRunOptions): Promise<void>;
+    private wait;
+}
+interface StepRunOptions {
+    done?: boolean;
+}
+export {};

package/vendor/core/ship/step.d.ts

@@ -0,0 +1,49 @@
+import type { Duration } from "../time/index.js";
+import type { Stage } from "./artifact/artifact";
+import type { Cut } from "./cut";
+/** Where a caller-defined step runs. Preflight steps precede the release prompt. */
+export type StepStage = "preflight" | Stage;
+/** What a running step tells whoever is watching the release. */
+export interface StepReport {
+    /** A package went to a registry that holds it until somebody approves it. */
+    staged(info: {
+        package: string;
+        version: string;
+        stageId: string;
+        url: string;
+    }): Promise<void>;
+}
+/** What one poll of a step's check found, for a check with more to say than pass or fail. */
+export interface CheckReport {
+    readonly passed: boolean;
+    /** What the step is still waiting on, in a word, such as `pending` or `held`. */
+    readonly status?: string;
+    /** Where a person can look into what it waits on. */
+    readonly url?: string;
+}
+/**
+ * One named unit of release work. A deadline tells callers when to consider the
+ * step hung; it never cancels the work. A check, when present, retries, backing
+ * off, until it confirms that the work really landed; `waited` is how long it
+ * has waited so far.
+ */
+export interface Step {
+    readonly name: string;
+    readonly deadline: Duration;
+    readonly stage?: StepStage;
+    run(cut: Cut, report?: StepReport): Promise<void>;
+    /**
+     * What the step does in a dry run in place of `run`, with no check after
+     * it: say what it would send, or send it somewhere local instead. A step
+     * without one runs as usual when it only works on this machine (preflight,
+     * stamp and build), and is skipped from the publish stage on, so a dry run
+     * never sends anything out.
+     */
+    dryRun?(cut: Cut): Promise<void>;
+    check?(cut: Cut, waited: Duration): Promise<boolean | CheckReport>;
+    /**
+     * How often to check, steadily, in place of the backoff, for a check
+     * whose answer comes soon and is worth hearing as it comes.
+     */
+    readonly checkEvery?: Duration;
+}

package/vendor/core/ship/trust.d.ts

@@ -0,0 +1,11 @@
+import { type Logger } from "../log/index.js";
+import { Duration } from "../time/index.js";
+import type { Artifact } from "./artifact/artifact";
+/** Where `Release.trust()` says what it did; the console by default. */
+export interface TrustOptions {
+    log?: Logger;
+    /** How long to wait between packages, which npm asks for to avoid its rate limit; 2 seconds by default. */
+    pause?: Duration;
+}
+/** Has each artifact that publishes from CI trust it, as `Release.trust()` runs it. */
+export declare function trust(artifacts: readonly Artifact[], opts?: TrustOptions): Promise<void>;