@howells/husky 0.1.2 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Howells
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -18,7 +18,7 @@ In `package.json`:
     "prepare": "howells-husky"
   },
   "lint-staged": {
-    "*.{js,ts,jsx,tsx,json,jsonc,css}": "howells-ox-fix"
+    "*.{js,ts,jsx,tsx,json,jsonc,css}": "howells-fix"
   }
 }
 ```
@@ -29,21 +29,38 @@ That's it. On `pnpm install`, the hooks are installed automatically.
 
 ### Pre-commit
 
-Runs `pnpm lint-staged` — formats staged files with the configured Howells formatter.
-Use `howells-ox-fix` for projects on the Ox lint path. `howells-format` remains supported
-for older projects.
+Runs `pnpm lint-staged` — formats staged files with the configured Howells formatter. Use `howells-fix`. The older names `howells-ox-fix` and `howells-format` are still accepted (legacy) for projects mid-migration.
 
 ### Pre-push
 
 Runs `pnpm typecheck` and `pnpm lint`. Both must pass before code reaches the remote.
 
+Both run against the **working directory**, so their result only describes what is being pushed when the working directory is what is being pushed. Git names the refs on stdin, so the hook can tell:
+
+| What you are pushing | What happens |
+| --- | --- |
+| The commit you have checked out | Typecheck and lint run. A failure blocks the push. |
+| A ref that is not `HEAD` | Skipped, and said out loud. The checks would describe a different tree. |
+| A branch deletion | Ignored; nothing is being added to check. |
+| Nothing on stdin | Checked anyway. An unverified push is what this hook exists to stop. |
+
+**Why a non-`HEAD` push is skipped rather than failed.** It is neither a pass nor a failure - it is unverifiable, and reporting the wrong tree's result is worse than admitting the hook cannot see. The case this matters for is the rescue path: work that exists in one place, in a tree that does not typecheck, is exactly what most needs pushing. The old behaviour failed that push for a reason unrelated to what was being pushed, leaving `--no-verify` as the only route - which disables every gate at once.
+
+### The hooks are immutable, and now they say so
+
+`.husky/pre-commit` and `.husky/pre-push` are overwritten from this package on every install. That is deliberate: a repo cannot weaken its own gate to get something to pass.
+
+What changed is that it is no longer silent. If an install replaces a hook whose contents differ from the packaged one, it says so and names the file. Before, a customised hook vanished on the next `pnpm install` with nothing printed, so whoever wrote it believed it was in effect until it demonstrably was not.
+
+**To change a hook, change it here and publish.** There is no per-repo override, by design.
+
 ## Requirements
 
 Your `package.json` must have:
 
 - `"typecheck"` script (e.g. `tsc --noEmit` or `turbo run typecheck`)
 - `"lint"` script (e.g. `howells-lint` or `turbo run lint`)
-- `"lint-staged"` config using `howells-ox-fix` or `howells-format`
+- `"lint-staged"` config using `howells-fix` (`howells-ox-fix` and `howells-format` still accepted, legacy)
 
 ## Why a package?
 

package/bin/detect.mjs

@@ -0,0 +1,62 @@
+/**
+ * Pure formatter-detection helpers for @howells/husky.
+ *
+ * Kept free of side effects so the install-time bin can stay a thin shell
+ * around behaviour that is unit-testable in isolation.
+ */
+
+// `howells-fix` is the current canonical @howells/lint fixer; `howells-ox-fix`
+// and `howells-format` are earlier names still in use by repos mid-migration.
+// Accept all three so a correct lint-staged config never draws a false warning.
+export const lintStagedFormatterCommands = [
+  "howells-fix",
+  "howells-ox-fix",
+  "howells-format",
+];
+
+export const recommendedLintStagedCommand = "howells-fix";
+
+/**
+ * Flatten a lint-staged config object into the list of command strings it runs.
+ * Values may be a single command string or an array of them.
+ */
+export function lintStagedCommandValues(config) {
+  return Object.values(config).flatMap((value) => {
+    if (typeof value === "string") {
+      return [value];
+    }
+    if (Array.isArray(value)) {
+      return value.filter((item) => typeof item === "string");
+    }
+    return [];
+  });
+}
+
+/**
+ * True when a single lint-staged command invokes a supported Howells formatter.
+ */
+export function usesSupportedFormatter(command) {
+  return lintStagedFormatterCommands.some((formatter) =>
+    command.includes(formatter)
+  );
+}
+
+/**
+ * Decide whether the primary `husky` spawn failed to launch and we should
+ * fall back to `npx husky`. A spawn that launched but exited non-zero is not a
+ * launch failure — only a spawn `error` (e.g. ENOENT) warrants the fallback.
+ */
+export function shouldUseNpxFallback(primaryResult) {
+  return Boolean(primaryResult.error);
+}
+
+/**
+ * True when the npx fallback itself failed — either it could not launch, or it
+ * launched and exited with a non-zero status.
+ */
+export function fallbackFailed(fallbackResult) {
+  return Boolean(
+    fallbackResult.error ||
+    (fallbackResult.status !== null && fallbackResult.status !== 0)
+  );
+}

package/bin/howells-husky.mjs

@@ -23,39 +23,19 @@ import {
   readFileSync,
   chmodSync,
 } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import path from "node:path";
 
-const __dirname = import.meta.dirname;
-const packageRoot = resolve(__dirname, "..");
+import {
+  fallbackFailed,
+  lintStagedCommandValues,
+  recommendedLintStagedCommand,
+  shouldUseNpxFallback,
+  usesSupportedFormatter,
+} from "./detect.mjs";
+
+const scriptDir = import.meta.dirname;
+const packageRoot = path.resolve(scriptDir, "..");
 const projectRoot = process.cwd();
-// `howells-fix` is the current canonical @howells/lint fixer; `howells-ox-fix`
-// and `howells-format` are earlier names still in use by repos mid-migration.
-// Accept all three so a correct lint-staged config never draws a false warning.
-const lintStagedFormatterCommands = [
-  "howells-fix",
-  "howells-ox-fix",
-  "howells-format",
-];
-const recommendedLintStagedCommand = "howells-fix";
-
-function lintStagedCommandValues(config) {
-  return Object.values(config).flatMap((value) => {
-    if (typeof value === "string") {
-      return [value];
-    }
-    if (Array.isArray(value)) {
-      return value.filter((item) => typeof item === "string");
-    }
-    return [];
-  });
-}
-
-function usesSupportedFormatter(command) {
-  return lintStagedFormatterCommands.some((formatter) =>
-    command.includes(formatter)
-  );
-}
 
 // Skip in CI environments — hooks aren't needed there
 if (process.env.CI === "true" || process.env.VERCEL === "1") {
@@ -63,19 +43,19 @@ if (process.env.CI === "true" || process.env.VERCEL === "1") {
 }
 
 // Skip if not in a git repo (e.g. during npm pack)
-if (!existsSync(join(projectRoot, ".git"))) {
+if (!existsSync(path.join(projectRoot, ".git"))) {
   process.exit(0);
 }
 
 // Step 1: Run husky to initialise .husky/ directory
-const huskyBin = resolve(packageRoot, "node_modules", ".bin", "husky");
+const huskyBin = path.resolve(packageRoot, "node_modules", ".bin", "husky");
 const huskyResult = spawnSync(huskyBin, [], {
   cwd: projectRoot,
   env: process.env,
   stdio: "inherit",
 });
 
-if (huskyResult.error) {
+if (shouldUseNpxFallback(huskyResult)) {
   // Fallback: try resolving husky from the project's node_modules
   const fallbackResult = spawnSync("npx", ["husky"], {
     cwd: projectRoot,
@@ -83,33 +63,54 @@ if (huskyResult.error) {
     stdio: "inherit",
   });
 
-  if (
-    fallbackResult.error ||
-    (fallbackResult.status !== null && fallbackResult.status !== 0)
-  ) {
+  if (fallbackFailed(fallbackResult)) {
     console.error("[@howells/husky] Failed to initialise husky");
     process.exit(1);
   }
 }
 
 // Step 2: Copy canonical hook scripts
-const huskyDir = join(projectRoot, ".husky");
+const huskyDir = path.join(projectRoot, ".husky");
 if (!existsSync(huskyDir)) {
   mkdirSync(huskyDir, { recursive: true });
 }
 
 const hooks = ["pre-commit", "pre-push"];
-const hooksDir = join(packageRoot, "hooks");
+const hooksDir = path.join(packageRoot, "hooks");
 
+// The overwrite is deliberate: the hooks are the package's, not the project's,
+// so a weakened gate cannot survive an install. What was missing is that it
+// happened in silence — a customised hook vanished on the next `pnpm install`
+// with nothing said, so the author believed their change was in effect until
+// it demonstrably was not. Replacing is still unconditional; it is now audible.
 for (const hook of hooks) {
-  const source = join(hooksDir, hook);
-  const dest = join(huskyDir, hook);
+  const source = path.join(hooksDir, hook);
+  const dest = path.join(huskyDir, hook);
+
+  let replacedLocalEdit = false;
+  if (existsSync(dest)) {
+    replacedLocalEdit =
+      readFileSync(dest, "utf-8") !== readFileSync(source, "utf-8");
+  }
+
   copyFileSync(source, dest);
   chmodSync(dest, 0o755);
+
+  if (replacedLocalEdit) {
+    console.warn(
+      `[@howells/husky] Replaced .husky/${hook} with the packaged version; your local edits to it are gone.`
+    );
+    console.warn(
+      "  These hooks are intentionally immutable, so a repo cannot weaken its own gate."
+    );
+    console.warn(
+      "  Change them in @howells/husky and publish, or the next install reverts you again."
+    );
+  }
 }
 
 // Step 3: Validate lint-staged config
-const packageJsonPath = join(projectRoot, "package.json");
+const packageJsonPath = path.join(projectRoot, "package.json");
 if (existsSync(packageJsonPath)) {
   const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
 

package/hooks/pre-push

@@ -1,2 +1,58 @@
+#!/usr/bin/env sh
+#
+# Pre-push gate: typecheck and lint before anything reaches a remote.
+#
+# Both checks run against the WORKING DIRECTORY, so their result only describes
+# what is being pushed when the working directory *is* what is being pushed.
+#
+# Git says what is actually being pushed on stdin, one line per ref:
+#
+#     <local ref> <local sha> <remote ref> <remote sha>
+#
+# When a pushed sha is not HEAD - archiving a salvage ref, pushing a branch that
+# is not checked out - the checks would be measuring a different tree. That is
+# neither a pass nor a failure. It is unverifiable, and it is reported as such
+# rather than folded into either, because a gate that reports the wrong tree's
+# result is worse than one that admits it cannot see.
+#
+# This matters most on the rescue path. Work that exists in one place, in a tree
+# that does not typecheck, is exactly what most needs pushing - and the old
+# behaviour failed that push for a reason unrelated to the thing being pushed,
+# leaving `--no-verify` as the only route and disabling every gate at once.
+
+ZERO=0000000000000000000000000000000000000000
+
+head_sha=$(git rev-parse HEAD 2>/dev/null)
+unverifiable=""
+saw_ref=0
+
+while read -r local_ref local_sha _remote_ref _remote_sha; do
+  [ -z "$local_sha" ] && continue
+  saw_ref=1
+
+  # A zero local sha is a branch deletion. Nothing is being added to check.
+  [ "$local_sha" = "$ZERO" ] && continue
+
+  # The common case: pushing the commit that is checked out. The working
+  # directory is the right tree and the checks below describe it.
+  [ "$local_sha" = "$head_sha" ] && continue
+
+  unverifiable="$unverifiable $local_ref"
+done
+
+if [ -n "$unverifiable" ]; then
+  echo "[@howells/husky] Not verified:$unverifiable"
+  echo "  These refs are not HEAD, so typecheck and lint would describe a"
+  echo "  different tree than the one being pushed. Skipped rather than"
+  echo "  reported as passing. Verify on the branch itself, or in CI."
+  exit 0
+fi
+
+# No refs on stdin means git did not tell us what it is pushing. Check anyway:
+# an unverified push is the thing this hook exists to prevent.
+if [ "$saw_ref" = "0" ]; then
+  echo "[@howells/husky] No refs on stdin; checking the working directory."
+fi
+
 pnpm typecheck || exit 1
 pnpm lint || exit 1

package/package.json

@@ -1,29 +1,41 @@
 {
   "name": "@howells/husky",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Standardised git hooks for Howells projects. Immutable pre-commit and pre-push configuration.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/commoninstruments/husky.git"
+  },
   "bin": {
     "howells-husky": "bin/howells-husky.mjs"
   },
   "files": [
-    "bin/*.mjs",
+    "bin/detect.mjs",
+    "bin/howells-husky.mjs",
     "hooks/*",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
+  "type": "module",
   "exports": {
     "./package.json": "./package.json"
   },
   "scripts": {
-    "lint": "howells-ox-check --config=oxlint.config.ts package.json bin hooks README.md oxlint.config.ts oxfmt.config.ts",
-    "lint:fix": "howells-ox-fix --config=oxlint.config.ts package.json bin hooks README.md oxlint.config.ts oxfmt.config.ts",
-    "format": "howells-oxfmt --write package.json bin hooks README.md oxlint.config.ts oxfmt.config.ts README.md"
+    "lint": "howells-check --config=oxlint.config.ts package.json bin hooks README.md oxlint.config.ts oxfmt.config.ts",
+    "lint:fix": "howells-fix --config=oxlint.config.ts package.json bin hooks README.md oxlint.config.ts oxfmt.config.ts",
+    "format": "howells-oxfmt --write package.json bin hooks README.md oxlint.config.ts oxfmt.config.ts",
+    "test": "node --test bin/detect.test.mjs bin/pre-push.test.mjs"
   },
   "dependencies": {
     "husky": "^9.1.7",
     "lint-staged": "^16.4.0"
   },
   "devDependencies": {
-    "@howells/lint": "^0.2.1"
-  }
+    "@howells/lint": "^1.1.0"
+  },
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "packageManager": "pnpm@11.11.0"
 }