@monte3l/groundwork 0.0.0

package/templates/core/bin/lib/protected-paths.mjs

@@ -0,0 +1,23 @@
+// Single source of truth for the guarded source/test path shape used by the
+// Claude hook layer to prevent hub-authored or branch-isolation writes into
+// source and test trees. Shared by:
+//   - .claude/hooks/guard-branch-isolation.mjs  (blocks writes while HEAD is main)
+//   - .claude/hooks/guard-hub-src-writes.mjs    (blocks hub writes on any branch)
+//
+// Keeping the regex in one place means neither guard can silently diverge
+// from the other when the protected glob set evolves.
+
+/**
+ * Returns true if `filePath` has any `src/` or `tests/` path segment --
+ * this single check covers a flat `src/`/`tests/` layout AND a nested one
+ * (`packages/<pkg>/src/`), since both contain the literal substring
+ * `/src/` preceded by a path boundary.
+ *
+ * Matches both relative and absolute paths (the `(^|\/)` anchor).
+ *
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isProtectedPath(filePath) {
+  return /(^|\/)src\//.test(filePath) || /(^|\/)tests\//.test(filePath);
+}

package/templates/core/bin/lib/report.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * Shared structured-reporter contract every bin/check-*.mjs and bin/verify.mjs
+ * gate routes through, so output is consistent (human-readable by default,
+ * `--json` for machine consumption) without each gate reimplementing it.
+ */
+import { execFileSync } from "node:child_process";
+
+/** True when `--json` is present in the given argv. */
+export function parseJsonFlag(argv) {
+  return argv.includes("--json");
+}
+
+/** The repository root, via `git rev-parse --show-toplevel`. */
+export function repoRoot() {
+  return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+    encoding: "utf8",
+  }).trim();
+}
+
+/**
+ * Creates a reporter that accumulates `ok`/`warn`/`fail` lines, printing each
+ * immediately (unless `json`, in which case only `finish()` prints, as one
+ * JSON object). `finish()` sets `process.exitCode` (1 if anything failed) and
+ * returns whether the run passed.
+ */
+export function createReporter(json) {
+  const lines = [];
+  let failed = false;
+
+  function ok(message) {
+    lines.push({ level: "ok", message });
+    if (!json) console.log(`  ok  ${message}`);
+  }
+
+  function warn(message) {
+    lines.push({ level: "warn", message });
+    if (!json) console.warn(`warn  ${message}`);
+  }
+
+  function fail(message) {
+    failed = true;
+    lines.push({ level: "fail", message });
+    if (!json) console.error(`fail  ${message}`);
+  }
+
+  function finish() {
+    if (json) {
+      console.log(JSON.stringify({ ok: !failed, lines }, null, 2));
+    }
+    process.exitCode = failed ? 1 : 0;
+    return !failed;
+  }
+
+  return { ok, warn, fail, finish };
+}

package/templates/core/bin/lib/signed-range.mjs

@@ -0,0 +1,178 @@
+/**
+ * Shared git-signature helpers for the push-time guard.
+ *
+ * @see .claude/hooks/guard-git-push-signed.mjs -- the agent-side PreToolUse
+ * hook that inspects a `git push` Bash command before it runs.
+ */
+import { execFileSync } from "node:child_process";
+
+/**
+ * Signature codes that `git`'s `%G?` placeholder considers acceptable:
+ *   G = a good (validly verified) signature,
+ *   U = a good signature with unknown validity (signer key not in the local
+ *       trust store) -- still cryptographically valid, so we accept it.
+ * Everything else -- N (none), B (bad), E (cannot check), X/Y/R
+ * (expired/revoked) -- is treated as unsigned/unverified.
+ */
+const VALID_SIGNATURE_CODES = new Set(["G", "U"]);
+
+/**
+ * Default git runner; returns stdout as a string. Injectable for tests.
+ * stderr is discarded so expected failures while probing candidate bases
+ * (e.g. "no upstream configured") don't leak into the hook's output -- the
+ * throw is what callers act on.
+ */
+function defaultRunGit(args) {
+  return execFileSync("git", args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+}
+
+// `git` global options that consume the following token as their argument, so
+// we can skip past them when hunting for the subcommand (e.g. `git -c k=v push`).
+const GLOBAL_OPTS_WITH_ARG = new Set([
+  "-c",
+  "-C",
+  "--git-dir",
+  "--work-tree",
+  "--namespace",
+  "--exec-path",
+]);
+
+/**
+ * Decide whether a shell command string performs a real `git push` (as opposed
+ * to a dry run or some other git subcommand). Handles `&&`/`||`/`;`/newline
+ * chains by inspecting each segment, and skips git global options.
+ *
+ * @param {string} command
+ * @returns {{ isPush: boolean, dryRun: boolean }}
+ */
+export function parseGitPush(command) {
+  if (typeof command !== "string") return { isPush: false, dryRun: false };
+  for (const segment of command.split(/&&|\|\||;|\n/)) {
+    const tokens = segment.trim().split(/\s+/).filter(Boolean);
+    let i = tokens.findIndex((t) => t === "git" || t.endsWith("/git"));
+    if (i === -1) continue;
+    i += 1;
+    while (i < tokens.length) {
+      const t = tokens[i];
+      if (GLOBAL_OPTS_WITH_ARG.has(t)) {
+        i += 2;
+        continue;
+      }
+      if (t.startsWith("-")) {
+        i += 1;
+        continue;
+      }
+      break;
+    }
+    if (tokens[i] !== "push") continue;
+    const rest = tokens.slice(i + 1);
+    const dryRun = rest.includes("--dry-run") || rest.includes("-n");
+    return { isPush: true, dryRun };
+  }
+  return { isPush: false, dryRun: false };
+}
+
+/**
+ * The commits that a push would send: everything reachable from `HEAD` but
+ * not from the branch's upstream or `origin/main` -- both that resolve are
+ * excluded together, not just the first. Local `main` is used only as a
+ * LAST RESORT, when neither remote ref resolves (e.g. a fresh local-only
+ * repo with no `origin`) -- never unioned in alongside them, since `main`
+ * can be `HEAD` itself and excluding it unconditionally would erase the
+ * very commits being pushed.
+ *
+ * Falls back to just `HEAD` when nothing resolves at all (a brand-new
+ * repo/branch). Already-pushed history is intentionally excluded -- we only
+ * vet what's new.
+ *
+ * @param {(args: string[]) => string} [runGit]
+ * @returns {string[]} commit SHAs (newest first), possibly empty
+ */
+export function outgoingCommits(runGit = defaultRunGit) {
+  const resolves = (ref) => {
+    try {
+      runGit(["rev-parse", "--verify", "--quiet", ref]);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  const excludeRefs = ["@{upstream}", "origin/main"].filter(resolves);
+  if (excludeRefs.length === 0 && resolves("main")) {
+    excludeRefs.push("main");
+  }
+
+  if (excludeRefs.length === 0) {
+    try {
+      return [runGit(["rev-parse", "HEAD"]).trim()].filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+  try {
+    const out = runGit(["rev-list", "HEAD", "--not", ...excludeRefs]);
+    return out
+      .split("\n")
+      .map((s) => s.trim())
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The `%G?` signature code for a single commit.
+ *
+ * @param {string} sha
+ * @param {(args: string[]) => string} [runGit]
+ * @returns {string}
+ */
+function commitSignatureCode(sha, runGit = defaultRunGit) {
+  return runGit(["show", "--no-patch", "--format=%G?", sha]).trim();
+}
+
+/**
+ * Filter a list of commit SHAs down to those whose signature is missing or
+ * invalid (i.e. `%G?` is not in {@link VALID_SIGNATURE_CODES}). A commit whose
+ * code cannot be read is reported as unsigned rather than silently skipped.
+ *
+ * @param {string[]} shas
+ * @param {(args: string[]) => string} [runGit]
+ * @returns {{ sha: string, code: string }[]}
+ */
+export function unsignedCommits(shas, runGit = defaultRunGit) {
+  const bad = [];
+  for (const sha of shas) {
+    let code;
+    try {
+      code = commitSignatureCode(sha, runGit);
+    } catch {
+      code = "E";
+    }
+    if (!VALID_SIGNATURE_CODES.has(code)) bad.push({ sha, code });
+  }
+  return bad;
+}
+
+/**
+ * Whether this machine's git is configured to sign commits at all
+ * (`commit.gpgsign`/`commit.gpgSign` = true, checked at any config scope).
+ * `guard-git-push-signed.mjs` uses this as its opt-in switch: a project that
+ * hasn't set up commit signing gets no enforcement (nothing to enforce would
+ * otherwise block every single push), and enabling signing locally turns the
+ * guard on with no other configuration step.
+ *
+ * @param {(args: string[]) => string} [runGit]
+ * @returns {boolean}
+ */
+export function signingEnabled(runGit = defaultRunGit) {
+  try {
+    return runGit(["config", "--get", "commit.gpgsign"]).trim() === "true";
+  } catch {
+    return false;
+  }
+}