@arc-e-tect/api-only-publisher 0.18.4 → 0.18.6

package/README.adoc

@@ -6,7 +6,7 @@
 :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.18.4
+:api-only-publisher-version: 0.18.6
 
 [NOTE]
 .About this documentation
@@ -23,6 +23,8 @@ image:https://img.shields.io/github/v/release/Arc-E-Tect/SoftwareEngineeringDone
 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]
 
+Current release: *{api-only-publisher-version}*, as link:CHANGELOG.md[the changelog →] records it.
+
 [NOTE]
 .Where the links in this document go
 ====
@@ -291,6 +293,10 @@ The name becomes file names, a properties key, a Maven artifactId, a git tag and
 |Broker host
 |`--broker-host <host[:port]>`
 |`kafka:9092`. Asked only for a library with AsyncAPI.
+
+|Run the Publisher with
+|`--runner <npm\|docker>`
+|`npm`. How the pre-push hook runs `check`: `npx`, from the library's own `package.json`, or the Docker image of this Publisher's version (<<installation,Installation §>>).
 |===
 
 A flag always wins: its question is not asked, and an invalid value, or a flag for a kind the library does not hold, stops `init` before it writes anything.
@@ -303,6 +309,13 @@ What each kind of library gets::
 * *Both*: both trees, one target building both documents, and one schema they share: `specs/openapi/components/common/schemas/ExampleIdV1.yaml`, which the HTTP response and the event payload both refer to.
 That is the library's convention in miniature -- a definition used by both protocols is one fragment -- and why the whole source root is staged together (<<what-build-does,What `build` does §>>).
 
+What every library gets as well::
+A `pre-push` git hook, `.githooks/pre-push` at the top of the repository, that runs `check` before every push (<<version-hook,Checking versions before every push §>>).
+Inside a git repository, `init` also points this clone's git at it, with `git config core.hooksPath .githooks`, unless `core.hooksPath` is already set.
+When the repository's hooks are run by a hook manager -- a `.husky` directory, a `lefthook.yml`, a `.pre-commit-config.yaml`, or a `core.hooksPath` that points somewhere else -- `init` writes no hook, which would compete with it, and prints the command to add to the manager's `pre-push` entry instead.
+A `core.hooksPath` in your global git configuration counts as well, deliberately: setting one for this repository would quietly switch off the hooks you run everywhere else, such as a company-wide secret scanner.
+Add the command to those hooks, or set `core.hooksPath` for this repository yourself if that is what you want.
+
 What it reports::
 `init` never overwrites what is there unless told to, and says for every file what it did:
 +
@@ -314,6 +327,8 @@ The message names every slot added -- see <<init-additive,Adding a kind to an ex
 `differs`:: The file was there, and does not match: where the library has diverged from the scaffold, usually on purpose.
 It is left alone.
 `overwrote`:: The file differed, and `--force` replaced it.
+`skipped`:: The pre-push hook was not written, because a hook manager runs the repository's hooks.
+`configured`:: `core.hooksPath` was not set, and now points at `.githooks`.
 +
 At a terminal, `--force` first lists the files that still differ -- after any additive update apionly.yaml already got -- and asks once whether to overwrite them; without a terminal, or with `--yes`, it overwrites them without asking.
 
@@ -385,6 +400,19 @@ Only `build` does this; `lint` does not, and no report file is written.
 [#versions]
 == Versions
 
+[WARNING]
+.You maintain the version files yourself
+====
+The Publisher never writes a version file.
+It does not raise a version when it builds, packs or publishes, and it does not work one out from commit messages the way semantic-release does.
+The version it publishes is whatever the target's version file says.
+It only writes that version into the built document's `info.version`.
+
+So when you change a target's fragments, raise the version in that target's version file yourself, in the same commit.
+The Publisher checks that you did: `check` and `publish` refuse a target that changed without a new version (<<version-guard,A changed target needs a new version §>>).
+A `pre-push` git hook runs the same check on your own machine, before anything leaves it (<<version-hook,Checking versions before every push §>>).
+====
+
 Every published target has a version of its own, and it is kept in the library, beside the fragments it describes.
 
 .specs/openapi/bundles/orders.bundle.properties
@@ -434,34 +462,135 @@ Both read only git: the target's release tags, its history, and the working tree
 |A version above the latest release; one below it is refused.
 
 |No release tags at all
-|Compared with the merge-base with the main branch, or with the ref `--since` names: a target changed since then needs a higher version than its version file declared there, and a version lower than it was there is refused.
+|Compared with the merge-base with the base branch, or with the ref `--since` names: a target changed since then needs a higher version than its version file declared there, and a version lower than it was there is refused.
 A target whose version file was not there yet is new, and passes.
 |===
 
 Release tags are named by `versioning.tagFormat`, `{target}-v{version}` by default: `orders-v2.1.0`.
 The Publisher never creates them: the pipeline that publishes does, after it has published, because a tool that pushes to git needs write access to the repository it builds from.
 The reference pipelines show the step, and the `gitlab-package` channel's `release: true` creates the tag with the release.
-The main branch is `versioning.mainBranch`, `main` by default; its remote-tracking branch, `origin/main`, is preferred, as that is what a CI checkout has.
+The base branch is `versioning.baseBranch`, `main` by default; its remote-tracking branch, `origin/<base branch>`, is preferred, as that is what a CI checkout has.
+Set it to the branch that holds the release you validate against, which need not be `main`.
+A library whose default branch is `pre-prod` cuts a release there and deploys it to staging, and later merges `pre-prod` into `main` only to record that the production deployment was approved.
+For that library the last reviewed versions live on `pre-prod`, so that is the branch to compare with:
+
+[source,yaml]
+----
+versioning:
+  baseBranch: pre-prod   # compared with origin/pre-prod, or pre-prod when there is no remote copy
+----
+
 
 A pre-release follows the same rules, by its full version:
 
-* Its version file need not change: `--pre-release rc.2` already makes a new version, so a target changed since the main branch passes with an unchanged file.
+* Its version file need not change: `--pre-release rc.2` already makes a new version, so a target changed since the base branch passes with an unchanged file.
 * A pre-release that was released before -- a tag `orders-v2.1.0-rc.1` -- is refused when the target changed since, as a release is.
 * A pre-release of a version already released is refused: `2.1.0-rc.1` sorts before `2.1.0`, so it can never be the next version.
 
 Where the guard cannot decide, it says so, and only `check` fails on it: `check` is the gate, while `publish` fails on a proven violation alone.
 Outside a git repository, `check` fails and `publish` warns that the versions were not checked.
-A target with no release tag, in a checkout that has no merge-base with the main branch -- a shallow clone, or no main branch at all -- is `undecided`: `check` fails naming it, and `publish` warns and publishes it; a target with a release tag is decided all the same.
+A target with no release tag, in a checkout that has no merge-base with the base branch -- a shallow clone, or no such branch at all -- is `undecided`: `check` fails naming it, and `publish` warns and publishes it; a target with a release tag is decided all the same.
 In CI, fetch the full history and the tags -- `actions/checkout` with `fetch-depth: 0`, or `GIT_DEPTH: 0` on GitLab -- so that nothing is left undecided.
-Without release tags, the check on the main branch itself compares the main branch with itself, so it is in the pull request that it catches a missing bump; the tags are what make it exact everywhere.
+Without release tags, the check on the base branch itself compares the base branch with itself, so it is in the pull request that it catches a missing bump; the tags are what make it exact everywhere.
 
-To catch it before a push, call `check` from whatever runs the repository's git hooks -- a `pre-push` hook, or a hook manager such as husky or lefthook:
+[#version-hook]
+=== Checking versions before every push
 
+The pipeline catches a missing version bump, but only after you have pushed.
+A git hook catches it before then.
+A hook is a script that git runs on your machine at a fixed moment.
+A `pre-push` hook runs when you type `git push`, and if it fails, git sends nothing.
+The hook below runs `check`.
+It needs no hook manager and nothing outside git and the Publisher.
+
+`init` writes it, as `.githooks/pre-push` at the top of the repository (<<init,Scaffolding a library §>>).
+`--runner` picks the variant: `npm`, the default, or `docker`.
+When the library is in a subdirectory, the hook goes to the top all the same, because that is where git runs hooks from, and runs `check` in the library's directory.
+A second library in the same repository finds the hook there already and reports it as `differs`: add its `check` to the hook by hand.
+
+For a library that already exists, write the hook yourself:
+
+. *Create the hook* as `.githooks/pre-push` in the repository, the one that holds `apionly.yaml`.
+The file has no extension.
+Pick the variant for the way the library runs the Publisher (<<installation,Installation §>>):
++
+.`.githooks/pre-push`, with the Publisher in `package.json`
 [source,sh]
 ----
 #!/bin/sh
+# Refuses the push when a published target changed without a new version in its version file.
+# check compares with origin's base branch and the release tags: bring them up to date.
+git fetch --quiet --tags origin || echo "pre-push: could not fetch origin; checking against what is here" >&2
 exec npx --no-install api-only-publisher check
 ----
++
+.`.githooks/pre-push`, with the Docker image
+[source,sh,subs="attributes+"]
+----
+#!/bin/sh
+# Refuses the push when a published target changed without a new version in its version file.
+# check compares with origin's base branch and the release tags: bring them up to date.
+git fetch --quiet --tags origin || echo "pre-push: could not fetch origin; checking against what is here" >&2
+exec docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" \
+  arcetect/api-only-publisher:{api-only-publisher-version} check
+----
++
+The hook fetches every branch of `origin`, so it never needs to know which one `versioning.baseBranch` names, and changing that setting needs no change to the hook.
+It fetches on your machine, not in the container: the image has no ssh client and none of your credentials.
++
+Git runs a hook from the top of the repository.
+When `apionly.yaml` is in a subdirectory, add `cd <that directory> || exit 1` before the `npx` line, or `-C <that directory>` after `check` in the Docker variant, which needs the whole repository mounted to read its history.
+
+. *Make it executable*, and commit it, so that everyone who clones the repository gets it:
++
+[source,sh]
+----
+chmod +x .githooks/pre-push
+git add .githooks/pre-push
+git commit -m "chore: check API versions before every push"
+----
++
+On Windows, `chmod` has no effect, and neither does the executable bit `init` sets.
+Use `git update-index --chmod=+x .githooks/pre-push` before the commit instead.
+Git for Windows runs the hook with its own `sh`, so the script works there as it is.
+
+. *Tell git to use the directory.*
+Git only looks in `.git/hooks` by default, and that directory is never committed.
+Every clone has to run this once; `init` runs it for the clone it scaffolds in:
++
+[source,sh]
+----
+git config core.hooksPath .githooks
+----
++
+Put this line in the library's own README, or in its setup script, so nobody has to remember it.
+A hook manager such as husky or lefthook does this step for you when its dependencies are installed.
+If you already use one, call the same `check` command from its `pre-push` entry instead; `init` prints that command when it finds one.
+
+. *Try it.*
+Change a fragment of a published target and commit it without changing its version file.
+`git push` should now stop, and the message names the target and its version file:
++
+[source,console]
+----
+$ git push
+orders             2.1.0          VIOLATION  orders changed since the merge-base with main (3f2a91c0d4e1), but its version is still 2.1.0: raise it in specs/openapi/bundles/orders.bundle.properties
+Error: 1 target(s) changed without a new version:
+  orders 2.1.0: orders changed since the merge-base with main (3f2a91c0d4e1), but its version is still 2.1.0: raise it in specs/openapi/bundles/orders.bundle.properties
+A published version is never replaced: a changed specification needs a changed version.
+error: failed to push some refs to 'origin'
+----
++
+Raise the version, commit, and push again.
+
+Some things to know about the hook:
+
+* It checks every published target, not only those the pushed commits touch: a target that did not change passes, and the whole check takes seconds.
+* `check` looks at the working tree, and that includes changes you have not committed yet.
+Commit or stash them before you push, so it checks what you are actually pushing.
+* It needs neither credentials nor a network beyond the `git fetch`, and it builds nothing.
+* `git push --no-verify` skips the hook.
+The pipeline still runs the same check, so skipping it only means you find out later.
 
 [#closure]
 == Independent versioning, and the dependency closure
@@ -952,7 +1081,7 @@ It publishes each target to a GitLab project's Generic Package Registry, on gitl
 [source,yaml]
 ----
 channels:
-  gitlab-package:                          # in a GitLab CI job, nothing below is needed
+  gitlab-package:                          # in a GitLab CI job, nothing below is needed, unless it inherits a GITLAB_TOKEN
     # url: https://gitlab.example.com/api/v4  # default: $CI_API_V4_URL, else https://gitlab.com/api/v4
     # project: group/subgroup/api-library     # an ID or a path; default: $CI_PROJECT_ID
     # tokenEnv: GITLAB_TOKEN                  # default; when unset, $CI_JOB_TOKEN is used
@@ -985,6 +1114,10 @@ link:pipelines/gitlab-ci.yml[The reference pipeline →] publishes this way, fro
 |===
 
 Without either, nothing is sent to GitLab, and `publish` warns, naming both (<<channel-problems,When a channel cannot take a version §>>).
+
+*A `GITLAB_TOKEN` the job inherits wins over `CI_JOB_TOKEN`*, whether it comes from the project, a parent group or the instance, and is sent as a personal or project access token.
+When it is expired or lacks the `api` scope, the read-back fails with `401 Unauthorized` or `403 insufficient_scope`, although the job token itself would have worked.
+Set `tokenEnv: CI_JOB_TOKEN` and `tokenType: job` on the channel to use the job token regardless (link:../docs/guides/publishing-to-gitlab/overview.adoc#token-shadowed[When the job fails with 401 or 403 →]).
 A deploy token is the least privilege for packages alone: it reaches one project's package registry and nothing else.
 
 *The same version again.*
@@ -1135,7 +1268,7 @@ portfolio:                # absent is fine; an aggregate builds on documented de
 
 versioning:               # absent is fine; see A changed target needs a new version §
   tagFormat: "{target}-v{version}"  # the release tags the pipeline creates; the default
-  mainBranch: main        # compared with when a target has no release tag; the default
+  baseBranch: main        # compared with when a target has no release tag; the default
 ----
 
 `targets` is the single source of truth for what gets built.

package/package.json

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

package/src/cli.js

@@ -9,6 +9,7 @@ const { loadFrom, ConfigError } = require("./config");
 const { build, prepare, BuildError } = require("./pipeline");
 const { init, scaffold, plan } = require("./init");
 const { resolveValues } = require("./init-questions");
+const { planHook, setHooksPath, HOOKS_DIR } = require("./init-hook");
 const { resolvePortfolioValues, writePortfolioSection } = require("./config-command");
 const { PlaceholderError } = require("./placeholders");
 const { VersionError } = require("./version");
@@ -34,7 +35,7 @@ Usage:
                           [--title <text>] [--contract-version <version>]
                           [--contact-name <text>] [--contact-url <url>]
                           [--license <spdx-id>] [--license-url <url>]
-                          [--server-url <url>] [--broker-host <host[:port]>]
+                          [--server-url <url>] [--broker-host <host[:port]>] [--runner <npm|docker>]
   api-only-publisher config [section] [--yes] [--portfolio-paths <target-prefix|none>]
                             [--portfolio-location <dir>]
   api-only-publisher build [--target <name>]... [--pre-release <ids>] [--openapi|--asyncapi]
@@ -64,6 +65,9 @@ Options:
   --title, --contract-version, --contact-name, --contact-url, --license,
   --license-url, --server-url, --broker-host
                     init only: the value of that question; a flag always wins.
+  --runner <npm|docker>
+                    init only: how the pre-push hook init writes runs check.
+                    Default: npm.
   --portfolio-paths <target-prefix|none>, --portfolio-location <dir>
                     config only: the value of that question; a flag always wins.
   --since <ref>     changed: the git ref to compare the working tree against.
@@ -94,7 +98,7 @@ function parseArgs(argv) {
     const INIT_VALUES = {
         "--title": "title", "--contract-version": "contractVersion", "--contact-name": "contactName",
         "--contact-url": "contactUrl", "--license": "license", "--license-url": "licenseUrl",
-        "--server-url": "serverUrl", "--broker-host": "brokerHost",
+        "--server-url": "serverUrl", "--broker-host": "brokerHost", "--runner": "runner",
     };
     const CONFIG_VALUES = { "--portfolio-paths": "paths", "--portfolio-location": "location" };
     const positional = [];
@@ -232,26 +236,52 @@ async function runInit(options, positional, io, log) {
         }
 
         log(`Scaffolding a specification library in ${dir}`);
+        const hook = planHook(dir, values.runner, require("../package.json").version);
+        const scaffolded = { ...scaffold(values), ...hook.files };
         let force = options.force;
         if (terminal && force) {
             // Asked, --force means "after showing me": it overwrites what differs only
             // once the list has been seen and agreed to.
-            const differing = plan(dir, scaffold(values), values, portfolio).filter((entry) => entry.status === "differs");
+            const differing = plan(dir, scaffolded, values, portfolio).filter((entry) => entry.status === "differs");
             if (differing.length > 0) {
                 output.write(`These files differ from the scaffold:\n${differing.map((d) => `  ${d.rel}\n`).join("")}`);
                 const answer = await terminal.question(`Overwrite these ${differing.length} file(s)? [y/N] `);
                 force = /^y(es)?$/i.test(answer.trim());
             }
         }
-        init(dir, { values, force, log, portfolio });
+        init(dir, { values, force, log, portfolio, extra: hook.files, executable: hook.executable });
         if (portfolioStatusThisRun === "present") log("  present    portfolio (already configured; init never changes it)");
+        const next = reportHook(hook, log);
         log(`\nNext: api-only-publisher build -C ${dir}`);
+        for (const line of next) log(line);
     } finally {
         if (terminal) terminal.close();
     }
     return 0;
 }
 
+/**
+ * Reports what init did about the pre-push hook beyond writing its file, and does
+ * the one thing left: pointing this clone's git at .githooks, when nothing else
+ * already decides where its hooks are. README.adoc#version-hook.
+ *
+ * @returns {string[]} the lines to print after "Next:", for what init could not do itself
+ */
+function reportHook(hook, log) {
+    if (hook.manager) {
+        log(`  skipped    ${HOOKS_DIR}/pre-push (${hook.manager} runs this repository's hooks)`);
+        return [`Add to its pre-push hook: ${hook.command}`];
+    }
+    if (!hook.repository) {
+        return [`Once this is a git repository, run the pre-push hook: git config core.hooksPath ${HOOKS_DIR}`];
+    }
+    if (hook.hooksPath === "unset") {
+        setHooksPath(hook.repository);
+        log(`  configured core.hooksPath=${HOOKS_DIR} (this clone runs the pre-push hook)`);
+    }
+    return [`Every other clone runs the pre-push hook after: git config core.hooksPath ${HOOKS_DIR}`];
+}
+
 const CONFIGURABLE_SECTIONS = ["portfolio"];
 
 /**

package/src/config.js

@@ -36,7 +36,7 @@ const TARGET_KEYS = ["openapi", "asyncapi", "publish", "versionFile", "channels"
 const TARGET_KIND_KEYS = ["bundle", "aggregate", "info"];
 const PORTFOLIO_KEYS = ["openapi", "security", "location"];
 const PORTFOLIO_OPENAPI_KEYS = ["paths", "operationIds", "tags"];
-const VERSIONING_KEYS = ["tagFormat", "mainBranch"];
+const VERSIONING_KEYS = ["tagFormat", "baseBranch"];
 
 // What every portfolio setting is when apionly.yaml says nothing: safe for the
 // ordinary case (a gateway routing /<target>/** to each service), and named rather
@@ -206,6 +206,9 @@ function load(configPath) {
     }
 
     const versioning = parsed.versioning || {};
+    if (versioning && typeof versioning === "object" && "mainBranch" in versioning) {
+        throw new ConfigError("versioning.mainBranch was renamed to versioning.baseBranch: rename the key, its value stays the same");
+    }
     checkKeys(versioning, VERSIONING_KEYS, "versioning");
     if (versioning.tagFormat !== undefined) {
         const format = requireString(versioning.tagFormat, "versioning.tagFormat");
@@ -213,7 +216,7 @@ function load(configPath) {
             throw new ConfigError(`versioning.tagFormat must contain {target} and {version}, not ${JSON.stringify(format)}`);
         }
     }
-    if (versioning.mainBranch !== undefined) requireString(versioning.mainBranch, "versioning.mainBranch");
+    if (versioning.baseBranch !== undefined) requireString(versioning.baseBranch, "versioning.baseBranch");
 
     const channels = parsed.channels || {};
     const types = channelTypes(channels);
@@ -347,8 +350,8 @@ function load(configPath) {
         tagFormat() {
             return this.versioning.tagFormat || "{target}-v{version}";
         },
-        mainBranch() {
-            return this.versioning.mainBranch || "main";
+        baseBranch() {
+            return this.versioning.baseBranch || "main";
         },
         // Where pack and publish write archives, and split its parts, unless --out says
         // otherwise; relative to this configuration, as every other path here is.

package/src/init-hook.js

@@ -0,0 +1,135 @@
+"use strict";
+
+// The pre-push hook `init` offers: `check` on the developer's own machine, before a
+// target that changed without a new version leaves it. README.adoc#version-hook.
+//
+// Unlike the rest of the scaffold, where the hook goes and whether it is written at
+// all depends on the repository the library is in, so this is where git is read:
+//
+// - The hook lives in .githooks/ at the top of the repository, committed, because
+//   .git/hooks never is; core.hooksPath points git at it, once per clone.
+// - A repository whose hooks a manager runs -- husky, lefthook, pre-commit, or a
+//   core.hooksPath that points elsewhere -- gets no hook file, which would compete
+//   with the manager, only the command to add to its pre-push entry.
+// - The hook fetches on the host, never inside the Docker image: the image has no
+//   ssh client and no credentials, and origin is what check compares with.
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const HOOKS_DIR = ".githooks";
+const IMAGE = "arcetect/api-only-publisher";
+
+function tryGit(args, cwd) {
+    try {
+        return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    } catch {
+        return null;
+    }
+}
+
+/** The closest directory at or above `dir` that exists: init may be scaffolding one that does not yet. */
+function existingAncestor(dir) {
+    let current = dir;
+    while (!fs.existsSync(current)) current = path.dirname(current);
+    return current;
+}
+
+/** A path as a single-quoted shell word. */
+function shellQuote(text) {
+    return /^[A-Za-z0-9_./-]+$/.test(text) ? text : `'${text.replace(/'/g, "'\\''")}'`;
+}
+
+/** The image tag the Docker variant runs: this Publisher's own version, or latest for a build that was never released. */
+function imageTag(version) {
+    return /^\d+\.\d+\.\d+$/.test(version) && version !== "0.0.0" ? version : "latest";
+}
+
+/**
+ * The command a pre-push hook runs, from the top of the repository, for a library
+ * `sub` below it ("" when the library is at the top).
+ *
+ * npx finds the Publisher in the library's own node_modules, so the npm variant
+ * changes into the library first; the Docker variant mounts the whole repository,
+ * .git included, and names the library with -C.
+ */
+function checkCommand(runner, sub, version) {
+    if (runner === "docker") {
+        return `docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" ${IMAGE}:${imageTag(version)} check` +
+            (sub ? ` -C ${shellQuote(sub)}` : "");
+    }
+    return `${sub ? `cd ${shellQuote(sub)} && ` : ""}npx --no-install api-only-publisher check`;
+}
+
+const FETCH = `git fetch --quiet --tags origin || echo "pre-push: could not fetch origin; checking against what is here" >&2`;
+
+/** The hook script itself. */
+function hookScript(runner, sub, version) {
+    const lines = [
+        "#!/bin/sh",
+        "# Written by api-only-publisher init: refuses the push when a published target",
+        "# changed without a new version in its version file. `git push --no-verify` skips it.",
+        "# check compares with origin's base branch and the release tags: bring them up to date.",
+        FETCH,
+    ];
+    // A failed cd must stop the push, not run check somewhere else.
+    if (runner === "npm" && sub) lines.push(`cd ${shellQuote(sub)} || exit 1`, `exec ${checkCommand(runner, "", version)}`);
+    else lines.push(`exec ${checkCommand(runner, sub, version)}`);
+    return lines.join("\n") + "\n";
+}
+
+/** The hook manager this repository already uses, by name, or null. */
+function hookManager(top, hooksPath) {
+    if (fs.existsSync(path.join(top, ".husky"))) return "husky";
+    for (const file of ["lefthook.yml", "lefthook.yaml", ".lefthook.yml", ".lefthook.yaml"]) {
+        if (fs.existsSync(path.join(top, file))) return "lefthook";
+    }
+    if (fs.existsSync(path.join(top, ".pre-commit-config.yaml"))) return "pre-commit";
+    if (hooksPath && path.normalize(hooksPath).replace(/[\\/]+$/, "") !== HOOKS_DIR) return `core.hooksPath (${hooksPath})`;
+    return null;
+}
+
+/**
+ * What init does about the hook for a library in `dir`, run with `runner`.
+ *
+ * @returns {{
+ *     files: Object<string, string>,   the hook file, keyed by its path relative to dir; empty under a manager
+ *     executable: string[],            which of those files to make executable
+ *     manager: string|null,            the hook manager found, if any
+ *     command: string,                 what a manager's pre-push entry should run
+ *     repository: string|null,         the top of the git repository, or null outside one
+ *     hooksPath: "unset"|"set"|null,   whether init should set core.hooksPath; null when it has nothing to do
+ * }}
+ */
+function planHook(dir, runner, version) {
+    const top = tryGit(["rev-parse", "--show-toplevel"], existingAncestor(dir));
+    const repository = top === null ? null : fs.realpathSync(top);
+    // Real paths, as git answers with: a directory reached through a symlink -- /var on macOS -- would never match.
+    const ancestor = existingAncestor(dir);
+    const libraryDir = path.join(fs.realpathSync(ancestor), path.relative(ancestor, dir));
+    // Outside a repository, the library is taken to become the top of one.
+    const root = repository || libraryDir;
+    const sub = path.relative(root, libraryDir).split(path.sep).join("/");
+    const hooksPath = repository ? tryGit(["config", "--get", "core.hooksPath"], repository) : null;
+    const manager = repository ? hookManager(repository, hooksPath) : null;
+    const command = checkCommand(runner, sub, version);
+    if (manager) return { files: {}, executable: [], manager, command, repository, hooksPath: null };
+
+    const rel = path.relative(libraryDir, path.join(root, HOOKS_DIR, "pre-push")).split(path.sep).join("/");
+    return {
+        files: { [rel]: hookScript(runner, sub, version) },
+        executable: [rel],
+        manager: null,
+        command,
+        repository,
+        hooksPath: hooksPath ? "set" : "unset",
+    };
+}
+
+/** Points git at .githooks in this clone. */
+function setHooksPath(repository) {
+    execFileSync("git", ["config", "core.hooksPath", HOOKS_DIR], { cwd: repository, stdio: "ignore" });
+}
+
+module.exports = { planHook, setHooksPath, imageTag, HOOKS_DIR };

package/src/init-questions.js

@@ -100,6 +100,14 @@ const QUESTIONS = [
     },
     { key: "serverUrl", flag: "--server-url", text: "Production server URL", check: checkUrl, when: hasOpenapi },
     { key: "brokerHost", flag: "--broker-host", text: "Broker host, with its port", check: checkHost, when: hasAsyncapi, name: "a broker host" },
+    {
+        // How the pre-push hook runs check: through the library's own npm install, or the image.
+        key: "runner", flag: "--runner", text: "Run the Publisher with: npm or docker",
+        read: (text) => {
+            const runner = text.trim().toLowerCase();
+            return ["npm", "docker"].includes(runner) ? { value: runner } : { problem: `'${text}' is not npm or docker` };
+        },
+    },
 ];
 
 /** Reads an answer to a question: the value, or what is wrong with it. */

package/src/init.js

@@ -29,6 +29,7 @@ const DEFAULTS = Object.freeze({
     licenseUrl: "https://www.apache.org/licenses/LICENSE-2.0.html",
     serverUrl: "https://api.example.invalid",
     brokerHost: "kafka:9092",
+    runner: "npm",
 });
 
 /** A value as a YAML scalar: plain where YAML reads it back unchanged, quoted where it would not. */
@@ -362,9 +363,15 @@ function plan(targetDir, files, values, portfolio) {
  * `portfolio`, given, is added the same way, as one more slot: whether the
  * library is about to have more than one target -- and so whether this is worth
  * asking about at all -- is decided before init is called, not here.
+ *
+ * `extra` are files beyond the scaffold, keyed as it is -- the pre-push hook, whose
+ * place depends on the repository, which init-hook.js reads -- and written by the
+ * same rules; those `executable` names are made executable whenever they are written.
  */
-function init(targetDir, { values = DEFAULTS, force = false, log = () => {}, portfolio = null } = {}) {
-    const files = scaffold(values);
+function init(targetDir, {
+    values = DEFAULTS, force = false, log = () => {}, portfolio = null, extra = {}, executable = [],
+} = {}) {
+    const files = { ...scaffold(values), ...extra };
     const report = { created: [], overwritten: [], identical: [], differing: [], updated: [] };
     const updates = [];
 
@@ -386,6 +393,7 @@ function init(targetDir, { values = DEFAULTS, force = false, log = () => {}, por
         const file = path.join(targetDir, rel);
         fs.mkdirSync(path.dirname(file), { recursive: true });
         fs.writeFileSync(file, files[rel]);
+        if (executable.includes(rel)) fs.chmodSync(file, 0o755);
         (status === "missing" ? report.created : report.overwritten).push(rel);
     }
 

package/src/version-guard.js

@@ -62,13 +62,13 @@ function fallbackBaseline(config, repoRoot, since) {
         if (!commit) throw new GuardError(`--since ${since} is not a commit in this repository`);
         return { ref: commit, label: `${since} (${commit.slice(0, 12)})` };
     }
-    const branch = config.mainBranch();
+    const branch = config.baseBranch();
     for (const candidate of [`origin/${branch}`, branch]) {
         if (!tryGit(["rev-parse", "--verify", "--quiet", `${candidate}^{commit}`], repoRoot)) continue;
         const base = tryGit(["merge-base", "HEAD", candidate], repoRoot);
         if (base) return { ref: base, label: `the merge-base with ${branch} (${base.slice(0, 12)})` };
     }
-    return { missing: `no merge-base with ${branch}, the branch versioning.mainBranch names, to compare a target without a release tag with. ` +
+    return { missing: `no merge-base with ${branch}, the branch versioning.baseBranch names, to compare a target without a release tag with. ` +
         "In CI, fetch the full history and the branch (actions/checkout with fetch-depth: 0, or GIT_DEPTH: 0 on GitLab), " +
         "or name the ref to compare with: --since <ref>." };
 }