@yunuseon/kayra 0.5.1 → 0.6.0

package/ansible/playbooks/edge.yml

@@ -34,6 +34,8 @@
       register: ufw_status
       changed_when: false
       failed_when: false
+      # Only reads, so it runs in check mode too (kayra plan).
+      check_mode: false
 
     - name: Disable ufw
       ansible.builtin.command: ufw disable

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

@@ -31,6 +31,8 @@
   ansible.builtin.command: timedatectl show --property=Timezone --value
   register: current_timezone
   changed_when: false
+  # Only reads, so it runs in check mode too (kayra plan).
+  check_mode: false
 
 - name: Set timezone
   ansible.builtin.command: timedatectl set-timezone {{ timezone | default('Europe/Berlin') }}

package/ansible/roles/forgejo-config/tasks/main.yml

@@ -2,7 +2,7 @@
 # =============================================================================
 # forgejo-config role — what a Forgejo holds beyond its own config file, as
 # code: users and their SSH keys, organizations, Actions runners, repos (created empty
-# where missing) and their settings (issues, pull requests, actions), Actions
+# where missing, or as a pull mirror of another forge) and their settings (issues, pull requests, actions), Actions
 # secrets, collaborators, webhooks and push mirrors, from
 # forgejo_config in the server's vars.yml. Adds what is missing through the
 # API, adopts what already matches, never deletes. Talks to Forgejo on the
@@ -17,6 +17,8 @@
   until: forgejo_version.status == 200
   retries: 30
   delay: 2
+  # Only reads, so it runs in check mode too (kayra plan).
+  check_mode: false
 
 - name: Look up users
   ansible.builtin.uri:
@@ -27,6 +29,8 @@
   loop: "{{ forgejo_config.users | default([]) }}"
   loop_control: {label: "{{ item.name }}"}
   no_log: true
+  # Only reads, so it runs in check mode too (kayra plan).
+  check_mode: false
 
 # Random password, never stored: these users work with tokens.
 - name: Create missing users
@@ -55,6 +59,8 @@
   loop: "{{ forgejo_config.orgs | default([]) }}"
   loop_control: {label: "{{ item.name }}"}
   no_log: true
+  # Only reads, so it runs in check mode too (kayra plan).
+  check_mode: false
 
 # An organization owns repos and packages alike, and its visibility is
 # theirs: a private one keeps what it owns, images included, from the world.
@@ -93,6 +99,8 @@
   loop: "{{ forgejo_config.ssh_keys | default([]) }}"
   loop_control: {label: "{{ item.user }} {{ item.title }}"}
   no_log: true
+  # Only reads, so it runs in check mode too (kayra plan).
+  check_mode: false
 
 # Matched by type and key, whatever title or comment either side carries.
 - name: Add missing SSH keys
@@ -140,6 +148,8 @@
   loop: "{{ forgejo_config.repos }}"
   loop_control: {label: "{{ item.name }}"}
   no_log: true
+  # Only reads, so it runs in check mode too (kayra plan).
+  check_mode: false
 
 # Empty, and private from the start where its settings say so (the settings
 # are applied below too, but a public repo, even for a moment, is published);
@@ -157,7 +167,30 @@
       private: "{{ item.settings.private | default(false) }}"
     status_code: [201]
   changed_when: true
-  loop: "{{ forgejo_repos.results | selectattr('status', 'eq', 404) | map(attribute='item') | list }}"
+  loop: "{{ forgejo_repos.results | selectattr('status', 'eq', 404) | map(attribute='item') | rejectattr('pull_mirror', 'defined') | list }}"
+  loop_control: {label: "{{ item.name }}"}
+  no_log: true
+
+# A repo whose home is elsewhere (pull_mirror: its clone URL): Forgejo clones
+# it once and fetches it again on mirror_interval (a setting, as
+# mirror_interval: 10m0s). An existing repo is adopted as it is.
+- name: Create missing pull mirrors
+  ansible.builtin.uri:
+    url: "{{ forgejo_config.url }}/api/v1/repos/migrate"
+    method: POST
+    headers: {Authorization: "token {{ forgejo_admin_token }}"}
+    body_format: json
+    body:
+      clone_addr: "{{ item.pull_mirror }}"
+      repo_owner: "{{ item.name.split('/')[0] }}"
+      repo_name: "{{ item.name.split('/')[1] }}"
+      mirror: true
+      private: "{{ item.settings.private | default(false) }}"
+      service: git
+    status_code: [201]
+    timeout: 300
+  changed_when: true
+  loop: "{{ forgejo_repos.results | selectattr('status', 'eq', 404) | map(attribute='item') | selectattr('pull_mirror', 'defined') | list }}"
   loop_control: {label: "{{ item.name }}"}
   no_log: true
 
@@ -170,6 +203,8 @@
   loop: "{{ forgejo_config.repos | subelements('collaborators', skip_missing=True) }}"
   loop_control: {label: "{{ item.0.name }} {{ item.1.user }}"}
   no_log: true
+  # Only reads, so it runs in check mode too (kayra plan).
+  check_mode: false
 
 - name: Grant collaborators their permission
   ansible.builtin.uri:
@@ -222,6 +257,8 @@
   loop: "{{ forgejo_config.repos | product(['hooks', 'push_mirrors']) | list }}"
   loop_control: {label: "{{ item.0.name }} {{ item.1 }}"}
   no_log: true
+  # Only reads, so it runs in check mode too (kayra plan).
+  check_mode: false
 
 # A push to any branch calls the URL (with notifyCommit: Jenkins polls).
 - name: Add missing webhooks
@@ -303,6 +340,8 @@
   loop: "{{ service_token_files.results }}"
   loop_control: {label: "{{ item.item.secret }}"}
   no_log: true
+  # Only reads, so it runs in check mode too (kayra plan).
+  check_mode: false
 
 - name: Mint service tokens
   ansible.builtin.command:

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

@@ -106,6 +106,8 @@
     group: deploy
     mode: "0600"
   become: true
+  # It holds secrets: --diff (kayra plan) says that it would change, never how.
+  diff: false
 
 - name: Render Authelia secrets
   ansible.builtin.copy:
@@ -213,6 +215,8 @@
     group: deploy
     mode: "0600"
   become: true
+  # It holds secrets: --diff (kayra plan) says that it would change, never how.
+  diff: false
 
 # The registry used to have a public, basic-auth router. Nothing outside the
 # server pushes or pulls, so it is gone; the copy above never deletes files.
@@ -256,6 +260,8 @@
   delay: 10
   until: jenkins_health.rc == 0
   changed_when: false
+  # Only reads, so it runs in check mode too (kayra plan).
+  check_mode: false
 
 # casc/ is a bind mount, so a changed 00-platform.yaml only takes effect on
 # a reload; so do new tokens, read from files by ${readFile:…}.

package/cli/dist/cli.js

@@ -1,4 +1,4 @@
-import { command, constant, multiple, object, option, or } from "@optique/core";
+import { command, constant, multiple, object, option, optional, or } from "@optique/core";
 import { message } from "@optique/core/message";
 import { argument } from "@optique/core/primitives";
 import { choice } from "@optique/core/valueparser";
@@ -10,12 +10,18 @@ export const parser = (fleet) => {
     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 })), {
+        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).`), 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") }), {
+        }), command("app", command("purge", object({ name: constant("app purge"), server, app: argument(appNameParser) })), { brief: message `Delete a removed app's volumes: its data, irreversibly.` })), 
+        // On the whole fleet
+        or(command("status", object({ name: constant("status") }), {
+            brief: message `Every server and whether a machine exists for it.`,
+        }), 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("validate", object({ name: constant("validate"), server: optional(server) }), {
+            brief: message `Check the fleet beyond its schemas: secrets, apps against their contract, stacks, routes.`,
+        }), command("doctor", object({ name: constant("doctor") }), {
             brief: message `Check that this Mac can run every command on every server.`,
-        })),
+        }))),
     });
 };

package/cli/dist/commands/server.js

@@ -62,6 +62,24 @@ export const provision = (engine, server) => ok([
         ? [run(["tofu", terraform(server), "init", "-input=false"]), run(["tofu", terraform(server), "apply", "-auto-approve"])]
         : []),
 ]);
+/** The playbook for the server's kind, as setup runs it; plan adds check mode. */
+const hostPlaybook = (engine, server, extra = []) => 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}`,
+    ...extra,
+], ansibleEnv(engine, vaultEnv(server)));
 /** The host layer: the playbook for the server's kind. */
 export const setup = (engine, server) => ok([
     fromMain(engine, server),
@@ -71,22 +89,21 @@ export const setup = (engine, server) => ok([
         : []),
     ...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))),
+    hostPlaybook(engine, server),
+]);
+/**
+ * What provision and setup would change, changing nothing: OpenTofu's plan and
+ * the playbook in check mode, with diffs (files holding secrets say only that
+ * they would change). From any checkout: it previews a branch against a server.
+ */
+export const preview = (engine, server) => ok([
+    ...reachable(engine, server),
+    ...(server.terraform
+        ? [run(["tofu", terraform(server), "init", "-input=false"]), run(["tofu", terraform(server), "plan", "-input=false", "-lock=false"])]
+        : []),
+    collections(engine, vaultEnv(server)),
+    hostPlaybook(engine, server, ["--check", "--diff"]),
+    { kind: "note", text: `kayra plan changed nothing on ${server.name}: the changed tasks above are what kayra setup would do.` },
 ]);
 /** Register every app in server.yml, then remove the rest (their data kept). */
 export const apps = (engine, server) => {

package/cli/dist/commands/validate.js

@@ -0,0 +1,84 @@
+import { appManifestSchema, secretsSchema, settings } from "../settings.js";
+const problem = (text) => ({ problem: true, text });
+const skipped = (text) => ({ problem: false, text });
+const mapping = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? Object.fromEntries(Object.entries(value)) : {};
+const strings = (value) => Array.isArray(value) ? value.filter((each) => typeof each === "string") : [];
+const secretSettingNames = (kind) => settings.filter((each) => each.secret && each.kinds.includes(kind)).map((each) => each.name);
+/** secrets.yml: known secrets typed; anything else must be a helper vars.yml uses. */
+const secretsFindings = (facts) => {
+    if (facts.secrets.kind === "locked")
+        return [skipped(`secrets.yml not checked: ${facts.secrets.reason}`)];
+    const values = facts.secrets.values;
+    const typed = secretsSchema(facts.server.kind).safeParse(values);
+    const typeProblems = typed.success
+        ? []
+        : typed.error.issues.slice(0, 1).map((issue) => problem(`secrets.yml: ${issue.path.join(".")}: ${issue.message}`));
+    const known = secretSettingNames(facts.server.kind);
+    const unused = Object.keys(values)
+        .filter((key) => !known.includes(key) && !key.startsWith("ansible_"))
+        .filter((key) => !new RegExp(`\\b${key}\\b`).test(facts.varsText))
+        .map((key) => problem(`secrets.yml: '${key}' is no secret of a ${facts.server.kind} server, and vars.yml does not use it`));
+    return [...typeProblems, ...unused];
+};
+/** compose_stacks.stacks and stacks/ name the same stacks. */
+const stackFindings = (facts) => {
+    const listed = strings(mapping(facts.vars["compose_stacks"])["stacks"]);
+    return [
+        ...listed
+            .filter((name) => !facts.stackDirs.includes(name))
+            .map((name) => problem(`compose_stacks.stacks: '${name}' has no stacks/${name}/compose.yaml`)),
+        ...facts.stackDirs
+            .filter((name) => !listed.includes(name))
+            .map((name) => problem(`stacks/${name} is not in compose_stacks.stacks, so it never runs`)),
+    ];
+};
+/** edge_routes: subdomains and an upstream host:port. */
+const routeFindings = (facts) => {
+    const routes = Array.isArray(facts.vars["edge_routes"]) ? facts.vars["edge_routes"] : [];
+    return routes.flatMap((route, index) => {
+        const fields = mapping(route);
+        const upstream = fields["upstream"];
+        return [
+            ...strings(fields["subdomains"])
+                .filter((sub) => !/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(sub))
+                .map((sub) => problem(`edge_routes[${String(index)}]: '${sub}' is not a subdomain`)),
+            ...(typeof upstream === "string" && /^[^\s:]+:\d+$/.test(upstream)
+                ? []
+                : [problem(`edge_routes[${String(index)}]: upstream must be host:port`)]),
+        ];
+    });
+};
+/** Each app's contract against the fleet's values for it. */
+const appFindings = (facts) => facts.server.apps.flatMap((app) => {
+    const manifest = facts.manifests[app.name];
+    if (manifest === undefined)
+        return [skipped(`app ${app.name} not checked: not cloned yet (kayra apps clones it)`)];
+    const parsed = appManifestSchema.safeParse(manifest);
+    if (!parsed.success)
+        return [problem(`app ${app.name}: its app.yml: ${parsed.error.issues.at(0)?.message ?? "invalid"}`)];
+    if (parsed.data.name !== app.name)
+        return [problem(`app ${app.name}: its app.yml says name ${parsed.data.name}`)];
+    const config = facts.appConfig[app.name] ?? {};
+    const missingConfig = (parsed.data.config ?? [])
+        .filter((key) => !(key in config))
+        .map((key) => problem(`apps/${app.name}.yml: no value for ${key}, which app.yml asks for`));
+    const secrets = facts.appSecrets[app.name];
+    const missingSecrets = secrets === undefined || secrets.kind === "locked"
+        ? (parsed.data.secrets ?? []).length === 0
+            ? []
+            : [skipped(`apps/${app.name}.secrets.yml not checked: ${secrets?.reason ?? "missing"}`)]
+        : (parsed.data.secrets ?? [])
+            .filter((key) => !(key in secrets.values))
+            .map((key) => problem(`apps/${app.name}.secrets.yml: no value for ${key}, which app.yml asks for`));
+    return [...missingConfig, ...missingSecrets];
+});
+/** Everything validate finds for one server, problems first. */
+export const findings = (facts) => [...secretsFindings(facts), ...stackFindings(facts), ...routeFindings(facts), ...appFindings(facts)].toSorted((a, b) => Number(b.problem) - Number(a.problem));
+/** One server's report: a line saying whether it holds, then each finding. */
+export const report = (name, found) => {
+    const problems = found.filter((each) => each.problem);
+    return [
+        `${problems.length === 0 ? "ok  " : "FAIL"} ${name}`,
+        ...found.map((each) => `     ${each.problem ? "✗" : "·"} ${each.text}`),
+    ];
+};

package/cli/dist/fleet.js

@@ -1,12 +1,23 @@
-import { parse } from "yaml";
+import { parseDocument } from "yaml";
 import { absolutePath, appName, domain, vaultPasswordFile, } from "./brand.js";
 import { all, err, map, ok } from "./result.js";
-export const serverKinds = ["platform", "edge", "nas"];
+import { serverKinds, serverSchema, varsSchema } from "./settings.js";
+import { checkSettings, checkShape, knownSettings } from "./validate.js";
+export { serverKinds };
 export const serverTargets = ["multipass", "hetzner", "home"];
 const mapping = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? Object.fromEntries(Object.entries(value)) : undefined;
+/** YAML text as a value; a syntax error is a value too, not an exception. */
+export const yamlOf = (text) => {
+    const document = parseDocument(text);
+    const problem = document.errors.at(0);
+    return problem === undefined ? ok(document.toJS()) : err(`is not valid YAML: ${problem.message.split("\n")[0] ?? ""}`);
+};
 const fields = (text) => {
-    const value = parse(text);
-    if (value === null)
+    const parsed = yamlOf(text);
+    if (!parsed.ok)
+        return parsed;
+    const value = parsed.value;
+    if (value === null || value === undefined)
         return ok({});
     const result = mapping(value);
     return result === undefined ? err("is not a YAML mapping") : ok(result);
@@ -90,6 +101,9 @@ export const parseServer = (files) => {
     const apps = all(declaredApps.map(app));
     if (!apps.ok)
         return apps;
+    const shape = checkShape("server.yml", descriptor.value, serverSchema);
+    if (!shape.ok)
+        return shape;
     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)
@@ -110,6 +124,9 @@ export const parseServer = (files) => {
     const vars = fields(files.vars);
     if (!vars.ok)
         return err(`vars.yml ${vars.error}`);
+    const varsChecked = checkSettings("vars.yml", vars.value, varsSchema(kind.value), knownSettings(kind.value));
+    if (!varsChecked.ok)
+        return varsChecked;
     const backupDir = mapping(vars.value["restic_backup"])?.["dir"];
     return ok({
         name: files.name,

package/cli/dist/gather.js

@@ -0,0 +1,57 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { yamlOf } from "./fleet.js";
+import { capture } from "./interpret.js";
+const text = (path) => (existsSync(path) ? readFileSync(path, "utf8") : undefined);
+const mappingOf = (source) => {
+    if (source === undefined)
+        return {};
+    const parsed = yamlOf(source);
+    return parsed.ok && typeof parsed.value === "object" && parsed.value !== null && !Array.isArray(parsed.value)
+        ? Object.fromEntries(Object.entries(parsed.value))
+        : {};
+};
+const vaulted = (source) => source.startsWith("$ANSIBLE_VAULT");
+/** A secrets file's values: plaintext as is, a vault only with the server's password file. */
+const secretsOf = async (server, path) => {
+    const source = text(path);
+    if (source === undefined)
+        return { kind: "locked", reason: "missing" };
+    if (!vaulted(source))
+        return { kind: "readable", values: mappingOf(source) };
+    if (server.vault.kind !== "file" || !existsSync(server.vault.file))
+        return { kind: "locked", reason: "vaulted, and no vault password file here" };
+    const opened = await capture(["ansible-vault", "view", "--vault-password-file", server.vault.file, path], "capture");
+    return opened.code === 0
+        ? { kind: "readable", values: mappingOf(opened.stdout) }
+        : { kind: "locked", reason: "the vault password does not open it" };
+};
+const appPath = (entry) => {
+    const parsed = JSON.parse(entry);
+    const path = typeof parsed === "object" && parsed !== null && "path" in parsed ? parsed.path : undefined;
+    return typeof path === "string" ? path : ".";
+};
+/** What validate needs of a server, read from the fleet (and its clones under .cache/apps). */
+export const gather = async (root, server) => {
+    const varsText = text(join(server.dir, "vars.yml")) ?? "";
+    const stacks = join(server.dir, "stacks");
+    const appSecrets = await Promise.all(server.apps.map(async (app) => [app.name, await secretsOf(server, join(server.dir, "apps", `${app.name}.secrets.yml`))]));
+    return {
+        server,
+        vars: mappingOf(varsText),
+        varsText,
+        secrets: await secretsOf(server, join(server.dir, "secrets.yml")),
+        stackDirs: existsSync(stacks)
+            ? readdirSync(stacks, { withFileTypes: true })
+                .filter((entry) => entry.isDirectory())
+                .map((entry) => entry.name)
+                .toSorted()
+            : [],
+        appConfig: Object.fromEntries(server.apps.map((app) => [app.name, mappingOf(text(join(server.dir, "apps", `${app.name}.yml`)))])),
+        appSecrets: Object.fromEntries(appSecrets),
+        manifests: Object.fromEntries(server.apps.flatMap((app) => {
+            const manifest = text(join(root, ".cache", "apps", app.name, appPath(app.entry), "app.yml"));
+            return manifest === undefined ? [] : [[app.name, mappingOf(manifest)]];
+        })),
+    };
+};

package/cli/dist/load.js

@@ -1,8 +1,10 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fleetRoot, serverDir, serverName, within } from "./brand.js";
-import { parseServer } from "./fleet.js";
-import { all, err, map, ok } from "./result.js";
+import { parseServer, yamlOf } from "./fleet.js";
+import { all, err, flatMap, map, ok } from "./result.js";
+import { defaultsSchema } from "./settings.js";
+import { checkSettings, knownSettings } from "./validate.js";
 /** The fleet is the nearest directory, from `from` upwards, with a servers/defaults.yml. */
 export const findFleetRoot = (from) => {
     if (existsSync(join(from, "servers", "defaults.yml")))
@@ -42,7 +44,20 @@ const readServer = (root, entry) => {
     });
     return server.ok ? server : err(`servers/${entry}/server.yml: ${server.error}`);
 };
-export const loadFleet = (root) => map(all(readdirSync(join(root, "servers"), { withFileTypes: true })
+/** servers/defaults.yml: settings shared by every server, any kind's. */
+const checkDefaults = (root) => {
+    const parsed = yamlOf(readFileSync(join(root, "servers", "defaults.yml"), "utf8"));
+    if (!parsed.ok)
+        return err(`servers/defaults.yml ${parsed.error}`);
+    const values = parsed.value;
+    if (values === null || values === undefined)
+        return ok(true);
+    if (typeof values !== "object" || Array.isArray(values))
+        return err("servers/defaults.yml is not a YAML mapping");
+    return map(checkSettings("servers/defaults.yml", Object.fromEntries(Object.entries(values)), defaultsSchema, knownSettings(undefined)), () => true);
+};
+export const loadFleet = (root) => flatMap(checkDefaults(root), () => fleetOf(root));
+const fleetOf = (root) => map(all(readdirSync(join(root, "servers"), { withFileTypes: true })
     .filter((entry) => entry.isDirectory() && existsSync(join(root, "servers", entry.name, "server.yml")))
     .map((entry) => entry.name)
     .toSorted()

package/cli/dist/main.js

@@ -7,6 +7,8 @@ import { parser } from "./cli.js";
 import { doctor } from "./commands/doctor.js";
 import * as server from "./commands/server.js";
 import { status } from "./commands/status.js";
+import { findings, report } from "./commands/validate.js";
+import { gather } from "./gather.js";
 import { serverNamed } from "./fleet.js";
 import { interpret } from "./interpret.js";
 import { findFleetRoot, loadFleet } from "./load.js";
@@ -31,6 +33,8 @@ const onServer = (on, target, command) => {
             return server.deploy(on, target);
         case "setup":
             return server.setup(on, target);
+        case "plan":
+            return server.preview(on, target);
         case "apps":
             return server.apps(on, target);
         case "hosts":
@@ -81,6 +85,16 @@ else {
     if (args.command.name === "status") {
         (await status(fleet.value)).forEach(io.out);
     }
+    else if (args.command.name === "validate") {
+        const chosen = args.command.server;
+        const servers = fleet.value.servers.filter((each) => chosen === undefined || each.name === chosen);
+        const reports = await Promise.all(servers.map(async (each) => findings(await gather(fleet.value.root, each))));
+        reports.forEach((found, index) => {
+            report(servers[index]?.name ?? "", found).forEach(io.out);
+        });
+        // eslint-disable-next-line functional/immutable-data -- the exit status; process.exit() could cut piped output short
+        process.exitCode = reports.some((found) => found.some((each) => each.problem)) ? 1 : 0;
+    }
     else {
         const steps = plan(fleet.value, args.command);
         if (!steps.ok)

package/cli/dist/schemas.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { appManifestSchema, appValuesSchema, defaultsSchema, serverKinds, serverSchema, settings, varsSchema, } from "./settings.js";
+const version = "https://json-schema.org/draft/2020-12/schema";
+const jsonSchema = (title, schema) => ({
+    ...z.toJSONSchema(schema, { target: "draft-2020-12", unrepresentable: "any" }),
+    $schema: version,
+    title,
+});
+/** The fleet's files as JSON Schemas, for editors: published in the package under schema/. */
+export const jsonSchemas = () => ({
+    "server.json": jsonSchema("server.yml", serverSchema),
+    "defaults.json": jsonSchema("defaults.yml", defaultsSchema),
+    ...Object.fromEntries(serverKinds.map((kind) => [`vars-${kind}.json`, jsonSchema(`vars.yml (kind ${kind})`, varsSchema(kind))])),
+    "app.json": jsonSchema("app.yml", appManifestSchema),
+    "app-values.json": jsonSchema("apps/<app>.yml and apps/<app>.secrets.yml", appValuesSchema),
+});
+const kindsOf = (each) => each.kinds.join(", ");
+/** MDX reads <…> as a component and {…} as an expression; a table cell's | ends it. */
+const escaped = (description) => description.replaceAll("|", "\\|").replaceAll("<", "&lt;").replaceAll("{", "&#123;").replaceAll("}", "&#125;");
+const row = (each) => `| \`${each.name}\` | ${kindsOf(each)} | ${escaped(each.description)} |`;
+const table = (chosen) => ["| Setting | Kinds | What it is |", "|---|---|---|", ...chosen.map(row)].join("\n");
+const editorLine = (kind) => `# yaml-language-server: $schema=../../node_modules/@yunuseon/kayra/schema/vars-${kind}.json`;
+/** The docs site's settings page, generated from the same registry as the schemas. */
+export const settingsPage = () => [
+    "---",
+    "title: Settings",
+    "description: Every setting a fleet can give its servers, generated from kayra's schemas.",
+    "---",
+    "",
+    "{/* Generated by `npm run schemas` from cli/src/settings.ts — edit there, not here. */}",
+    "",
+    "A server's `vars.yml` may set the settings of its kind and nothing else: an unknown key stops every",
+    "kayra command, with a suggestion where it looks like a typo. `servers/defaults.yml` holds settings",
+    "shared by every server. Secrets go in `secrets.yml` — a secret in `vars.yml` is refused.",
+    "",
+    "Editors complete and check these files from the JSON Schemas in the package (`schema/`), e.g. as",
+    "the first line of a platform server's `vars.yml`:",
+    "",
+    "```yaml",
+    editorLine("platform"),
+    "```",
+    "",
+    "## Settings",
+    "",
+    table(settings.filter((each) => !each.secret)),
+    "",
+    "## Secrets",
+    "",
+    table(settings.filter((each) => each.secret)),
+    "",
+    "Ansible's own variables (`ansible_*`) are allowed everywhere.",
+    "",
+].join("\n");