feat: add :guard and :init runseal wrappers with git hooks (#3)

:guard runs the local validation suite (cargo fmt/clippy/test --locked,
mirroring CI smoke, plus deno fmt/lint/check on .runseal/). :init validates
tools/paths and installs pre-commit (refuse main + runseal :guard) and
commit-msg (<area>: <summary>) hooks, with --force backup of foreign hooks.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: PerishCode

.runseal/hooks/commit-msg

@@ -0,0 +1,39 @@
+#!/usr/bin/env sh
+# santi :init hook: generated by runseal :init
+set -eu
+
+if [ "$#" -ne 1 ] || [ ! -f "$1" ]; then
+  echo "commit message file not found" >&2
+  exit 1
+fi
+
+subject=$(sed -n '
+/^[[:space:]]*#/d
+/[^[:space:]]/ {
+  s/^[[:space:]]*//
+  s/[[:space:]]*$//
+  p
+  q
+}
+' "$1")
+
+if [ -z "$subject" ]; then
+  echo "commit subject is empty" >&2
+  exit 1
+fi
+
+case "$subject" in
+  "Merge "*|"Revert "*|"fixup!"*|"squash!"*)
+    exit 0
+    ;;
+esac
+
+if ! printf '%s\n' "$subject" | grep -Eq '^[a-z][a-z0-9-]*(/[a-z0-9-]+)*: [^[:space:]].*'; then
+  echo "commit subject must look like '<area>: <imperative summary>'" >&2
+  echo "actual: $subject" >&2
+  exit 1
+fi
+
+if [ "${#subject}" -gt 72 ]; then
+  echo "warning: commit subject is ${#subject} chars; prefer <= 72" >&2
+fi

.runseal/hooks/pre-commit

@@ -0,0 +1,14 @@
+#!/usr/bin/env sh
+# santi :init hook: generated by runseal :init
+set -eu
+root=$(git rev-parse --show-toplevel)
+cd "$root"
+
+branch=$(git symbolic-ref --quiet --short HEAD || true)
+if [ "$branch" = "main" ]; then
+  printf '%s\n' "pre-commit: refusing to commit directly on main" >&2
+  printf '%s\n' "create a feature branch first, then commit again" >&2
+  exit 1
+fi
+
+runseal :guard

.runseal/lib/guard/guard.ts

@@ -0,0 +1,61 @@
+//! `runseal :guard` — the local validation suite the pre-commit hook runs.
+//!
+//! Mirrors the CI `smoke (ubuntu-latest)` job (cargo fmt/clippy/test, all
+//! `--locked` like CI) so "green locally" means "green in CI", plus the Deno
+//! checks for the `.runseal/` wrappers that CI does not cover. Runnable on
+//! demand as well as from the hook.
+
+import { run } from "@/lib/std/cmd.ts";
+import { join } from "@/lib/std/fs.ts";
+import { repoRoot } from "@/lib/std/repo.ts";
+
+interface Step {
+  title: string;
+  command: string;
+  args: string[];
+}
+
+export async function guard(): Promise<number> {
+  const repo = repoRoot();
+  const wrappers = wrapperFiles(repo);
+  const config = ".runseal/deno.json";
+
+  const steps: Step[] = [
+    { title: "cargo fmt", command: "cargo", args: ["fmt", "--all", "--check"] },
+    {
+      title: "cargo clippy",
+      command: "cargo",
+      args: ["clippy", "--locked", "--workspace", "--all-targets", "--", "-D", "warnings"],
+    },
+    { title: "cargo test", command: "cargo", args: ["test", "--locked", "--workspace"] },
+    {
+      title: "deno fmt",
+      command: "deno",
+      args: ["fmt", "--config", config, "--check", ".runseal"],
+    },
+    { title: "deno lint", command: "deno", args: ["lint", "--config", config, ".runseal"] },
+    { title: "deno check", command: "deno", args: ["check", "--config", config, ...wrappers] },
+  ];
+
+  for (const step of steps) {
+    console.log(`==> ${step.title}`);
+    const code = await run(step.command, step.args, { cwd: repo });
+    if (code !== 0) {
+      console.error(`:guard: ${step.title} failed`);
+      return code;
+    }
+  }
+  console.log("guard: ok");
+  return 0;
+}
+
+/** Discover wrapper entrypoints so `deno check` covers them (and their libs). */
+function wrapperFiles(repo: string): string[] {
+  const files: string[] = [];
+  for (const entry of Deno.readDirSync(join(repo, ".runseal/wrappers"))) {
+    if (entry.isFile && entry.name.endsWith(".ts")) {
+      files.push(`.runseal/wrappers/${entry.name}`);
+    }
+  }
+  return files.sort();
+}

.runseal/lib/init/init.ts

@@ -0,0 +1,113 @@
+//! `runseal :init [--force]` — validate the repo and install git hooks.
+//!
+//! Installs `.runseal/hooks/{pre-commit,commit-msg}` into the repo's hooks
+//! directory. Existing hooks generated by a prior `:init` are replaced; foreign
+//! hooks are left alone unless `--force` is given (then backed up first).
+
+import { capture } from "@/lib/std/cmd.ts";
+import { exists, join } from "@/lib/std/fs.ts";
+
+const MARKER = "santi :init hook";
+const HOOKS = ["pre-commit", "commit-msg"];
+const REQUIRED_TOOLS = ["git", "deno", "cargo", "runseal"];
+const REQUIRED_PATHS = [
+  "runseal.toml",
+  ".runseal/deno.json",
+  ".runseal/hooks/pre-commit",
+  ".runseal/hooks/commit-msg",
+  ".runseal/wrappers/guard.ts",
+];
+
+export async function init(argv: string[]): Promise<number> {
+  if (argv.includes("-h") || argv.includes("--help")) {
+    usage();
+    return 0;
+  }
+  const force = argv.includes("--force");
+  const positional = argv.find((arg) => !arg.startsWith("-"));
+  if (positional !== undefined) return fail(`unexpected argument: ${positional}`);
+
+  console.log("==> resolving repository");
+  const root = (await capture("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
+  if (root === "") return fail("not inside a git repository");
+  const gitDir = (await capture("git", ["rev-parse", "--absolute-git-dir"])).stdout.trim();
+  const hooksDir = join(gitDir, "hooks");
+  console.log(`repository: ${root}`);
+
+  console.log("==> checking required tools");
+  for (const tool of REQUIRED_TOOLS) {
+    if (!(await toolExists(tool))) return fail(`missing required tool: ${tool}`);
+  }
+  console.log(`ok: ${REQUIRED_TOOLS.join(", ")}`);
+
+  console.log("==> checking repository entrypoints");
+  for (const rel of REQUIRED_PATHS) {
+    if (!exists(join(root, rel))) return fail(`missing required path: ${rel}`);
+  }
+  console.log("ok: repository entrypoints");
+
+  console.log("==> installing git hooks");
+  Deno.mkdirSync(hooksDir, { recursive: true });
+  for (const name of HOOKS) {
+    const dest = join(hooksDir, name);
+    const prepared = prepareHook(dest, force);
+    if (prepared !== 0) return prepared;
+    Deno.copyFileSync(join(root, ".runseal/hooks", name), dest);
+    chmod755(dest);
+    console.log(`installed ${dest}`);
+  }
+  console.log("hooks installed — commits now refuse main and run `runseal :guard`");
+  return 0;
+}
+
+function prepareHook(dest: string, force: boolean): number {
+  if (!exists(dest)) return 0;
+  let content = "";
+  try {
+    content = Deno.readTextFileSync(dest);
+  } catch {
+    content = "";
+  }
+  if (content.includes(MARKER)) return 0; // generated by us; safe to replace
+  if (!force) {
+    return fail(
+      `${dest} exists and was not generated by :init — rerun with --force to back it up and replace it`,
+    );
+  }
+  const backup = backupNumbered(dest);
+  console.log(`backed up existing hook to ${backup}`);
+  return 0;
+}
+
+function backupNumbered(path: string): string {
+  let candidate = `${path}.bak`;
+  let n = 1;
+  while (exists(candidate)) candidate = `${path}.bak.${n++}`;
+  Deno.renameSync(path, candidate);
+  return candidate;
+}
+
+async function toolExists(tool: string): Promise<boolean> {
+  const result = await capture("sh", ["-c", `command -v ${tool}`]);
+  return result.code === 0 && result.stdout.trim() !== "";
+}
+
+function chmod755(path: string): void {
+  try {
+    Deno.chmodSync(path, 0o755);
+  } catch {
+    // non-unix platform; git uses its own executable handling
+  }
+}
+
+function usage(): void {
+  console.log("Usage: runseal :init [--force]");
+  console.log("");
+  console.log("Validate the repo and install git hooks (pre-commit, commit-msg).");
+  console.log("  --force   back up a non-generated existing hook before replacing it");
+}
+
+function fail(message: string): number {
+  console.error(`:init: ${message}`);
+  return 1;
+}

.runseal/lib/std/fs.ts

@@ -0,0 +1,14 @@
+//! Tiny filesystem path helpers, shared by wrappers.
+
+export function exists(path: string): boolean {
+  try {
+    Deno.statSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function join(...parts: string[]): string {
+  return parts.join("/").replace(/(?<!:)\/{2,}/g, "/");
+}

.runseal/wrappers/guard.ts

@@ -0,0 +1,6 @@
+//! `runseal :guard` — run the local validation suite (mirrors CI smoke + Deno
+//! checks). Thin entry point; logic lives in the guard module.
+
+import { guard } from "@/lib/guard/guard.ts";
+
+Deno.exit(await guard());

.runseal/wrappers/init.ts

@@ -0,0 +1,6 @@
+//! `runseal :init [--force]` — install local git hooks. Thin entry point; logic
+//! lives in the init module.
+
+import { init } from "@/lib/init/init.ts";
+
+Deno.exit(await init(Deno.args));