@arc-e-tect/api-only-publisher 0.8.0 → 0.10.0

package/README.adoc

@@ -6,12 +6,12 @@
 :source-highlighter: rouge
 // The released version of this component: its snippets use it. The release
 // workflow updates it; do not change it by hand.
-:api-only-publisher-version: 0.8.0
+:api-only-publisher-version: 0.10.0
 
 image:https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/actions/workflows/nvd-cache-refresh.yml/badge.svg[Vulnerability Scan,link=https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/actions/workflows/nvd-cache-refresh.yml]
 image:https://img.shields.io/npm/v/@arc-e-tect/api-only-publisher[npm,link=https://www.npmjs.com/package/@arc-e-tect/api-only-publisher]
 image:https://img.shields.io/github/v/release/Arc-E-Tect/SoftwareEngineeringDoneRight-API?filter=api-only-publisher-v*[GitHub release,link=https://github.com/Arc-E-Tect/SoftwareEngineeringDoneRight-API/releases?q=api-only-publisher]
-image:https://img.shields.io/badge/Node-22%2B-339933?logo=node.js[Node 22+,link=https://nodejs.org]
+image:https://img.shields.io/badge/Node-22.14%2B-339933?logo=node.js[Node 22.14+,link=https://nodejs.org]
 image:https://img.shields.io/badge/License-MIT-blue[MIT,link=LICENSE]
 
 [NOTE]
@@ -344,6 +344,9 @@ A `publish: false` target keeps the version its source declares.
 . **Lint** the finished document, so a broken fragment surfaces against the target it actually affects.
 `build` prints the linter's output only when the lint fails, and writes no report; to see warnings, and to write each document's report under `reports.lint`, run `lint`.
 
+. **Report operations with no example**, after the lint and apart from it: an AsyncAPI message without `examples`, or an OpenAPI request body or response without one, is logged as a finding, and `lint.examples.<kind>` decides whether that fails the build (<<examples-check,An operation with no example is reported apart from lint §>>).
+Only `build` does this; `lint` does not, and no report file is written.
+
 [#versions]
 == Versions
 
@@ -606,7 +609,7 @@ Configured portfolio: paths=none, location=portfolios
 |`file`
 |A local directory, laid out as `<directory>/<target>/<version>/`.
 Not a distribution mechanism between repositories: it makes the pipeline testable end to end with no infrastructure, lets a library share one build with the projects that implement it, and is a local-iteration escape hatch.
-Publishing a version again replaces that version and keeps the others; with `clean: true` only the version being published is kept, for a directory that is a build output rather than a record of releases.
+Publishing a version again writes it again and keeps the others (<<idempotent,Publishing the same version again §>>); with `clean: true` only the version being published is kept, for a directory that is a build output rather than a record of releases.
 
 |`maven`
 |A path publishes into a repository layout on disk; an `http(s)` URL deploys to a remote repository with an HTTP `PUT` per file and a bearer token.
@@ -618,20 +621,109 @@ Native for Gradle consumers: version resolution, caching and conflict handling c
 |`github-release`
 |The language-neutral floor: immutable per tag, works for private repositories with a token, readable by a consumer with no JVM and no Node.js.
 No dependency-resolution semantics and no update notification, which is why it is the fallback rather than the default.
+
+|`nuget`
+|A path writes a `.nupkg` into a local feed; an `http(s)` URL -- the feed's service index -- pushes to a remote one.
+Native for .NET consumers: a `PackageReference` at a version, restored from a feed. See <<nuget,The `nuget` channel §>>.
+|===
+
+[#idempotent]
+=== Publishing the same version again
+
+`publish` is idempotent: publishing a version again with the same content changes nothing, on every channel.
+
+That rests on `pack` being reproducible.
+The same documents always pack to the same archive, byte for byte: the archive is written with a fixed mode, no owner and a fixed timestamp, and `manifest.json`'s `producedAt` is not the time `pack` ran but the time of the commit being packed.
+Set `SOURCE_DATE_EPOCH` (seconds since 1970, the https://reproducible-builds.org/specs/source-date-epoch/[reproducible-builds convention ↗]) to choose another; outside a git repository, where there is no commit, it is the only way to make two packs identical, and without it `producedAt` is the current time.
+
+What happens when the destination already has the version:
+
+[cols="1,3", options="header"]
+|===
+|Destination |Already has the version
+
+|`file`; `maven` and `nuget` to a directory; `npm` with `publish: false`
+|Written again. With the same content the bytes are the same; with different content the version is replaced, and every subscriber whose lockfile recorded the old bytes fails its build until the change is published as a new version.
+
+|`maven` and `nuget` to a URL, `npm`, `github-release`
+|The same bytes: nothing is sent, and the log says `already published, identical`. Different bytes: `publish` fails, naming the version -- a published version is never replaced, so publish the change as a new version.
+`github-release` compares the asset it would upload with the one the release has, and never overwrites one.
+A NuGet feed that cannot return the package it has, so there is nothing to compare, fails as a different one would.
 |===
 
 Credentials are read from the environment, never from configuration.
-`channels.maven.tokenEnv` names the variable, `MAVEN_TOKEN` by default; a configuration file gets committed, and a credential in a committed file is a credential that has leaked.
+`channels.maven.tokenEnv` names the variable, `MAVEN_TOKEN` by default, and `channels.nuget.tokenEnv` the NuGet API key's, `NUGET_API_KEY` by default; a configuration file gets committed, and a credential in a committed file is a credential that has leaked.
 
 link:../docs/reference/how-publisher-and-subscriber-work-together.adoc#channels[How the Publisher and the Subscriber work together →] lists each channel's layout and options.
 
+[#nuget]
+=== The `nuget` channel
+
+It is published without the .NET SDK, as the Maven channel is published without Maven: a `.nupkg` is a ZIP archive the Publisher writes itself, and a push is one HTTP request.
+
+[source,yaml]
+----
+channels:
+  nuget:
+    idPrefix: Contoso.Contracts          # required
+    # packageId: Contoso.Users           # replaces the whole id, for every target
+    repository: build/nuget-feed         # a directory, or a feed's service index URL
+    # tokenEnv: NUGET_API_KEY            # the variable holding the API key, for a URL
+    # authors: Contoso API team          # default: idPrefix
+    # license: MIT                       # an SPDX expression; default: UNLICENSED
+----
+
+*The package id* is `<idPrefix>.<target in PascalCase>`: target `user-account` with `idPrefix: Contoso.Contracts` is `Contoso.Contracts.UserAccount`, the dotted PascalCase .NET uses for namespaces, from a kebab-case target.
+`packageId` replaces it.
+An id NuGet would refuse -- anything but letters, digits and underscores in parts separated by single dots or dashes, or longer than 100 characters -- is refused before anything is written.
+
+*The version* is the contract's, and a pre-release is a NuGet pre-release: `2.1.0-rc.1` is not picked by a floating range such as `2.1.*`, only when asked for.
+A version with build metadata, such as `2.1.0+build.7`, is refused before anything is written: NuGet ignores `+metadata` when it identifies a package, so it would be the same package as every other build of `2.1.0`, and a feed refuses the second.
+
+*A local feed* is a directory in the layout `nuget add` writes, which the NuGet documentation recommends over a flat folder:
+
+----
+<repository>/<id, lower case>/<version>/
+    <id>.<version>.nupkg
+    <id>.<version>.nupkg.sha512
+    <id>.nuspec
+    manifest.json           -- beside the package, so provenance is readable without unpacking it
+----
+
+A .NET build uses it with `dotnet nuget add source <repository>`, or a `nuget.config` entry.
+
+*A remote feed* is configured by its service index, the URL a feed's settings show and that ends in `index.json`, such as `https://api.nuget.org/v3/index.json`.
+The Publisher reads the service index for its `PackagePublish/2.0.0` endpoint, then pushes the package there with one `PUT`, as `multipart/form-data`, with the key from the environment variable `tokenEnv` names in the `X-NuGet-ApiKey` header.
+A feed that already has the version answers 409; the Publisher then reads the feed's copy back (its `PackageBaseAddress/3.0.0` resource) and succeeds when it is the same package, and fails when it is not, or cannot be read (<<idempotent,Publishing the same version again §>>).
+Without the variable set, the push fails before anything is sent, naming it.
+That is how nuget.org, GitHub Packages and self-hosted feeds such as BaGet take a push.
+A feed that authenticates some other way -- Azure Artifacts, which expects a credential provider or a token in an `Authorization` header -- is not supported yet; only the local-HTTP-stub tests exercise the push, not a real feed.
+
+*The package holds* the `.nuspec`, the two Open Packaging Conventions parts (`[Content_Types].xml` and `_rels/.rels`), and exactly what `pack` produced -- the documents and `manifest.json` -- extracted, never rebuilt, under `contracts/`:
+
+----
+Contoso.Contracts.UserAccount.nuspec
+[Content_Types].xml
+_rels/.rels
+contracts/asyncapi.yaml
+contracts/manifest.json
+contracts/openapi.yaml
+----
+
+`contracts/` is the contract with the consumer, and changes only with a major version of the Publisher.
+NuGet gives the folder no behaviour: nothing is copied into a project, nothing is compiled, and a restore reports no warning for a package with no assemblies.
+Until a `.targets` file places and verifies the documents for a .NET build, a consumer reads them where restore put them, `~/.nuget/packages/<id, lower case>/<version>/contracts/` (or `$(NuGetPackageRoot)` in MSBuild), and verifies them against `contracts/manifest.json`.
+
+The same packed archive always produces a byte-identical package: entries in a fixed order, a fixed timestamp.
+Since `pack` is reproducible, publishing the same commit again produces the same package too, so a republish to a local feed can be checked as unchanged.
+
 [#why-registries]
-=== Why npm and Maven rather than release assets alone
+=== Why npm, Maven and NuGet rather than release assets alone
 
 Publishing is passive.
 The producer releases `2.1.0` and nothing happens in an implementation repository until somebody looks.
 
-Renovate and Dependabot understand npm and Maven natively, so a contract bump arrives downstream as a pull request without any bespoke machinery.
+Renovate and Dependabot understand npm, Maven and NuGet natively, so a contract bump arrives downstream as a pull request without any bespoke machinery.
 That is the practical argument for preferring them, and the reason to design the coordinates so that standard update bots can read them.
 
 [#pre-releases]
@@ -687,6 +779,9 @@ reports:
   lint: build/reports/lint
 lint:
   unreferenced: error  # a fragment no target reaches: error, warn or off
+  examples:
+    asyncapi: warn      # a message with no example: error, warn (the default) or off
+    openapi: warn       # a request body or response with no example: error, warn (the default) or off
 
 toolchain:
   redocly: "@redocly/cli@2.52.0"
@@ -781,6 +876,34 @@ Any other YAML file under the source root counts.
 
 `lint` lints every document even when one of them fails, and names every failure at the end, so a single run reports all of them.
 
+[#examples-check]
+=== An operation with no example is reported apart from lint
+
+`build` also checks, after linting, whether each operation's example is one the rest of the API-Only toolchain could use -- and reports that separately from lint's own findings, since "your contract is wrong" and "your contract limits what you can do with it downstream" are different claims.
+Neither specification requires an example, and this is not a specification-validity rule: it is never run as a Redocly plugin or a Spectral ruleset.
+
+For AsyncAPI, it is whether a message's own `examples` array is non-empty -- what Microcks reads to build its async mocks and its conformance tests:
+
+[source,text]
+----
+AsyncAPI operation '<operationId>': message '<messageKey>' (<fragment, or where in the bundle>) carries no example, so this bundle cannot be used for Microcks-based conformance testing.
+----
+
+For OpenAPI, it is whether a request body's or response's media type declares `example`/`examples`, or the schema it references carries its own top-level `examples`.
+Nothing downstream currently reads an OpenAPI example, so the message never claims the bundle cannot be used -- only that the generated documentation is weaker without one:
+
+[source,text]
+----
+OpenAPI operation '<operationId>': <request body, or response <status>> (<fragment, or where in the bundle>) carries no example, which makes the generated documentation harder to read.
+----
+
+A body or response with no `content` at all, such as a `204`, has nothing to exemplify and is never reported.
+
+`lint.examples.asyncapi` and `lint.examples.openapi` each default to `warn`; `error` fails the build, `off` does not look.
+The findings appear in the build log only: `lint` does not run this check, and there is no report file, so a job that only runs `lint` never sees them -- run `build`, and read its log.
+With `error`, the build fails with `<n> operation(s) in <file> have no example (lint.examples.<kind> is error):`, followed by each finding.
+A library that has adopted the Microcks-based conformance emitter will usually want `lint.examples.asyncapi: error`: publishing a bundle its own toolchain cannot use is a real defect there, not merely a gap (link:../docs/reference/authoring-a-specification-library.adoc#give-every-operation-an-example[Give every operation an example →]).
+
 [#version-stamping]
 === Version stamping edits one scalar
 
@@ -1005,7 +1128,7 @@ Anything else is a bug; please report it.
 npm test
 ----
 
-Covers every module and every command: placeholder substitution, version stamping, version files, configuration parsing, closures, packing, channels, splitting, and the scaffold.
+Covers every module and every command: placeholder substitution, version stamping, version files, configuration parsing, closures, packing, channels, splitting, aggregates, the example check, and the scaffold.
 `build.e2e.test.js` runs the real bundlers.
 The run fails below 90% of lines and functions, or 80% of branches.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arc-e-tect/api-only-publisher",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Builds, packs and publishes API description documents from a library of reusable fragments.",
   "license": "MIT",
   "author": "Arc-E-Tect",

package/src/channel-error.js

@@ -0,0 +1,7 @@
+"use strict";
+
+// The error every distribution channel throws, in a module of its own so that a channel
+// implemented outside channels.js can throw it without requiring channels.js back.
+class ChannelError extends Error {}
+
+module.exports = { ChannelError };

package/src/channels.js

@@ -13,8 +13,9 @@ const path = require("path");
 const { execFileSync } = require("child_process");
 
 const { isPrerelease, npmDistTag } = require("./version-policy");
+const { ChannelError } = require("./channel-error");
+const { publishNuget } = require("./nuget");
 
-class ChannelError extends Error {}
 
 /**
  * `file` -- publish to a local directory.
@@ -150,8 +151,23 @@ function publishNpm(archive, manifest, options, log) {
             return { location, distTag, name };
         }
 
-        const args = ["publish", "--tag", distTag];
-        if (options.registry) args.push("--registry", options.registry);
+        // Idempotent: a version the registry already has is left alone when it is the
+        // same package, and refused when it is not -- npm never replaces a version.
+        const registry = options.registry ? ["--registry", options.registry] : [];
+        const local = JSON.parse(execFileSync("npm", ["pack", "--dry-run", "--json"],
+            { cwd: workDir, encoding: "utf8", stdio: "pipe" }))[0].integrity;
+        const published = npmPublishedIntegrity(name, version, registry);
+        if (published === local) {
+            log(`-- npm ${name}@${version} is already published, identical; nothing to do`);
+            return { location: name + "@" + version, distTag, name, alreadyPublished: true };
+        }
+        if (published) {
+            throw new ChannelError(
+                `npm already has ${name}@${version}, and it is not this package (${published}, not ${local}). ` +
+                "A published version is never replaced; publish the change as a new version.");
+        }
+
+        const args = ["publish", "--tag", distTag, ...registry];
         // A signed attestation tying this tarball to the commit and workflow run
         // that produced it. A tool whose whole purpose is making provenance
         // auditable should not ask to be taken on trust itself. Requires a public
@@ -166,6 +182,19 @@ function publishNpm(archive, manifest, options, log) {
     }
 }
 
+/** The integrity npm records for `name@version`, or null when it has no such version. */
+function npmPublishedIntegrity(name, version, registry) {
+    try {
+        const out = execFileSync("npm", ["view", `${name}@${version}`, "dist.integrity", ...registry],
+            { encoding: "utf8", stdio: "pipe" }).trim();
+        return out || null;
+    } catch (error) {
+        const output = `${error.stdout || ""}${error.stderr || ""}`;
+        if (/E404/.test(output)) return null;
+        throw new ChannelError(`could not ask npm whether ${name}@${version} is published: ${output.trim() || error.message}`);
+    }
+}
+
 /**
  * `github-release` -- attach the archive to a GitHub release.
  *
@@ -204,7 +233,29 @@ function publishGithubRelease(archive, manifest, options, log) {
         gh(args);
     }
 
-    gh(["release", "upload", tag, archive, "--repo", repository, "--clobber"]);
+    // Idempotent, as the registries are: an asset the release already has is left alone
+    // when it is the same bytes, and refused when it is not. Never --clobber: that would
+    // replace a published contract under the same version.
+    const asset = path.basename(archive);
+    const assets = exists
+        ? gh(["release", "view", tag, "--repo", repository, "--json", "assets", "--jq", ".assets[].name"]).split("\n").map((a) => a.trim())
+        : [];
+    if (assets.includes(asset)) {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "api-only-gh-"));
+        try {
+            gh(["release", "download", tag, "--repo", repository, "--pattern", asset, "--dir", dir]);
+            if (fs.readFileSync(path.join(dir, asset)).equals(fs.readFileSync(archive))) {
+                log(`-- ${repository} release ${tag} already has ${asset}, identical; nothing to do`);
+                return { location: `${repository}@${tag}`, tag, alreadyPublished: true };
+            }
+        } finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+        throw new ChannelError(
+            `${repository} release ${tag} already has ${asset}, and it is not this archive. ` +
+            "A published version is never replaced; publish the change as a new version.");
+    }
+    gh(["release", "upload", tag, archive, "--repo", repository]);
     log(`-- Published ${manifest.target} ${manifest.version} to ${repository} release ${tag}`);
     return { location: `${repository}@${tag}`, tag };
 }
@@ -241,6 +292,18 @@ async function putFile(url, body, token, contentType) {
     }
 }
 
+/** What a Maven repository holds at `url`, or null when it holds nothing there. */
+async function getFile(url, token) {
+    const response = await fetch(url, { headers: { "Authorization": `Bearer ${token}` } });
+    if (response.status === 404) return null;
+    if (!response.ok) {
+        throw new ChannelError(`GET ${url} failed: ${response.status} ${response.statusText}. ` +
+            (response.status === 401 || response.status === 403
+                ? "Check the token in the environment variable named by channels.maven.tokenEnv." : ""));
+    }
+    return Buffer.from(await response.arrayBuffer());
+}
+
 function publishMavenRemote(archive, manifest, options, log) {
     const tokenEnv = options.tokenEnv || "MAVEN_TOKEN";
     const token = process.env[tokenEnv];
@@ -258,24 +321,42 @@ function publishMavenRemote(archive, manifest, options, log) {
         `${options.groupId.split(".").join("/")}/${artifactId}/${version}/${artifactId}-${version}`;
 
     const work = (async () => {
-        await putFile(`${base}.${extension}`, fs.readFileSync(archive), token, "application/octet-stream");
+        // Idempotent: an artifact the repository already has is left alone when it is
+        // the same bytes, and refused when it is not.
+        const bytes = fs.readFileSync(archive);
+        const existing = await getFile(`${base}.${extension}`, token);
+        if (existing) {
+            if (existing.equals(bytes)) return true;
+            throw new ChannelError(
+                `${options.repository} already has ${options.groupId}:${artifactId}:${version}, and it is not this archive. ` +
+                "A published version is never replaced; publish the change as a new version.");
+        }
+        await putFile(`${base}.${extension}`, bytes, token, "application/octet-stream");
         await putFile(`${base}.pom`,
             Buffer.from(pom(options.groupId, artifactId, version, extension), "utf8"),
             token, "application/xml");
         await putFile(`${base}-manifest.json`,
             Buffer.from(JSON.stringify(manifest, null, 2) + "\n", "utf8"),
             token, "application/json");
+        return false;
     })();
 
     // The CLI is synchronous throughout; surfacing the promise here would make
     // every caller async for one channel's benefit.
-    return work.then(() => {
-        log(`-- Deployed ${options.groupId}:${artifactId}:${version} to ${options.repository}`);
-        return { location: `${base}.${extension}`, coordinates: `${options.groupId}:${artifactId}:${version}@${extension}` };
+    return work.then((alreadyPublished) => {
+        log(alreadyPublished
+            ? `-- ${options.groupId}:${artifactId}:${version} is already in ${options.repository}, identical; nothing to do`
+            : `-- Deployed ${options.groupId}:${artifactId}:${version} to ${options.repository}`);
+        return {
+            location: `${base}.${extension}`, coordinates: `${options.groupId}:${artifactId}:${version}@${extension}`,
+            ...(alreadyPublished ? { alreadyPublished } : {}),
+        };
     });
 }
 
-const CHANNELS = { file: publishFile, maven: publishMaven, npm: publishNpm, "github-release": publishGithubRelease };
+const CHANNELS = {
+    file: publishFile, maven: publishMaven, npm: publishNpm, "github-release": publishGithubRelease, nuget: publishNuget,
+};
 
 function publish(archive, manifest, channel, options, log = () => {}) {
     const handler = CHANNELS[channel];

package/src/config.js

@@ -27,7 +27,8 @@ const DEFAULTS_KIND_KEYS = { openapi: ["lint", "outputName", "fragmentPaths"], a
 const PLACEHOLDERS_KEYS = ["strict"];
 const BUILD_KEYS = ["staging", "dist"];
 const REPORTS_KEYS = ["lint"];
-const LINT_KEYS = ["unreferenced"];
+const LINT_KEYS = ["unreferenced", "examples"];
+const LINT_EXAMPLES_KEYS = ["openapi", "asyncapi"];
 const DISTRIBUTION_KEYS = ["root", "layout"];
 const TARGET_KEYS = ["openapi", "asyncapi", "publish", "versionFile"];
 const TARGET_KIND_KEYS = ["bundle", "aggregate", "info"];
@@ -121,6 +122,7 @@ function load(configPath) {
     checkKeys(reports, REPORTS_KEYS, "reports");
     const lint = parsed.lint || {};
     checkKeys(lint, LINT_KEYS, "lint");
+    if (lint.examples) checkKeys(lint.examples, LINT_EXAMPLES_KEYS, "lint.examples");
     if (parsed.distribution) checkKeys(parsed.distribution, DISTRIBUTION_KEYS, "distribution");
 
     const portfolio = parsed.portfolio || {};
@@ -284,6 +286,20 @@ function load(configPath) {
             }
             return mode;
         },
+        // What the build does about an operation whose example this kind's
+        // toolchain could use, and does not have: `warn`, the default, reports it;
+        // `error` fails the build; `off` does not look. Examples are never
+        // mandatory to the specification, so the default suits a library that has
+        // not adopted Microcks; a library that has wants `error` for asyncapi.
+        lintExamples(kind) {
+            const configured = (this.lint.examples || {})[kind];
+            const mode = configured === undefined ? "warn" : configured;
+            if (!["error", "warn", "off"].includes(mode)) {
+                throw new ConfigError(
+                    `lint.examples.${kind} must be error, warn or off, not ${JSON.stringify(configured)}`);
+            }
+            return mode;
+        },
         tool(name) {
             return requireString(this.toolchain[name], `toolchain.${name}`);
         },

package/src/examples.js

@@ -0,0 +1,172 @@
+"use strict";
+
+// Whether a bundled document's operations carry examples the rest of the API-Only
+// toolchain can do something with.
+//
+// Both OpenAPI and AsyncAPI make examples optional, and the specification linters
+// are right to accept their absence: a contract without one is a valid contract.
+// This is a toolchain-compatibility check instead -- can Microcks, or the
+// TranscriberJ, do anything useful with what is about to be published -- and the
+// answer, and so the message, differs per kind. Neither runs from a Redocly plugin
+// or a Spectral ruleset: one implementation, one message shape, aware of why it
+// cares, reported apart from either linter's own findings.
+//
+// AsyncAPI: Microcks builds its async mocks and its conformance tests from a
+// message's own `examples` -- an array of {name, summary, payload} on the Message
+// Object itself. A message with none cannot be used for Microcks-based conformance
+// testing at all, so the message says exactly that.
+//
+// OpenAPI: nothing downstream currently reads an example. The TranscriberJ
+// processes a bundle without one perfectly well -- bodies take arguments,
+// constraints become constants. So the OpenAPI message claims only what is true:
+// weaker documentation, never that the bundle cannot be used.
+
+const KEY = "x-fragment-path";
+
+/** The value at a local JSON pointer (`#/a/b/0`) within `document`, or undefined. */
+function pointer(document, ref) {
+    if (typeof ref !== "string" || !ref.startsWith("#/")) return undefined;
+    let node = document;
+    for (const raw of ref.slice(2).split("/")) {
+        if (node === null || typeof node !== "object") return undefined;
+        const segment = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+        node = node[segment];
+    }
+    return node;
+}
+
+/** `node`, or what it points to when it is a `{ $ref }`. */
+function resolve(document, node) {
+    if (node && typeof node === "object" && typeof node.$ref === "string") {
+        return pointer(document, node.$ref);
+    }
+    return node;
+}
+
+/**
+ * Every AsyncAPI operation whose message carries no example, in operation order.
+ *
+ * An operation naming no message explicitly acts on every message of its channel,
+ * so each of those is checked in its place. A message this document cannot resolve
+ * -- a dangling `$ref`, which lint would already have refused -- is skipped rather
+ * than reported here.
+ *
+ * @returns {Array<{operationId: string, messageKey: string, fragmentPath: string|null, at: string}>}
+ */
+function asyncapiOperationsWithoutExamples(document) {
+    const findings = [];
+    const operations = document.operations || {};
+    for (const [operationId, operation] of Object.entries(operations)) {
+        if (!operation || typeof operation !== "object") continue;
+        const channel = resolve(document, operation.channel);
+        const named = Array.isArray(operation.messages) ? operation.messages : [];
+        const entries = named.length > 0
+            ? named.map((ref) => [
+                typeof ref.$ref === "string" ? ref.$ref.split("/").pop() : null,
+                resolve(document, ref),
+            ])
+            : Object.entries((channel && channel.messages) || {});
+
+        for (const [messageKey, message] of entries) {
+            if (!message || typeof message !== "object" || messageKey === null) continue;
+            const examples = message.examples;
+            if (Array.isArray(examples) && examples.length > 0) continue;
+            findings.push({
+                operationId,
+                messageKey,
+                fragmentPath: message[KEY] || null,
+                at: `/operations/${operationId}`,
+            });
+        }
+    }
+    return findings;
+}
+
+/** Whether any media type of a request body or response object has an example. */
+function hasExample(document, bodyOrResponse) {
+    const content = bodyOrResponse.content;
+    if (!content || typeof content !== "object") return true; // nothing to exemplify
+    return Object.values(content).some((mediaType) => {
+        if (!mediaType || typeof mediaType !== "object") return false;
+        if (mediaType.example !== undefined) return true;
+        if (mediaType.examples && Object.keys(mediaType.examples).length > 0) return true;
+        const schema = resolve(document, mediaType.schema);
+        return !!(schema && Array.isArray(schema.examples) && schema.examples.length > 0);
+    });
+}
+
+const METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+
+/**
+ * Every OpenAPI operation whose request body or a response carries no example, in
+ * path-and-method order.
+ *
+ * An entity counts as having one when a media type declares `example` or
+ * `examples` directly, or when the schema that media type's `schema` resolves to
+ * -- not a property inside it -- carries its own top-level `examples`. A body or
+ * response with no `content` at all, such as a 204, has nothing to exemplify and
+ * is not reported.
+ *
+ * @returns {Array<{operationId: string, part: string, fragmentPath: string|null, at: string}>}
+ */
+function openapiOperationsWithoutExamples(document) {
+    const findings = [];
+    const paths = document.paths || {};
+    for (const [route, pathItem] of Object.entries(paths)) {
+        if (!pathItem || typeof pathItem !== "object") continue;
+        for (const method of METHODS) {
+            const operation = pathItem[method];
+            if (!operation || typeof operation !== "object") continue;
+            const operationId = operation.operationId || `${method.toUpperCase()} ${route}`;
+            const at = `/paths/${route.replace(/~/g, "~0").replace(/\//g, "~1")}/${method}`;
+
+            if (operation.requestBody) {
+                const body = resolve(document, operation.requestBody);
+                if (body && !hasExample(document, body)) {
+                    findings.push({ operationId, part: "request body", fragmentPath: body[KEY] || null, at });
+                }
+            }
+
+            for (const [status, raw] of Object.entries(operation.responses || {})) {
+                const response = resolve(document, raw);
+                if (response && !hasExample(document, response)) {
+                    findings.push({
+                        operationId, part: `response ${status}`, fragmentPath: response[KEY] || null, at,
+                    });
+                }
+            }
+        }
+    }
+    return findings;
+}
+
+/**
+ * The warning text for one AsyncAPI finding.
+ *
+ * @param {{operationId: string, messageKey: string, fragmentPath: string|null}} finding
+ * @returns {string}
+ */
+function asyncapiMessage(finding) {
+    const where = finding.fragmentPath || `at ${finding.at}`;
+    return `AsyncAPI operation '${finding.operationId}': message '${finding.messageKey}' (${where}) ` +
+        "carries no example, so this bundle cannot be used for Microcks-based conformance testing.";
+}
+
+/**
+ * The warning text for one OpenAPI finding.
+ *
+ * @param {{operationId: string, part: string, fragmentPath: string|null}} finding
+ * @returns {string}
+ */
+function openapiMessage(finding) {
+    const where = finding.fragmentPath || `at ${finding.at}`;
+    return `OpenAPI operation '${finding.operationId}': ${finding.part} (${where}) ` +
+        "carries no example, which makes the generated documentation harder to read.";
+}
+
+module.exports = {
+    asyncapiOperationsWithoutExamples,
+    openapiOperationsWithoutExamples,
+    asyncapiMessage,
+    openapiMessage,
+};

package/src/nuget.js

@@ -0,0 +1,275 @@
+"use strict";
+
+// `nuget` -- publish as a NuGet package, for a .NET build.
+//
+// Written directly rather than with nuget.exe or `dotnet pack`, as the Maven channel is
+// written without mvn: a specification repository needs no .NET SDK to reach a .NET
+// audience. A .nupkg is a ZIP archive of a .nuspec, two Open Packaging Conventions parts
+// and the content, and a push is one multipart HTTP PUT.
+//
+// The package carries what `pack` produced, extracted, never rebuilt, under `contracts/`:
+// a folder NuGet gives no behaviour, so the path is the whole contract with a consumer
+// that reads it from its global packages folder today, and the later .targets that
+// places and verifies it is free to decide how it is delivered. That path does not change
+// without a major version of the Publisher.
+//
+// Renovate and Dependabot understand NuGet, so a contract bump reaches a .NET consumer as
+// a pull request, as it does an npm or Maven one.
+
+const crypto = require("crypto");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const { parse, isPrerelease } = require("./version-policy");
+const { zip } = require("./zip");
+const { ChannelError } = require("./channel-error");
+
+/** Where the documents and manifest.json sit inside the package. */
+const CONTENT_FOLDER = "contracts";
+
+// NuGet's own rule (NuGet.Client, PackageIdValidator), and nuget.org's length limit.
+const ID = /^\w+([.-]\w+)*$/;
+const ID_MAX_LENGTH = 100;
+
+const PUBLISH_RESOURCE = "PackagePublish/2.0.0";
+const CONTENT_RESOURCE = "PackageBaseAddress/3.0.0";
+
+function pascalCase(target) {
+    return target.split(/[-_.]/).filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1)).join("");
+}
+
+/**
+ * The package id for a target: `packageId` when configured, otherwise
+ * `<idPrefix>.<target in PascalCase>`, as the Maven channel takes `groupId` and an
+ * optional `artifactId`. Refused, before anything is written, when NuGet would refuse it.
+ */
+function packageId(target, options) {
+    let id = options.packageId;
+    if (!id) {
+        if (!options.idPrefix) throw new ChannelError("the nuget channel requires an idPrefix, such as Contoso.Contracts");
+        id = `${options.idPrefix}.${pascalCase(target)}`;
+    }
+    if (!ID.test(id) || id.length > ID_MAX_LENGTH) {
+        throw new ChannelError(
+            `'${id}' is not a valid NuGet package id: letters, digits and underscores, in parts ` +
+            `separated by single dots or dashes, at most ${ID_MAX_LENGTH} characters. ` +
+            "Set channels.nuget.idPrefix, or channels.nuget.packageId, to one that is.");
+    }
+    return id;
+}
+
+/** Refuses a version NuGet would not tell apart from another. */
+function checkVersion(version) {
+    if (parse(version).build) {
+        throw new ChannelError(
+            `version '${version}' carries build metadata, which NuGet ignores when it identifies a ` +
+            "package: it would be the same package as every other build of " +
+            `${version.split("+")[0]}, and a feed refuses the second. Publish it without the +metadata.`);
+    }
+}
+
+function escape(text) {
+    return String(text).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+
+/** The .nuspec: what the npm channel writes into package.json, in NuGet's terms. */
+function nuspec(id, manifest, options) {
+    const source = manifest.source || {};
+    const repository = source.repository
+        ? `    <repository type="git" url="${escape(source.repository)}"` +
+          (source.commit ? ` commit="${escape(source.commit)}"` : "") + " />\n"
+        : "";
+    return '<?xml version="1.0" encoding="utf-8"?>\n' +
+        '<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">\n' +
+        "  <metadata>\n" +
+        `    <id>${escape(id)}</id>\n` +
+        `    <version>${escape(manifest.version)}</version>\n` +
+        `    <authors>${escape(options.authors || options.idPrefix || id)}</authors>\n` +
+        `    <description>API description documents for ${escape(manifest.target)}.</description>\n` +
+        `    <license type="expression">${escape(options.license || "UNLICENSED")}</license>\n` +
+        repository +
+        "  </metadata>\n" +
+        "</package>\n";
+}
+
+function contentTypes(names) {
+    // Not path.extname: it reads "_rels/.rels" as a dotfile with no extension, and OPC needs "rels".
+    const extension = (name) => {
+        const base = path.posix.basename(name);
+        return base.includes(".") ? base.slice(base.lastIndexOf(".") + 1) : "";
+    };
+    const extensions = [...new Set(names.map(extension).filter(Boolean))].sort();
+    const types = extensions.map((extension) =>
+        `<Default Extension="${escape(extension)}" ContentType="${extension === "rels"
+            ? "application/vnd.openxmlformats-package.relationships+xml" : "application/octet"}" />`);
+    return '<?xml version="1.0" encoding="utf-8"?>' +
+        `<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">${types.join("")}</Types>`;
+}
+
+function relationships(nuspecName) {
+    return '<?xml version="1.0" encoding="utf-8"?>' +
+        '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">' +
+        `<Relationship Type="http://schemas.microsoft.com/packaging/2010/07/manifest" Target="/${escape(nuspecName)}" Id="Rnuspec" />` +
+        "</Relationships>";
+}
+
+/**
+ * The .nupkg bytes: the .nuspec, the packaging parts, then everything the packed archive
+ * holds, extracted and sorted. The same archive always yields the same bytes.
+ */
+function nupkg(archive, id, manifest, options) {
+    const work = fs.mkdtempSync(path.join(os.tmpdir(), "api-only-nuget-"));
+    try {
+        execFileSync("tar", ["-xzf", archive, "-C", work], { encoding: "utf8" });
+        const content = fs.readdirSync(work).sort().map((name) => ({
+            name: `${CONTENT_FOLDER}/${name}`, data: fs.readFileSync(path.join(work, name)),
+        }));
+        const nuspecName = `${id}.nuspec`;
+        const rels = "_rels/.rels";
+        const names = [nuspecName, rels, ...content.map((entry) => entry.name)];
+        return {
+            bytes: zip([
+                { name: nuspecName, data: Buffer.from(nuspec(id, manifest, options), "utf8") },
+                { name: "[Content_Types].xml", data: Buffer.from(contentTypes(names), "utf8") },
+                { name: rels, data: Buffer.from(relationships(nuspecName), "utf8") },
+                ...content,
+            ]),
+            nuspec: nuspec(id, manifest, options),
+        };
+    } finally {
+        fs.rmSync(work, { recursive: true, force: true });
+    }
+}
+
+/**
+ * Write the package into a local feed, in the hierarchical layout `nuget add` writes --
+ * `<id>/<version>/<id>.<version>.nupkg`, lower-cased, with the .sha512 and .nuspec beside
+ * it -- plus manifest.json, so provenance is readable without unpacking, as in Maven.
+ */
+function publishLocal(archive, manifest, options, id, log) {
+    const { bytes, nuspec: spec } = nupkg(archive, id, manifest, options);
+    const lowerId = id.toLowerCase();
+    const lowerVersion = String(manifest.version).toLowerCase();
+    const feed = path.resolve(options.baseDir || ".", options.repository);
+    const dir = path.join(feed, lowerId, lowerVersion);
+    fs.mkdirSync(dir, { recursive: true });
+
+    const file = path.join(dir, `${lowerId}.${lowerVersion}.nupkg`);
+    fs.writeFileSync(file, bytes);
+    fs.writeFileSync(`${file}.sha512`, crypto.createHash("sha512").update(bytes).digest("base64"));
+    fs.writeFileSync(path.join(dir, `${lowerId}.nuspec`), spec);
+    fs.writeFileSync(path.join(dir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+
+    log(`-- Published NuGet ${id} ${manifest.version} to ${feed}`);
+    return { location: file, id, version: manifest.version, prerelease: isPrerelease(manifest.version) };
+}
+
+/** The resources a feed's service index lists. */
+async function feedResources(index) {
+    const response = await fetch(index);
+    if (!response.ok) {
+        throw new ChannelError(`could not read the NuGet service index at ${index}: ${response.status} ${response.statusText}`);
+    }
+    const resources = (await response.json()).resources || [];
+    const find = (type) => (resources.find((r) => r["@type"] === type) || {})["@id"] || null;
+    const publish = find(PUBLISH_RESOURCE);
+    if (!publish) {
+        throw new ChannelError(`the NuGet feed at ${index} has no ${PUBLISH_RESOURCE} resource, so it cannot be pushed to`);
+    }
+    return { publish, content: find(CONTENT_RESOURCE) };
+}
+
+/**
+ * Whether the feed's copy of this version is these bytes: true or false, or null when the
+ * feed offers no way to read it back.
+ */
+async function sameAsPublished(content, id, version, bytes, key) {
+    if (!content) return null;
+    const lowerId = id.toLowerCase();
+    const lowerVersion = String(version).toLowerCase();
+    const url = `${content.replace(/\/?$/, "/")}${lowerId}/${lowerVersion}/${lowerId}.${lowerVersion}.nupkg`;
+    const response = await fetch(url, { headers: { "X-NuGet-ApiKey": key } });
+    if (!response.ok) return null;
+    return Buffer.from(await response.arrayBuffer()).equals(bytes);
+}
+
+/**
+ * Push the package to a remote feed: one PUT to the endpoint the service index names,
+ * the package as the first part of a multipart body, the key in X-NuGet-ApiKey.
+ *
+ * The key is read from the environment, never from configuration, as the Maven channel
+ * reads its token.
+ */
+function publishRemote(archive, manifest, options, id, log) {
+    const tokenEnv = options.tokenEnv || "NUGET_API_KEY";
+    const key = process.env[tokenEnv];
+    if (!key) {
+        throw new ChannelError(
+            `no API key in $${tokenEnv}, which channels.nuget.tokenEnv names. ` +
+            "Remote publication needs one; set it in the release job's environment.");
+    }
+    const { bytes } = nupkg(archive, id, manifest, options);
+
+    return (async () => {
+        const { publish: endpoint, content } = await feedResources(options.repository);
+        const boundary = `api-only-${crypto.createHash("sha256").update(bytes).digest("hex").slice(0, 32)}`;
+        const body = Buffer.concat([
+            Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="package"; filename="package.nupkg"\r\n` +
+                "Content-Type: application/octet-stream\r\n\r\n", "utf8"),
+            bytes,
+            Buffer.from(`\r\n--${boundary}--\r\n`, "utf8"),
+        ]);
+        const response = await fetch(endpoint, {
+            method: "PUT",
+            headers: {
+                "X-NuGet-ApiKey": key,
+                "Content-Type": `multipart/form-data; boundary=${boundary}`,
+                "Content-Length": String(body.length),
+            },
+            body,
+        });
+        if (response.status === 409) {
+            // Idempotent: the same package again is success, a different one is not.
+            const same = await sameAsPublished(content, id, manifest.version, bytes, key);
+            if (same) {
+                log(`-- NuGet ${id} ${manifest.version} is already published, identical; nothing to do`);
+                return {
+                    location: endpoint, id, version: manifest.version, prerelease: isPrerelease(manifest.version),
+                    alreadyPublished: true,
+                };
+            }
+            throw new ChannelError(`the NuGet feed already has ${id} ${manifest.version}` +
+                (same === false ? ", and it is not this package" : ", and it cannot be read back to compare") +
+                "; a published version is never replaced, so publish the change as a new version");
+        }
+        if (!response.ok) {
+            throw new ChannelError(`the NuGet feed refused the package: ${response.status} ${response.statusText}. ` +
+                (response.status === 401 || response.status === 403
+                    ? "Check the key in the environment variable named by channels.nuget.tokenEnv." : ""));
+        }
+        log(`-- Pushed NuGet ${id} ${manifest.version} to ${endpoint}`);
+        return { location: endpoint, id, version: manifest.version, prerelease: isPrerelease(manifest.version) };
+    })();
+}
+
+/**
+ * The channel: a path writes into a local feed, an http(s) URL -- the feed's service
+ * index -- pushes to a remote one. Everything that can be refused is refused before
+ * anything is written or sent.
+ */
+function publishNuget(archive, manifest, options, log) {
+    const id = packageId(manifest.target, options);
+    checkVersion(manifest.version);
+    if (!options.repository) {
+        throw new ChannelError("the nuget channel requires a repository: a directory for a local feed, or a feed's service index URL");
+    }
+    if (/^https?:\/\//.test(options.repository)) {
+        return publishRemote(archive, manifest, options, id, log);
+    }
+    return publishLocal(archive, manifest, options, id, log);
+}
+
+module.exports = { publishNuget, packageId, nuspec, checkVersion, CONTENT_FOLDER };

package/src/pack.js

@@ -11,6 +11,8 @@ const crypto = require("crypto");
 const { execFileSync } = require("child_process");
 const YAML = require("yaml");
 
+const { tgz } = require("./tar");
+
 const MANIFEST_NAME = "manifest.json";
 const MANIFEST_SCHEMA_VERSION = 1;
 
@@ -42,7 +44,31 @@ function gitInfo(cwd) {
  * one version to differ by a line ending, which surfaces months later as an
  * unexplainable verify failure.
  */
-function manifest(config, target, { version, files, closureSha256, producedAt = new Date() }) {
+/**
+ * When the documents were produced: SOURCE_DATE_EPOCH when it is set -- the
+ * reproducible-builds convention, and the way to choose it -- otherwise the time of the
+ * commit being packed, and the current time only outside a git repository. Never simply
+ * "now" inside one: packing the same commit twice has to give the same manifest, and so
+ * the same archive, or no channel could publish the same version twice idempotently.
+ */
+function producedAtFor(cwd) {
+    const epoch = process.env.SOURCE_DATE_EPOCH;
+    if (epoch !== undefined && epoch !== "") {
+        if (!/^\d+$/.test(epoch)) {
+            throw new PackError(`SOURCE_DATE_EPOCH must be a whole number of seconds since 1970, not '${epoch}'`);
+        }
+        return new Date(Number(epoch) * 1000);
+    }
+    try {
+        const seconds = execFileSync("git", ["log", "-1", "--format=%ct"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        if (/^\d+$/.test(seconds)) return new Date(Number(seconds) * 1000);
+    } catch {
+        // Not a git repository, or one with no commits yet.
+    }
+    return new Date();
+}
+
+function manifest(config, target, { version, files, closureSha256, producedAt = producedAtFor(config.root) }) {
     if (!version) throw new PackError(`target '${target}': pack requires a version`);
 
     const source = gitInfo(config.root);
@@ -111,13 +137,9 @@ function pack(config, target, { version, closureSha256, outDir, log = () => {} }
 
     // Deterministic archive: sorted entry names, and no mtime/owner noise, so the
     // same inputs produce the same bytes on any machine.
-    const entries = documents.map((d) => path.basename(d)).concat([MANIFEST_NAME]).sort();
-    execFileSync("tar", [
-        "-czf", archive,
-        "-C", distDir,
-        "--numeric-owner",
-        ...entries,
-    ], { encoding: "utf8" });
+    const entries = documents.map((d) => path.basename(d)).concat([MANIFEST_NAME]).sort()
+        .map((name) => ({ name, data: fs.readFileSync(path.join(distDir, name)) }));
+    fs.writeFileSync(archive, tgz(entries, Math.floor(Date.parse(data.producedAt) / 1000)));
 
     log(`-- Packed ${path.basename(archive)} (${data.files.length} document(s))`);
     return { archive, manifest: data, manifestPath };

package/src/pipeline.js

@@ -11,6 +11,9 @@ const { substituteFile } = require("./placeholders");
 const { stampFile } = require("./version");
 const { generateAsyncApi, generateOpenApi, openapiPushDown, isAggregate } = require("./aggregate");
 const { stampFiles, componentPaths, strayPaths, fragmentStamps, unresolvedStamps, FragmentPathError, KEY } = require("./fragment-paths");
+const {
+    asyncapiOperationsWithoutExamples, openapiOperationsWithoutExamples, asyncapiMessage, openapiMessage,
+} = require("./examples");
 
 class BuildError extends Error {}
 
@@ -205,6 +208,33 @@ function lint(config, kind, file, log, { report = false, reportFile = null } = {
     if (report && output.trim()) log(output.trimEnd());
 }
 
+/**
+ * Reports operations of a built document whose example this kind's toolchain
+ * could use, and does not have -- separately from lint's own findings, since
+ * "your contract is wrong" and "your contract limits what you can do with it
+ * downstream" are different claims and read worse conflated.
+ *
+ * Governed by `lint.examples.<kind>`: `warn`, the default, logs each finding and
+ * continues; `error` logs them and fails the build; `off` does not look.
+ */
+function checkExamples(config, kind, file, log) {
+    const mode = config.lintExamples(kind);
+    if (mode === "off") return;
+
+    const document = YAML.parse(fs.readFileSync(file, "utf8"));
+    const findings = kind === "asyncapi"
+        ? asyncapiOperationsWithoutExamples(document).map(asyncapiMessage)
+        : openapiOperationsWithoutExamples(document).map(openapiMessage);
+    if (findings.length === 0) return;
+
+    for (const message of findings) log(`-- ${message}`);
+    if (mode === "error") {
+        throw new BuildError(
+            `${findings.length} operation(s) in ${path.basename(file)} have no example ` +
+            "(lint.examples." + kind + " is error):\n" + findings.map((m) => `  ${m}`).join("\n"));
+    }
+}
+
 /**
  * Copy a built document to the project that implements the target.
  *
@@ -304,6 +334,7 @@ function build(config, { targets, versionOf = () => null, kinds = ["openapi", "a
                 stampFile(outFile, version);
             }
             lint(config, kind, outFile, log);
+            checkExamples(config, kind, outFile, log);
 
             let distributed = null;
             if (config.isPublished(target)) {
@@ -317,4 +348,6 @@ function build(config, { targets, versionOf = () => null, kinds = ["openapi", "a
     return results;
 }
 
-module.exports = { build, prepare, stage, substituteTree, bundle, bundleWithFragmentPaths, lint, distribute, BuildError };
+module.exports = {
+    build, prepare, stage, substituteTree, bundle, bundleWithFragmentPaths, lint, checkExamples, distribute, BuildError,
+};

package/src/tar.js

@@ -0,0 +1,66 @@
+"use strict";
+
+// A reproducible .tgz writer, for the archive `pack` produces.
+//
+// The system tar records each file's modification time, owner and permissions, and gzip
+// records when it ran, so packing the same documents twice gave two archives. GNU and BSD
+// tar do not agree on the flags that would pin those, so the archive is written here: a
+// ustar header per file, with a fixed mode, no owner, and a modification time the caller
+// chooses, then gzip with no timestamp and a fixed operating-system byte.
+
+const zlib = require("zlib");
+
+class TarError extends Error {}
+
+const BLOCK = 512;
+
+function octal(value, length) {
+    return value.toString(8).padStart(length - 1, "0") + "\0";
+}
+
+function header(name, size, mtime) {
+    const nameBytes = Buffer.from(name, "utf8");
+    if (nameBytes.length > 100 || name.includes("/") || name === "" || name === "." || name === "..") {
+        throw new TarError(`${JSON.stringify(name)} cannot be an entry of the archive: a plain file name of at most 100 bytes`);
+    }
+    const block = Buffer.alloc(BLOCK, 0);
+    nameBytes.copy(block, 0);
+    block.write(octal(0o644, 8), 100, "ascii");
+    block.write(octal(0, 8), 108, "ascii");
+    block.write(octal(0, 8), 116, "ascii");
+    block.write(octal(size, 12), 124, "ascii");
+    block.write(octal(mtime, 12), 136, "ascii");
+    block.write("        ", 148, "ascii");
+    block.write("0", 156, "ascii");
+    block.write("ustar\0", 257, "ascii");
+    block.write("00", 263, "ascii");
+    let sum = 0;
+    for (const byte of block) sum += byte;
+    block.write(octal(sum, 7) + " ", 148, "ascii");
+    return block;
+}
+
+/**
+ * A gzipped ustar archive of `entries`, in the order given, every entry with mode 0644,
+ * owner 0 and modification time `mtime`. The same arguments always give the same bytes.
+ *
+ * @param {Array<{name: string, data: Buffer}>} entries plain file names and their bytes
+ * @param {number} mtime seconds since the epoch
+ * @returns {Buffer}
+ */
+function tgz(entries, mtime) {
+    const parts = [];
+    for (const { name, data } of entries) {
+        parts.push(header(name, data.length, mtime), data);
+        const padding = (BLOCK - (data.length % BLOCK)) % BLOCK;
+        if (padding) parts.push(Buffer.alloc(padding, 0));
+    }
+    parts.push(Buffer.alloc(BLOCK * 2, 0));
+    const gzipped = zlib.gzipSync(Buffer.concat(parts), { level: 9 });
+    // zlib writes the operating system it was built for into byte 9; 255 is "unknown",
+    // so an archive packed on Windows is the same as one packed on Linux.
+    gzipped[9] = 0xff;
+    return gzipped;
+}
+
+module.exports = { tgz, TarError };

package/src/zip.js

@@ -0,0 +1,103 @@
+"use strict";
+
+// A deterministic ZIP writer, for the .nupkg the nuget channel builds.
+//
+// Node has no ZIP writer, and the Publisher carries one runtime dependency; zip, unlike
+// tar, is not reliably installed on Windows or in slim CI images. The subset needed is
+// small: a local header and deflated data per entry, a central directory, and an end
+// record. No ZIP64, no encryption, no extra fields.
+//
+// Deterministic by construction, so that the same packed archive always yields the same
+// package: entries are written in the order given, every entry carries the same fixed
+// timestamp, and deflate runs at a fixed level.
+
+const zlib = require("zlib");
+
+class ZipError extends Error {}
+
+// 1980-01-01 00:00:00, the earliest time a DOS date can hold.
+const DOS_DATE = (0 << 9) | (1 << 5) | 1;
+const DOS_TIME = 0;
+const UTF8_NAMES = 0x0800;
+
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    return c >>> 0;
+});
+
+function crc32(buffer) {
+    let crc = 0xffffffff;
+    for (const byte of buffer) crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    return (crc ^ 0xffffffff) >>> 0;
+}
+
+/** Refuses a name that is empty, absolute, climbs out, uses backslashes, or repeats. */
+function checkNames(entries) {
+    const seen = new Set();
+    for (const { name } of entries) {
+        if (!name || name.startsWith("/") || name.includes("\\") || name.split("/").includes("..")) {
+            throw new ZipError(`${JSON.stringify(name)} is not a valid entry name`);
+        }
+        if (seen.has(name)) throw new ZipError(`${JSON.stringify(name)} appears twice`);
+        seen.add(name);
+    }
+}
+
+/**
+ * A ZIP archive of `entries`, in the order given.
+ *
+ * @param {Array<{name: string, data: Buffer}>} entries forward-slash paths and their bytes
+ * @returns {Buffer}
+ */
+function zip(entries) {
+    checkNames(entries);
+    const locals = [];
+    const centrals = [];
+    let offset = 0;
+    for (const { name, data } of entries) {
+        const nameBytes = Buffer.from(name, "utf8");
+        const deflated = zlib.deflateRawSync(data, { level: 9 });
+        const crc = crc32(data);
+
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(20, 4);
+        local.writeUInt16LE(UTF8_NAMES, 6);
+        local.writeUInt16LE(8, 8);
+        local.writeUInt16LE(DOS_TIME, 10);
+        local.writeUInt16LE(DOS_DATE, 12);
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(deflated.length, 18);
+        local.writeUInt32LE(data.length, 22);
+        local.writeUInt16LE(nameBytes.length, 26);
+        locals.push(local, nameBytes, deflated);
+
+        const central = Buffer.alloc(46);
+        central.writeUInt32LE(0x02014b50, 0);
+        central.writeUInt16LE(20, 4);
+        central.writeUInt16LE(20, 6);
+        central.writeUInt16LE(UTF8_NAMES, 8);
+        central.writeUInt16LE(8, 10);
+        central.writeUInt16LE(DOS_TIME, 12);
+        central.writeUInt16LE(DOS_DATE, 14);
+        central.writeUInt32LE(crc, 16);
+        central.writeUInt32LE(deflated.length, 20);
+        central.writeUInt32LE(data.length, 24);
+        central.writeUInt16LE(nameBytes.length, 28);
+        central.writeUInt32LE(offset, 42);
+        centrals.push(central, nameBytes);
+
+        offset += local.length + nameBytes.length + deflated.length;
+    }
+    const directory = Buffer.concat(centrals);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(directory.length, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...locals, directory, end]);
+}
+
+module.exports = { zip, crc32, ZipError };