@yunuseon/kayra 0.10.0 → 0.12.0

package/cli/dist/cli.js

@@ -14,7 +14,7 @@ export const parser = (fleet) => {
         dryRun: option("--dry-run", { description: message `Print the plan instead of running it.` }),
         command: or(
         // On one server
-        or(onServer("up", message `Provision, set up everything, point /etc/hosts at it.`), onServer("provision", message `Create or update the machine (target home: build the image to import).`), onServer("deploy", message `Host setup and every app, no provisioning.`), onServer("setup", message `The host layer only: the playbook for the server's kind.`), onServer("plan", message `What provision and setup would change, changing nothing (OpenTofu plan, Ansible check mode).`), onServer("apps", message `Make the server's apps match server.yml: register each, remove the rest (data kept).`), onServer("hosts", message `Point the domain at a multipass VM in /etc/hosts (sudo).`), command("ssh", object({ name: constant("ssh"), server, remote: multiple(argument(string({ metavar: "COMMAND" }))) }), { brief: message `SSH into the server, or run a command there (after --).` }), onServer("down", message `Destroy the machine.`), onServer("adopt", message `Once, for a server we did not create: add the deploy user as root.`), command("backup", command("test", object({ name: constant("backup test"), server })), {
+        or(onServer("up", message `Provision, set up everything, point /etc/hosts at it.`), onServer("provision", message `Create or update the machine (target home: build the image to import).`), onServer("deploy", message `Host setup and every app, no provisioning.`), onServer("setup", message `The host layer only: the playbook for the server's kind.`), onServer("plan", message `What provision and setup would change, changing nothing (OpenTofu plan, Ansible check mode).`), onServer("verify", message `Whether a platform server works as its users see it: logins, certificates, webhooks, apps, runs, alerts.`), onServer("apps", message `Make the server's apps match server.yml: register each, remove the rest (data kept).`), onServer("hosts", message `Point the domain at a multipass VM in /etc/hosts (sudo).`), command("ssh", object({ name: constant("ssh"), server, remote: multiple(argument(string({ metavar: "COMMAND" }))) }), { brief: message `SSH into the server, or run a command there (after --).` }), onServer("down", message `Destroy the machine.`), onServer("adopt", message `Once, for a server we did not create: add the deploy user as root.`), command("backup", command("test", object({ name: constant("backup test"), server })), {
             brief: message `Restore the latest backup to a scratch dir, check it, delete it.`,
         }), command("app", or(command("check", object({ name: constant("app check"), dir: optional(argument(string({ metavar: "DIR" }))) }), {
             brief: message `In an app's repository: what the platform checks at deploy (app.yml, images, compose policy). No fleet needed.`,

package/cli/dist/commands/server.js

@@ -148,7 +148,13 @@ export const hosts = (engine, server) => ok(server.target === "multipass"
     ]
     : [{ kind: "note", text: `hosts: ${server.target} uses real DNS, nothing to do.` }]);
 const sequence = (plans) => map(all(plans), (each) => each.flat());
-export const deploy = (engine, server) => sequence([setup(engine, server), apps(engine, server)]);
+/** Whether a platform server works as its users see it (scripts/local/verify.sh); other kinds have nothing to check yet. */
+const verifyStep = (engine, server) => run(["bash", script(engine, "verify.sh"), server.name], fleetEnv(engine));
+export const verify = (engine, server) => server.kind === "platform"
+    ? ok([verifyStep(engine, server)])
+    : err(`'${server.name}' is of kind ${server.kind}: kayra verify checks platform servers only.`);
+/** Host setup, then the apps; a platform server is verified at the end, so a deploy that leaves it broken fails. */
+export const deploy = (engine, server) => map(sequence([setup(engine, server), apps(engine, server)]), (plan) => server.kind === "platform" ? [...plan, verifyStep(engine, server)] : plan);
 export const up = (engine, server) => sequence([provision(engine, server), deploy(engine, server), hosts(engine, server)]);
 export const down = (engine, server) => server.terraform
     ? ok([

package/cli/dist/fleet.js

@@ -39,8 +39,12 @@ const vault = (descriptor) => {
         ? map(absolutePath(file), (path) => ({ kind: "file", file: vaultPasswordFile(path) }))
         : err("vault_password_file must be a path");
 };
-/** Apps live in their own repo: the builder clones it over HTTPS, and the app root stays inside it. */
-const app = (value) => {
+/**
+ * Apps live in their own repo: the builder clones it over HTTPS, and the app
+ * root stays inside it. A multipass server, a test machine by definition, may
+ * clone over plain HTTP too: the upgrade lab serves its fixture app that way.
+ */
+const app = (target) => (value) => {
     const entry = mapping(value);
     if (entry === undefined)
         return err("an app must be a mapping");
@@ -48,8 +52,9 @@ const app = (value) => {
     if (!name.ok)
         return name;
     const repo = entry["repo"];
-    if (typeof repo !== "string" || !repo.startsWith("https://"))
-        return err(`app ${name.value}: repo must be an https:// URL`);
+    const schemes = target === "multipass" ? ["https://", "http://"] : ["https://"];
+    if (typeof repo !== "string" || !schemes.some((scheme) => repo.startsWith(scheme)))
+        return err(`app ${name.value}: repo must be an https:// URL${target === "multipass" ? " (or http:// on multipass)" : ""}`);
     const path = entry["path"] ?? ".";
     if (typeof path !== "string" || `/${path}/`.includes("/../"))
         return err(`app ${name.value}: path must stay inside its repo`);
@@ -98,7 +103,7 @@ export const parseServer = (files) => {
         return err("apps must be a list");
     if (kind.value !== "platform" && declaredApps.length > 0)
         return err("apps run on platform servers only");
-    const apps = all(declaredApps.map(app));
+    const apps = all(declaredApps.map(app(target.value)));
     if (!apps.ok)
         return apps;
     const shape = checkShape("server.yml", descriptor.value, serverSchema);

package/cli/dist/main.js

@@ -38,6 +38,8 @@ const onServer = (on, target, command) => {
             return server.setup(on, target);
         case "plan":
             return server.preview(on, target);
+        case "verify":
+            return server.verify(on, target);
         case "apps":
             return server.apps(on, target);
         case "hosts":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunuseon/kayra",
-  "version": "0.10.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

package/scripts/local/verify.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# =============================================================================
+# verify.sh <server> — is a platform server working, as its users see it?
+# Run by `kayra verify` and at the end of `kayra deploy` / `kayra up`.
+#
+# From here, the way the world reaches it (each name pinned to the server's
+# address, so neither DNS nor /etc/hosts has to be in place yet):
+#   - auth.<domain> answers; the platform's own pages (hosts.conf) send a
+#     browser to the login, not a 403 from rules Authelia never loaded
+#   - every certificate is a real one (Let's Encrypt or mkcert), never
+#     Traefik's default
+#   - an unsigned webhook is refused; every app hostname answers, not 5xx
+# On the server (one SSH call):
+#   - every app in server.yml is registered, and nothing else
+#   - every app's containers run, none unhealthy; its last run did not fail
+#   - every platform container runs, none unhealthy; no alert is open
+#
+# Certificates and routes can lag a fresh deploy (ACME, DNS-01's minute), so
+# the probes retry for VERIFY_WAIT seconds (default 150) before failing.
+# Written for macOS's bash 3.2 too.
+# =============================================================================
+set -euo pipefail
+
+KAYRA_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+FLEET_ROOT="${FLEET_ROOT:?the directory of the fleet (servers/), set by kayra}"
+name="${1:?Usage: verify.sh <server>}"
+dir="${FLEET_ROOT}/servers/${name}"
+wait="${VERIFY_WAIT:-150}"
+failed=0
+
+fail() { echo "✗ $*"; failed=1; }
+pass() { echo "✓ $*"; }
+
+domain="$(yq -r '.domain' "${dir}/server.yml")"
+inventory="${dir}/inventory.ini"
+[ -f "$inventory" ] || { fail "no inventory for ${name}: provision it first"; exit 1; }
+field() { awk -v key="$1" '{for (i = 1; i <= NF; i++) if (index($i, key "=") == 1) {print substr($i, length(key) + 2); exit}}' "$inventory"; }
+address="$(field ansible_host)"
+port="$(field ansible_port)"
+user="$(field ansible_user)"
+key="$(field ansible_ssh_private_key_file)"
+registered_wanted="$(yq -r '.apps // [] | .[].name' "${dir}/server.yml")"
+
+# ── From outside ────────────────────────────────────────────────────────────
+# "<status> <redirect> <verify result> <issuer CN>" for a host, pinned to the server.
+probe() {
+    local host="$1" method="${2:-GET}" result issuer
+    result="$(curl -s -o /dev/null -m 10 -X "$method" -H 'Accept: text/html' \
+        --resolve "${host}:443:${address}" -w '%{http_code} %{redirect_url} %{ssl_verify_result}' \
+        "https://${host}/" 2>/dev/null || echo "000 - -")"
+    issuer="$(openssl s_client -connect "${address}:443" -servername "$host" </dev/null 2>/dev/null \
+        | openssl x509 -noout -issuer 2>/dev/null | sed -n 's/.*CN *= *//p')"
+    echo "${result} ${issuer:-none}"
+}
+
+# Probes until `test` accepts the answer or VERIFY_WAIT runs out; prints the last answer.
+until_ok() {
+    local host="$1" method="$2" test="$3" deadline answer
+    deadline=$(( $(date +%s) + wait ))
+    while :; do
+        answer="$(probe "$host" "$method")"
+        if "$test" "$answer"; then echo "$answer"; return 0; fi
+        [ "$(date +%s)" -lt "$deadline" ] || { echo "$answer"; return 1; }
+        sleep 10
+    done
+}
+
+real_cert() { case "$1" in *"TRAEFIK DEFAULT CERT"|*" none") return 1 ;; esac; [ "$(cut -d' ' -f3 <<< "$1")" = 0 ]; }
+answers() { real_cert "$1" && [ "$(cut -d' ' -f1 <<< "$1")" = 200 ]; }
+to_login() { real_cert "$1" && [ "$(cut -d' ' -f1 <<< "$1")" = 302 ] && case "$(cut -d' ' -f2 <<< "$1")" in "https://auth.${domain}/"*) return 0 ;; esac; return 1; }
+not_5xx() { real_cert "$1" && case "$(cut -d' ' -f1 <<< "$1")" in 000|5*) return 1 ;; esac; }
+refused() { real_cert "$1" && [ "$(cut -d' ' -f1 <<< "$1")" = 401 ]; }
+
+describe() { echo "HTTP $(cut -d' ' -f1 <<< "$1"), certificate by $(cut -d' ' -f4- <<< "$1") (verify $(cut -d' ' -f3 <<< "$1"))"; }
+
+check() {
+    local label="$1" host="$2" method="$3" test="$4" answer
+    if answer="$(until_ok "$host" "$method" "$test")"; then pass "$label"; else fail "${label}: $(describe "$answer")"; fi
+}
+
+check "auth.${domain} answers" "auth.${domain}" GET answers
+while IFS= read -r sub; do
+    [ "$sub" = auth ] || check "${sub}.${domain} sends a browser to the login" "${sub}.${domain}" GET to_login
+done < <(awk '!/^[[:space:]]*(#|$)/ {print $1}' "${KAYRA_ROOT}/hosts.conf")
+
+first_app="$(head -1 <<< "$registered_wanted")"
+if [ -n "$first_app" ]; then
+    hook() {
+        curl -s -o /dev/null -m 10 -X POST --resolve "deploy.${domain}:443:${address}" \
+            -w '%{http_code}' "https://deploy.${domain}/hook/${first_app}" 2>/dev/null || echo 000
+    }
+    code="$(hook)"
+    [ "$code" = 401 ] && pass "an unsigned webhook is refused" || fail "an unsigned webhook to /hook/${first_app}: HTTP ${code}, not 401"
+    while IFS= read -r sub; do
+        [ -z "$sub" ] || check "${sub}.${domain} answers" "${sub}.${domain}" GET not_5xx
+    done < <(bash "${KAYRA_ROOT}/scripts/local/app-manifests.sh" --subdomains "$name")
+fi
+
+# ── On the server ───────────────────────────────────────────────────────────
+facts="$(ssh -p "${port:-22}" -i "$key" -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o LogLevel=ERROR \
+    "${user}@${address}" 'set -e
+cd /opt/platform
+echo "registered $(ls apps 2>/dev/null | sed -n "s/\.json$//p" | sort | tr "\n" " ")"
+echo "alerts $(ls alerts 2>/dev/null | tr "\n" " ")"
+docker compose ps -a --format "{{.Service}}|{{.State}}|{{.Health}}" | sed "s/^/platform /"
+for app in $(ls apps 2>/dev/null | sed -n "s/\.json$//p"); do
+    docker ps -a --filter "label=com.docker.compose.project=$app" --format "{{.Names}}|{{.State}}|{{.Status}}" | sed "s/^/container $app /"
+    last=$(ls runs/$app 2>/dev/null | sort | tail -1)
+    [ -z "$last" ] || echo "run $app $(sed -n "s/.*\"state\":\"\([a-z]*\)\".*/\1/p" runs/$app/$last/meta.json) $last"
+done' 2>&1)" || { fail "the server answers over SSH: ${facts}"; exit 1; }
+
+wanted="$(sort <<< "$registered_wanted" | tr '\n' ' ')"
+have="$(sed -n 's/^registered //p' <<< "$facts")"
+wanted="$(xargs <<< "$wanted")"
+have="$(xargs <<< "$have")"
+[ "$wanted" = "$have" ] && pass "registered: ${have:-no apps}" \
+    || fail "registered: ${have:-nothing}; server.yml says ${wanted:-no apps} (kayra apps ${name})"
+
+alerts="$(sed -n 's/^alerts //p' <<< "$facts" | xargs)"
+[ -z "$alerts" ] && pass "no alert is open" || fail "open alerts: ${alerts}"
+
+bad_platform="$(sed -n 's/^platform //p' <<< "$facts" | awk -F'|' '$2 != "running" || $3 == "unhealthy" || $3 == "starting" {print $1 " " $2 " " $3}')"
+[ -z "$bad_platform" ] && pass "every platform container runs" || fail "platform containers: $(paste -sd',' - <<< "$bad_platform")"
+
+while IFS= read -r app; do
+    [ -n "$app" ] || continue
+    containers="$(sed -n "s/^container ${app} //p" <<< "$facts")"
+    run="$(sed -n "s/^run ${app} //p" <<< "$facts")"
+    # One-shot containers (an init, a migration) exit 0 and stay exited.
+    bad="$(awk -F'|' '$2 != "running" && $3 !~ /^Exited \(0\)/ || $3 ~ /unhealthy|health: starting/ {print $1 " " $3}' <<< "$containers")"
+    # Registered and never run: waiting for its first push, not broken.
+    if [ -z "$containers" ] && [ -z "$run" ]; then pass "${app}: not deployed yet"; continue
+    elif [ -z "$containers" ]; then fail "${app}: no containers"
+    elif [ -n "$bad" ]; then fail "${app}: $(paste -sd',' - <<< "$bad")"
+    else pass "${app}: $(grep -c . <<< "$containers") container(s) up"; fi
+    case "$run" in
+        failure*) fail "${app}: its last run failed ($(cut -d' ' -f2 <<< "$run"): kayra app logs ${name} ${app})" ;;
+        "") pass "${app}: no runs yet" ;;
+        *) pass "${app}: last run $(cut -d' ' -f1 <<< "$run")" ;;
+    esac
+done <<< "$registered_wanted"
+
+exit "$failed"