@techgoblin/gobstack 0.0.0-stage → 0.4.4-beta.2

package/automations/bugreporter-intake.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# bugreporter-intake.sh — A-01's intake validator (the gate in front of `goblin-bugreporter`, P13).
+#
+#   bash bugreporter-intake.sh <slug> [--reports <dir>] [--cards]
+#
+# A report is a FILE WITH A SCHEMA, not prose in a card body: prose invites the agent to fill
+# the gaps by guessing, and a guess at intake poisons everything downstream. This script does
+# the schema check with line-oriented shell, computes the content-only dedup key, and prints
+# the exact card command.
+#
+# Exit codes: 0 the report passed intake | 1 REFUSED (the gap is named) | 2 could not run.
+#
+# The report is UNTRUSTED INPUT, so nothing reads it into a shell: the card is created by
+# exec'ing an argv array (`run_card`), and the form printed for an operator (`card_cmd`) quotes
+# every value that came out of the report. There is no `eval` on any path. A `symptom:` carrying
+# a backtick, `$(...)` or a quote is text, in the card title and on the printed line alike.
+#
+# An under-specified report is filed, not dropped and not guessed: the refusal command carries
+# NO --assignee, so the dispatcher buckets the card `skipped_unassigned` and it is structurally
+# un-spawnable, while remaining visible on the board to a human.
+set -uo pipefail
+
+SLUG=""
+REPORTS="reports"
+CARDS=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --reports) REPORTS="${2:-}"; shift 2 ;;
+    --cards)   CARDS=1; shift ;;
+    -h|--help) sed -n '2,/^set -/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    -*)
+      printf 'bugreporter-intake: unknown option: %s\n' "$1" >&2; exit 2 ;;
+    *) SLUG="$1"; shift ;;
+  esac
+done
+
+[ -n "$SLUG" ] || { printf 'bugreporter-intake: usage: bugreporter-intake.sh <slug> [--reports <dir>]\n' >&2; exit 2; }
+REPORT="$REPORTS/$SLUG/report.yaml"
+[ -f "$REPORT" ] || { printf 'bugreporter-intake: no report at %s\n' "$REPORT" >&2; exit 2; }
+
+field() { sed -n "s/^$1:[[:space:]]*//p" "$REPORT" | head -n 1; }
+# present <key> — the key exists AND carries something: an inline value, or at least one
+# indented item under it (repro_steps is a block list, so a bare `field` read is empty for a
+# perfectly good report - that false refusal was measured and is why this helper exists).
+present() {
+  grep -q "^$1:" "$REPORT" || return 1
+  [ -n "$(field "$1")" ] && return 0
+  awk -v k="$1" '
+    $0 ~ ("^" k ":[[:space:]]*$") { inb = 1; next }
+    inb && /^[^[:space:]]/ { inb = 0 }
+    inb && /^[[:space:]]+[^[:space:]]/ { f = 1 }
+    END { exit !f }
+  ' "$REPORT"
+}
+sha12() {
+  if command -v sha256sum >/dev/null 2>&1; then printf '%s' "$1" | sha256sum | cut -c1-12
+  else printf '%s' "$1" | shasum -a 256 | cut -c1-12; fi
+}
+# normalised = lowercased, whitespace collapsed, trimmed. The dedup key is a function of THIS
+# and nothing else: no date, no run id, no counter - or it dedups nothing.
+normalise() { printf '%s' "$1" | tr 'A-Z' 'a-z' | tr -s '[:space:]' ' ' | sed 's/^ //; s/ $//'; }
+
+REPO=$(field repo)
+SYMPTOM=$(field symptom)
+REVISION=$(field revision)
+KEY=$(field dedup_key)
+
+MISSING=""
+for k in repo symptom expected observed repro_steps revision; do
+  present "$k" || MISSING="$MISSING $k"
+done
+
+WANT_KEY="bug:${REPO}:$(sha12 "$(normalise "$SYMPTOM")")"
+
+TITLE="bug: ${SYMPTOM}"
+
+# shq <word> — the word quoted for a shell, so the printed form can be pasted without executing
+# anything the report says. Single quotes make backticks and `$( )` text; an embedded single
+# quote is written as the four-character `'\''` (close, escaped quote, reopen).
+shq() { local s="$1"; s=${s//\'/\'\\\'\'}; printf "'%s'" "$s"; }
+
+# card_cmd <title-suffix> <idempotency-key> <max-runtime> <max-retries> [assignee-args...]
+# The card command as it is PRINTED for an operator. Every value that came out of the report is
+# shell-quoted; flags and numbers are printed literally, so the line stays greppable. The printed
+# form is what skills/goblin-bugreporter/SKILL.md step 1 tells the operator to run, so it must be
+# paste-safe: the report is the untrusted input this gate exists to validate (G8-1).
+card_cmd() {
+  local title="$TITLE$1" key="$2" rt="$3" rr="$4"; shift 4
+  local a
+  printf 'hermes kanban create %s' "$(shq "$title")"
+  for a in "$@"; do printf ' %s' "$a"; done
+  printf ' --idempotency-key %s --body-file %s --max-runtime %s --max-retries %s\n' \
+    "$(shq "$key")" "$(shq "$REPORT")" "$rt" "$rr"
+}
+
+# run_card <title-suffix> <idempotency-key> <max-runtime> <max-retries> [assignee-args...]
+# The same card as an ARGV ARRAY: no `eval`, no command string, so the title reaches the board as
+# ONE argument whatever it contains. Never build a shell command out of file content (G8-1).
+run_card() {
+  local title="$TITLE$1" key="$2" rt="$3" rr="$4"; shift 4
+  hermes kanban create "$title" "$@" --idempotency-key "$key" --body-file "$REPORT" \
+    --max-runtime "$rt" --max-retries "$rr"
+}
+
+if [ -n "$MISSING" ]; then
+  printf 'bugreporter-intake: REFUSED - %s carries no value for:%s\n' "$REPORT" "$MISSING"
+  printf '# the card is created WITHOUT --assignee, so no agent can be spawned on it\n'
+  card_cmd " (incomplete intake)" "${KEY:-incomplete:$SLUG}" 600 0
+  exit 1
+fi
+
+if [ -n "$KEY" ] && [ "$KEY" != "$WANT_KEY" ]; then
+  printf 'bugreporter-intake: REFUSED - the recorded dedup_key is not the content key\n'
+  printf '  recorded   %s\n  recomputed %s\n' "$KEY" "$WANT_KEY"
+  printf '  a key derived from a date, a run id or a counter dedups nothing\n'
+  card_cmd " (bad key)" "$WANT_KEY" 600 0
+  exit 1
+fi
+
+# The false-positive guard: a reproduction must name a revision that exists. A report with an
+# unverifiable `revision:` is a refusal, not a card.
+if [ -d "$REPO" ]; then
+  if ! ( cd "$REPO" && git rev-parse --verify --quiet "$REVISION^{commit}" >/dev/null 2>&1 ); then
+    printf 'bugreporter-intake: REFUSED - revision "%s" does not resolve in %s\n' "$REVISION" "$REPO"
+    card_cmd " (unresolvable revision)" "$WANT_KEY" 600 0
+    exit 1
+  fi
+else
+  printf '# note: %s is not a local directory - the revision gate is unexercised here\n' "$REPO" >&2
+fi
+
+if [ "$CARDS" -eq 0 ]; then
+  card_cmd "" "$WANT_KEY" 1800 1 --assignee researcher --skill goblin-bugreporter
+  exit 0
+fi
+if ! command -v hermes >/dev/null 2>&1; then
+  printf 'bugreporter-intake: hermes is not on PATH - the command is printed, no card was created\n' >&2
+  card_cmd "" "$WANT_KEY" 1800 1 --assignee researcher --skill goblin-bugreporter
+  exit 0
+fi
+run_card "" "$WANT_KEY" 1800 1 --assignee researcher --skill goblin-bugreporter >/dev/null 2>&1 \
+  || { printf 'bugreporter-intake: the card was NOT created\n' >&2; exit 1; }
+printf 'bugreporter-intake: card created with key %s\n' "$WANT_KEY"
+exit 0

package/automations/drift-audit.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# drift-audit.sh — A-02's producer, the no-agent half of `goblin-drift-audit` (P14).
+#
+#   bash drift-audit.sh [--root <glob>] [--state <file>] [--dry-run] [--cards] [--limit <n>]
+#
+# It compares a RECORDED CLAIM with an ARTIFACT, never a memory and never a judgement, so its
+# false-positive rate is structurally zero: the comparison is made by this script, which cannot
+# invent a finding.
+#
+#   claim 1: the HANDOFF names a commit that exists here and is an ancestor of HEAD  (HP-05)
+#   claim 2: every installed file still matches its recorded hash                     (IN-02)
+#   artifact: the repo's git state and the files on disk
+#
+# It is deliberately the FIRST automation to turn on: no agent sits inside the producer, so it
+# costs zero tokens when there is nothing to report.
+#
+# Exit codes: 0 clean, or nothing to do | 1 drift found | 2 could not run.
+#
+# Kill switch  <state> carrying `enabled: false` stops it dead, and prints nothing on stdout.
+# Ceiling      `run:` lines in <state> from the last 24 h, capped by --limit (default 5). A
+#              capped run prints one `# capped` line, so "silent because clean" and "silent
+#              because the ceiling was hit" are never confused for each other.
+set -uo pipefail
+
+ROOT_GLOB="${HOME}/projects/*"
+STATE="${GOBLIN_DRIFT_STATE:-${HOME}/.goblin/automations/drift-audit.state}"
+DRY_RUN=0
+CARDS=0
+LIMIT=5
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --root)    ROOT_GLOB="${2:-}"; shift 2 ;;
+    --state)   STATE="${2:-}"; shift 2 ;;
+    --limit)   LIMIT="${2:-}"; shift 2 ;;
+    --dry-run) DRY_RUN=1; shift ;;
+    --cards)   CARDS=1; shift ;;
+    -h|--help) sed -n '2,/^set -/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) printf 'drift-audit: unknown option: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+sha12() {
+  if command -v sha256sum >/dev/null 2>&1; then printf '%s' "$1" | sha256sum | cut -c1-12
+  else printf '%s' "$1" | shasum -a 256 | cut -c1-12; fi
+}
+
+# ---- kill switch -------------------------------------------------------------
+if [ -f "$STATE" ] && grep -q '^enabled:[[:space:]]*false' "$STATE"; then
+  printf 'drift-audit: disabled (enabled: false in %s)\n' "$STATE" >&2
+  exit 0
+fi
+
+# ---- the producer's own ceiling ----------------------------------------------
+TODAY=$(date -u +%F)
+RUNS=0
+if [ -f "$STATE" ]; then
+  RUNS=$(grep -c "^run: $TODAY" "$STATE" 2>/dev/null || true)
+  case "$RUNS" in ''|*[!0-9]*) RUNS=0 ;; esac
+fi
+if [ "$RUNS" -ge "$LIMIT" ]; then
+  printf '# capped: %s of %s runs used today - nothing filed\n' "$RUNS" "$LIMIT"
+  exit 0
+fi
+
+# ---- enumerate targets by glob, never by memory ------------------------------
+TARGETS=0
+SKIPPED=""
+DRIFT=""
+DETAIL=""
+
+for d in $ROOT_GLOB; do
+  [ -d "$d" ] || continue
+  TARGETS=$((TARGETS + 1))
+  if [ ! -f "$d/.goblin/goblin.yaml" ]; then
+    SKIPPED="$SKIPPED $(basename "$d")"
+    continue
+  fi
+  if [ ! -f "$d/.goblin/bin/goblin-verify" ]; then
+    SKIPPED="$SKIPPED $(basename "$d")(no-verifier)"
+    continue
+  fi
+  # --only IN-02,HP-05 rather than a full run: both are builtins that write no runtime state,
+  # so the audit never edits the tree it is auditing (design rule 2 of the honesty section).
+  OUT=$( cd "$d" && bash .goblin/bin/goblin-verify --json --only IN-02,HP-05 2>/dev/null )
+  RC=$?
+  case "$RC" in
+    0|1) ;;
+    *) SKIPPED="$SKIPPED $(basename "$d")(verify-exit-$RC)"; continue ;;
+  esac
+  FAILED=$(printf '%s' "$OUT" | grep -o '"id":"[A-Z][A-Z0-9-]*","status":"FAIL"' | sed 's/"id":"//; s/","status":"FAIL"//')
+  for id in $FAILED; do
+    DRIFT="$DRIFT $d/$id"
+    DETAIL="$DETAIL$d	$id	cd $d && bash .goblin/bin/goblin-verify --only $id
+"
+  done
+done
+
+# ---- print nothing when there is nothing to file -----------------------------
+# A clean run writes nothing either: the ceiling counts the runs that FILED something (the
+# cards it created), never the runs that found nothing - otherwise a quiet week would exhaust
+# the ceiling and silence a real finding.
+if [ -z "$DRIFT" ]; then
+  exit 0
+fi
+
+printf '%s' "$DETAIL"
+printf '# coverage: %s target(s) audited by glob, %s drifting, skipped:%s\n' \
+  "$TARGETS" "$(printf '%s' "$DRIFT" | wc -w | tr -d ' ')" "${SKIPPED:- none}"
+printf '# run: %s of %s today\n' "$((RUNS + 1))" "$LIMIT"
+
+if [ "$DRY_RUN" -eq 0 ]; then
+  [ -d "$(dirname "$STATE")" ] || mkdir -p "$(dirname "$STATE")"
+  printf 'run: %s\n' "$TODAY" >> "$STATE"
+fi
+if [ "$CARDS" -eq 1 ]; then
+  if command -v hermes >/dev/null 2>&1; then
+    printf '%s' "$DETAIL" | while IFS=$'\t' read -r repo id cmd; do
+      [ -n "$id" ] || continue
+      KEY="drift:$(basename "$repo"):$id"
+      BODY=$(mktemp)
+      {
+        printf '# Drift: %s %s\n\n' "$(basename "$repo")" "$id"
+        printf 'The producer compared a recorded claim with an artifact and they disagree.\n\n'
+        printf '    %s\n\n' "$cmd"
+        printf 'Reproduces at %s. Dedup key: %s\n' "$(date -u +%F)" "$KEY"
+        printf 'sha256 of the record: %s\n' "$(sha12 "$repo$id$cmd")"
+      } > "$BODY"
+      hermes kanban create "drift: $(basename "$repo") $id" --assignee architect \
+        --skill goblin-drift-audit --idempotency-key "$KEY" --body-file "$BODY" \
+        --max-runtime 1800 --max-retries 1 >/dev/null 2>&1 \
+        || printf 'drift-audit: could not create the card for %s %s\n' "$(basename "$repo")" "$id" >&2
+      rm -f "$BODY"
+    done
+  else
+    printf 'drift-audit: hermes is not on PATH - the record is printed, no card was created\n' >&2
+  fi
+fi
+exit 1

package/automations/report.schema.tsv

@@ -0,0 +1,10 @@
+key	required	shape
+repo	yes	path or remote of the repository the defect is in
+symptom	yes	one line, observable
+expected	yes	one line
+observed	yes	one line
+repro_steps	yes	ordered list, one item per line, 4-space indented
+revision	yes	a commit that exists in that repository
+dedup_key	yes	bug:<repo>:<sha256(normalised symptom)[:12]> - content only, never a date
+environment	no	platform/version; absent is recorded as unknown, never guessed
+evidence	no	paths to captures; evidence for a human, never harness proof

package/bans/README.md

@@ -0,0 +1,82 @@
+# The ban list — forbidden must fail mechanically
+
+`manifest/bans.tsv` is the table; `bin/goblin-bans` is the engine; this directory holds the
+probes. Dune's rule 2, made a gate: **a ban without a mechanism is a wish.** A ban enters
+`bans.tsv` only with a real command in its `detect` column, or it does not enter at all.
+
+## How a ban is run
+
+```
+.goblin/bin/goblin-bans              # every ban the config's `bans:` list turns on
+.goblin/bin/goblin-bans --only BN-01 # one ban
+.goblin/bin/goblin-bans --list       # the table
+```
+
+A `detect` command runs from the repo root and exits
+
+| exit | meaning |
+|---|---|
+| 0 | the tree is clean |
+| 1 | the ban is violated — the exit code alone is the signal; stdout, when any, names the offending lines |
+| 2 | the check could not run — **fail closed**, never a silent pass |
+| 3 | nothing to check (e.g. no `layers:` declared) — SKIP with that reason |
+
+A ban the config does not name is SKIPPED with that reason; a ban whose `globs` match no file
+is SKIPPED with that reason. An empty or missing table is **exit 2**.
+
+## Narrow exceptions (Dune rule 5)
+
+Two escape hatches ship, and both are filtered **before the exit code is chosen** — a filter
+applied to a probe's stdout afterwards cannot change a verdict, so it would be decorative, and
+every violation inside an exempted path would be a permanent RED with no remedy (that was
+**W5-1**, measured `rc 0` at `72490f0` → `rc 1` at `7fec08f`).
+
+```
+bans_exempt:                 # in .goblin/goblin.yaml — a path prefix, or a whole path
+  - BN-03 src/legacy         # <ban id> <path prefix>: that ban, that path, nothing else
+```
+
+```
+export const a: any = 1;    // BAN-OK(BN-01): the value is narrowed at the boundary
+```
+
+An inline escape clears **one line** for **that ban**; a non-empty reason after the colon is
+required, so `BAN-OK(BN-01)` on its own is not an escape. Path exemption is segment-aligned and
+compared as written: `src` exempts `src/a.ts` and `src/legacy/b.ts`, never `src2/c.ts`, and a
+prefix carrying a trailing slash (`src/legacy/`) strips nothing, so it matches no file and exempts
+nothing - write the prefix without one. Both shipped probes are controlled in
+`tests/t-verify-red.sh` (AA1): the trailing-slash case is the LAYER probe's control (`BN-05`, AA1
+§7-6), and the same rule holds for the ban probe - measured on `BN-01`: `- BN-01 src` PASSes,
+`- BN-01 src/` FAILs, because it exempts nothing.
+
+The engine passes both to the probe through its environment rather than editing stdout:
+
+| variable | meaning |
+|---|---|
+| `GOBLIN_BANS_ID` | the ban being probed — what an inline `BAN-OK(<id>)` must name |
+| `GOBLIN_BANS_EXEMPT` | newline-separated path prefixes this ban exempts |
+
+`bans/grep-ban.sh` and `bans/layer-check.sh` honour both (the layer probe honours the path list
+only — its documented escape is `layers:` or a move, not an inline marker). A project's **own**
+probe that ignores the variables keeps the old behaviour: a violation inside an exempted path
+stays RED. That is deliberate — the failure is **closed**, never open — and it is recorded in
+`docs/LIMITS.md`.
+
+## No npm, no AST
+
+The engine uses `bash`/`grep`/`awk` only — the dependency contract in `docs/CONTRACTS.md`. So
+these are **text probes**, not AST checks: a `: any` inside a string or a comment is reported,
+and `Record<string, any>` (no leading `:`) is missed. The AST-grade form of the same bans needs
+a parser the contract does not allow; that gap is `docs/LIMITS.md` #27, stated rather than
+hidden. A text probe with a known false-positive set is still a gate — it goes red on the move
+it forbids — which is what a ban is for.
+
+## Turning a ban on
+
+```yaml
+bans: [BN-01, BN-02, BN-05]      # the bans this project turns on; an unlisted ban SKIPs
+bans_exempt:                     # narrow, explicit, reviewed (Dune rule 5)
+  - BN-03 src/legacy             # <ban id> <path prefix>
+layers:                          # what BN-05 reads; "<from> <to>"
+  - src/renderer src/main
+```

package/bans/grep-ban.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# grep-ban.sh — a grep-backed ban probe with a fail-closed exit contract.
+#
+#   usage: grep-ban.sh -e <pattern> [-e <pattern> ...] <dir|file> ...
+#
+# Exit: 0 the tree is clean | 1 the ban is violated (offending lines on stdout)
+#       2 the check could not run (no pattern, no path, or grep itself failed).
+# It never exits 0 on a tool error - a ban that silently passes when its tool is missing
+# is worse than advisory (PR-03 / D6).
+#
+# It reads TEXT, with no AST and no comments blanked: a `: any` inside a string or a
+# comment is reported. That limit is stated, not hidden - the AST-grade form needs a
+# parser the no-npm contract (docs/CONTRACTS.md) does not allow (docs/LIMITS.md #27).
+#
+# NARROW, EXPLICIT EXCEPTIONS (Dune rule 5). The engine exports two variables, and the hits are
+# filtered BEFORE the exit code is chosen - a filter applied to stdout after the fact cannot
+# change a verdict and is therefore decorative (W5-1: `bans_exempt:` produced a permanent RED):
+#
+#   GOBLIN_BANS_ID       the ban being probed (BN-01 ...)
+#   GOBLIN_BANS_EXEMPT   newline-separated path prefixes this ban exempts
+#
+# A hit is dropped when its FILE is under an exempt prefix, or when the offending LINE carries
+# the inline escape `// BAN-OK(<id>): <reason>`. Both are segment-aligned and both require the
+# documented form: `src` exempts `src/a.ts` and `src/legacy/b.ts`, never `src2/c.ts`, and a
+# `BAN-OK(<id>)` with no `: <reason>` after it is NOT an escape (it is a wish). When nothing is
+# left the probe exits 0: there is no violation outside the declared exception.
+
+set -uo pipefail
+pats=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -e) [ $# -ge 2 ] || { echo "grep-ban: -e needs a pattern" >&2; exit 2; }
+        pats+=("${2:-}"); shift 2 ;;
+    --) shift; break ;;
+    -*) echo "grep-ban: unknown option $1" >&2; exit 2 ;;
+    *) break ;;
+  esac
+done
+[ "${#pats[@]}" -gt 0 ] || { echo "grep-ban: no pattern given" >&2; exit 2; }
+[ "$#" -gt 0 ] || { echo "grep-ban: no path given" >&2; exit 2; }
+# A declared glob that does not exist on disk is not an error: the engine already turns
+# "no matching files" into a SKIP with a reason before it calls this. Silently dropping a
+# missing path here is what stops one absent sibling (BN-03's `app` beside `src/components`)
+# from failing the ban closed on a tree that is clean.
+paths=()
+for p in "$@"; do [ -e "$p" ] && paths+=("$p"); done
+[ "${#paths[@]}" -gt 0 ] || exit 0
+args=()
+for p in "${pats[@]}"; do args+=(-e "$p"); done
+out=$(grep -rnE "${args[@]}" \
+        --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' --include='*.mjs' \
+        -- "${paths[@]}" 2>&1)
+rc=$?
+
+# The exemption filter. It runs on hits only, so the fail-closed arms below are untouched.
+ban_exempt_filter() {
+  GOBLIN_BANS_EXEMPT="${GOBLIN_BANS_EXEMPT:-}" GOBLIN_BANS_ID="${GOBLIN_BANS_ID:-}" awk '
+    BEGIN {
+      n = 0
+      if (ENVIRON["GOBLIN_BANS_EXEMPT"] != "") n = split(ENVIRON["GOBLIN_BANS_EXEMPT"], ex, "\n")
+      id = ENVIRON["GOBLIN_BANS_ID"]
+      pat = ""
+      if (id != "") pat = "BAN-OK\\(" id "\\)[[:space:]]*:[[:space:]]*[^[:space:]]"
+    }
+    {
+      f = $0; sub(/:.*/, "", f)
+      for (i = 1; i <= n; i++) {
+        p = ex[i]
+        if (p == "") continue
+        if (f == p || index(f, p "/") == 1) next
+      }
+      if (pat != "" && $0 ~ pat) next
+      print
+    }'
+}
+
+case "$rc" in
+  1) exit 0 ;;                              # no match: clean
+  0) out=$(printf '%s\n' "$out" | ban_exempt_filter) ;;   # matches: drop the declared exceptions
+  *) printf '%s\n' "$out" >&2; exit 2 ;;    # grep could not run: fail closed
+esac
+[ -n "$(printf '%s' "$out" | tr -d '[:space:]')" ] || exit 0
+printf '%s\n' "$out"
+exit 1

package/bans/layer-check.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# layer-check.sh — BN-05's detect. The boundary ban Dune actually mechanises.
+#
+# Reads the config's `layers:` list, each item "<from> <to>", and fails when a file under
+# <from> imports across into <to>. The import test is a text probe for an import path that
+# names <to>'s last path segment - so it catches `from '../main/db'` in a renderer, and it
+# does NOT resolve module aliases or dynamic imports. Stated, not hidden (docs/LIMITS.md #27).
+#
+# Exit: 0 clean | 1 a crossing import (lines on stdout) | 2 could not run | 3 no layers declared.
+
+set -uo pipefail
+SELF_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+ROOT=$(cd "$SELF_DIR/../.." && pwd)          # .goblin/bans/ -> repo root
+CONFIG="$ROOT/.goblin/goblin.yaml"
+[ -f "$CONFIG" ] || { echo "layer-check: no $CONFIG" >&2; exit 2; }
+
+layers=$(awk '
+  $0 ~ /^layers:[[:space:]]*$/ { inb = 1; next }
+  inb && /^[^ ]/ { inb = 0 }
+  inb && /^  - / { v = $0; sub(/^  - /, "", v); print v }
+' "$CONFIG")
+[ -n "$layers" ] || { echo "no layers declared in $CONFIG - declare a from/to pair to turn BN-05 on"; exit 3; }
+
+bad=""
+while read -r from to; do
+  [ -n "$from" ] && [ -n "$to" ] || continue
+  [ -d "$ROOT/$from" ] || continue
+  seg=${to##*/}
+  hits=$(cd "$ROOT" && grep -rnE "from[[:space:]]+['\"][^'\"]*${seg}/" \
+           --include='*.ts' --include='*.tsx' --include='*.js' --include='*.jsx' "$from" 2>/dev/null || true)
+  [ -n "$hits" ] && bad="$bad$hits"$'\n'
+done <<EOF
+$layers
+EOF
+
+# A narrow, explicit exception (Dune rule 5) reaches this probe through the same environment the
+# engine gives grep-ban.sh: GOBLIN_BANS_EXEMPT is a newline-separated list of path prefixes, and a
+# hit whose FILE is under one of them does not count. Filtering here, before the exit code, is what
+# makes the exception able to change a verdict (W5-1). BN-05's documented escape is `layers:` or a
+# move, not the inline marker, so no BAN-OK is honoured here. A probe that ignores the variable
+# keeps the old, fail-closed behaviour.
+if [ -n "$bad" ] && [ -n "${GOBLIN_BANS_EXEMPT:-}" ]; then
+  bad=$(GOBLIN_BANS_EXEMPT="$GOBLIN_BANS_EXEMPT" printf '%s' "$bad" | awk '
+    BEGIN { n = split(ENVIRON["GOBLIN_BANS_EXEMPT"], ex, "\n") }
+    {
+      f = $0; sub(/:.*/, "", f)
+      for (i = 1; i <= n; i++) {
+        p = ex[i]
+        if (p == "") continue
+        if (f == p || index(f, p "/") == 1) next
+      }
+      print
+    }')
+fi
+
+if [ -n "$bad" ]; then printf '%s' "$bad"; exit 1; fi
+exit 0

package/bin/goblin

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# goblin — the global CLI dispatcher (W1, PLAN-V1 §2.3 / W1-SPEC §3).
+#
+#   goblin verify [--only <id[,id...]>] [--json] [--list] [--source <path>]
+#   goblin bans   [--only <id[,id...]>] [--list]
+#   goblin audit  [--target <dir>] [--print]
+#   goblin doctor [--platform <p>]      # W4a
+#   goblin emit   --platform <p> [...]  # W4a/W4b
+#   goblin init   [...]                 # W6: the first-run wizard
+#   goblin upgrade [--target .] [...]   # W3
+#   goblin --version
+#
+# Identity: the package is goblin-stack, the command is `goblin`. W1 ships the DISPATCH
+# SHELL only — the node shim and npm packaging are W2, doctor/emit are W4a (exit-2
+# placeholders naming their workstream), upgrade is W3 (same). G3 forbids a runtime
+# rewrite: the engine stays bash, this file only routes and propagates.
+#
+# The four-value verify contract is unchanged and non-negotiable (bin/goblin-verify:5-9):
+#   0  every executed check passed
+#   1  at least one check failed
+#   2  could not run
+#   3  the manifest itself is broken
+# Every subcommand propagates the engine's exit code verbatim; no wrapper translates a
+# 1 into a 0. A placeholder that silently exited 0 would be a green build doing nothing.
+#
+# Root resolution: find_installed_root() at bin/goblin-verify:64-77 is preserved
+# BYTE-FOR-BYTE (walk up from $PWD to .goblin/goblin.yaml; fall back to git toplevel,
+# then $PWD — the D20 nested-repo fix). W1 changes nothing about its logic.
+#
+# No npm, no jq, no yq, no network. bash/awk/sed/grep only.
+
+set -uo pipefail
+
+SELF_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+SRC=$(cd "$SELF_DIR/.." && pwd)
+VERSION=$(cat "$SRC/VERSION" 2>/dev/null || printf 'unknown')
+
+g_err() { printf 'error: %s\n' "$*" >&2; }
+
+usage() {
+  cat <<'USAGE'
+goblin — the goblin-stack command line.
+
+  goblin verify [--only <id[,id...]>] [--json] [--list] [--source <path>]
+  goblin bans   [--only <id[,id...]>] [--list]
+  goblin audit  [--target <dir>] [--print]
+  goblin doctor [--platform <p>] [--target <dir>]
+  goblin emit   --platform <p> --scope project|global [...]
+  goblin init   [--target <dir>] [--class app|A-F] [--dry-run]
+  goblin upgrade [--target .] [--dry-run] [--yes] [--engine-dir <path>]
+  goblin --version
+
+Exit codes (verify): 0 pass | 1 a check failed | 2 could not run | 3 the manifest is
+broken. Every subcommand propagates the engine's exit code verbatim.
+USAGE
+}
+
+# ---- the repo-root locator, preserved byte-for-byte from bin/goblin-verify:64-77 ----
+find_installed_root() {
+  local d="$PWD"
+  while :; do
+    if [ -f "$d/.goblin/goblin.yaml" ]; then printf '%s\n' "$d"; return 0; fi
+    [ "$d" = "/" ] && return 1
+    d=$(dirname "$d")
+  done
+}
+
+# ---- subcommand dispatch ------------------------------------------------------
+CMD="${1:-}"
+[ -n "$CMD" ] || { usage; exit 2; }
+shift
+
+case "$CMD" in
+  verify)
+    # The engine is whatever the per-repo chain resolves (W1 §2.3): --source, vendored,
+    # engine_dir:, GOBLIN_ENGINE_DIR, ~/.goblin/engine — all inside goblin-verify. The
+    # CLI is a pass-through, not a second root-resolution opinion (§3.4).
+    exec bash "$SRC/bin/goblin-verify" "$@"
+    ;;
+  bans)
+    exec bash "$SRC/bin/goblin-bans" "$@"
+    ;;
+  audit)
+    exec bash "$SRC/bin/goblin-audit" "$@"
+    ;;
+  doctor)
+    # W4a: one run, three platforms (the §7 report); the dispatcher routes and
+    # propagates the doctor's 0/1/2 verbatim, like every other subcommand.
+    exec bash "$SRC/bin/goblin-doctor" "$@"
+    ;;
+  emit)
+    # W4a: per-platform emission (the §4 contract); the 0/1/2 exit contract is the
+    # same three values verify's wrapper states, propagated verbatim.
+    exec bash "$SRC/bin/goblin-emit" "$@"
+    ;;
+  init)
+    # W6: the first-run wizard. It drives install/emit/verify and propagates their
+    # exit contract verbatim, like every other subcommand here.
+    exec bash "$SRC/bin/goblin-init" "$@"
+    ;;
+  upgrade)
+    # W3: the migration lives in its own checkout-level script (W3-SPEC §1.1);
+    # the dispatcher routes and propagates the four-value contract verbatim.
+    exec bash "$SRC/bin/goblin-upgrade" "$@"
+    ;;
+  --version|-V|-v)
+    printf '%s\n' "$VERSION"
+    exit 0
+    ;;
+  -h|--help|help)
+    usage
+    exit 0
+    ;;
+  *)
+    g_err "unknown subcommand: $CMD"
+    usage >&2
+    exit 2
+    ;;
+esac