@homeflare/config 0.10.0 → 0.11.0

package/src/hooks/install.ts

@@ -1,14 +1,18 @@
 /**
  * Adoption: the one wrapper every repo commits, and the check that it has not drifted.
  *
- * ★ WHY A WRAPPER AT ALL. husky can only run a file that is tracked in the repo, so
+ * ★ WHY A WRAPPER AT ALL. git can only run a file that is present in the worktree, so
  *   something must be committed per repo. This keeps that something to a delegation
  *   whose text is owned HERE — the behaviour lives in one package, and a repo that
  *   edits its copy is reported as drift rather than quietly diverging.
  * ★ ONE FILE, TWO NAMES. The wrapper reads the hook name from `$0`, so `pre-commit`
  *   and `pre-push` are byte-identical and there is a single text to keep in step.
+ * ★ THE DIRECTORY KEEPS HUSKY'S NAME, NOT HUSKY. `.husky/` is where the estate's hook files
+ *   already live (homeflare-kit, homeflare-alerts, the house monorepo); since 2026-09-23 git
+ *   runs them directly through `core.hooksPath` — see activate.ts for why husky's own
+ *   `.husky/_` left every fresh worktree without hooks.
  */
-import { chmod, mkdir } from 'node:fs/promises';
+import { chmod, mkdir, stat } from 'node:fs/promises';
 
 /** The hook files this package installs, in the order a contributor meets them. */
 export const HOOK_NAMES = ['pre-commit', 'pre-push'] as const;
@@ -16,27 +20,34 @@ export const HOOK_NAMES = ['pre-commit', 'pre-push'] as const;
 /** Where the runner lives once `bun install` has run. Relative: git runs hooks at the root. */
 const RUNNER = 'node_modules/@homeflare/config/bin/hooks.ts';
 
+/** What a consumer's `prepare` script runs, so every `bun install` activates the hooks. */
+export const PREPARE: string = `bun ${RUNNER} activate`;
+
 /**
- * ⚠️ IT EXITS 0 WHEN THE RUNNER IS ABSENT. A checkout with no `node_modules` would
+ * ⚠️ IT EXITS 0 WHEN THE RUNNER IS ABSENT. A worktree with no `node_modules` would
  *   otherwise fail every commit with a module-resolution error, and the first thing
  *   anyone would do is delete the hook. Failing open is the right trade for a
  *   convenience; the required checks on `main` are what must fail closed.
+ * ★ `"$@"` AND STDIN PASS THROUGH. `pre-push` reads the remote name from its first argument
+ *   and the pushed refs from stdin (push-range.ts); `exec` keeps both.
+ * ⚠️ NO SHEBANG, AND THAT IS MEASURED, NOT FORGOTTEN: git 2.55 runs an executable hook that
+ *   has none through `sh` (2026-09-23), and the husky-era files in the estate have none.
  */
 export const HUSKY_HOOK: string = `# HomeFlare shared git hook. The behaviour lives in @homeflare/config, not in this file,
 # and the same bytes are installed as .husky/pre-commit and .husky/pre-push — the hook
-# name comes from $0.
+# name comes from $0, and git's arguments and stdin pass straight through.
 #
-# ⚠️ A hook is a local convenience, not a gate: it is skippable with --no-verify and does
-#   not exist in a fresh clone until \`bun install\` runs the \`prepare\` script. The
-#   required checks on main stay the gate.
+# ⚠️ A hook is a local convenience, not a gate: it is skippable with --no-verify, and a
+#   worktree runs it only once \`bun install\` has run there. The required checks on main
+#   stay the gate.
 #
 # Regenerate this file with: bun ${RUNNER} install
 hook="${RUNNER}"
 if [ ! -f "$hook" ]; then
-  echo "husky: $hook is missing — run 'bun install' to enable the HomeFlare hooks; skipping"
+  echo "homeflare hooks: $hook is missing — run 'bun install' in this worktree; skipping" >&2
   exit 0
 fi
-exec bun "$hook" "$(basename "$0")"
+exec bun "$hook" "$(basename "$0")" "$@"
 `;
 
 /** Write the wrapper into `.husky/`. Returns the paths written, relative to the project. */
@@ -46,8 +57,8 @@ export async function installHooks(projectDir: string): Promise<readonly string[
   for (const name of HOOK_NAMES) {
     const path = `${projectDir}/.husky/${name}`;
     await Bun.write(path, HUSKY_HOOK);
-    // ⚠️ husky's own runner does `sh -e "$s"`, which does not need the execute bit, but
-    //   `core.hooksPath=.husky` without husky does. Set it so both mechanisms work.
+    // ⛔ THE EXECUTE BIT IS REQUIRED. git runs a `core.hooksPath` file directly and IGNORES
+    //   a non-executable hook, with nothing but an advice line to say so.
     await chmod(path, 0o755);
     written.push(`.husky/${name}`);
   }
@@ -66,20 +77,25 @@ export async function problemsInHooks(projectDir: string): Promise<readonly stri
   const manifest = Bun.file(`${projectDir}/package.json`);
 
   if (!(await manifest.exists())) return ['package.json: missing'];
-  const pkg = (await manifest.json()) as {
-    scripts?: Record<string, string>;
-    devDependencies?: Record<string, string>;
-  };
+  const pkg = (await manifest.json()) as { scripts?: Record<string, string> };
 
-  if (!(pkg.scripts?.['prepare'] ?? '').includes('husky')) {
-    problems.push('package.json: no "prepare": "husky" script — a fresh clone installs no hooks');
+  const prepare = pkg.scripts?.['prepare'] ?? '';
+  if (!/bin\/hooks\.ts activate/.test(prepare)) {
+    problems.push(
+      `package.json: "prepare" does not run \`${PREPARE}\` — no clone or worktree gets hooks`,
+    );
   }
-  if (pkg.devDependencies?.['husky'] === undefined) {
-    problems.push('package.json: husky is not a devDependency');
+  // ⚠️ husky POINTS core.hooksPath AT AN UNTRACKED `.husky/_` that exists only where it ran —
+  //   the gap activate.ts closes. Left in `prepare`, it undoes the activation.
+  if (/\bhusky\b/.test(prepare)) {
+    problems.push(
+      'package.json: "prepare" still runs husky, which re-points core.hooksPath at .husky/_',
+    );
   }
 
   for (const name of HOOK_NAMES) {
-    const file = Bun.file(`${projectDir}/.husky/${name}`);
+    const path = `${projectDir}/.husky/${name}`;
+    const file = Bun.file(path);
     if (!(await file.exists())) {
       problems.push(`.husky/${name}: missing — run \`bun ${RUNNER} install\``);
       continue;
@@ -89,6 +105,9 @@ export async function problemsInHooks(projectDir: string): Promise<readonly stri
         `.husky/${name}: differs from the @homeflare/config wrapper — run \`bun ${RUNNER} install\`, or change it in the package`,
       );
     }
+    if (((await stat(path)).mode & 0o111) === 0) {
+      problems.push(`.husky/${name}: not executable, so git ignores it — chmod +x it and commit`);
+    }
   }
 
   return problems;

package/src/hooks/push-plan.ts

@@ -0,0 +1,167 @@
+/**
+ * What `pre-push` runs: the repository's own `check`, with the expensive lanes narrowed to
+ * the push or left to CI.
+ *
+ * ★ IT READS `check` RATHER THAN NAMING TOOLS. `check` is the command CI runs, so the lanes
+ *   here are that command's lanes — a repository that adds a step to `check` gets it in the
+ *   hook with no change to this package. Hard-coding `tsc` and `bun test` would drift from
+ *   whichever repository added a step first, and certify a push CI rejects.
+ * ★ THREE THINGS CHANGE, AND ONLY THREE:
+ *   1. every `bun test …` becomes `bun test … --changed=<base>` — Bun's own import-graph
+ *      answer to "which test files can these changed files reach" (bun 1.4, measured
+ *      2026-09-23: 11 changed files ran 2 of 246 test files in homeflare-kit);
+ *   2. `build` and `smoke` scripts are skipped — minutes in a big workspace, and CI runs
+ *      both on every pull request;
+ *   3. everything else (lint, types, a `--check` script) runs exactly as `check` spells it.
+ *      They are seconds, whole-program by nature, and deterministic.
+ * ⛔ PURE. No git, no filesystem, no process: the whole contract is a function of the
+ *   scripts table and the base, so the estate's real `check` shapes are pinned by a table
+ *   test (tests/hooks-push-plan.test.ts) instead of by a live push.
+ */
+
+/** One step of the pre-push run. */
+export type Lane =
+  /** Run `command` through `sh -c` at the repository root. */
+  | { readonly kind: 'run'; readonly label: string; readonly command: string }
+  /** A test runner; `scoped` says whether it was narrowed to the push. */
+  | {
+      readonly kind: 'test';
+      readonly label: string;
+      readonly command: string;
+      readonly scoped: boolean;
+    }
+  /** Not run here, and why. */
+  | { readonly kind: 'skip'; readonly label: string; readonly why: string };
+
+/**
+ * ⚠️ BY NAME, AND ONLY THESE. A build in homeflare-kit is every package; a smoke test packs
+ *   and installs tarballs. Both are CI jobs on every pull request, and neither says anything
+ *   a type check and the reachable tests did not already say about a typical push.
+ */
+const LEFT_TO_CI = /^(build|smoke)(:|$)/;
+
+/** Recursion guard: a script that names itself, directly or through another, stops here. */
+const MAX_DEPTH = 8;
+
+/**
+ * Split a script on top-level `&&`, or return undefined when it is anything else.
+ *
+ * ⛔ UNDEFINED MEANS "RUN IT WHOLE". `||`, `;`, a pipe, a redirect, a background `&` or a
+ *   substitution each change what the pieces mean together, and a hook that re-plumbed them
+ *   would run something the repository never wrote. Quoted text is left alone, so
+ *   `--path-ignore-patterns="homeflare-*\/**"` survives intact.
+ */
+export function andChain(script: string): readonly string[] | undefined {
+  const parts: string[] = [];
+  let quote: string | undefined;
+  let current = '';
+  for (let i = 0; i < script.length; i++) {
+    const char = script[i] ?? '';
+    if (quote !== undefined) {
+      if (char === quote) quote = undefined;
+      current += char;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      current += char;
+      continue;
+    }
+    if (char === '&' && script[i + 1] === '&') {
+      parts.push(current.trim());
+      current = '';
+      i += 1;
+      continue;
+    }
+    if ('|;&<>`'.includes(char) || (char === '$' && script[i + 1] === '(')) return undefined;
+    current += char;
+  }
+  if (quote !== undefined) return undefined;
+  parts.push(current.trim());
+  return parts.some((part) => part === '') ? undefined : parts;
+}
+
+/** The script a segment names: `bun run x`, `npm run x`, or `npm test`. Else undefined. */
+function scriptRef(segment: string, scripts: Readonly<Record<string, string>>): string | undefined {
+  const words = segment.split(/\s+/);
+  if (words.length === 2 && words[0] === 'npm' && words[1] === 'test') return 'test';
+  const [runner, verb, name] = words;
+  if (words.length !== 3 || verb !== 'run' || name === undefined) return undefined;
+  if (runner !== 'bun' && runner !== 'npm') return undefined;
+  return Object.hasOwn(scripts, name) ? name : undefined;
+}
+
+/** `bun test …` — the runner, not a script called `test`. */
+const isBunTest = (segment: string): boolean => /^bun\s+test(\s|$)/.test(segment);
+
+function testLane(segment: string, base: string | undefined): Lane {
+  return base === undefined
+    ? { kind: 'test', label: segment, command: segment, scoped: false }
+    : { kind: 'test', label: segment, command: `${segment} --changed=${base}`, scoped: true };
+}
+
+function expand(
+  script: string,
+  scripts: Readonly<Record<string, string>>,
+  base: string | undefined,
+  depth: number,
+): readonly Lane[] | undefined {
+  const segments = andChain(script);
+  if (segments === undefined || depth > MAX_DEPTH) return undefined;
+  const lanes: Lane[] = [];
+  for (const segment of segments) {
+    if (isBunTest(segment)) {
+      lanes.push(testLane(segment, base));
+      continue;
+    }
+    const name = scriptRef(segment, scripts);
+    if (name === undefined) {
+      lanes.push({ kind: 'run', label: segment, command: segment });
+      continue;
+    }
+    if (LEFT_TO_CI.test(name)) {
+      lanes.push({ kind: 'skip', label: segment, why: 'CI runs it on every pull request' });
+      continue;
+    }
+    const inner = expand(scripts[name] ?? '', scripts, base, depth + 1);
+    if (inner !== undefined && inner.some((lane) => lane.kind !== 'run')) {
+      // Something inside needs narrowing or skipping: open the script up.
+      lanes.push(...inner);
+    } else if (/^test(:|$)/.test(name)) {
+      // ⚠️ A TEST SCRIPT WITH NO `bun test` IN IT RUNS IN FULL, AND SAYS SO — vitest with
+      //   coverage thresholds (a narrowed run would fail them), `node --test`, anything piped.
+      //   Narrowing it would mean rewriting a command this package does not understand.
+      lanes.push({ kind: 'test', label: segment, command: segment, scoped: false });
+    } else {
+      // ★ A SCRIPT WITH NOTHING TO NARROW RUNS UNDER ITS OWN NAME. `bun run lint` keeps
+      //   Bun's PATH handling and reads the way the repository wrote it.
+      lanes.push({ kind: 'run', label: segment, command: segment });
+    }
+  }
+  return lanes;
+}
+
+/**
+ * The lanes `pre-push` runs for this `scripts` table.
+ *
+ * `base` is the commit the push is measured from; `undefined` runs every test lane in full
+ * (an unknown base, or a push that changes what every test runs on).
+ * ⚠️ AN EMPTY LIST MEANS NO `check` SCRIPT — the caller reports that; it is not a pass.
+ */
+export function planLanes(
+  scripts: Readonly<Record<string, string>>,
+  base: string | undefined,
+): readonly Lane[] {
+  const check = scripts['check'];
+  if (check === undefined) return [];
+  // ⚠️ A `check` THAT IS NOT A PLAIN `&&` CHAIN IS RUN WHOLE, tests and all, and reported
+  //   as unscoped. No estate repository has one (surveyed 2026-09-23); the fallback exists so
+  //   an unusual one is checked rather than skipped.
+  const whole: Lane = {
+    kind: 'test',
+    label: 'bun run check',
+    command: 'bun run check',
+    scoped: false,
+  };
+  return expand(check, scripts, base, 0) ?? [whole];
+}

package/src/hooks/push-range.ts

@@ -0,0 +1,177 @@
+/**
+ * What a push changes: the base it is measured from, and the files between that base and
+ * the commit being pushed.
+ *
+ * ★ THE BASE COMES FROM GIT, NOT FROM A GUESS. A pre-push hook reads
+ *   `<local ref> <local sha> <remote ref> <remote sha>` on stdin. The remote sha is exactly
+ *   "what the remote has now", so a second push to a branch checks only what is new.
+ * 🔴 A BRANCH-NAME BASE IS VACUOUS ON THE BASE BRANCH. Measured in the house monorepo
+ *   2026-09-08: `turbo --affected` compares against `main`, so on `main` itself it selected
+ *   zero packages and a real two-commit push ran zero tests. Taking the base from stdin
+ *   cannot do that — the remote sha is never the commit being pushed.
+ * ⛔ AN UNKNOWN BASE WIDENS, IT NEVER NARROWS TO NOTHING. No merge base (a shallow clone, a
+ *   rewritten history), no remote-tracking branch: every lane runs, tests in full. A gate
+ *   whose base is unusable must do MORE work, never quietly run nothing.
+ */
+import { probe } from './report.ts';
+
+/** One line of git's pre-push stdin. */
+export type PushRef = {
+  readonly localRef: string;
+  readonly localSha: string;
+  readonly remoteRef: string;
+  readonly remoteSha: string;
+};
+
+export type PushScope =
+  /** The push changes no file (a deletion, or a branch at its base): nothing to check. */
+  | { readonly kind: 'empty'; readonly why: string }
+  /** Measured from `base`: `changed` is every path that differs between it and the tip. */
+  | {
+      readonly kind: 'scoped';
+      readonly base: string;
+      readonly changed: readonly string[];
+      readonly why: string;
+    }
+  /** No usable base: run every lane, tests in full. */
+  | { readonly kind: 'unscoped'; readonly why: string }
+  /** The pushed commit is not what is checked out, so the working tree cannot vouch for it. */
+  | { readonly kind: 'elsewhere'; readonly why: string };
+
+/** git's "no such ref" sentinel — 40 zeros (64 under SHA-256). */
+const ZERO = /^0+$/;
+
+export function parsePushRefs(stdin: string): readonly PushRef[] {
+  const refs: PushRef[] = [];
+  for (const line of stdin.split('\n')) {
+    const [localRef, localSha, remoteRef, remoteSha] = line.trim().split(/\s+/);
+    if (localRef && localSha && remoteRef && remoteSha) {
+      refs.push({ localRef, localSha, remoteRef, remoteSha });
+    }
+  }
+  return refs;
+}
+
+const short = (sha: string): string => sha.slice(0, 9);
+
+async function ok(root: string, args: readonly string[]): Promise<boolean> {
+  return (await probe(['git', '-C', root, ...args])).code === 0;
+}
+
+async function out(root: string, args: readonly string[]): Promise<string | undefined> {
+  const result = await probe(['git', '-C', root, ...args]);
+  return result.code === 0 ? result.stdout.trim() : undefined;
+}
+
+/**
+ * The remote's default branch as a local ref: `<remote>/HEAD` when the clone recorded it,
+ * else `<remote>/main`, else `<remote>/master`.
+ * ⚠️ `refs/remotes/<remote>/HEAD` IS OFTEN ABSENT — `git clone` sets it, `git init` plus
+ *   `git remote add` does not — so the fallbacks are the common path, not the rare one.
+ */
+async function defaultBranch(root: string, remote: string): Promise<string | undefined> {
+  const head = await out(root, ['symbolic-ref', '--quiet', `refs/remotes/${remote}/HEAD`]);
+  if (head !== undefined && head !== '') return head;
+  for (const name of ['main', 'master']) {
+    const ref = `refs/remotes/${remote}/${name}`;
+    if (await ok(root, ['rev-parse', '--verify', '--quiet', ref])) return ref;
+  }
+  return undefined;
+}
+
+/**
+ * Where the pushed commit is measured from.
+ *
+ * ★ A FAST-FORWARD IS MEASURED FROM THE REMOTE SHA — only what this push adds.
+ * ⚠️ ANYTHING ELSE IS MEASURED FROM THE MERGE BASE WITH THE DEFAULT BRANCH: a new branch
+ *   (zero remote sha), a remote sha this clone has not fetched, or a force-push after a
+ *   rebase — where diffing against the old tip would drag in everything `main` gained since.
+ */
+async function baseFor(
+  root: string,
+  remote: string,
+  ref: PushRef,
+): Promise<{ base: string; why: string } | { why: string }> {
+  const { localSha, remoteSha } = ref;
+  if (
+    !ZERO.test(remoteSha) &&
+    (await ok(root, ['cat-file', '-e', `${remoteSha}^{commit}`])) &&
+    (await ok(root, ['merge-base', '--is-ancestor', remoteSha, localSha]))
+  ) {
+    return { base: remoteSha, why: `since ${short(remoteSha)}, what ${remote} has now` };
+  }
+  const branch = await defaultBranch(root, remote);
+  if (branch === undefined) return { why: `no ${remote}/main or ${remote}/master to measure from` };
+  const mergeBase = await out(root, ['merge-base', localSha, branch]);
+  if (mergeBase === undefined || mergeBase === '') {
+    return { why: `no merge base with ${branch} (a shallow clone, or unrelated history)` };
+  }
+  const name = branch.replace(/^refs\/remotes\//, '');
+  return { base: mergeBase, why: `since ${short(mergeBase)}, where this branch left ${name}` };
+}
+
+/**
+ * Resolve the push git described on stdin. With no stdin (a manual run) the push is
+ * `HEAD` to a new branch — measured from the merge base with the default branch.
+ * 🔴 THE LANES RUN ON THE WORKING TREE, SO ONLY A PUSH OF `HEAD` CAN BE CHECKED HERE. Found
+ *   in review 2026-09-23 and reproduced: `git push origin broken` from a clean `main`
+ *   measured the right files, then ran `bun test --changed` against `main`'s tree, found
+ *   nothing, and printed "passed". A ref that is not checked out now comes back
+ *   `elsewhere`, which the caller reports as NOT CHECKED — never as a pass. (The old
+ *   whole-`check` hook had the same blind spot; it just ran unrelated tests while in it.)
+ * ⚠️ WITH SEVERAL REFS, THE ONE AT `HEAD` IS MEASURED and the rest are named as unchecked.
+ */
+export async function pushScope(
+  root: string,
+  remote: string,
+  refs: readonly PushRef[],
+): Promise<PushScope> {
+  const pushed = refs.filter((ref) => !ZERO.test(ref.localSha));
+  if (refs.length > 0 && pushed.length === 0) {
+    return { kind: 'empty', why: 'this push only deletes refs' };
+  }
+  const head = await out(root, ['rev-parse', 'HEAD']);
+  const atHead = pushed.find((ref) => ref.localSha === head);
+  const others = pushed.filter((ref) => ref !== atHead).map((ref) => ref.localRef);
+  if (pushed.length > 0 && atHead === undefined) {
+    return {
+      kind: 'elsewhere',
+      why: `pushing ${others.join(', ')}, but the checkout is at ${short(head ?? '?')}`,
+    };
+  }
+  const ref = atHead ?? {
+    localRef: 'HEAD',
+    localSha: head ?? 'HEAD',
+    remoteRef: '',
+    remoteSha: '0'.repeat(40),
+  };
+  const found = await baseFor(root, remote, ref);
+  const also = others.length > 0 ? `; ${others.join(', ')} not checked here` : '';
+  if (!('base' in found)) return { kind: 'unscoped', why: `${found.why}${also}` };
+
+  const diff = await probe([
+    'git',
+    '-C',
+    root,
+    'diff',
+    '--name-only',
+    '-z',
+    found.base,
+    ref.localSha,
+  ]);
+  if (diff.code !== 0) return { kind: 'unscoped', why: `git diff ${short(found.base)} failed` };
+  const changed = diff.stdout.split('\0').filter((path) => path !== '');
+  if (changed.length === 0) return { kind: 'empty', why: `no file differs ${found.why}${also}` };
+  return { kind: 'scoped', base: found.base, changed, why: `${found.why}${also}` };
+}
+
+/**
+ * A path that changes what EVERY test runs on: a manifest, a lockfile, Bun's config, a
+ * tsconfig. Bun's `--changed` follows imports and none of these is imported — measured
+ * 2026-09-23, editing package.json selected 0 of 246 test files — so a push touching one
+ * runs the tests in full rather than none of them.
+ */
+export function changesEverything(path: string): boolean {
+  const name = path.split('/').pop() ?? '';
+  return /^(package\.json|bun\.lockb?|bunfig\.toml|tsconfig.*\.json)$/.test(name);
+}

package/src/hooks/report.ts

@@ -28,7 +28,7 @@ const BYPASS: Record<Hook, string> = {
  * ⛔ So the hook strips them rather than trusting fourteen test suites to remember. The
  *   gate must see the repository through `cwd`, the way CI does.
  */
-function withoutGitEnv(): Record<string, string | undefined> {
+export function withoutGitEnv(): Record<string, string | undefined> {
   return Object.fromEntries(
     Object.entries(process.env).filter(([name]) => !name.startsWith('GIT_')),
   );
@@ -49,10 +49,34 @@ export async function run(cmd: readonly string[], isolated = false): Promise<num
 
 /** Capture a command's stdout. Used for git plumbing only. */
 export async function capture(cmd: readonly string[]): Promise<string> {
+  return (await probe(cmd)).stdout;
+}
+
+/** Capture a command's stdout AND its exit code — git plumbing that answers by status. */
+export async function probe(cmd: readonly string[]): Promise<{ code: number; stdout: string }> {
   const proc = Bun.spawn([...cmd], { stdout: 'pipe', stderr: 'ignore' });
-  const text = await new Response(proc.stdout).text();
-  await proc.exited;
-  return text;
+  const stdout = await new Response(proc.stdout).text();
+  return { code: await proc.exited, stdout };
+}
+
+/**
+ * Run one pre-push lane through `sh -c` at `root`, as `bun run` would run a script line.
+ *
+ * ⚠️ `node_modules/.bin` FIRST ON PATH, because a lane opened up from a script is no longer
+ *   run by `bun run`, which is what used to put it there — `vitest` or `oxfmt` in an expanded
+ *   script would otherwise be "command not found" on a machine without a global copy.
+ * 🔴 AND WITHOUT THE HOOK'S `GIT_*` — see `withoutGitEnv`.
+ */
+export async function runLane(command: string, root: string): Promise<number> {
+  const env = withoutGitEnv();
+  env['PATH'] = `${root}/node_modules/.bin:${env['PATH'] ?? ''}`;
+  const proc = Bun.spawn(['sh', '-c', command], {
+    cwd: root,
+    env,
+    stdout: 'inherit',
+    stderr: 'inherit',
+  });
+  return await proc.exited;
 }
 
 /**
@@ -60,8 +84,9 @@ export async function capture(cmd: readonly string[]): Promise<string> {
  *
  * ⚠️ NOT `bunx` BY DEFAULT. On a cache miss `bunx` downloads from the registry, and a
  *   git hook that reaches the network mid-commit is a hang waiting for a flaky link.
- *   husky puts `node_modules/.bin` on PATH, but this runs outside husky in tests, so
- *   the local binary is named outright when it exists and `bunx` is only the fallback.
+ *   Git runs the hook with the caller's PATH, which has no `node_modules/.bin` (husky
+ *   used to add it; the hooks no longer run through husky), so the local binary is named
+ *   outright when it exists and `bunx` is only the fallback.
  */
 export function tool(root: string, name: string): readonly string[] {
   const local = `${root}/node_modules/.bin/${name}`;

package/src/hooks/secrets.ts

@@ -0,0 +1,42 @@
+/**
+ * Refuse to commit anything that looks like a credential.
+ *
+ * ⛔ FIRST GATE, ALWAYS. A secret that reaches a public repository is compromised the moment
+ *   it is pushed — rotating it is the only remedy, and rewriting history does not help
+ *   because the object is already fetched and mirrored. Every other check can be fixed
+ *   after the fact; this one cannot. Moved here from homeflare-kit's own
+ *   scripts/hooks/secrets.ts (2026-09-23) so every repository commits under it, not one.
+ * ★ gitleaks IS THE TOOL, not a hand-rolled regex list. It ships hundreds of maintained rules
+ *   and an entropy engine, and it reads the repository's own `.gitleaks.toml` when there is
+ *   one; a homegrown pattern set covers the token shapes its author thought of.
+ * ⚠️ IT IS A GO BINARY, NOT AN npm PACKAGE — nothing in package.json can install it, so a
+ *   missing binary is explained rather than surfacing as "command not found".
+ * ⚠️ `git --staged`, NOT `protect`. Measured 2026-09-15 on gitleaks 8.30.1: `protect` still
+ *   runs, but the documented surface is `gitleaks git` / `dir` / `stdin`.
+ */
+import { fail, ok, run } from './report.ts';
+
+const INSTALL = 'brew install gitleaks — Linux: https://github.com/gitleaks/gitleaks/releases';
+
+export async function scanStagedSecrets(): Promise<void> {
+  // ⛔ NOT A SILENT SKIP. A secret scan that quietly does nothing is worse than none: it
+  //   reads, in a log and in a reviewer's head, as coverage that does not exist.
+  if (Bun.which('gitleaks') === null) {
+    fail(
+      'pre-commit',
+      'gitleaks is not installed, so the staged changes were NOT scanned',
+      INSTALL,
+    );
+  }
+  // `--redact`, so a real finding never prints the secret into a scrollback, a CI log, or an
+  // agent's context.
+  const code = await run(['gitleaks', 'git', '--staged', '--redact', '--no-banner', '.']);
+  if (code !== 0) {
+    fail(
+      'pre-commit',
+      'gitleaks found a secret in the staged changes',
+      'remove it, then ROTATE it — assume anything committed is already compromised',
+    );
+  }
+  ok('pre-commit: gitleaks found no secret in the staged changes');
+}

package/src/hooks.ts

@@ -6,43 +6,59 @@
  *   notices, and two repos disagree about what a commit must satisfy. Here the repo
  *   commits a delegating wrapper and the behaviour ships with the package, so changing
  *   the rule is one release and a version bump rather than fourteen edits.
- *
- * ⚠️ HUSKY, NOT lefthook OR A BARE `core.hooksPath`. It is already the estate's
- *   mechanism in the repos that have working hooks, it installs from `prepare` on a
- *   plain `bun install`, and it keeps the hook files tracked and reviewable. A second
- *   mechanism alongside it would mean two ways to answer "are hooks on in this repo".
+ * ★ TRACKED `.husky/`, RUN BY GIT THROUGH `core.hooksPath` — NOT husky's `.husky/_`. Since
+ *   2026-09-23 the mechanism is the one that reaches every worktree; activate.ts has the
+ *   measurement. The files keep the directory name the estate already uses.
+ * ★ PRE-PUSH IS SCOPED TO THE PUSH (push-range.ts, push-plan.ts): the repository's own
+ *   `check`, with `bun test` narrowed to the tests the pushed files can reach and the build
+ *   and smoke test left to CI. Many agents push to many repositories at once; a pre-push
+ *   that re-ran every suite was the one people learned to skip.
  *
  * Usage from a hook file — see `HUSKY_HOOK`:
  *
  *     bun node_modules/@homeflare/config/bin/hooks.ts pre-commit
  */
+import { activateHooks } from './hooks/activate.ts';
 import { preCommit, prePush } from './hooks/gates.ts';
-import { HOOK_NAMES, HUSKY_HOOK, installHooks, problemsInHooks } from './hooks/install.ts';
+import { HOOK_NAMES, HUSKY_HOOK, PREPARE, installHooks, problemsInHooks } from './hooks/install.ts';
+import { type Lane, planLanes } from './hooks/push-plan.ts';
 import { type Hook, note, ok } from './hooks/report.ts';
 
-export { HOOK_NAMES, HUSKY_HOOK, installHooks, problemsInHooks };
-export type { Hook };
+export { HOOK_NAMES, HUSKY_HOOK, PREPARE, activateHooks, installHooks, planLanes, problemsInHooks };
+export type { Hook, Lane };
 
 /** The commands `bin/hooks.ts` accepts. */
-export type Command = Hook | 'install';
+export type Command = Hook | 'install' | 'activate';
 
 export function isCommand(value: string): value is Command {
-  return value === 'pre-commit' || value === 'pre-push' || value === 'install';
+  return ['pre-commit', 'pre-push', 'install', 'activate'].includes(value);
 }
 
 /**
- * Run one hook, or install the wrappers.
+ * Run one hook, write the wrappers, or activate them.
  *
+ * `args` are git's own hook arguments (for `pre-push`: the remote name and URL) and
+ * `stdin` is what git wrote to the hook (for `pre-push`: the refs being pushed).
  * ⛔ Never exits non-zero for a reason the caller cannot act on: an unknown command is a
  *   programming error in the wrapper and is reported as such, not as a failed commit.
  */
-export async function runCommand(command: Command, root: string): Promise<void> {
+export async function runCommand(
+  command: Command,
+  root: string,
+  args: readonly string[] = [],
+  stdin = '',
+): Promise<void> {
   if (command === 'install') {
     const written = await installHooks(root);
     ok(`wrote ${written.join(', ')} — commit them`);
-    note('they do nothing until `bun install` runs `prepare` (husky)');
+    note(`then set "prepare": "${PREPARE}" so every install activates them`);
+    return;
+  }
+  if (command === 'activate') {
+    const result = await activateHooks(root);
+    (result.active ? ok : note)(`homeflare hooks: ${result.message}`);
     return;
   }
   if (command === 'pre-commit') return await preCommit(root);
-  return await prePush(root);
+  return await prePush(root, args, stdin);
 }