@yunuseon/kayra 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunuseon/kayra",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "A self-hosted app platform and the CLI that runs it: Traefik, Authelia, a registry, rootless BuildKit and a small deployer per server, set up with OpenTofu and Ansible.",
   "license": "MIT",
   "author": "Yunus Öztürk",

package/scripts/agent/guard.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# =============================================================================
+# guard.sh — Claude Code's PreToolUse hook on Bash, in kayra and every fleet
+# (.claude/settings.json): an AI agent may build, test and read freely, but a
+# command that changes something real waits for the operator to approve it,
+# in that moment.
+#
+# Reads the hook's JSON on stdin; prints a permissionDecision "ask" with the
+# reason for:
+#   - kayra commands that change a server (up, provision, setup, deploy,
+#     apps, adopt, down, app purge|deploy|rollback, job) unless --dry-run or
+#     the server is a multipass one (its server.yml under the project)
+#   - ansible / ansible-playbook against an inventory, ansible-vault reading
+#     or writing a vault
+#   - merging a PR, API writes (gh api / tea api with PUT, PATCH, DELETE),
+#     deleting or editing a repository, publishing a release or a package
+#   - git push of main or a tag, a force push, deleting a remote branch
+#   - tofu / terraform apply, destroy, import, state changes
+#   - destructive commands over SSH (rm, docker rm/stop/prune/down, systemctl…)
+# Anything else: no output, the normal permission flow.
+#
+# It reads the command's text, so it stops mistakes and instructions smuggled
+# in through files or web pages, not a determined adversary: a script it does
+# not read runs whatever it contains. Cases: ci/tests/guard/run.sh.
+# =============================================================================
+set -uo pipefail
+
+command="$(jq -r '.tool_input.command // empty' 2>/dev/null)"
+[ -n "$command" ] || exit 0
+project="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+ask() {
+    jq -n --arg reason "$1" \
+        '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "ask", permissionDecisionReason: ("guard: " + $reason)}}'
+    exit 0
+}
+has() { grep -qE -- "$1" <<< "$command"; }
+
+# ── kayra changing a server ─────────────────────────────────────────────────
+kayra='(^|[;&|(` ]|/)(kayra|kayra\.js|main\.ts|main\.js)'
+verbs='(up|provision|setup|deploy|apps|adopt|down|hosts|job|app (purge|deploy|rollback))'
+if has "${kayra} +(--[a-z-]+ +)*${verbs}( |$)" && ! has '--dry-run'; then
+    # The server: the word after the verb (after the app subcommand for app …).
+    server="$(grep -oE -- "${kayra} +(--[a-z-]+ +)*${verbs} +[a-z0-9][a-z0-9-]*" <<< "$command" | head -1 | awk '{print $NF}')"
+    target=""
+    [ -z "$server" ] || [ ! -f "${project}/servers/${server}/server.yml" ] \
+        || target="$(sed -n 's/^target: *\([a-z]*\).*/\1/p' "${project}/servers/${server}/server.yml")"
+    [ "$target" = multipass ] || ask "kayra changes ${server:-a server}${target:+ (target ${target})}"
+fi
+
+# ── Ansible and the vaults ──────────────────────────────────────────────────
+has '(^|[;&|( ])ansible-vault +(decrypt|view|edit|encrypt|encrypt_string|rekey|create)( |$)' \
+    && ask "ansible-vault opens or writes a vault"
+has '(^|[;&|( ])ansible(-playbook)? .*(-i|--inventory)[ =]' && ask "ansible runs against an inventory"
+
+# ── The forges ──────────────────────────────────────────────────────────────
+has '(^|[;&|( ])(gh|tea) +(pr|pulls) +merge( |$)' && ask "a pull request is merged"
+has '(^|[;&|( ])(gh|tea) +api .*(-X|--method)[ =]*(PUT|PATCH|DELETE)' && ask "a forge API write"
+has '(^|[;&|( ])gh +repo +(delete|edit|rename|archive)( |$)' && ask "a repository is changed or deleted"
+has '(^|[;&|( ])gh +release +(create|delete|edit|upload)( |$)' && ask "a release is published or changed"
+has '(^|[;&|( ])npm +publish( |$)' && ! has 'npm +publish.*--dry-run' && ask "a package is published"
+
+# ── git push of what others build on ────────────────────────────────────────
+if has '(^|[;&|( ])git +push( |$)'; then
+    has 'git +push.*( |:)(main|master)( |$)' && ask "main is pushed"
+    has 'git +push.*( --tags| --follow-tags| refs/tags/| v[0-9])' && ask "a tag is pushed (a release)"
+    has 'git +push.*( -f( |$)| --force| \+)' && ask "a force push"
+    # A push that names no branch pushes the current one: main, if that is where we are.
+    case "$(git branch --show-current 2>/dev/null)" in
+        main|master) has 'git +push( +-[a-zA-Z-]+)*( +origin)?( *$|[;&|])' && ask "main is pushed (the current branch)" ;;
+    esac
+    has 'git +push.*( --delete| -d( |$)| :[^ ])' && ask "a remote branch or tag is deleted"
+fi
+
+# ── OpenTofu / Terraform ────────────────────────────────────────────────────
+has '(^|[;&|( ])(tofu|terraform) +(-chdir=[^ ]+ +)?(apply|destroy|import|state +(rm|mv|push|replace-provider)|taint|untaint|force-unlock)( |$)' \
+    && ask "OpenTofu changes infrastructure or state"
+
+# ── Destructive commands on a server ────────────────────────────────────────
+if has '(^|[;&|( ])(kayra +ssh|ssh) '; then
+    has '(rm +-|docker +(volume|image|system|container|network) +(rm|prune)|docker +(rm|stop|kill|restart)( |$)|compose +(down|stop|rm|restart|kill)( |$)|systemctl +(stop|restart|disable|mask)|reboot|shutdown|apt(-get)? +(install|remove|purge)|ufw |iptables )' \
+        && ask "a destructive command over SSH"
+fi
+exit 0