@howells/husky 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @howells/husky
+
+Standardised git hooks for Howells projects. Immutable pre-commit and pre-push configuration.
+
+## Install
+
+```bash
+pnpm add -D @howells/husky
+```
+
+## Setup
+
+In `package.json`:
+
+```json
+{
+  "scripts": {
+    "prepare": "howells-husky"
+  },
+  "lint-staged": {
+    "*.{js,ts,jsx,tsx,json,jsonc,css}": "howells-format"
+  }
+}
+```
+
+That's it. On `pnpm install`, the hooks are installed automatically.
+
+## What it does
+
+### Pre-commit
+
+Runs `pnpm lint-staged` — formats staged files with `howells-format`.
+
+### Pre-push
+
+Runs `pnpm typecheck` and `pnpm lint`. Both must pass before code reaches the remote.
+
+## 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-format`
+
+## Why a package?
+
+The hooks are shipped from the package, not stored in the project. This means:
+
+- Agents can't weaken hooks to get code to pass
+- All projects share identical gate configuration
+- Upgrading the package upgrades the hooks everywhere
+
+## Skipped environments
+
+Hooks are skipped when `CI=true` or `VERCEL=1` (no git hooks needed in CI/deployment).

package/bin/howells-husky.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+/**
+ * @howells/husky — standardised git hooks installer.
+ *
+ * Usage: add `"prepare": "howells-husky"` to package.json.
+ *
+ * On `pnpm install`, this script:
+ *   1. Runs `husky` to initialise the .husky/ directory
+ *   2. Copies the canonical pre-commit and pre-push hooks
+ *   3. Validates that lint-staged config exists in package.json
+ *
+ * The hook scripts are immutable — they come from the package,
+ * not from the project. This prevents agents or developers from
+ * weakening the configuration to get things to pass.
+ */
+
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, chmodSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(__dirname, "..");
+const projectRoot = process.cwd();
+
+// Skip in CI environments — hooks aren't needed there
+if (process.env.CI === "true" || process.env.VERCEL === "1") {
+  process.exit(0);
+}
+
+// Skip if not in a git repo (e.g. during npm pack)
+if (!existsSync(join(projectRoot, ".git"))) {
+  process.exit(0);
+}
+
+// Step 1: Run husky to initialise .husky/ directory
+const huskyBin = resolve(packageRoot, "node_modules", ".bin", "husky");
+const huskyResult = spawnSync(huskyBin, [], {
+  cwd: projectRoot,
+  stdio: "inherit",
+  env: process.env,
+});
+
+if (huskyResult.error) {
+  // Fallback: try resolving husky from the project's node_modules
+  const fallbackResult = spawnSync("npx", ["husky"], {
+    cwd: projectRoot,
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  if (fallbackResult.error || (fallbackResult.status !== null && fallbackResult.status !== 0)) {
+    console.error("[@howells/husky] Failed to initialise husky");
+    process.exit(1);
+  }
+}
+
+// Step 2: Copy canonical hook scripts
+const huskyDir = join(projectRoot, ".husky");
+if (!existsSync(huskyDir)) {
+  mkdirSync(huskyDir, { recursive: true });
+}
+
+const hooks = ["pre-commit", "pre-push"];
+const hooksDir = join(packageRoot, "hooks");
+
+for (const hook of hooks) {
+  const source = join(hooksDir, hook);
+  const dest = join(huskyDir, hook);
+  copyFileSync(source, dest);
+  chmodSync(dest, 0o755);
+}
+
+// Step 3: Validate lint-staged config
+const packageJsonPath = join(projectRoot, "package.json");
+if (existsSync(packageJsonPath)) {
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+
+  if (!packageJson["lint-staged"]) {
+    console.warn(
+      '[@howells/husky] Warning: no "lint-staged" config found in package.json.',
+    );
+    console.warn(
+      '  Add: "lint-staged": { "*.{js,ts,jsx,tsx,json,jsonc,css}": "howells-format" }',
+    );
+  }
+
+  // Check that the lint-staged command uses howells-format
+  const lsConfig = packageJson["lint-staged"];
+  if (lsConfig) {
+    const commands = Object.values(lsConfig);
+    const usesHowells = commands.some(
+      (cmd) => typeof cmd === "string" && cmd.includes("howells-format"),
+    );
+    if (!usesHowells) {
+      console.warn(
+        "[@howells/husky] Warning: lint-staged should use howells-format.",
+      );
+      console.warn(
+        '  Expected: "*.{js,ts,jsx,tsx,json,jsonc,css}": "howells-format"',
+      );
+    }
+  }
+
+  // Check that typecheck and lint scripts exist
+  const scripts = packageJson.scripts || {};
+  if (!scripts.typecheck) {
+    console.warn(
+      '[@howells/husky] Warning: no "typecheck" script found. Pre-push hook requires it.',
+    );
+  }
+  if (!scripts.lint) {
+    console.warn(
+      '[@howells/husky] Warning: no "lint" script found. Pre-push hook requires it.',
+    );
+  }
+}
+
+console.log("[@howells/husky] Hooks installed.");

package/hooks/pre-commit

@@ -0,0 +1 @@
+pnpm lint-staged

package/hooks/pre-push

@@ -0,0 +1,2 @@
+pnpm typecheck || exit 1
+pnpm lint || exit 1

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@howells/husky",
+  "version": "0.1.0",
+  "description": "Standardised git hooks for Howells projects. Immutable pre-commit and pre-push configuration.",
+  "license": "MIT",
+  "files": [
+    "bin/*.mjs",
+    "hooks/*",
+    "README.md"
+  ],
+  "bin": {
+    "howells-husky": "bin/howells-husky.mjs"
+  },
+  "dependencies": {
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  }
+}