@cratis/pi 0.0.1 → 2.0.2

package/package/corpus/hooks/scripts/cratis-pattern-scan.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# PostToolUse hook — deterministic pattern pass over a just-edited file.
+#
+# Zero model calls, zero token cost until something actually matches. Reads the Claude Code
+# hook JSON on stdin, resolves the edited file, and runs every applicable pattern from
+# cratis-patterns.json against it. A match appends a one-line reminder to context; it NEVER
+# blocks (always exits 0). Each pattern fires at most once per file per session, so it
+# cannot flood the conversation.
+#
+# Escape hatch: CRATIS_HOOKS_SKIP_SCAN=1 disables the pass entirely.
+set -euo pipefail
+
+# SCRIPTDIR, not a path relative to the caller: shellcheck resolves a plain relative `source=`
+# against the current working directory, and these hooks are linted from wherever CI happens to run.
+# shellcheck source=SCRIPTDIR/hook-lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/hook-lib.sh"
+
+[ "${CRATIS_HOOKS_SKIP_SCAN:-0}" = "1" ] && exit 0
+
+input="$(hook_read_stdin)"
+[ -n "$input" ] || exit 0
+
+# jq is the repository's established JSON dependency. If it is not
+# installed the hook degrades to a silent no-op rather than breaking the session.
+hook_have jq || exit 0
+
+root="$(hook_repo_root)"
+cwd="$(hook_json "$input" '.cwd')"
+[ -n "$cwd" ] || cwd="$root"
+
+file="$(hook_json "$input" '.tool_input.file_path')"
+[ -n "$file" ] || file="$(hook_json "$input" '.tool_input.notebook_path')"
+[ -n "$file" ] || exit 0
+
+file="$(hook_abspath "$file" "$cwd")"
+[ -f "$file" ] || exit 0
+
+# Never scan binaries or very large files — this hook must stay cheap.
+LC_ALL=C grep -Iq . "$file" 2>/dev/null || exit 0
+size="$(wc -c <"$file" 2>/dev/null || printf '0')"
+[ "${size:-0}" -le 2000000 ] || exit 0
+
+rel="$(hook_relpath "$file" "$root")"
+
+# ── Pattern set: shipped defaults + optional local extension / override ───────
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+base_file="${CRATIS_HOOKS_PATTERNS:-$here/cratis-patterns.json}"
+local_file="$here/cratis-patterns.local.json"
+[ -f "$base_file" ] || exit 0
+
+if [ -f "$local_file" ]; then
+    # Local entries with the same id win; new ids are appended.
+    merged="$(jq -s '
+        {patterns: (
+            ((.[0].patterns // []) | map(select(.id as $i | ((.[1].patterns // []) | map(.id) | index($i)) == null)))
+            + ((.[1].patterns // []))
+        )}' "$base_file" "$local_file" 2>/dev/null || true)"
+    [ -n "$merged" ] || merged="$(cat "$base_file")"
+else
+    merged="$(cat "$base_file")"
+fi
+
+# One record per line. Fields separated by US (0x1f); list members inside a field by SOH (0x01).
+# `join` is used instead of @tsv because @tsv escapes backslashes, which would corrupt regexes.
+records="$(printf '%s' "$merged" | jq -r '
+    .patterns // []
+    | map(select((.enabled // true) == true))
+    | .[]
+    | [ .id,
+        .pattern,
+        .message,
+        (.rule // ""),
+        ((.paths // ["**/*"]) | join("
")),
+        ((.exclude_paths // []) | join("
")),
+        ((.requires_in_file // []) | join("
")),
+        ((.absent_in_file // []) | join("
")),
+        (.within_type_attribute // ""),
+        ((.join_lines // 1) | tostring) ]
+    | join("")
+' 2>/dev/null || true)"
+[ -n "$records" ] || exit 0
+
+session="$(hook_json "$input" '.session_id')"
+state_dir="$(hook_state_dir "${session:-nosession}")" || exit 0
+seen_file="$state_dir/pattern-scan.seen"
+
+# Match a file against the newline-separated ERE list on stdin. mode=all|none.
+file_has() {
+    local mode="$1" f="$2" re
+    while IFS= read -r re; do
+        [ -n "$re" ] || continue
+        if LC_ALL=C grep -Eq -- "$re" "$f" 2>/dev/null; then
+            [ "$mode" = "none" ] && return 1
+        else
+            [ "$mode" = "all" ] && return 1
+        fi
+    done
+    return 0
+}
+
+findings=""
+while IFS=$'\037' read -r id pattern message rule paths excludes requires absent attr joinlines; do
+    [ -n "${id:-}" ] || continue
+    [ -n "${pattern:-}" ] || continue
+
+    printf '%s' "${paths:-}" | tr '\001' '\n' | hook_glob_match "$rel" || continue
+    if [ -n "${excludes:-}" ]; then
+        printf '%s' "$excludes" | tr '\001' '\n' | hook_glob_match "$rel" && continue
+    fi
+    if [ -n "${requires:-}" ]; then
+        printf '%s' "$requires" | tr '\001' '\n' | file_has all "$file" || continue
+    fi
+    if [ -n "${absent:-}" ]; then
+        printf '%s' "$absent" | tr '\001' '\n' | file_has none "$file" || continue
+    fi
+
+    # The scan: first matching line number, or nothing. Regexes travel through ENVIRON
+    # because `awk -v` performs backslash-escape processing on the value.
+    line="$(
+        CRATIS_PAT="$pattern" CRATIS_ATTR="${attr:-}" CRATIS_JOIN="${joinlines:-1}" awk '
+            function cnt(s, ch,    n, i) { n = 0; for (i = 1; i <= length(s); i++) if (substr(s, i, 1) == ch) n++; return n }
+            function trim(s) { sub(/^[ \t]+/, "", s); sub(/[ \t\r]+$/, "", s); return s }
+            BEGIN {
+                pat  = ENVIRON["CRATIS_PAT"]
+                attr = ENVIRON["CRATIS_ATTR"]
+                jn   = ENVIRON["CRATIS_JOIN"] + 0
+                if (jn < 1) jn = 1
+                if (attr != "") attrRe = "\\[" attr "(\\]|\\()"
+                mode = 0; depth = 0; pending = ""
+            }
+            {
+                lines[NR] = $0
+                if (attr == "") next
+                t = trim($0)
+                if (mode == 2) {                                  # inside a braced type body
+                    scope[NR] = 1
+                    depth += cnt($0, "{") - cnt($0, "}")
+                    if (depth <= 0) mode = 0
+                    next
+                }
+                if (mode == 1) {                                  # declaration still being read
+                    scope[NR] = 1
+                    if (index($0, "{") > 0) {
+                        depth = cnt($0, "{") - cnt($0, "}")
+                        mode = (depth > 0) ? 2 : 0
+                    } else if (index($0, ";") > 0) {
+                        mode = 0
+                    }
+                    next
+                }
+                if (t == "" || t ~ /^\/\// || t ~ /^\*/ || t ~ /^\/\*/) next
+                if (t ~ /^\[/) { pending = pending " " t; next }  # accumulate attributes
+                if (t ~ /(^|[ \t])(record|class|struct|interface)([ \t]|$)/) {
+                    if (attrRe != "" && pending ~ attrRe) {
+                        scope[NR] = 1
+                        if (index($0, "{") > 0)      { depth = cnt($0, "{") - cnt($0, "}"); mode = (depth > 0) ? 2 : 0 }
+                        else if (index($0, ";") > 0) { mode = 0 }
+                        else                         { mode = 1 }
+                    }
+                    pending = ""
+                    next
+                }
+                pending = ""
+            }
+            END {
+                for (i = 1; i <= NR; i++) {
+                    if (attr != "" && !(i in scope)) continue
+                    tl = trim(lines[i])
+                    if (tl ~ /^\/\// || tl ~ /^\*/ || tl ~ /^\/\*/) continue
+                    buf = lines[i]
+                    for (j = 1; j < jn; j++) if (i + j <= NR) buf = buf " " lines[i + j]
+                    if (buf ~ pat) { print i; exit }
+                }
+            }
+        ' "$file" 2>/dev/null || true
+    )"
+    [ -n "$line" ] || continue
+
+    hook_claim_once "$seen_file" "$id	$rel" || continue
+
+    findings="${findings}${rel}:${line} — [${rule}] ${message}
+"
+done <<EOF
+$records
+EOF
+
+[ -n "$findings" ] || exit 0
+
+context="Cratis rule check on the file you just edited (deterministic pattern pass, not a build):
+${findings}
+These are framework contracts from .cratis/ai/rules/general.md. Fix them now rather than at the quality gate."
+
+jq -n --arg ctx "$context" '{
+    systemMessage: "cratis-hooks: rule reminder appended to context",
+    hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: $ctx }
+}'
+exit 0

package/package/corpus/hooks/scripts/cratis-patterns.json

@@ -0,0 +1,84 @@
+{
+    "$comment": [
+        "Deterministic pattern pass for the Cratis PostToolUse hook (cratis-pattern-scan.sh).",
+        "Data, not code: a consuming repository extends or overrides this without touching the script.",
+        "  - drop a cratis-patterns.local.json next to this file to ADD patterns (merged, never replaces)",
+        "  - or point CRATIS_HOOKS_PATTERNS at a replacement file",
+        "  - set \"enabled\": false on a shipped pattern in the local file to silence it (matched by id)",
+        "",
+        "Pattern fields:",
+        "  id                    stable identifier; also the de-duplication key (fires once per file per session)",
+        "  rule                  human reference into .cratis/ai/rules (shown with the reminder)",
+        "  pattern               POSIX ERE, matched line by line",
+        "  paths                 globs the file must match (repo-relative)",
+        "  exclude_paths         globs that veto the match",
+        "  message               the one-line reminder appended to context",
+        "  join_lines            optional; match against N joined lines so a signature can wrap (default 1)",
+        "  within_type_attribute optional; only match inside a type declaration carrying [ThatAttribute]",
+        "  requires_in_file      optional EREs that must ALSO match somewhere in the file",
+        "  absent_in_file        optional EREs that must NOT match anywhere in the file",
+        "  enabled               optional; default true",
+        "",
+        "The C# patterns are application-profile only (.cratis/ai/rules/general.md). They are scoped by the",
+        "\"paths\" globs to Source/**, the application source root general.md documents — not a path",
+        "in Cratis/AI itself, which is a corpus of markdown and JSON with no C# source, so they never",
+        "fire here. A framework-profile repository (Arc, Chronicle, Fundamentals, Components) should",
+        "disable them in its local file; a repository whose application source root is not Source/",
+        "re-scopes the \"paths\" globs there instead."
+    ],
+    "patterns": [
+        {
+            "id": "cratis-automap-call",
+            "rule": "general.md rule 10 [contract]",
+            "pattern": "\\.AutoMap[[:space:]]*\\(",
+            "paths": ["Source/**/*.cs"],
+            "exclude_paths": ["**/obj/**", "**/bin/**", "**/*.g.cs", "**/*.Designer.cs"],
+            "absent_in_file": ["NoAutoMap"],
+            "message": "AutoMap is on by default in Chronicle — never call `.AutoMap()`. Remove the call and match property names; use `[SetFrom<T>]` or `.Set().To()` only for genuine name differences. `.AutoMap()` is legal only inside a scope previously disabled with `.NoAutoMap()`."
+        },
+        {
+            "id": "cratis-ieventlog-in-handle",
+            "rule": "general.md rule 14 [contract]",
+            "pattern": "Handle[[:space:]]*\\([^)]*IEventLog",
+            "join_lines": 5,
+            "paths": ["Source/**/*.cs"],
+            "exclude_paths": ["**/obj/**", "**/bin/**", "**/*.g.cs"],
+            "message": "Never inject `IEventLog` into `Handle()`. Express appends through the return type — return the event, `IEnumerable<object>`, or `EventForEventSourceId` wrappers for cross-stream appends."
+        },
+        {
+            "id": "cratis-nullable-event-property",
+            "rule": "general.md rule 6 [contract]",
+            "pattern": "[A-Za-z_][A-Za-z0-9_.]*(<[^<>]*>)?\\?[[:space:]]+[A-Za-z_]",
+            "within_type_attribute": "EventType",
+            "paths": ["Source/**/*.cs"],
+            "exclude_paths": ["**/obj/**", "**/bin/**", "**/*.g.cs"],
+            "message": "Avoid nullable properties on an `[EventType]` — Chronicle's analyzer warns on them. Model the optional fact as a separate event, or resolve the nullable command input to a non-null sentinel before constructing the event."
+        },
+        {
+            "id": "cratis-route-on-readmodel",
+            "rule": "general.md rule 12 [contract]",
+            "pattern": "\\[Route[[:space:]]*\\(",
+            "within_type_attribute": "ReadModel",
+            "paths": ["Source/**/*.cs"],
+            "exclude_paths": ["**/obj/**", "**/bin/**", "**/*.g.cs"],
+            "message": "Model-bound query custom paths use `[Path(\"...\")]` (Cratis `PathAttribute`), not ASP.NET `[Route]`. `[Route]` is reserved for controller-based endpoints, which this convention avoids."
+        },
+        {
+            "id": "cratis-controller-base",
+            "rule": "general.md rule 1 [contract]",
+            "pattern": "[:,][[:space:]]*ControllerBase([^A-Za-z0-9_]|$)",
+            "requires_in_file": ["using[[:space:]]+Microsoft\\.AspNetCore\\.Mvc[[:space:]]*;"],
+            "paths": ["Source/**/*.cs"],
+            "exclude_paths": ["**/obj/**", "**/bin/**", "**/*.g.cs"],
+            "message": "Model-bound — no controllers. Commands are `[Command]` records with a public instance `Handle()`; queries are `static` methods on `[ReadModel]` records. Arc generates the HTTP surface."
+        },
+        {
+            "id": "cratis-primereact-dialog-import",
+            "rule": "general.md rule 16 [convention]",
+            "pattern": "from[[:space:]]+['\"]primereact/dialog['\"]",
+            "paths": ["**/*.ts", "**/*.tsx"],
+            "exclude_paths": ["**/node_modules/**", "**/dist/**", "**/wwwroot/**", "**/obj/**", "**/bin/**"],
+            "message": "Never import `Dialog` from `primereact/dialog` — use `CommandDialog` / `Dialog` from `@cratis/components`."
+        }
+    ]
+}

package/package/corpus/hooks/scripts/cratis-quality-gate.sh

@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+# Stop hook — the real quality gate.
+#
+# Looks at what actually changed in the working tree, runs only the gates that change touches,
+# and exits 2 (blocking turn-end, stderr fed back to the model) when one fails. It never edits
+# code: it only builds, tests and lints. If nothing relevant changed it exits immediately and
+# silently, so a documentation- or corpus-only turn costs nothing.
+#
+# Gate commands are data (quality-gates.json), not code — see that file for the schema.
+#
+# Environment:
+#   CRATIS_HOOKS_SKIP_GATE=1     skip the gate entirely
+#   CRATIS_HOOKS_GATE_DRYRUN=1   print the dispatch plan (which gates would run, and why) and exit 0
+#   CRATIS_HOOKS_GATES=<path>    use a different gate configuration file
+set -euo pipefail
+
+# SCRIPTDIR, not a path relative to the caller: shellcheck resolves a plain relative `source=`
+# against the current working directory, and these hooks are linted from wherever CI happens to run.
+# shellcheck source=SCRIPTDIR/hook-lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/hook-lib.sh"
+
+[ "${CRATIS_HOOKS_SKIP_GATE:-0}" = "1" ] && exit 0
+
+input="$(hook_read_stdin)"
+hook_have jq || exit 0
+
+# Never re-enter: Claude Code sets stop_hook_active when the previous Stop hook already
+# blocked and the model is continuing. Blocking again would loop forever.
+if [ -n "$input" ] && [ "$(hook_json "$input" '.stop_hook_active')" = "true" ]; then
+    exit 0
+fi
+
+root="$(hook_repo_root)"
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+config="${CRATIS_HOOKS_GATES:-$here/quality-gates.json}"
+dryrun="${CRATIS_HOOKS_GATE_DRYRUN:-0}"
+
+[ -f "$config" ] || exit 0
+jq -e . "$config" >/dev/null 2>&1 || {
+    printf 'cratis-quality-gate: %s is not valid JSON — gate skipped.\n' "$config" >&2
+    exit 0
+}
+[ "$(jq -r '.enabled // true' "$config")" = "true" ] || exit 0
+
+# ── What changed in the working tree ─────────────────────────────────────────
+git -C "$root" rev-parse --git-dir >/dev/null 2>&1 || exit 0
+changed="$(
+    {
+        git -C "$root" diff --name-only HEAD 2>/dev/null || true
+        git -C "$root" ls-files --others --exclude-standard 2>/dev/null || true
+    } | LC_ALL=C sort -u
+)"
+[ -n "$changed" ] || exit 0
+
+# ── Project discovery ────────────────────────────────────────────────────────
+# A gate names *what kind of project* it builds, never a product's file. The repository's
+# own solution or package is discovered here, so the shipped gates activate unchanged in an
+# application, a framework, or a corpus-only repository. Read lazily: a configuration whose
+# gates all use literal requires.paths never pays for the listing.
+repo_paths=""
+repo_paths_read=0
+repository_paths() {
+    if [ "$repo_paths_read" -eq 0 ]; then
+        repo_paths_read=1
+        repo_paths="$(
+            {
+                git -C "$root" ls-files 2>/dev/null || true
+                git -C "$root" ls-files --others --exclude-standard 2>/dev/null || true
+            } | LC_ALL=C sort -u
+        )"
+    fi
+    printf '%s\n' "$repo_paths"
+}
+
+# Print the repository path a gate should be located by, given newline-separated globs.
+# The globs are tried IN ORDER and the first one with a match wins, so a configuration can
+# state a preference ("a solution at the root, else one anywhere") rather than depending on
+# where a path happens to sort. Prints nothing when nothing matches.
+discover_path() {
+    local g match
+    while IFS= read -r g; do
+        [ -n "$g" ] || continue
+        match="$(repository_paths | hook_glob_first_match "$g" || true)"
+        [ -n "$match" ] && { printf '%s\n' "$match"; return 0; }
+    done <<EOF
+$1
+EOF
+    return 1
+}
+
+gate_count="$(jq -r '.gates | length' "$config")"
+[ "${gate_count:-0}" -gt 0 ] || exit 0
+fail_fast="$(jq -r '.failFast // true' "$config")"
+max_lines="$(jq -r '.maxOutputLines // 60' "$config")"
+
+tmp_root="$(hook_state_dir "$(hook_json "$input" '.session_id')")" || tmp_root="${TMPDIR:-/tmp}"
+log_dir="$tmp_root/gate-logs"
+mkdir -p "$log_dir" 2>/dev/null || log_dir="${TMPDIR:-/tmp}"
+
+# Does any changed path match this gate's globs (and survive its excludes)?
+gate_triggered() {
+    local idx="$1" inc exc p
+    inc="$(jq -r --argjson i "$idx" '.gates[$i].changed // [] | .[]' "$config")"
+    exc="$(jq -r --argjson i "$idx" '.gates[$i].excludeChanged // [] | .[]' "$config")"
+    [ -n "$inc" ] || return 1
+    while IFS= read -r p; do
+        [ -n "$p" ] || continue
+        printf '%s\n' "$inc" | hook_glob_match "$p" || continue
+        if [ -n "$exc" ]; then
+            printf '%s\n' "$exc" | hook_glob_match "$p" && continue
+        fi
+        return 0
+    done <<EOF
+$changed
+EOF
+    return 1
+}
+
+# Report the first unmet requirement, or nothing when the gate can run here.
+gate_unmet() {
+    local idx="$1" c p
+    while IFS= read -r c; do
+        [ -n "$c" ] || continue
+        hook_have "$c" || { printf "command '%s' is not on PATH" "$c"; return 0; }
+    done <<EOF
+$(jq -r --argjson i "$idx" '.gates[$i].requires.commands // [] | .[]' "$config")
+EOF
+    while IFS= read -r p; do
+        [ -n "$p" ] || continue
+        [ -e "$root/$p" ] || { printf "'%s' does not exist in this repository" "$p"; return 0; }
+    done <<EOF
+$(jq -r --argjson i "$idx" '.gates[$i].requires.paths // [] | .[]' "$config")
+EOF
+    return 0
+}
+
+idx=0
+ran=0
+while [ "$idx" -lt "$gate_count" ]; do
+    id="$(jq -r --argjson i "$idx" '.gates[$i].id' "$config")"
+    desc="$(jq -r --argjson i "$idx" '.gates[$i].description // ""' "$config")"
+    wd="$(jq -r --argjson i "$idx" '.gates[$i].workingDirectory // ""' "$config")"
+
+    if ! gate_triggered "$idx"; then
+        [ "$dryrun" = "1" ] && printf 'cratis-quality-gate: SKIP  %-24s (no matching change)\n' "$id" >&2
+        idx=$((idx + 1))
+        continue
+    fi
+
+    # workingDirectoryFrom is discovery AND requirement in one: the gate runs in the directory
+    # of the discovered project file, and a repository holding no such file is a NO-OP.
+    if [ -z "$wd" ]; then
+        wd_globs="$(jq -r --argjson i "$idx" '.gates[$i].workingDirectoryFrom // [] | .[]' "$config")"
+        if [ -n "$wd_globs" ]; then
+            wd_path="$(discover_path "$wd_globs" || true)"
+            if [ -z "$wd_path" ]; then
+                printf 'cratis-quality-gate: NO-OP %-24s — no repository path matches %s. Configure it in %s.\n' \
+                    "$id" "$(printf '%s' "$wd_globs" | tr '\n' ' ')" "${config#"$root"/}" >&2
+                idx=$((idx + 1))
+                continue
+            fi
+            wd="$(dirname "$wd_path")"
+        fi
+    fi
+    [ -n "$wd" ] || wd="."
+
+    unmet="$(gate_unmet "$idx")"
+    if [ -n "$unmet" ]; then
+        printf 'cratis-quality-gate: NO-OP %-24s — %s. Configure it in %s.\n' \
+            "$id" "$unmet" "${config#"$root"/}" >&2
+        idx=$((idx + 1))
+        continue
+    fi
+
+    cmd=()
+    while IFS= read -r arg; do
+        cmd+=("$arg")
+    done <<EOF
+$(jq -r --argjson i "$idx" '.gates[$i].command // [] | .[]' "$config")
+EOF
+    if [ "${#cmd[@]}" -eq 0 ]; then
+        idx=$((idx + 1))
+        continue
+    fi
+
+    if [ "$dryrun" = "1" ]; then
+        printf 'cratis-quality-gate: RUN   %-24s %s\n                            $ %s   (cwd: %s)\n' \
+            "$id" "$desc" "${cmd[*]}" "$wd" >&2
+        idx=$((idx + 1))
+        ran=$((ran + 1))
+        continue
+    fi
+
+    log="$log_dir/$id.log"
+    rc=0
+    (cd "$root/$wd" && "${cmd[@]}") >"$log" 2>&1 || rc=$?
+    ran=$((ran + 1))
+
+    if [ "$rc" -ne 0 ]; then
+        {
+            printf 'QUALITY GATE FAILED: %s (exit %s)\n' "$id" "$rc"
+            printf '  %s\n' "$desc"
+            printf '  $ %s   (cwd: %s)\n\n' "${cmd[*]}" "$wd"
+            printf -- '--- last %s lines ---\n' "$max_lines"
+            tail -n "$max_lines" "$log" 2>/dev/null || true
+            printf -- '--- end ---\n\n'
+            printf 'Fix the failure and re-run the gate. Never change code merely to make a gate pass,\n'
+            printf 'and never suppress warnings. Full log: %s\n' "$log"
+        } >&2
+        [ "$fail_fast" = "true" ] && exit 2
+        failed=1
+    fi
+
+    idx=$((idx + 1))
+done
+
+[ "${failed:-0}" -eq 0 ] || exit 2
+[ "$dryrun" = "1" ] && printf 'cratis-quality-gate: dry run complete — %s gate(s) would run.\n' "$ran" >&2
+exit 0

package/package/corpus/hooks/scripts/hook-lib.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# Shared helpers for the Cratis enforcement hooks.
+#
+# Sourced by cratis-guard-writes.sh, cratis-pattern-scan.sh and cratis-quality-gate.sh.
+# Portable: bash 3.2 (macOS system bash) and up, BSD + GNU userland. No GNU-only flags,
+# no `mapfile`/`readarray`, no associative arrays, no `eval`.
+set -euo pipefail
+
+# ── Environment ───────────────────────────────────────────────────────────────
+
+# Root of the repository the hook is running for.
+hook_repo_root() {
+    local d="${CLAUDE_PROJECT_DIR:-}"
+    if [ -n "$d" ] && [ -d "$d" ]; then
+        (cd "$d" && pwd)
+        return 0
+    fi
+    (cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)
+}
+
+# True when the named command is on PATH.
+hook_have() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+# Read all of stdin. Never fails on an empty pipe.
+hook_read_stdin() {
+    cat 2>/dev/null || true
+}
+
+# Extract a single scalar from a JSON document on $1 using the jq path in $2.
+# Prints the empty string when jq is absent, the JSON is malformed, or the path is null.
+hook_json() {
+    local json="$1" path="$2"
+    hook_have jq || return 0
+    printf '%s' "$json" | jq -r "$path // empty" 2>/dev/null || true
+}
+
+# ── Paths ─────────────────────────────────────────────────────────────────────
+
+# Absolutize $1 against $2 (a directory), leaving already-absolute paths untouched.
+hook_abspath() {
+    local p="$1" base="${2:-$PWD}"
+    case "$p" in
+        /*) printf '%s\n' "$p" ;;
+        *) printf '%s\n' "${base%/}/$p" ;;
+    esac
+}
+
+# Make $1 relative to the root $2 when it lives underneath it.
+hook_relpath() {
+    local p="$1" r="${2%/}"
+    case "$p" in
+        "$r"/*) printf '%s\n' "${p#"$r"/}" ;;
+        *) printf '%s\n' "$p" ;;
+    esac
+}
+
+# Glob dialect (gitignore/minimatch-like, matched against a repo-relative path):
+#   **/   any number of leading directories (including none)
+#   **    any characters, directory separators included
+#   *     any characters except /
+#   ?     one character except /
+#
+# The conversion is an awk source fragment shared by both matchers below rather than
+# copied into each, so the two directions cannot drift apart.
+hook_glob_awk_lib='
+        function g2re(g,    out, i, n, c, c2, c3) {
+            out = "^"; n = length(g)
+            for (i = 1; i <= n; i++) {
+                c = substr(g, i, 1)
+                if (c == "*") {
+                    c2 = substr(g, i + 1, 1); c3 = substr(g, i + 2, 1)
+                    if (c2 == "*" && c3 == "/") { out = out "(.*/)?"; i += 2 }
+                    else if (c2 == "*")         { out = out ".*";     i += 1 }
+                    else                        { out = out "[^/]*" }
+                } else if (c == "?") {
+                    out = out "[^/]"
+                } else if (index(".[]()+^$\\{}|", c) > 0) {
+                    out = out "\\" c
+                } else {
+                    out = out c
+                }
+            }
+            return out "$"
+        }
+'
+
+# Does path $1 match any of the newline-separated globs on stdin?
+hook_glob_match() {
+    CRATIS_GLOB_PATH="$1" awk "$hook_glob_awk_lib"'
+        BEGIN { p = ENVIRON["CRATIS_GLOB_PATH"]; found = 0 }
+        { g = $0; sub(/^[ \t]+/, "", g); sub(/[ \t\r]+$/, "", g) }
+        g == "" { next }
+        { if (p ~ g2re(g)) { found = 1; exit } }
+        END { exit(found ? 0 : 1) }
+    '
+}
+
+# The other direction: print the FIRST newline-separated path on stdin matching any of the
+# newline-separated globs in $1, and exit 0. Prints nothing and exits 1 when none matches,
+# or when $1 holds no glob.
+#
+# hook_glob_match answers "does this one path match?" and costs a process per path, which is
+# right for the handful of changed files a hook sees. Discovery asks the mirror question over
+# every path in the repository, so it gets one awk pass instead of thousands of processes.
+hook_glob_first_match() {
+    CRATIS_GLOBS="$1" awk "$hook_glob_awk_lib"'
+        BEGIN {
+            count = 0
+            n = split(ENVIRON["CRATIS_GLOBS"], globs, "\n")
+            for (i = 1; i <= n; i++) {
+                g = globs[i]; sub(/^[ \t]+/, "", g); sub(/[ \t\r]+$/, "", g)
+                if (g != "") res[++count] = g2re(g)
+            }
+            found = 0
+        }
+        count == 0 { exit }
+        { p = $0; sub(/[ \t\r]+$/, "", p) }
+        p == "" { next }
+        {
+            for (i = 1; i <= count; i++) {
+                if (p ~ res[i]) { print p; found = 1; exit }
+            }
+        }
+        END { exit(found ? 0 : 1) }
+    '
+}
+
+# ── Session state ─────────────────────────────────────────────────────────────
+
+# Per-session scratch directory used to de-duplicate reminders. Session ids are
+# sanitized so a hostile value cannot escape the scratch root.
+hook_state_dir() {
+    local session="${1:-nosession}" base
+    session="$(printf '%s' "$session" | tr -c 'A-Za-z0-9._-' '_')"
+    [ -n "$session" ] || session="nosession"
+    base="${TMPDIR:-/tmp}"
+    base="${base%/}/cratis-hooks/$session"
+    mkdir -p "$base" 2>/dev/null || return 1
+    printf '%s\n' "$base"
+}
+
+# Record key $2 in the state file $1. Returns 0 the first time, 1 afterwards.
+hook_claim_once() {
+    local file="$1" key="$2"
+    if [ -f "$file" ] && LC_ALL=C grep -Fqx -- "$key" "$file" 2>/dev/null; then
+        return 1
+    fi
+    printf '%s\n' "$key" >>"$file" 2>/dev/null || true
+    return 0
+}