feedback.sh

#!/usr/bin/env bash
# feedback.sh — cross-repo agent ticket courier. Single write path for the
# feedback/ folder system. See FEEDBACK.md for the contract. UTC only.
set -euo pipefail

VERSION="1.0.0"
SCHEMA="1"

# ---- enums (single source of truth) ----------------------------------------
TYPES="bug feature regression docs question chore"
SEVERITIES="low medium high critical"
STATES="open acknowledged resolved rejected duplicate"

# ---- small helpers ----------------------------------------------------------
die()  { printf 'feedback: %s\n' "$*" >&2; exit 1; }
now()  { date -u +%Y-%m-%dT%H:%M:%SZ; }
today(){ date -u +%Y-%m-%d; }
in_list() { local x="$1"; shift; for v in $*; do [ "$v" = "$x" ] && return 0; done; return 1; }

repo_root() { git rev-parse --show-toplevel 2>/dev/null || die "not inside a git repo"; }

slugify() {
  printf '%s' "$1" | tr '[:upper:]' '[:lower:]' \
    | sed -e 's/[^a-z0-9]\{1,\}/-/g' -e 's/^-//' -e 's/-$//' | cut -c1-60
}

normalize_remote() { # url -> owner/repo
  local u="${1%.git}"
  u="${u#git@github.com:}"; u="${u#https://github.com/}"; u="${u#ssh://git@github.com/}"
  printf '%s' "$u"
}

gen_id() { printf 'fb-%s-%s' "$(date -u +%Y%m%d)" "$(head -c3 /dev/urandom | od -An -tx1 | tr -d ' \n')"; }

# Read a frontmatter key (handles colons in the value; restricted to the block).
fm_get() { # file key
  awk -v k="$2" '
    NR==1 && $0=="---"{infm=1; next}
    infm && $0=="---"{exit}
    infm {
      if (index($0,k": ")==1) { print substr($0,length(k)+3); exit }
      if ($0==k":")           { print ""; exit }
    }' "$1"
}

# Set/replace a frontmatter key in place (only within the block).
fm_set() { # file key value
  local tmp; tmp="$(mktemp)"
  awk -v k="$2" -v v="$3" '
    NR==1 && $0=="---"{infm=1; print; next}
    infm && $0=="---"{
      if(!done){ print k": "v; done=1 }
      infm=0; print; next
    }
    infm && (index($0,k": ")==1 || $0==k":") { print k": "v; done=1; next }
    {print}
  ' "$1" >"$tmp" && mv "$tmp" "$1"
}

log() { # repo-root message
  printf '%s\t%s\n' "$(now)" "$2" >> "$1/feedback/.log"
}

valid_transition() { # from to
  case "$1" in
    open)         in_list "$2" acknowledged rejected duplicate ;;
    acknowledged) in_list "$2" resolved rejected duplicate ;;
    *)            return 1 ;;  # resolved/rejected/duplicate are terminal
  esac
}

find_ticket() { # id -> path (searches whole feedback tree)
  local root; root="$(repo_root)"
  grep -rl "^id: $1$" "$root/feedback" 2>/dev/null | head -n1
}

# ---- commands ---------------------------------------------------------------
cmd_file() {
  local target="" type="bug" sev="medium" title="" sref="" spath="" maint="" agent="claude-code"
  while [ $# -gt 0 ]; do case "$1" in
    --target)     target="$2"; shift 2;;
    --type)       type="$2";   shift 2;;
    --severity)   sev="$2";    shift 2;;
    --title)      title="$2";  shift 2;;
    --source-ref) sref="$2";   shift 2;;
    --path)       spath="$2";  shift 2;;
    --maintainer) maint="$2";  shift 2;;
    --agent)      agent="$2";  shift 2;;
    *) die "file: unknown arg '$1'";;
  esac; done

  [ -n "$target" ] || die "file: --target owner/repo required"
  [ -n "$title" ]  || die "file: --title required"
  in_list "$type" $TYPES        || die "file: bad --type '$type' (one of: $TYPES)"
  in_list "$sev"  $SEVERITIES   || die "file: bad --severity '$sev' (one of: $SEVERITIES)"
  case "$target" in */*) :;; *) die "file: --target must be owner/repo";; esac

  local root src tdir id created fname slug trepo
  root="$(repo_root)"
  src="$(normalize_remote "$(git config --get remote.origin.url 2>/dev/null || echo unknown/unknown)")"
  [ -z "$sref" ] && sref="$(git rev-parse --short HEAD 2>/dev/null || echo '')"
  trepo="${target#*/}"
  id="$(gen_id)"; created="$(now)"; slug="$(slugify "$title")"
  tdir="$root/feedback/outbox/${target}"
  fname="$tdir/$(today)--${trepo}--${type}--${slug}.md"
  mkdir -p "$tdir"

  cat >"$fname" <<EOF
---
id: $id
schema: $SCHEMA
type: $type
severity: $sev
status: open
title: $title
source_repo: $src
source_agent: $agent
source_ref: $sref
source_path: $spath
target_repo: $target
target_maintainer: $maint
created: $created
updated: $created
github_issue:
related:
---

## Summary
$title

## Context / repro
<!-- where this surfaced; commands, inputs, observed behavior -->

## Expected
<!-- what should happen instead -->

## Proposed fix
<!-- optional: the change you'd suggest -->

## Acceptance criteria
- [ ] <!-- concrete, checkable outcome -->
- [ ] <!-- second outcome if needed -->
EOF

  log "$root" "file $id $type/$sev -> $target ($fname)"
  printf '%s\n' "$fname"
}

cmd_route() {
  local via="gh" only="" into=""
  while [ $# -gt 0 ]; do case "$1" in
    --via)    via="$2";  shift 2;;
    --target) only="$2"; shift 2;;
    --into)   into="$2"; shift 2;;
    *) die "route: unknown arg '$1'";;
  esac; done
  in_list "$via" gh local || die "route: --via must be gh or local"

  local root; root="$(repo_root)"
  [ -d "$root/feedback/outbox" ] || { echo "route: nothing to route"; return 0; }

  local f t status routed=0
  while IFS= read -r f; do
    [ -n "$f" ] || continue
    t="$(fm_get "$f" target_repo)"
    [ -n "$only" ] && [ "$t" != "$only" ] && continue
    status="$(fm_get "$f" status)"
    [ "$status" = "open" ] || continue

    if [ "$via" = "gh" ]; then
      command -v gh >/dev/null || die "route: gh not installed (use --via local)"
      local title type sev src url
      title="$(fm_get "$f" title)"; type="$(fm_get "$f" type)"
      sev="$(fm_get "$f" severity)"; src="$(fm_get "$f" source_repo)"
      url="$(gh issue create --repo "$t" --title "$title" --body-file "$f" \
              --label "feedback" --label "type/$type" --label "severity/$sev" \
              --label "source/$src" 2>/dev/null)" || die "route: gh issue create failed for $t"
      fm_set "$f" github_issue "$url"
      fm_set "$f" status acknowledged
      fm_set "$f" updated "$(now)"
      log "$root" "route gh $(fm_get "$f" id) -> $url"
      echo "routed (gh): $(fm_get "$f" id) -> $url"
    else
      local tpath dest
      tpath="${into:-$root/../${t#*/}}"
      [ -d "$tpath/.git" ] || die "route: target checkout not found at '$tpath' (use --into PATH)"
      dest="$tpath/feedback/inbox"; mkdir -p "$dest"
      cp "$f" "$dest/$(basename "$f")"
      fm_set "$f" status acknowledged
      fm_set "$f" updated "$(now)"
      log "$root" "route local $(fm_get "$f" id) -> $dest"
      echo "routed (local): $(fm_get "$f" id) -> $dest"
    fi
    routed=$((routed+1))
  done < <(find "$root/feedback/outbox" -type f -name '*.md' 2>/dev/null | sort)
  echo "routed $routed ticket(s)"
}

cmd_list() {
  local scope="" want=""
  while [ $# -gt 0 ]; do case "$1" in
    --inbox)  scope="inbox";  shift;;
    --outbox) scope="outbox"; shift;;
    --status) want="$2";      shift 2;;
    *) die "list: unknown arg '$1'";;
  esac; done

  local root base f st; root="$(repo_root)"
  base="$root/feedback"; [ -n "$scope" ] && base="$base/$scope"
  [ -d "$base" ] || { echo "(no tickets)"; return 0; }
  printf '%-22s %-9s %-7s %-9s %s\n' "ID" "TYPE" "SEV" "STATUS" "TITLE -> TARGET"
  while IFS= read -r f; do
    st="$(fm_get "$f" status)"
    [ -n "$want" ] && [ "$st" != "$want" ] && continue
    printf '%-22s %-9s %-7s %-9s %s -> %s\n' \
      "$(fm_get "$f" id)" "$(fm_get "$f" type)" "$(fm_get "$f" severity)" \
      "$st" "$(fm_get "$f" title)" "$(fm_get "$f" target_repo)"
  done < <(find "$base" -type f -name '*.md' 2>/dev/null | sort)
}

cmd_resolve() {
  [ $# -ge 1 ] || die "resolve: <id> required"
  local id="$1"; shift
  local to="" note=""
  while [ $# -gt 0 ]; do case "$1" in
    --status) to="$2";   shift 2;;
    --note)   note="$2"; shift 2;;
    *) die "resolve: unknown arg '$1'";;
  esac; done
  [ -n "$to" ] || die "resolve: --status required"
  in_list "$to" $STATES || die "resolve: bad --status '$to'"

  local f from root; f="$(find_ticket "$id")"
  [ -n "$f" ] || die "resolve: ticket '$id' not found"
  from="$(fm_get "$f" status)"
  valid_transition "$from" "$to" || die "resolve: illegal transition $from -> $to"

  fm_set "$f" status "$to"
  fm_set "$f" updated "$(now)"
  root="$(repo_root)"
  log "$root" "resolve $id $from -> $to${note:+ ($note)}"
  echo "$id: $from -> $to"
}

cmd_validate() {
  local root f errs=0; root="$(repo_root)"
  [ -d "$root/feedback" ] || { echo "validate: no feedback/ dir — ok"; return 0; }
  while IFS= read -r f; do
    head -n1 "$f" | grep -qx -- '---' || { echo "ERR $f: missing frontmatter"; errs=$((errs+1)); continue; }
    local k v
    for k in id schema type severity status title source_repo target_repo created updated; do
      v="$(fm_get "$f" "$k")"
      [ -n "$v" ] || { echo "ERR $f: empty required key '$k'"; errs=$((errs+1)); }
    done
    in_list "$(fm_get "$f" type)"     $TYPES      || { echo "ERR $f: bad type";     errs=$((errs+1)); }
    in_list "$(fm_get "$f" severity)" $SEVERITIES || { echo "ERR $f: bad severity"; errs=$((errs+1)); }
    in_list "$(fm_get "$f" status)"   $STATES     || { echo "ERR $f: bad status";   errs=$((errs+1)); }
    for k in created updated; do
      case "$(fm_get "$f" "$k")" in *Z) :;; *) echo "ERR $f: '$k' not UTC (...Z)"; errs=$((errs+1));; esac
    done
  done < <(find "$root/feedback" -type f -name '*.md' 2>/dev/null)
  [ "$errs" -eq 0 ] && { echo "validate: ok"; return 0; }
  echo "validate: $errs error(s)"; return 1
}

cmd_help() {
  cat <<EOF
feedback.sh v$VERSION — cross-repo agent ticket courier (single write path)

  file    --target owner/repo --type T --severity S --title "..."
          [--source-ref SHA] [--path file:line] [--maintainer name] [--agent name]
  route   [--via gh|local] [--target owner/repo] [--into PATH]
  list    [--inbox|--outbox] [--status STATE]
  resolve <id> --status resolved|rejected|duplicate [--note "..."]
  validate
  help

  types:      $TYPES
  severities: $SEVERITIES
  states:     $STATES
EOF
}

# ---- dispatch ---------------------------------------------------------------
[ $# -ge 1 ] || { cmd_help; exit 1; }
sub="$1"; shift
case "$sub" in
  file)     cmd_file "$@";;
  route)    cmd_route "$@";;
  list)     cmd_list "$@";;
  resolve)  cmd_resolve "$@";;
  validate) cmd_validate "$@";;
  help|-h|--help) cmd_help;;
  *) die "unknown command '$sub' (try: help)";;
esac