@yunuseon/kayra 0.0.0-stage → 0.5.0

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),
+];

package/cli/dist/commands/server.js

@@ -0,0 +1,215 @@
+import { within, } from "../brand.js";
+import { run } from "../plan.js";
+import { all, err, map, ok } from "../result.js";
+/** The local scripts that read the fleet's files find them here, not beside themselves. */
+const fleetEnv = ({ fleet }) => ({ FLEET_ROOT: fleet });
+const script = ({ kayra }, name) => within(kayra, "scripts", "local", name);
+const ansiblePath = ({ kayra }, ...segments) => within(kayra, "ansible", ...segments);
+const inventory = (server) => within(server.dir, "inventory.ini");
+const terraform = (server) => `-chdir=${within(server.dir, "terraform")}`;
+/** How Ansible gets the vault password: from a file, or by asking. */
+const vaultEnv = (server) => {
+    switch (server.vault.kind) {
+        case "file":
+            return { ANSIBLE_VAULT_PASSWORD_FILE: server.vault.file };
+        case "ask":
+            return { ANSIBLE_ASK_VAULT_PASS: "True" };
+        case "none":
+            return {};
+    }
+};
+const ansibleEnv = (engine, env) => ({ ...env, ANSIBLE_CONFIG: ansiblePath(engine, "ansible.cfg") });
+/** Real servers change only from main as merged; a multipass one from anything. */
+const fromMain = (engine, server) => ({
+    kind: "check",
+    label: `${server.name} may be changed from this checkout`,
+    probe: { kind: "exits-zero", argv: ["bash", script(engine, "require-main.sh"), server.name], env: fleetEnv(engine) },
+    onFailure: "stop",
+});
+/** Before Ansible's UNREACHABLE: why a home machine cannot be reached. */
+const reachable = (engine, server) => server.target === "home"
+    ? [
+        {
+            kind: "check",
+            label: `${server.name} answers over SSH`,
+            probe: {
+                kind: "exits-zero",
+                argv: ["bash", script(engine, "home-reach.sh"), server.name, server.kind],
+                env: fleetEnv(engine),
+            },
+            onFailure: "stop",
+        },
+    ]
+    : [];
+/** The pinned Ansible collections; a no-op once installed. */
+const collections = (engine, env) => ({
+    kind: "run",
+    argv: ["ansible-galaxy", "collection", "install", "-r", ansiblePath(engine, "requirements.yml")],
+    env,
+    stdout: "discard",
+});
+const appSubdomains = (engine, server) => ({
+    kind: "query",
+    argv: ["bash", script(engine, "app-manifests.sh"), "--subdomains", server.name],
+    words: "many",
+    env: fleetEnv(engine),
+});
+const certs = (engine, domain, subdomains) => run(["bash", script(engine, "certs.sh"), domain, within(engine.fleet, ".cache", "certs"), ...subdomains]);
+export const provision = (engine, server) => ok([
+    fromMain(engine, server),
+    ...(server.vm ? [run(["bash", script(engine, "home-image.sh"), server.name], fleetEnv(engine))] : []),
+    ...(server.terraform
+        ? [run(["tofu", terraform(server), "init", "-input=false"]), run(["tofu", terraform(server), "apply", "-auto-approve"])]
+        : []),
+]);
+/** The host layer: the playbook for the server's kind. */
+export const setup = (engine, server) => ok([
+    fromMain(engine, server),
+    // mkcert where Let's Encrypt cannot reach: test VMs, and home servers without DNS-01.
+    ...(server.kind === "platform" && server.target !== "hetzner" && !server.acmeDns
+        ? [certs(engine, server.domain, [appSubdomains(engine, server), ...server.stackHosts])]
+        : []),
+    ...reachable(engine, server),
+    collections(engine, vaultEnv(server)),
+    run([
+        "ansible-playbook",
+        "-i",
+        inventory(server),
+        ansiblePath(engine, "playbooks", `${server.kind}.yml`),
+        "-e",
+        `server=${server.name}`,
+        "-e",
+        `server_dir=${server.dir}`,
+        "-e",
+        `domain=${server.domain}`,
+        "-e",
+        `target=${server.target}`,
+        "-e",
+        `kayra_version=${engine.version}`,
+    ], ansibleEnv(engine, vaultEnv(server))),
+]);
+/** Register every app in server.yml, then remove the rest (their data kept). */
+export const apps = (engine, server) => {
+    const env = vaultEnv(server);
+    const playbook = (name, ...extra) => run(["ansible-playbook", "-i", inventory(server), ansiblePath(engine, "playbooks", name), ...extra], ansibleEnv(engine, env));
+    return ok([
+        fromMain(engine, server),
+        ...(server.kind === "platform"
+            ? [
+                ...server.apps.flatMap((app) => [
+                    collections(engine, env),
+                    playbook("app.yml", "-e", `server=${server.name}`, "-e", `server_dir=${server.dir}`, "-e", `domain=${server.domain}`, "-e", `{"app": ${app.entry}}`),
+                ]),
+                collections(engine, env),
+                playbook("apps-prune.yml", "-e", `{"keep": ${JSON.stringify(server.apps.map((app) => app.name))}}`),
+            ]
+            : []),
+    ]);
+};
+export const hosts = (engine, server) => ok(server.target === "multipass"
+    ? [
+        run([
+            "bash",
+            script(engine, "setup-hosts.sh"),
+            server.domain,
+            { kind: "query", argv: ["tofu", terraform(server), "output", "-raw", "server_ip"], words: "one" },
+            appSubdomains(engine, server),
+        ]),
+    ]
+    : [{ 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)]);
+export const up = (engine, server) => sequence([provision(engine, server), deploy(engine, server), hosts(engine, server)]);
+export const down = (server) => server.terraform
+    ? ok([
+        ...(server.target === "hetzner"
+            ? [
+                {
+                    kind: "confirm",
+                    prompt: `This destroys the Hetzner server '${server.name}' (${server.domain}). Type the name to confirm: `,
+                    expect: server.name,
+                },
+            ]
+            : []),
+        run(["tofu", terraform(server), "destroy", "-auto-approve"]),
+    ])
+    : err(`${server.name} has no terraform/: nothing here creates it, so nothing destroys it`);
+/** Once, for a server we did not create: the deploy user, added as root. */
+export const adopt = (engine, server) => ok([
+    fromMain(engine, server),
+    collections(engine, {}),
+    run(["ansible-playbook", "-i", inventory(server), ansiblePath(engine, "playbooks", "adopt.yml")], ansibleEnv(engine, {})),
+]);
+/** A removed app's volumes: its data, irreversibly. */
+export const appPurge = (engine, server, app) => ok([
+    fromMain(engine, server),
+    run([
+        "ansible",
+        "servers",
+        "-i",
+        inventory(server),
+        "--become",
+        "-m",
+        "ansible.builtin.command",
+        "-a",
+        `/opt/platform/bin/app-purge ${app}`,
+    ], ansibleEnv(engine, {})),
+]);
+/**
+ * The restic-backup role's restore test: the latest backup, restored to a scratch dir and checked.
+ * It runs on the server, detached; kayra follows its log over SSH. Stopping kayra stops only the
+ * following, and running it again while a test runs follows that one instead of starting another.
+ */
+export const backupTest = (engine, server) => {
+    if (server.backupDir === undefined)
+        return err(`${server.name} has no restic_backup.dir in its vars.yml`);
+    if (server.inventory === undefined)
+        return err(`no inventory for '${server.name}' — provision it first.`);
+    return ok([
+        ...reachable(engine, server),
+        run([
+            "ansible",
+            "servers",
+            "-i",
+            inventory(server),
+            "--become",
+            "-e",
+            `@${within(server.dir, "secrets.yml")}`,
+            "-m",
+            "ansible.builtin.command",
+            "-a",
+            `docker compose -f ${server.backupDir}/docker-compose.yml exec -d -T backup /etc/backup/restore-test.sh`,
+        ], ansibleEnv(engine, vaultEnv(server))),
+        { kind: "note", text: "Following the restore test. Ctrl-C stops following, not the test." },
+        run([
+            "ssh",
+            "-p",
+            server.inventory.port,
+            "-i",
+            server.inventory.key,
+            "-o",
+            "StrictHostKeyChecking=accept-new",
+            `${server.inventory.user}@${server.inventory.host}`,
+            "sh",
+            `${server.backupDir}/follow-restore-test.sh`,
+        ]),
+    ]);
+};
+export const ssh = (server) => server.inventory === undefined
+    ? err(`no inventory for '${server.name}' — provision it first.`)
+    : ok([
+        run([
+            "ssh",
+            "-p",
+            server.inventory.port,
+            "-i",
+            server.inventory.key,
+            "-o",
+            "StrictHostKeyChecking=no",
+            "-o",
+            "UserKnownHostsFile=/dev/null",
+            `${server.inventory.user}@${server.inventory.host}`,
+        ]),
+    ]);
+/** mkcert certs for a domain and its subdomains, for local dev and multipass. */
+export const certsFor = (engine, domain, subdomains) => ok([certs(engine, domain, subdomains)]);

package/cli/dist/commands/status.js

@@ -0,0 +1,43 @@
+import { within } from "../brand.js";
+import { capture } from "../interpret.js";
+const describe = (machine) => {
+    switch (machine.kind) {
+        case "none":
+            return "not provisioned";
+        case "provisioned":
+            return `provisioned (${machine.ip ?? "?"})`;
+        case "unreadable":
+            return `state unreadable: ${machine.reason}`;
+    }
+};
+export const statusLine = (server, machine) => [
+    server.name.padEnd(10),
+    `kind=${server.kind.padEnd(9)} target=${server.target.padEnd(10)}`,
+    `domain=${server.domain.padEnd(24)}`,
+    `apps=${server.apps.map((app) => app.name).join(",").padEnd(10)}`,
+    describe(machine),
+].join("  ");
+/** Why tofu could not read the state, in a few words: the first line of its error. */
+export const unreadable = (stderr) => {
+    if (stderr.includes("tofu init"))
+        return "tofu init needed";
+    const line = stderr
+        .split("\n")
+        .map((each) => each.replace(/^[│╷╵\s]+/, "").replace(/^Error:\s*/, "").trim())
+        .find((each) => each !== "");
+    return line ?? "tofu failed";
+};
+const machine = async (server) => {
+    if (!server.terraform)
+        return { kind: "none" };
+    const chdir = `-chdir=${within(server.dir, "terraform")}`;
+    const state = await capture(["tofu", chdir, "state", "list", "-no-color"], "capture");
+    if (state.code !== 0)
+        return { kind: "unreadable", reason: unreadable(state.stderr) };
+    if (state.stdout.trim() === "")
+        return { kind: "none" };
+    const ip = await capture(["tofu", chdir, "output", "-raw", "server_ip"], "capture");
+    return { kind: "provisioned", ip: ip.code === 0 ? ip.stdout.replace(/\n+$/, "") : undefined };
+};
+/** Every server and whether a machine exists for it. Reads state, changes nothing. */
+export const status = async (fleet) => Promise.all(fleet.servers.map(async (server) => statusLine(server, await machine(server))));

package/cli/dist/fleet.js

@@ -0,0 +1,134 @@
+import { parse } from "yaml";
+import { absolutePath, appName, domain, vaultPasswordFile, } from "./brand.js";
+import { all, err, map, ok } from "./result.js";
+export const serverKinds = ["platform", "edge", "nas"];
+export const serverTargets = ["multipass", "hetzner", "home"];
+const mapping = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? Object.fromEntries(Object.entries(value)) : undefined;
+const fields = (text) => {
+    const value = parse(text);
+    if (value === null)
+        return ok({});
+    const result = mapping(value);
+    return result === undefined ? err("is not a YAML mapping") : ok(result);
+};
+const vaulted = (text) => text.startsWith("$ANSIBLE_VAULT");
+const oneOf = (allowed, value, field) => {
+    const match = allowed.find((candidate) => candidate === value);
+    return match === undefined
+        ? err(`${field} must be ${allowed.join(", ")}, not '${String(value)}'`)
+        : ok(match);
+};
+const vault = (descriptor) => {
+    const file = descriptor["vault_password_file"];
+    if (descriptor["vault"] !== true)
+        return ok({ kind: "none" });
+    if (file === undefined)
+        return ok({ kind: "ask" });
+    return typeof file === "string"
+        ? map(absolutePath(file), (path) => ({ kind: "file", file: vaultPasswordFile(path) }))
+        : err("vault_password_file must be a path");
+};
+/** Apps live in their own repo: Jenkins clones it over HTTPS, and the app root stays inside it. */
+const app = (value) => {
+    const entry = mapping(value);
+    if (entry === undefined)
+        return err("an app must be a mapping");
+    const name = typeof entry["name"] === "string" ? appName(entry["name"]) : err("an app needs a name");
+    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 path = entry["path"] ?? ".";
+    if (typeof path !== "string" || `/${path}/`.includes("/../"))
+        return err(`app ${name.value}: path must stay inside its repo`);
+    return ok({ name: name.value, repo, entry: JSON.stringify(value) });
+};
+const inventoryField = (inventory, key) => new RegExp(`${key}=([^ \\n]*)`).exec(inventory)?.[1] ?? "";
+const inventoryOf = (text) => ({
+    host: inventoryField(text, "ansible_host"),
+    port: inventoryField(text, "ansible_port") || "22",
+    user: inventoryField(text, "ansible_user"),
+    key: inventoryField(text, "ansible_ssh_private_key_file"),
+});
+const stackHosts = (stacks, serverDomain) => stacks
+    .flatMap((compose) => [...compose.matchAll(/Host\(`([^`]*)`\)/g)].map((match) => match[1] ?? ""))
+    .map((host) => (host.endsWith(`.${serverDomain}`) ? host.slice(0, -serverDomain.length - 1) : host));
+/** An app's config is plaintext, to be read and diffed; its secrets are vaulted wherever secrets.yml is. */
+const appValuesProblem = (appValues, secretsMustBeVaulted) => appValues
+    .map(({ file, text }) => file.endsWith(".secrets.yml")
+    ? secretsMustBeVaulted && !vaulted(text)
+        ? `apps/${file} must be vault-encrypted`
+        : undefined
+    : vaulted(text)
+        ? `apps/${file} is vault-encrypted; it holds config only — secrets go in apps/${file.replace(/\.yml$/, ".secrets.yml")}`
+        : undefined)
+    .find((problem) => problem !== undefined);
+/** What every command may rely on, checked for every server whenever the fleet loads. */
+export const parseServer = (files) => {
+    const descriptor = fields(files.descriptor);
+    if (!descriptor.ok)
+        return descriptor;
+    const kind = oneOf(serverKinds, descriptor.value["kind"] ?? "platform", "kind");
+    if (!kind.ok)
+        return kind;
+    const target = oneOf(serverTargets, descriptor.value["target"], "target");
+    if (!target.ok)
+        return target;
+    const declared = descriptor.value["domain"];
+    const serverDomain = typeof declared === "string" ? domain(declared) : err("domain is required");
+    if (!serverDomain.ok)
+        return serverDomain;
+    const serverVault = vault(descriptor.value);
+    if (!serverVault.ok)
+        return serverVault;
+    const declaredApps = descriptor.value["apps"] ?? [];
+    if (!Array.isArray(declaredApps))
+        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));
+    if (!apps.ok)
+        return apps;
+    if (target.value === "home" && files.inventory === undefined)
+        return err("target home needs a hand-written inventory.ini next to it");
+    if (target.value !== "home" && !files.terraform)
+        return err("no terraform/ next to it");
+    if (files.vars === undefined)
+        return err("no vars.yml next to it");
+    if (files.secrets === undefined)
+        return err("no secrets.yml next to it");
+    if (vaulted(files.vars))
+        return err("vars.yml is vault-encrypted; it holds settings only — secrets go in secrets.yml");
+    if (target.value !== "multipass" && serverVault.value.kind === "none")
+        return err(`target ${target.value} requires vault: true`);
+    if (target.value !== "multipass" && !vaulted(files.secrets))
+        return err(`target ${target.value} requires a vault-encrypted secrets.yml`);
+    const appValues = appValuesProblem(files.appValues, target.value !== "multipass");
+    if (appValues !== undefined)
+        return err(appValues);
+    const vars = fields(files.vars);
+    if (!vars.ok)
+        return err(`vars.yml ${vars.error}`);
+    const backupDir = mapping(vars.value["restic_backup"])?.["dir"];
+    return ok({
+        name: files.name,
+        dir: files.dir,
+        kind: kind.value,
+        target: target.value,
+        domain: serverDomain.value,
+        vault: serverVault.value,
+        secretsVaulted: vaulted(files.secrets),
+        apps: apps.value,
+        terraform: files.terraform,
+        vm: target.value === "home" && vars.value["vm"] !== undefined,
+        acmeDns: typeof vars.value["acme_dns"] === "string" && vars.value["acme_dns"] !== "",
+        inventory: files.inventory === undefined ? undefined : inventoryOf(files.inventory),
+        backupDir: typeof backupDir === "string" ? backupDir : undefined,
+        stackHosts: stackHosts(files.stacks, serverDomain.value),
+    });
+};
+export const serverNamed = (fleet, name) => {
+    const server = fleet.servers.find((candidate) => candidate.name === name);
+    return server === undefined ? err(`no server '${name}'`) : ok(server);
+};