@greenharness/greengate 0.0.0-stage → 3.1.0

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# greengate
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Catch the bad commit before it exists — and take the whole thing back out in one command.**
+
+[![CI](https://github.com/greenharness/greengate/actions/workflows/ci.yaml/badge.svg)](https://github.com/greenharness/greengate/actions/workflows/ci.yaml)
+[![Release](https://img.shields.io/github/v/release/greenharness/greengate?label=release)](https://github.com/greenharness/greengate/releases/latest)
+[![License](https://img.shields.io/github/license/greenharness/greengate)](LICENSE)
+
+A single Rust binary that checks `git commit` and `git push`. It ships
+thirty-nine built-in checks — commit-message conventions, conflict markers,
+secrets, the linters and test suites of the languages your repository actually
+uses — and each one fires only where the repository has opted into its tool, so
+there is no YAML to write before it is useful. The commit path links no
+external crates, a cloned repository's own checks stay inert until you
+`greengate trust` them, and `greengate uninstall` removes exactly the six shims install
+wrote. [How it compares](docs/similar-projects.md) to pre-commit, lefthook and
+husky.
+
+![greengate catching a commit and letting the fixed one through](docs/assets/amont-demo.gif)
+
+> **greengate was called amont until 3.0.0.** Installs place `amont` and
+> `amont-fleet` beside it as copies, so hooks baked to the old name keep
+> working; the `amont-*` crates stay at 2.3.1 and npm's `amont` at 2.3.0 (now
+> `cargo install greengate`, `npm i -D @greenharness/greengate`,
+> `brew install fredericrous/tap/greengate`). Config keys, `amont.conf` and
+> `AMONT_*` variables are unchanged. See [Installing](docs/install.md).
+
+`greengate list` says what runs in the repository you are standing in — here, a
+Python one:
+
+```
+pre-commit
+  ● ban-terms
+  ● ruff
+  ● secrets
+  …
+pre-push
+  ● audit-python
+  …
+  15 active here.  23 inert (Go, JavaScript, Kubernetes, Python, Rust) — greengate list --all
+```
+
+## Install
+
+```sh
+# Linux and macOS
+curl -fsSL https://raw.githubusercontent.com/greenharness/greengate/main/install/install.sh | sh
+```
+
+```powershell
+# Windows
+irm https://raw.githubusercontent.com/greenharness/greengate/main/install/install.ps1 | iex
+```
+
+Either one downloads a release binary, checks it against the published
+`SHA256SUMS`, and **enables nothing**. Homebrew, crates.io, npm, prebuilt
+archives and building from source: [installing](docs/install.md). Needs git
+2.31 or later.
+
+## Turning hooks on
+
+```sh
+cd <your-repo> && greengate install          # this repository only — the default
+greengate-fleet install --root ~/Developer   # many repositories at once
+greengate enroll --conventions declared      # every future clone on this machine
+```
+
+`enroll` is a standing grant; read [rolling out to a team](docs/team-rollout.md)
+before you use it. `greengate uninstall` removes the shims again —
+[opting out](docs/opting-out.md) covers that and everything short of it.
+
+## Day to day
+
+```sh
+greengate run                  # would my commit pass? (the staged set)
+greengate run --all-files      # does my working tree pass?
+greengate check src/main.rs    # these files, in the format editors already parse
+greengate rehearse --wait      # the push gate on a snapshot of HEAD, before you push
+greengate land                 # push this branch, then read the remote back to prove it moved
+greengate trust                # review what this repository's amont.conf declares
+git config amont.severity.clippy warn   # runs, reports, does not block
+git config hook.skip clippy             # does not run at all
+```
+
+## Documentation
+
+Versioned with the code in [`docs/`](docs/) and published as a
+[book](https://greenharness.github.io/greengate/):
+
+- [Installing and activating](docs/install.md) ·
+  [Rolling out to a team](docs/team-rollout.md) · [The CI backstop](docs/ci.md)
+- [The checks](docs/checks.md) · [Configuration](docs/configuration.md) ·
+  [Opting out](docs/opting-out.md) · [Commit conventions](docs/commit-convention.md)
+- [Where the hooks fit in your flow](docs/coding-flow.md) ·
+  [The trust model](docs/trust.md) · [Custom checks and packs](docs/custom-checks.md)
+- [Why you can let this near your commits](docs/index.md#why-you-can-let-this-near-your-commits) ·
+  [The repositories around it](docs/index.md#the-repositories-around-it) ·
+  [SECURITY.md](SECURITY.md) · [design records](docs/SUMMARY.md#design-records)
+
+## Contributing
+
+`make check` is the CI-parity target; setup, the zero-dependency rule and the
+house style are in [CONTRIBUTING.md](CONTRIBUTING.md). Questions in
+[Discussions](https://github.com/greenharness/greengate/discussions), bugs in
+[issues](https://github.com/greenharness/greengate/issues). By participating you
+agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+[MIT](LICENSE).

package/bin/greengate.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// The hook runtime. See ./native.js for how the platform binary is found.
+require("./native.js").become("greengate");

package/bin/native.js

@@ -0,0 +1,98 @@
+// Find the native binary npm installed for this platform, and become it.
+//
+// This wrapper exists only because a package manager can link a `bin` that
+// lives inside the package, and the native executable lives in a DIFFERENT
+// package — one of six, selected by npm from `os`/`cpu`/`libc`.
+//
+// It is not on the hook path. `amont init` bakes `current_exe()` — the native
+// binary this spawns, not this file — into `.git/hooks`, so the ~30ms of node
+// start-up below is paid once during `prepare` and never again on a commit.
+// See npm/README.md.
+//
+// Parameterised by binary name rather than copied per binary. Everything below
+// — pnpm's non-hoisting, the libc fallback, spawn-versus-exists, signal exit
+// codes — was learned once and is worth exactly one copy; a second wrapper that
+// duplicated it would be a second place for those lessons to rot.
+
+const { spawnSync } = require("node:child_process");
+const { existsSync } = require("node:fs");
+
+// The same six targets `release.yaml` builds, spelled the way npm spells them.
+// `libc` is why linux-x64 appears twice: a musl host cannot run the glibc build,
+// and npm will install only the package whose `libc` matches.
+const PACKAGES = {
+  "darwin arm64": "@greenharness/greengate-darwin-arm64",
+  "darwin x64": "@greenharness/greengate-darwin-x64",
+  "linux arm64": "@greenharness/greengate-linux-arm64-gnu",
+  "linux x64": ["@greenharness/greengate-linux-x64-gnu", "@greenharness/greengate-linux-x64-musl"],
+  "win32 x64": "@greenharness/greengate-win32-x64",
+};
+
+function candidates() {
+  const found = PACKAGES[`${process.platform} ${process.arch}`];
+  if (!found) return [];
+  return Array.isArray(found) ? found : [found];
+}
+
+// `require.resolve` rather than a hand-built `../amont-<target>/bin/…` path.
+// pnpm does not hoist — the real package sits under `node_modules/.pnpm/` — so a
+// path assembled from `__dirname` is correct under npm and wrong under pnpm and
+// yarn. Node's own resolver knows where the dependency actually is.
+function binaryOf(pkg, name) {
+  const exe = process.platform === "win32" ? `${name}.exe` : name;
+  try {
+    const p = require.resolve(`${pkg}/bin/${exe}`);
+    if (existsSync(p)) return p;
+  } catch {
+    // Not installed: either the wrong libc for this host, or an
+    // `--ignore-scripts`-style install that skipped optional deps.
+  }
+  return null;
+}
+
+// Existence is not runnability, so the loop is over SPAWNS, not paths. With a
+// package manager that ignores the `libc` field — yarn classic does, and
+// `npm install --force` is this file's own suggested remedy — BOTH linux-x64
+// builds get installed, gnu listed first, and on a musl host the gnu binary
+// fails at exec on the missing glibc loader while the right one sits a
+// candidate later. Only a spawn-level failure (`result.error`) falls through:
+// a binary that ran and exited non-zero has ANSWERED, and its exit code is the
+// whole product of a hook runner.
+function become(name) {
+  const failures = [];
+  for (const pkg of candidates()) {
+    const binary = binaryOf(pkg, name);
+    if (!binary) continue;
+    // `spawnSync` with inherited stdio rather than `execFileSync`: this forwards
+    // the child's exit CODE. It also keeps the child's stdin, which `amont run`
+    // reads.
+    const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
+    if (result.error) {
+      failures.push(`      ${binary}: ${result.error.message}`);
+      continue;
+    }
+    // A signalled child has a null status. Report it the way a shell does, so
+    // "killed by SIGINT" does not read as a clean exit 0.
+    if (result.status === null && result.signal) {
+      process.exit(128 + (require("node:os").constants.signals[result.signal] ?? 0));
+    }
+    process.exit(result.status ?? 1);
+  }
+
+  // Name the platform. "amont binary not found" sends people to reinstall;
+  // "no build for linux/ppc64" tells them the actual answer, which is that they
+  // want `cargo install amont` or the shell installer.
+  const target = `${process.platform}/${process.arch}`;
+  process.stderr.write(
+    `${name}: no runnable native binary for ${target}.\n` +
+      (failures.length ? `  Installed but could not run:\n${failures.join("\n")}\n` : "") +
+      `  npm installs one of: ${Object.values(PACKAGES).flat().join(", ")}\n` +
+      `  If your platform is not among them, build from source:\n` +
+      `      cargo install greengate\n` +
+      `  If it is, the optional dependency did not install — try:\n` +
+      `      npm install --force @greenharness/greengate\n`,
+  );
+  process.exit(1);
+}
+
+module.exports = { become };

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@greenharness/greengate",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.1.0",
+  "description": "Opinionated git hooks that judge what you are committing, not what is on disk",
+  "keywords": [
+    "git",
+    "git-hooks",
+    "pre-commit",
+    "pre-push",
+    "hooks",
+    "lint",
+    "husky"
+  ],
+  "homepage": "https://github.com/greenharness/greengate#readme",
+  "bugs": "https://github.com/greenharness/greengate/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/greenharness/greengate.git"
+  },
+  "license": "MIT",
+  "author": "Frederic Rousseau",
+  "type": "commonjs",
+  "_comment_bin": "Both names run the same wrapper: `greengate`, and `amont` for a package.json script or shim written before the rename.",
+  "bin": {
+    "greengate": "bin/greengate.js",
+    "amont": "bin/greengate.js"
+  },
+  "_comment_access": "Scoped packages default to RESTRICTED; this says public in the manifest too, so a hand-run publish cannot make the package private.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/greengate.js",
+    "bin/native.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@greenharness/greengate-darwin-arm64": "3.1.0",
+    "@greenharness/greengate-darwin-x64": "3.1.0",
+    "@greenharness/greengate-linux-arm64-gnu": "3.1.0",
+    "@greenharness/greengate-linux-x64-gnu": "3.1.0",
+    "@greenharness/greengate-linux-x64-musl": "3.1.0",
+    "@greenharness/greengate-win32-x64": "3.1.0"
+  }
+}