@yunuseon/kayra 0.0.0-stage → 0.4.0

package/ansible/roles/platform/templates/platform.env.j2

@@ -0,0 +1,41 @@
+# =============================================================================
+# {{ platform_dir }}/.env — generated by Ansible, do not edit on the server.
+#
+# Compose reads it automatically in {{ platform_dir }}, and COMPOSE_FILE means
+# `docker compose <cmd>` there needs no -f flags. App-agnostic: app secrets
+# reach Jenkins through bin/jenkins-app-apply, app config lives in
+# {{ apps_dir }}/<app>/.env. The agent secret lives in jenkins-agent.env.
+# =============================================================================
+
+COMPOSE_PROJECT_NAME=platform
+COMPOSE_FILE=docker-compose.yml:docker-compose.ci.yml{{ ':docker-compose.acme-dns.yml' if acme_dns else '' }}
+DOMAIN={{ domain }}
+AUTH_POLICY={{ authelia_policy }}
+APPS_DIR={{ apps_dir }}
+DOCKER_GID={{ ansible_facts.getent_group.docker[1] }}
+# Branch the pipeline library and platform jobs are loaded from.
+PLATFORM_REF={{ platform_ref }}
+PLATFORM_RENOVATE={{ (renovate_repositories | length > 0) | lower }}
+RENOVATE_SCHEDULE={{ renovate_schedule }}
+RENOVATE_PLATFORM={{ renovate_platform }}
+RENOVATE_ENDPOINT={{ renovate_endpoint }}
+RENOVATE_GIT_URL={{ renovate_git_url }}
+RENOVATE_GITHUB_COM_TOKEN={{ renovate_github_com_token }}
+RENOVATE_HOST_RULES={{ renovate_host_rules | to_json if renovate_host_rules else '' }}
+RENOVATE_REPOSITORIES={{ renovate_repositories | to_json }}
+
+# Jenkins
+JENKINS_ADMIN_USER={{ jenkins_admin_user }}
+JENKINS_ADMIN_PASSWORD={{ jenkins_admin_password }}
+
+# Git
+GIT_REMOTE_URL={{ git_remote_url }}
+GITHUB_WEBHOOK_SECRET={{ github_webhook_secret }}
+
+# Authelia SMTP. Empty address falls the notifier back to a file — passkey
+# enrolment then needs the code read off the server. The password is NOT here:
+# it is rendered to authelia/secrets/smtp_password, because an empty
+# AUTHELIA_NOTIFIER_SMTP_PASSWORD would make Authelia think SMTP is configured.
+AUTHELIA_SMTP_ADDRESS={{ authelia_smtp_address }}
+AUTHELIA_SMTP_USERNAME={{ authelia_smtp_username }}
+AUTHELIA_SMTP_SENDER={{ authelia_smtp_sender }}

package/ansible/roles/restic-backup/files/docker-compose.postgres.yml

@@ -0,0 +1,27 @@
+# Managed by Ansible (restic-backup role), where restic_backup.postgres lists
+# databases to dump: copied as docker-compose.yml. Mounts and networks, which
+# differ per server, are in docker-compose.override.yml next to it.
+services:
+  # Hands its static restic binary to the backup container and exits.
+  restic:
+    image: restic/restic:0.19.1
+    entrypoint: ["cp", "/usr/bin/restic", "/opt/restic/restic"]
+    volumes:
+      - restic-bin:/opt/restic
+
+  # Postgres for pg_dump, busybox crond for the schedule. A newer pg_dump
+  # reads older servers, so its major only has to be the highest dumped.
+  backup:
+    image: postgres:18.6-alpine3.24
+    restart: unless-stopped
+    entrypoint: ["crond", "-f", "-d", "8"]
+    depends_on:
+      restic:
+        condition: service_completed_successfully
+    volumes:
+      - restic-bin:/opt/restic:ro
+      - ./config:/etc/backup:ro
+      - ./cron:/etc/crontabs:ro
+
+volumes:
+  restic-bin:

package/ansible/roles/restic-backup/files/docker-compose.yml

@@ -0,0 +1,12 @@
+# Managed by Ansible (restic-backup role). Mounts and networks, which differ
+# per server, are in docker-compose.override.yml next to it. Where databases
+# are dumped first, docker-compose.postgres.yml takes this file's place.
+services:
+  # restic's image with busybox crond for the schedule.
+  backup:
+    image: restic/restic:0.19.1
+    restart: unless-stopped
+    entrypoint: ["crond", "-f", "-d", "8"]
+    volumes:
+      - ./config:/etc/backup:ro
+      - ./cron:/etc/crontabs:ro

package/ansible/roles/restic-backup/handlers/main.yml

@@ -0,0 +1,7 @@
+---
+# busybox crond reads its crontab at start only.
+- name: Restart backup
+  ansible.builtin.command: docker compose restart backup
+  args:
+    chdir: "{{ restic_backup.dir }}"
+  changed_when: true

package/ansible/roles/restic-backup/tasks/main.yml

@@ -0,0 +1,121 @@
+---
+# =============================================================================
+# restic-backup role — backs restic_backup.paths up to a restic repository (a
+# REST server, or SFTP with restic_backup.ssh), nightly, from a compose stack in restic_backup.dir. Postgres databases are
+# dumped first. Nothing outside restic_backup.dir is written, and the paths
+# are mounted read-only.
+#
+# By hand, on the server:
+#   docker compose -f <dir>/docker-compose.yml exec backup /etc/backup/backup.sh
+#   docker compose -f <dir>/docker-compose.yml logs backup
+# Restore test: kayra backup test <server> (starts one, follows its log)
+# =============================================================================
+
+- name: Assert every database has a password
+  ansible.builtin.assert:
+    that:
+      - item.name is match('^[a-z0-9_]+$')
+      - restic_backup_postgres_passwords[item.name] | default('') | length > 0
+    fail_msg: "postgres dump {{ item.name }}: name must be [a-z0-9_], and restic_backup_postgres_passwords.{{ item.name }} set in secrets.yml"
+    quiet: true
+  loop: "{{ restic_backup.postgres | default([]) }}"
+  loop_control:
+    label: "{{ item.name }}"
+
+# Traversable, and log/ readable: the operator follows a restore test over
+# SSH as their own user (kayra backup test). Everything else stays root's.
+- name: Create the backup directory
+  ansible.builtin.file:
+    path: "{{ restic_backup.dir }}"
+    state: directory
+    owner: root
+    group: root
+    mode: "0711"
+
+- name: Create backup directories
+  ansible.builtin.file:
+    path: "{{ restic_backup.dir }}/{{ item }}"
+    state: directory
+    owner: root
+    group: root
+    mode: "{{ '0755' if item == 'log' else '0700' }}"
+  loop: [config, cron, dumps, cache, restore-test, ssh, log]
+
+# With databases to dump, Postgres (pg_dump) with restic copied in; without,
+# restic's own image.
+- name: Copy compose file
+  ansible.builtin.copy:
+    src: "{{ 'docker-compose.postgres.yml' if restic_backup.postgres | default([]) else 'docker-compose.yml' }}"
+    dest: "{{ restic_backup.dir }}/docker-compose.yml"
+    mode: "0600"
+
+- name: Render compose override
+  ansible.builtin.template:
+    src: docker-compose.override.yml.j2
+    dest: "{{ restic_backup.dir }}/docker-compose.override.yml"
+    mode: "0600"
+
+- name: Render environment
+  ansible.builtin.template:
+    src: backup.env.j2
+    dest: "{{ restic_backup.dir }}/config/backup.env"
+    mode: "0600"
+  no_log: true
+
+- name: Render scripts
+  ansible.builtin.template:
+    src: "{{ item }}.j2"
+    dest: "{{ restic_backup.dir }}/config/{{ item }}"
+    mode: "0700"
+  loop: [backup.sh, restore-test.sh]
+
+# On the host, not in the container: the operator's SSH user runs it.
+- name: Render the restore test's follower
+  ansible.builtin.template:
+    src: follow-restore-test.sh.j2
+    dest: "{{ restic_backup.dir }}/follow-restore-test.sh"
+    owner: root
+    group: root
+    mode: "0755"
+
+# For an SFTP repository: the target's alias, its pinned host key, our key.
+- name: Render SSH config
+  ansible.builtin.template:
+    src: ssh_config.j2
+    dest: "{{ restic_backup.dir }}/ssh/config"
+    mode: "0600"
+  when: restic_backup.ssh is defined
+
+- name: Pin the target's host key
+  ansible.builtin.copy:
+    content: "{{ restic_backup.ssh.known_host }}\n"
+    dest: "{{ restic_backup.dir }}/ssh/known_hosts"
+    mode: "0600"
+  when: restic_backup.ssh is defined
+
+- name: Install the backup's SSH key
+  ansible.builtin.copy:
+    content: "{{ restic_backup_ssh_key | trim }}\n"
+    dest: "{{ restic_backup.dir }}/ssh/id_ed25519"
+    mode: "0600"
+  when: restic_backup.ssh is defined
+  no_log: true
+
+- name: Render exclude list
+  ansible.builtin.copy:
+    content: "{{ restic_backup.exclude | default([]) | join('\n') }}\n"
+    dest: "{{ restic_backup.dir }}/config/excludes.txt"
+    mode: "0600"
+
+# Into cron/, which is mounted as a directory: a single-file bind mount would
+# keep showing the container the file Ansible just replaced.
+- name: Render crontab
+  ansible.builtin.template:
+    src: root.crontab.j2
+    dest: "{{ restic_backup.dir }}/cron/root"
+    mode: "0600"
+  notify: Restart backup
+
+- name: Start backup stack
+  community.docker.docker_compose_v2:
+    project_src: "{{ restic_backup.dir }}"

package/ansible/roles/restic-backup/templates/backup.env.j2

@@ -0,0 +1,9 @@
+# Generated by Ansible (restic-backup role). Sourced by the scripts: cron
+# jobs do not inherit the container's environment.
+export PATH=/opt/restic:/usr/local/bin:/usr/bin:/bin
+export RESTIC_REPOSITORY={{ restic_backup.repository | quote }}
+export RESTIC_PASSWORD={{ restic_backup_password | quote }}
+export RESTIC_CACHE_DIR={{ (restic_backup.dir ~ '/cache') | quote }}
+{% for db in restic_backup.postgres | default([]) %}
+export PG_PASSWORD_{{ db.name | upper }}={{ restic_backup_postgres_passwords[db.name] | quote }}
+{% endfor %}

package/ansible/roles/restic-backup/templates/backup.sh.j2

@@ -0,0 +1,28 @@
+#!/bin/sh
+# Generated by Ansible (restic-backup role). Run by cron in the backup
+# container: dump the databases, back everything up, and on Sundays forget
+# and prune what restic_backup.keep no longer covers (where it is set; an
+# append-only repository is pruned on the receiving side instead).
+set -eu
+. /etc/backup/backup.env
+
+dumps='{{ restic_backup.dir }}/dumps'
+{% for db in restic_backup.postgres | default([]) %}
+PGPASSWORD="$PG_PASSWORD_{{ db.name | upper }}" pg_dump --format=custom \
+    --host={{ db.host }} --username={{ db.user }} --dbname={{ db.database }} \
+    --file="${dumps}/{{ db.name }}.dump.tmp"
+# UGOS's ACLs override the umask: new files would be world-readable.
+chmod 600 "${dumps}/{{ db.name }}.dump.tmp"
+mv "${dumps}/{{ db.name }}.dump.tmp" "${dumps}/{{ db.name }}.dump"
+{% endfor %}
+
+restic cat config >/dev/null 2>&1 || restic init
+restic backup --host '{{ inventory_hostname }}' --exclude-file /etc/backup/excludes.txt \
+    {{ restic_backup.paths | map('quote') | join(' ') }}
+{% if restic_backup.keep is defined %}
+
+if [ "$(date +%u)" = 7 ]; then
+    restic forget --prune --host '{{ inventory_hostname }}'{% for period, count in restic_backup.keep.items() %} --keep-{{ period }} {{ count }}{% endfor %}
+
+fi
+{% endif %}

package/ansible/roles/restic-backup/templates/docker-compose.override.yml.j2

@@ -0,0 +1,26 @@
+# Generated by Ansible from restic_backup in servers/<server>/vars.yml.
+{% set networks = restic_backup.postgres | default([]) | map(attribute='network') | unique | list %}
+services:
+  backup:
+    volumes:
+{% for path in restic_backup.paths %}
+      - {{ path }}:{{ path }}:ro
+{% endfor %}
+{% for dir in ['dumps', 'cache', 'restore-test', 'log'] %}
+      - {{ restic_backup.dir }}/{{ dir }}:{{ restic_backup.dir }}/{{ dir }}
+{% endfor %}
+{% if restic_backup.ssh is defined %}
+      - {{ restic_backup.dir }}/ssh:/root/.ssh:ro
+{% endif %}
+{% if networks %}
+    networks:
+{% for network in networks %}
+      - {{ network }}
+{% endfor %}
+
+networks:
+{% for network in networks %}
+  {{ network }}:
+    external: true
+{% endfor %}
+{% endif %}

package/ansible/roles/restic-backup/templates/follow-restore-test.sh.j2

@@ -0,0 +1,28 @@
+#!/bin/sh
+# Generated by Ansible (restic-backup role). Follows the restore test that is
+# running, or about to: its log until it ends, then exits with its status.
+# Runs on the host as the operator's SSH user (kayra backup test), so it reads
+# only log/. Stopping it leaves the restore test running.
+set -eu
+
+log='{{ restic_backup.dir }}/log'
+lock="${log}/restore-test.lock"
+
+# A test that runs holds the lock, and removed the last one's status only
+# after starting its log. It was just started, so wait for that.
+waited=0
+until [ -e "$lock" ] && ! flock -n "$lock" true && [ ! -e "${log}/restore-test.status" ]; do
+    if [ "$waited" -ge 30 ]; then
+        echo "No restore test started; its first lines go to the backup container's log." >&2
+        exit 1
+    fi
+    waited=$((waited + 1))
+    sleep 1
+done
+
+tail -n +1 -F "${log}/restore-test.log" &
+follower=$!
+flock "$lock" true
+sleep 1
+kill "$follower"
+exit "$(cat "${log}/restore-test.status")"

package/ansible/roles/restic-backup/templates/restore-test.sh.j2

@@ -0,0 +1,51 @@
+#!/bin/sh
+# Generated by Ansible (restic-backup role). Proves the latest snapshot comes
+# back: checks the repository, restores it (or restic_backup.restore_test_paths
+# of it) below restore-test/, and has
+# pg_restore read every database dump. Deletes the restored copy afterwards.
+# Started by cron (restore_test_schedule) or by kayra backup test, which
+# follows its log with follow-restore-test.sh. One at a time.
+set -eu
+. /etc/backup/backup.env
+
+log='{{ restic_backup.dir }}/log'
+exec 9>"${log}/restore-test.lock"
+if ! flock -n 9; then
+    echo "A restore test is already running: ${log}/restore-test.log" >&2
+    exit 75
+fi
+# The log first, then the old status: a follower waits for both to be fresh.
+exec >"${log}/restore-test.log" 2>&1
+rm -f "${log}/restore-test.status"
+# restic leaves progress out without a terminal; every 10 s instead.
+export RESTIC_PROGRESS_FPS=0.1
+
+result=failed
+finish() {
+    status=$?
+    echo "$status" > "${log}/restore-test.status"
+{% if restic_backup.ssh is defined %}
+    # The result, next to the repository, for the backup-check role to read.
+    date -u '+%Y-%m-%dT%H:%M:%SZ' > "/tmp/restore-test.${result}"
+    echo "put /tmp/restore-test.${result} {{ restic_backup.repository.split(':', 2)[2] }}/restore-test.${result}" \
+        | sftp -q -b - backup-target
+{% endif %}
+}
+trap finish EXIT
+
+target='{{ restic_backup.dir }}/restore-test'
+find "$target" -mindepth 1 -delete
+
+# Waits out a backup's or prune's lock; reads a twelfth of the data, a
+# different one each month, so all of it once a year.
+restic check --retry-lock 1h --read-data-subset "$(date +%m | sed 's/^0//')/12"
+restic restore latest --host '{{ inventory_hostname }}' --target "$target"{% for path in restic_backup.restore_test_paths | default([]) %} --include {{ path | quote }}{% endfor %}
+
+{% for db in restic_backup.postgres | default([]) %}
+pg_restore --list "${target}{{ restic_backup.dir }}/dumps/{{ db.name }}.dump" >/dev/null
+echo "{{ db.name }}: dump readable"
+{% endfor %}
+echo "restored $(find "$target" -type f | wc -l) files, $(du -sh "$target" | cut -f1)"
+find "$target" -mindepth 1 -delete
+echo "restore test passed"
+result=passed

package/ansible/roles/restic-backup/templates/root.crontab.j2

@@ -0,0 +1,6 @@
+# Generated by Ansible (restic-backup role). Output goes to the container log;
+# a restore test writes its own to log/restore-test.log.
+{{ restic_backup.schedule }} /etc/backup/backup.sh >/proc/1/fd/1 2>&1
+{% if restic_backup.restore_test_schedule is defined %}
+{{ restic_backup.restore_test_schedule }} /etc/backup/restore-test.sh >/proc/1/fd/1 2>&1
+{% endif %}

package/ansible/roles/restic-backup/templates/ssh_config.j2

@@ -0,0 +1,12 @@
+# Generated by Ansible (restic-backup role): the SFTP target, as the
+# repository's host alias `backup-target`.
+Host backup-target
+	HostName {{ restic_backup.ssh.host }}
+	User {{ restic_backup.ssh.user }}
+	Port {{ restic_backup.ssh.port | default(22) }}
+	IdentityFile /root/.ssh/id_ed25519
+	IdentitiesOnly yes
+	# The host key is pinned in known_hosts; nothing else is trusted.
+	StrictHostKeyChecking yes
+	UserKnownHostsFile /root/.ssh/known_hosts
+	ServerAliveInterval 60

package/ansible/roles/wireguard/handlers/main.yml

@@ -0,0 +1,9 @@
+---
+- name: Apply sysctl
+  ansible.builtin.command: sysctl --system
+  changed_when: true
+
+- name: Restart WireGuard
+  ansible.builtin.systemd:
+    name: wg-quick@wg0
+    state: restarted

package/ansible/roles/wireguard/tasks/main.yml

@@ -0,0 +1,33 @@
+---
+# =============================================================================
+# WireGuard role — this server is the tunnel's listening end; the peer (a
+# Fritzbox) dials in. wg-quick routes the peer's AllowedIPs through wg0, which
+# is how containers here reach hosts on the peer's LAN.
+# =============================================================================
+
+- name: Install WireGuard tools
+  ansible.builtin.apt:
+    name: wireguard-tools
+
+- name: Forward IPv4 between the tunnel and Docker's bridge
+  ansible.builtin.copy:
+    content: "net.ipv4.ip_forward=1\n"
+    dest: /etc/sysctl.d/99-ip-forward.conf
+    mode: "0644"
+  notify: Apply sysctl
+
+- name: Render wg0.conf
+  ansible.builtin.template:
+    src: wg0.conf.j2
+    dest: /etc/wireguard/wg0.conf
+    owner: root
+    group: root
+    mode: "0600"
+  no_log: true
+  notify: Restart WireGuard
+
+- name: Enable WireGuard
+  ansible.builtin.systemd:
+    name: wg-quick@wg0
+    enabled: true
+    state: started

package/ansible/roles/wireguard/templates/wg0.conf.j2

@@ -0,0 +1,12 @@
+# Generated by Ansible from servers/<server>/vars.yml (network) and secrets.yml
+# (keys). Do not edit here.
+[Interface]
+Address = {{ wireguard.address }}
+ListenPort = {{ wireguard.port }}
+PrivateKey = {{ wireguard_private_key }}
+
+[Peer]
+PublicKey = {{ wireguard.peer_public_key }}
+PresharedKey = {{ wireguard_peer_psk }}
+AllowedIPs = {{ wireguard.peer_allowed_ips | join(', ') }}
+PersistentKeepalive = {{ wireguard.keepalive }}

package/bin/kayra.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Runs the kayra the fleet pins. Whichever `kayra` is on PATH (a global
+// install, a linked checkout) hands over to node_modules/@yunuseon/kayra of the
+// fleet it is run in (the nearest directory with servers/defaults.yml), as
+// turbo or nx do; without one, it runs itself. `npm link @yunuseon/kayra` in a
+// fleet makes that pinned copy a checkout, for working on kayra itself.
+//
+// A checkout runs its TypeScript directly, never a build lying around; the
+// published package has no cli/src and runs the compiled CLI (Node strips no
+// types inside node_modules).
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const self = realpathSync(join(dirname(fileURLToPath(import.meta.url)), ".."));
+
+const fleetOf = (dir) =>
+  existsSync(join(dir, "servers", "defaults.yml")) ? dir : dirname(dir) === dir ? undefined : fleetOf(dirname(dir));
+
+const fleet = fleetOf(process.cwd());
+const pinnedDir = fleet === undefined ? undefined : join(fleet, "node_modules", "@yunuseon", "kayra");
+const pinned = pinnedDir !== undefined && existsSync(pinnedDir) ? realpathSync(pinnedDir) : self;
+
+if (pinned !== self) {
+  await import(pathToFileURL(join(pinned, "bin", "kayra.js")).href);
+} else {
+  const source = join(self, "cli", "src", "main.ts");
+  await import(pathToFileURL(existsSync(source) ? source : join(self, "cli", "dist", "main.js")).href);
+}

package/cli/dist/brand.js

@@ -0,0 +1,41 @@
+import { text } from "@optique/core/message";
+import { homedir } from "node:os";
+import { isAbsolute, join, normalize } from "node:path";
+import { err, ok } from "./result.js";
+export const serverName = (value) => /^[a-z0-9][a-z0-9-]*$/.test(value)
+    ? ok(value)
+    : err(`'${value}' is not a server name (lowercase letters, digits, dashes)`);
+export const appName = (value) => /^[a-z][a-z0-9-]*$/.test(value)
+    ? ok(value)
+    : err(`'${value}' is not an app name (lowercase letters, digits, dashes)`);
+export const subdomain = (value) => /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(value) ? ok(value) : err(`'${value}' is not a subdomain`);
+export const domain = (value) => /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z][a-z0-9-]*$/.test(value)
+    ? ok(value)
+    : err(`'${value}' is not a domain`);
+/** `~/…` is the operator's home, as Ansible reads it in vault_password_file. */
+export const absolutePath = (value) => {
+    const expanded = value === "~" || value.startsWith("~/") ? join(homedir(), value.slice(1)) : value;
+    return isAbsolute(expanded) ? ok(normalize(expanded)) : err(`'${value}' is not an absolute path`);
+};
+export const kayraRoot = (path) => path;
+export const fleetRoot = (path) => path;
+export const kayraVersion = (value) => typeof value === "string" && /^\d+\.\d+\.\d+$/.test(value)
+    ? ok(value)
+    : err(`'${String(value)}' is not a version MAJOR.MINOR.PATCH`);
+export const serverDir = (root, name) => join(root, "servers", name);
+export const vaultPasswordFile = (path) => path;
+export const within = (base, ...segments) => join(base, ...segments);
+/** An Optique value parser that mints a brand: arguments arrive already validated. */
+const minting = (metavar, mint, placeholder) => ({
+    mode: "sync",
+    metavar,
+    placeholder,
+    parse: (input) => {
+        const minted = mint(input);
+        return minted.ok ? { success: true, value: minted.value } : { success: false, error: [text(minted.error)] };
+    },
+    format: (value) => value,
+});
+export const appNameParser = minting("APP", appName, "app");
+export const domainParser = minting("DOMAIN", domain, "example.com");
+export const subdomainParser = minting("SUBDOMAIN", subdomain, "www");

package/cli/dist/cli.js

@@ -0,0 +1,21 @@
+import { command, constant, multiple, object, option, or } from "@optique/core";
+import { message } from "@optique/core/message";
+import { argument } from "@optique/core/primitives";
+import { choice } from "@optique/core/valueparser";
+import { appNameParser, domainParser, subdomainParser } from "./brand.js";
+/** The arguments kayra takes; server names are the fleet's, so they complete and are checked while parsing. */
+export const parser = (fleet) => {
+    const server = argument(choice(fleet.servers.map((each) => each.name), { metavar: "SERVER" }));
+    // eslint-disable-next-line functional/prefer-immutable-types -- Optique's Message is readonly only at the top
+    const onServer = (name, brief) => command(name, object({ name: constant(name), server }), { brief });
+    return object({
+        dryRun: option("--dry-run", { description: message `Print the plan instead of running it.` }),
+        command: or(command("status", object({ name: constant("status") }), {
+            brief: message `Every server and whether a machine exists for it.`,
+        }), 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("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).`), onServer("ssh", message `SSH into the server.`), 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", command("purge", object({ name: constant("app purge"), server, app: argument(appNameParser) })), { brief: message `Delete a removed app's volumes: its data, irreversibly.` }), command("certs", object({ name: constant("certs"), domain: argument(domainParser), subdomains: multiple(argument(subdomainParser)) }), { brief: message `mkcert certs for a domain and its subdomains (local dev, multipass).` }), command("doctor", object({ name: constant("doctor") }), {
+            brief: message `Check that this Mac can run every command on every server.`,
+        })),
+    });
+};

package/cli/dist/commands/doctor.js

@@ -0,0 +1,79 @@
+import { within } from "../brand.js";
+const everyServer = () => true;
+const tools = [
+    { program: "git", install: "brew install git", neededBy: everyServer },
+    { program: "ssh", install: "macOS ships it", neededBy: everyServer },
+    { program: "yq", install: "brew install yq", neededBy: everyServer },
+    { program: "jq", install: "brew install jq", neededBy: everyServer },
+    { program: "ansible-playbook", install: "brew install ansible", neededBy: everyServer },
+    { program: "ansible-galaxy", install: "brew install ansible", neededBy: everyServer },
+    { program: "ansible-vault", install: "brew install ansible", neededBy: (server) => server.vault.kind !== "none" },
+    { program: "tofu", install: "brew install opentofu", neededBy: (server) => server.terraform },
+    {
+        program: "mkcert",
+        install: "brew install mkcert && mkcert -install",
+        neededBy: (server) => server.kind === "platform" && server.target !== "hetzner",
+    },
+    {
+        program: "multipass",
+        install: "brew install --cask multipass",
+        neededBy: (server) => server.target === "multipass",
+    },
+    { program: "qemu-img", install: "brew install qemu", neededBy: (server) => server.vm },
+];
+const toolChecks = (fleet) => tools.flatMap((tool) => {
+    const users = fleet.servers.filter(tool.neededBy).map((server) => server.name);
+    return users.length === 0
+        ? []
+        : [
+            {
+                kind: "check",
+                label: `${tool.program} (${users.length === fleet.servers.length ? "every server" : users.join(", ")})`,
+                probe: { kind: "on-path", program: tool.program },
+                hint: tool.install,
+                onFailure: "continue",
+            },
+        ];
+});
+// ansible-vault opens whole-file vaults only; values vaulted inline are opened by setup.
+const vaultChecks = (fleet) => fleet.servers.flatMap((server) => server.vault.kind === "file" && server.secretsVaulted
+    ? [
+        {
+            kind: "check",
+            label: `vault password opens ${server.name}'s secrets.yml`,
+            probe: {
+                kind: "exits-zero",
+                argv: ["ansible-vault", "view", "--vault-password-file", server.vault.file, within(server.dir, "secrets.yml")],
+            },
+            hint: `the password file is ${server.vault.file}`,
+            onFailure: "continue",
+        },
+    ]
+    : []);
+/** The apps' repositories are cloned on this Mac with the operator's own git credentials. */
+const repoChecks = (fleet) => [...new Set(fleet.servers.flatMap((server) => server.apps.map((app) => app.repo)))].map((repo) => ({
+    kind: "check",
+    label: `git can read ${repo}`,
+    probe: { kind: "exits-zero", argv: ["sh", "-c", 'GIT_TERMINAL_PROMPT=0 git ls-remote "$1" HEAD', "sh", repo] },
+    hint: "gh auth login && gh auth setup-git (or git credentials of your own for that host)",
+    onFailure: "continue",
+}));
+const reachChecks = (fleet, kayra) => fleet.servers
+    .filter((server) => server.target === "home")
+    .map((server) => ({
+    kind: "check",
+    label: `${server.name} answers over SSH`,
+    probe: {
+        kind: "exits-zero",
+        argv: ["bash", within(kayra, "scripts", "local", "home-reach.sh"), server.name, server.kind],
+        env: { FLEET_ROOT: fleet.root },
+    },
+    onFailure: "continue",
+}));
+/** Is this Mac ready to run every command on every server? Each check reports; none stops the others. */
+export const doctor = (fleet, kayra) => [
+    ...toolChecks(fleet),
+    ...vaultChecks(fleet),
+    ...repoChecks(fleet),
+    ...reachChecks(fleet, kayra),
+];