laneyard 0.1.0 → 0.3.0

package/dist/src/cli/setup.js

@@ -0,0 +1,282 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Document, parseDocument, YAMLSeq } from "yaml";
+import { VALID_NAME, ensureFirstAdmin, hasAccount } from "../config/accounts.js";
+import { loadServerConfig } from "../config/load.js";
+import { serializeYaml as serialize } from "../config/yaml.js";
+import { bad, bold, dim, field, heading, ok, warn } from "./style.js";
+import { acceptingAsker, terminalAsker } from "./prompt.js";
+import { detectProject } from "./detect.js";
+/**
+ * Adds a project block to config.yml while preserving the rest of the file.
+ *
+ * It writes no account: accounts are `ensureFirstAdmin`'s business, and a
+ * function that registered a project *and* invented a password would have two
+ * reasons to be called and one of them a surprise.
+ *
+ * The edit goes through the YAML document rather than a parse/serialize
+ * round trip: the user's comments — and the order of their keys — survive.
+ * It's the same requirement as for the Fastfile: a hand-written file must
+ * never come back out damaged.
+ */
+export async function addProjectToConfig(path, entry) {
+    let doc;
+    try {
+        doc = parseDocument(await readFile(path, "utf8"));
+    }
+    catch {
+        doc = new Document({});
+    }
+    if (doc.contents === null)
+        doc = new Document({});
+    const projects = doc.getIn(["projects"]);
+    const seq = projects instanceof YAMLSeq ? projects : new YAMLSeq();
+    if (!(projects instanceof YAMLSeq))
+        doc.setIn(["projects"], seq);
+    for (const item of seq.items) {
+        const slug = item.get?.("slug");
+        if (slug === entry.slug) {
+            throw new Error(`A project already uses the slug "${entry.slug}" in ${path}`);
+        }
+    }
+    seq.add(doc.createNode(entry));
+    await writeFile(path, serialize(doc), "utf8");
+}
+/**
+ * Takes a project's block out of config.yml, leaving the rest of the file alone.
+ *
+ * Same requirement as `addProjectToConfig`, and for the same reason: the file is
+ * hand-written, so the edit goes through the YAML document and every comment,
+ * key order and blank line that isn't this project's survives it.
+ *
+ * Returns false when no block carried that slug, so the caller can answer 404
+ * rather than rewrite the file to say the same thing it already said.
+ */
+export async function removeProjectFromConfig(path, slug) {
+    const doc = parseDocument(await readFile(path, "utf8"));
+    const projects = doc.getIn(["projects"]);
+    if (!(projects instanceof YAMLSeq))
+        return false;
+    const at = projects.items.findIndex((item) => item.get?.("slug") === slug);
+    if (at === -1)
+        return false;
+    projects.items.splice(at, 1);
+    await writeFile(path, serialize(doc), "utf8");
+    return true;
+}
+/**
+ * Entry point for `laneyard setup`.
+ *
+ * It proposes rather than decides. An earlier version detected everything
+ * silently and wrote a configuration that looked plausible and pointed nowhere —
+ * the failure only surfaced later, as an unreadable lane list, far from its
+ * cause. Showing the values and letting them be corrected costs one screen and
+ * removes a whole class of that.
+ */
+export async function runSetupCommand(cwd, configPath, options = {}) {
+    const d = await detectProject(cwd);
+    if (d.fastlaneDir === null) {
+        process.stderr.write("No Fastfile found here. Laneyard drives fastlane: run the command from a project " +
+            "that already uses it, or run `fastlane init` first.\n");
+        return 1;
+    }
+    if (d.gitUrl === null) {
+        process.stderr.write("No git remote named \"origin\". Laneyard clones projects from their repository: " +
+            "add a remote, or set git_url by hand in config.yml.\n");
+        return 1;
+    }
+    const interactive = options.asker === undefined && options.yes !== true;
+    const asker = options.asker ?? (options.yes ? acceptingAsker : terminalAsker());
+    try {
+        process.stdout.write(heading("Found a fastlane project"));
+        process.stdout.write(field("repository", repositoryLabel(d.gitUrl)) + "\n");
+        if (d.subPath !== "") {
+            process.stdout.write(field("in", `${d.subPath}/`) + "\n");
+        }
+        // Two files, two purposes, and the difference is the one thing people get
+        // wrong here — so it is stated before anything is written rather than
+        // discovered afterwards when nothing turns out to be versioned.
+        process.stdout.write("\n" +
+            dim("  Two files will describe it:\n") +
+            dim(`    ${LANEYARD_YML.padEnd(13)}in the repository — how it builds. Commit it.\n`) +
+            dim(`    ${"config.yml".padEnd(13)}on this machine — where to clone it from, and your\n`) +
+            dim(`                 password. Never committed.\n`));
+        const existing = await existingProject(configPath, d.slug);
+        if (existing) {
+            process.stdout.write("\n" +
+                warn(`This machine already knows a project called ${bold(existing)}.\n`) +
+                dim("  Continuing replaces its entry. Give it another name to keep both.\n"));
+        }
+        const repoConfigPath = join(repoRoot(cwd, d.subPath), LANEYARD_YML);
+        if (await fileExists(repoConfigPath)) {
+            process.stdout.write("\n" + warn(`${LANEYARD_YML} already exists in the repository.\n`) +
+                dim("  Its values win over anything written here; it will be left alone.\n"));
+        }
+        // A machine with no account gets its first admin here. Asked rather than
+        // assumed: the name is typed into a login form every day afterwards, and
+        // `admin` is a poor thing to call a person once there are two of them.
+        const firstAccount = !(await hasAccount(configPath));
+        if (firstAccount) {
+            process.stdout.write("\n" +
+                warn("This machine has no account yet.\n") +
+                dim("  You will sign in with a name and a password. The password is generated below.\n"));
+        }
+        if (interactive) {
+            process.stdout.write("\n" + dim("Press Return to accept a value, or type a new one.") + "\n\n");
+        }
+        const adminName = firstAccount
+            ? await asker.ask("your name for signing in", DEFAULT_ADMIN_NAME)
+            : null;
+        if (adminName !== null && !VALID_NAME.test(adminName)) {
+            process.stderr.write("\n" + bad(`Invalid name: "${adminName}". Letters, digits, dot, dash and underscore.`) + "\n");
+            return 1;
+        }
+        const slug = options.slug ?? (await asker.ask("name for this project", d.slug));
+        if (!/^[a-z0-9][a-z0-9-]*$/.test(slug)) {
+            process.stderr.write("\n" + bad(`Invalid name: "${slug}". Lowercase letters, digits and hyphens only.`) + "\n");
+            return 1;
+        }
+        const gitUrl = await asker.ask("repository", d.gitUrl);
+        const branch = await asker.ask("default branch", d.defaultBranch, dim("A run uses this branch unless you pick another one when you start it."));
+        const fastlaneDir = await asker.ask("fastlane directory", d.fastlaneDir, dim("Relative to the repository root, because that is what Laneyard clones."));
+        const useBundler = await asker.confirm("\n" +
+            dim("  With bundler, runs use the fastlane version pinned in the Gemfile.\n") +
+            dim("  Without it, whichever fastlane is installed on the build machine.\n") +
+            "  Run fastlane through bundler?", d.runtime === "bundle");
+        const runtime = useBundler ? "bundle" : "system";
+        // Artifact patterns are shown, not asked: typing four globs correctly at a
+        // prompt is a miserable way to start, the detected ones are nearly always
+        // right, and the file is there to be edited when they are not.
+        const globs = d.artifactGlobs;
+        if (!(await asker.confirm(`\n${bold(`Set up "${slug}"`)}?`, true))) {
+            process.stdout.write(dim("Nothing written.") + "\n");
+            return 0;
+        }
+        // The account first, so the server block is written before the project list
+        // it sits above. `null` when this machine already has one, and then nothing
+        // is written and nothing is printed.
+        const generatedPassword = adminName === null ? null : await ensureFirstAdmin(configPath, adminName);
+        // The machine half: how to reach the project. Nothing here belongs in a
+        // repository — it is this server's own registry, plus its credentials.
+        await addProjectToConfig(configPath, {
+            slug,
+            name: slug,
+            git_url: gitUrl,
+            default_branch: branch,
+        });
+        // The repository half: how it builds. This is the part that was going into
+        // the machine's file and therefore never being committed — which is exactly
+        // backwards, since it is the part a colleague needs.
+        const wroteRepoConfig = await writeRepoConfigIfAbsent(repoConfigPath, {
+            fastlane_dir: fastlaneDir,
+            runtime,
+            artifact_globs: globs,
+            // Written down rather than re-inferred on every readiness check: a value
+            // in a file can be corrected when the guess was wrong, and setup and the
+            // checklist cannot end up disagreeing about the same repository.
+            ...(d.platforms.length > 0 ? { platforms: d.platforms } : {}),
+        });
+        const port = await configuredPort(configPath);
+        process.stdout.write(heading(`Project "${slug}" is set up`) +
+            field("repository", `${gitUrl} (${branch})`) + "\n" +
+            field("fastlane", fastlaneDir) + "\n" +
+            field("runtime", runtime) + "\n" +
+            field("artifacts", globs.join(", ") || dim("none detected")) + "\n" +
+            // Shown because it decides which half of the readiness checklist a
+            // project is held to, and because a wrong guess is corrected by editing
+            // one line of the file just written.
+            field("platforms", d.platforms.join(", ") || dim("none detected")) + "\n" +
+            "\n" +
+            (wroteRepoConfig
+                ? ok(`Wrote ${bold(LANEYARD_YML)} — ${bold("commit it")} so your team builds the same way.\n`)
+                : warn(`Left the existing ${LANEYARD_YML} alone.\n`)) +
+            ok(`Registered in ${configPath}\n`) +
+            // Last thing before the invitation to start the server, because it is
+            // the one line here that cannot be read again anywhere: the file holds
+            // a hash, and nothing holds the password.
+            (generatedPassword === null
+                ? ""
+                : heading("Your account") +
+                    field("name", bold(adminName)) + "\n" +
+                    field("password", bold(generatedPassword)) + "\n" +
+                    field("role", "admin") + "\n" +
+                    "\n" +
+                    warn("Write the password down — it is not shown again, and it is not stored.\n") +
+                    dim("  Add a colleague later with `laneyard user add <name> --role builder`.\n")) +
+            heading("Start Laneyard") +
+            `  ${bold("laneyard")}\n` +
+            `  ${dim(`http://localhost:${port}`)}\n` +
+            "\n" +
+            dim("Already running? The configuration is watched — it appears on its own.\n"));
+        return 0;
+    }
+    finally {
+        asker.close();
+    }
+}
+/**
+ * The port the server will actually listen on.
+ *
+ * Read back from the file rather than assumed: telling someone to open a port
+ * their configuration does not use is the kind of small wrongness that makes a
+ * tool feel unreliable on first contact.
+ */
+async function configuredPort(configPath) {
+    const res = await loadServerConfig(configPath);
+    return res.ok ? res.config.server.port : 7890;
+}
+/** The repository file, named once so the message and the write cannot disagree. */
+const LANEYARD_YML = "laneyard.yml";
+/**
+ * What the first account is called when nobody says otherwise.
+ *
+ * The same name a lone `password_hash` is read under, so a machine set up today
+ * and a machine upgraded from 0.2 sign in the same way.
+ */
+const DEFAULT_ADMIN_NAME = "admin";
+/**
+ * The repository root, from where the command ran and how deep it sits.
+ *
+ * `laneyard.yml` belongs at the root because that is where the server reads it:
+ * the clone is the repository, not the sub-directory someone was standing in.
+ */
+function repoRoot(cwd, subPath) {
+    return subPath === "" ? cwd : join(cwd, ...subPath.split("/").map(() => ".."));
+}
+const fileExists = async (path) => {
+    try {
+        await readFile(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** The name already registered under this slug, or null. */
+async function existingProject(configPath, slug) {
+    const res = await loadServerConfig(configPath);
+    if (!res.ok)
+        return null;
+    return res.config.projects.find((p) => p.slug === slug)?.slug ?? null;
+}
+/**
+ * Writes the repository's build configuration, unless it is already there.
+ *
+ * Never overwrites: a `laneyard.yml` in a repository was put there by someone,
+ * possibly with comments and choices this command knows nothing about, and its
+ * values win anyway.
+ */
+async function writeRepoConfigIfAbsent(path, settings) {
+    if (await fileExists(path))
+        return false;
+    const doc = new Document(settings);
+    doc.commentBefore =
+        " How this project builds. Committed, so everyone builds it the same way.\n" +
+            " Values here win over the project's block in the server's config.yml.";
+    await writeFile(path, doc.toString(), "utf8");
+    return true;
+}
+/** `git@github.com:you/thing.git` reads better as `you/thing` in a sentence. */
+function repositoryLabel(url) {
+    return url.replace(/^.*[:/]([^/:]+\/[^/]+?)(\.git)?$/, "$1");
+}

package/dist/src/cli/style.js

@@ -0,0 +1,31 @@
+/**
+ * The little colour this command needs, and no library to provide it.
+ *
+ * The palette is the product's own: green for what is settled, amber for what
+ * wants attention, dim for what is context. Nothing here is decorative — a
+ * colour that means nothing trains people to stop reading colours.
+ */
+/**
+ * Colour is dropped when the output is not a terminal, or when `NO_COLOR` is
+ * set. Escape codes in a piped log or a CI transcript are noise at best, and at
+ * worst they end up quoted into a bug report.
+ */
+const enabled = () => process.env["NO_COLOR"] === undefined && process.stdout.isTTY === true;
+const wrap = (code) => (text) => enabled() ? `[${code}m${text}` : text;
+export const bold = wrap("1");
+export const dim = wrap("2");
+export const green = wrap("32");
+export const amber = wrap("33");
+export const red = wrap("31");
+/** A heading: bold, with a blank line above it so sections breathe. */
+export const heading = (text) => `\n${bold(text)}\n`;
+/** `✓`, `▸`, `✗` in the same meanings they carry in the interface. */
+export const ok = (text) => `${green("✓")} ${text}`;
+export const warn = (text) => `${amber("▸")} ${text}`;
+export const bad = (text) => `${red("✗")} ${text}`;
+/**
+ * A `key   value` line, aligned so a block of them reads as a column.
+ * The width is fixed rather than computed: these labels are known and short,
+ * and a column that shifts between runs is harder to scan than a wide one.
+ */
+export const field = (label, value) => `  ${dim(label.padEnd(13))}${value}`;

package/dist/src/cli/user.js

@@ -0,0 +1,127 @@
+import { join } from "node:path";
+import { MIN_PASSWORD_LENGTH, VALID_NAME, hasAccount, refusalFor, upsertUserInConfig, } from "../config/accounts.js";
+import { loadServerConfig } from "../config/load.js";
+export const USER_USAGE = `laneyard user add <name> [--role admin|builder]
+
+The password is read from standard input, never from an argument:
+
+  echo "$PASSWORD" | laneyard user add renaud --role builder
+
+Without --role, the account is a builder: it can start a build, watch it, cancel
+it and download what it produced. An admin can do everything besides.
+`;
+const ROLES = ["admin", "builder"];
+/**
+ * Reads standard input whole.
+ *
+ * A single trailing newline is dropped: `echo "$PASSWORD" |` adds one, and a
+ * password that silently gained a `\n` is a password that never works again,
+ * with nothing on screen to explain why.
+ */
+async function readPassword(stdin) {
+    const chunks = [];
+    for await (const chunk of stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8").replace(/\r?\n$/, "");
+}
+function parse(args) {
+    let name = null;
+    // The role that can do the least, when nobody says. An account that turns out
+    // to need more is one command away; an account that quietly had more than it
+    // needed is found out later, differently.
+    let role = "builder";
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--role" || arg === "-r") {
+            const next = args[i + 1];
+            if (next === undefined || next.startsWith("-"))
+                return `--role needs ${ROLES.join(" or ")}.`;
+            if (!ROLES.includes(next))
+                return `Unknown role: ${next}. It is ${ROLES.join(" or ")}.`;
+            role = next;
+            i += 1;
+        }
+        else if (arg.startsWith("-")) {
+            return `Unknown option: ${arg}`;
+        }
+        else if (name === null) {
+            name = arg;
+        }
+        else {
+            // A second bare argument is almost certainly the password typed on the
+            // command line — exactly what this command exists to prevent.
+            return "The password is read from standard input, not from the command line.";
+        }
+    }
+    if (name === null)
+        return "Which account? Give it a name.";
+    return { name, role };
+}
+/**
+ * Entry point for `laneyard user`.
+ *
+ * Nothing it prints ever contains the password — not on success, not in an
+ * error. A terminal keeps scrollback and a shell keeps history; reading from
+ * stdin would be pointless if the value came straight back out.
+ */
+export async function runUserCommand(home, args, io) {
+    const [subcommand, ...rest] = args;
+    if (subcommand !== "add") {
+        io.err(subcommand === undefined ? USER_USAGE : `Unknown subcommand: ${subcommand}\n\n${USER_USAGE}`);
+        return 1;
+    }
+    const parsed = parse(rest);
+    if (typeof parsed === "string") {
+        io.err(`${parsed}\n\n${USER_USAGE}`);
+        return 1;
+    }
+    if (!VALID_NAME.test(parsed.name)) {
+        io.err(`"${parsed.name}" is not a name: letters, digits, dot, dash and underscore, ` +
+            "starting with a letter or a digit.\n");
+        return 1;
+    }
+    const configPath = join(home, "config.yml");
+    // A machine with no account at all is a machine that has not been set up. It
+    // is refused here rather than given its first account, because that first
+    // account has to be an admin and this command would happily write a lone
+    // builder — a configuration the server then refuses to load.
+    if (!(await hasAccount(configPath))) {
+        io.err(`No account yet in ${configPath}.\n` +
+            "Run `laneyard setup` from a project that uses fastlane: it creates the first admin.\n");
+        return 1;
+    }
+    const loaded = await loadServerConfig(configPath);
+    if (!loaded.ok) {
+        // Refused rather than written blind: the accounts already in the file are
+        // what says whether this change leaves the server with an admin.
+        io.err(`Unreadable configuration in ${configPath}: ${loaded.error}\n`);
+        return 1;
+    }
+    const existing = loaded.config.server.users;
+    const refusal = refusalFor(existing, parsed.name, parsed.role);
+    if (refusal) {
+        io.err(`${refusal}\n`);
+        return 1;
+    }
+    if (io.interactive) {
+        io.err("The password is read from standard input, and standard input is a terminal.\n" +
+            "Pipe it in instead, so it stays out of your shell history:\n\n" +
+            `  echo "$PASSWORD" | laneyard user add ${parsed.name} --role ${parsed.role}\n`);
+        return 1;
+    }
+    const password = await readPassword(io.stdin);
+    if (password === "") {
+        io.err("Nothing came in on standard input, so there is no password to set.\n");
+        return 1;
+    }
+    if (password.length < MIN_PASSWORD_LENGTH) {
+        io.err(`A password is at least ${MIN_PASSWORD_LENGTH} characters.\n`);
+        return 1;
+    }
+    const { created } = await upsertUserInConfig(configPath, { ...parsed, password });
+    io.out(`✓ ${parsed.name}  ${parsed.role}  ${created ? "added" : "replaced"}\n` +
+        // The server watches config.yml, so this takes effect without a restart.
+        // Saying so is what stops someone from restarting a build server for it.
+        "  the running server picks this up on its own.\n");
+    return 0;
+}

package/dist/src/config/accounts.js

@@ -0,0 +1,163 @@
+import { randomBytes } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { Document, parseDocument, YAMLSeq } from "yaml";
+import { hashPassword } from "../server/auth.js";
+import { LEGACY_ADMIN_NAME } from "./load.js";
+import { serializeYaml } from "./yaml.js";
+/**
+ * Accounts, as they are written to and taken out of config.yml.
+ *
+ * The API and the CLI both go through here, so that "add a builder" means the
+ * same thing however it was asked for — including the two refusals, which are
+ * decided here rather than twice, differently.
+ */
+/** Same rule as the schema. Stated once and read from both the API and the CLI. */
+export const VALID_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+/**
+ * The shortest password that may be stored.
+ *
+ * Not a policy in the corporate sense — there is no expiry and no character
+ * classes. It is the length below which scrypt's cost stops mattering, because
+ * the whole space can be walked through faster than one honest login.
+ */
+export const MIN_PASSWORD_LENGTH = 8;
+/**
+ * Why a change to the accounts must be refused, or null when it may proceed.
+ *
+ * `role` is the role the account will carry afterwards, or null when it is
+ * being removed. Both refusals are the same refusal: a server whose last admin
+ * is gone or demoted is a locked room — the interface offers nothing that can
+ * put an admin back, and the only way out is editing YAML by hand.
+ */
+export function refusalFor(users, name, role) {
+    const admins = users.filter((u) => u.role === "admin");
+    const isLastAdmin = admins.length === 1 && admins[0].name === name;
+    if (!isLastAdmin || role === "admin")
+        return null;
+    return role === null
+        ? `${name} is the only admin. Removing them would leave a server nobody can administer — ` +
+            "make someone else an admin first."
+        : `${name} is the only admin. Demoting them would leave a server nobody can administer — ` +
+            "make someone else an admin first.";
+}
+/** Reads config.yml as a document, or starts an empty one when there is no file. */
+async function open(path) {
+    let doc;
+    try {
+        doc = parseDocument(await readFile(path, "utf8"));
+    }
+    catch {
+        doc = new Document({});
+    }
+    if (doc.contents === null)
+        doc = new Document({});
+    return doc;
+}
+/**
+ * Turns a lone `server.password_hash` into the `users` form, in place.
+ *
+ * A file holding both is the one combination the loader refuses, so adding a
+ * colleague to a 0.2 installation has to migrate it — otherwise the act of
+ * inviting someone is the act of breaking the server's configuration.
+ *
+ * The name is the one the loader already reads that hash under, so nobody's
+ * password changes meaning on the way through.
+ */
+function migrateLegacyHash(doc) {
+    const hash = doc.getIn(["server", "password_hash"]);
+    if (typeof hash !== "string")
+        return;
+    doc.deleteIn(["server", "password_hash"]);
+    if (doc.hasIn(["server", "users"]))
+        return;
+    doc.setIn(["server", "users"], doc.createNode([{ name: LEGACY_ADMIN_NAME, role: "admin", password_hash: hash }]));
+}
+/** The accounts sequence, created if the file has none yet. */
+function usersSeq(doc) {
+    const existing = doc.getIn(["server", "users"]);
+    if (existing instanceof YAMLSeq)
+        return existing;
+    const seq = new YAMLSeq();
+    doc.setIn(["server", "users"], seq);
+    return seq;
+}
+const nameOf = (item) => item.get?.("name");
+/**
+ * Writes an account into config.yml, replacing one of the same name.
+ *
+ * The edit goes through the YAML document rather than a parse/serialize round
+ * trip, for the same reason as every other edit to this file: it is
+ * hand-written, and comments and key order must survive being touched.
+ *
+ * Returns whether the account is new, which is the difference between 201 and
+ * 200 and between "created" and "replaced" in a sentence.
+ */
+export async function upsertUserInConfig(path, entry) {
+    const doc = await open(path);
+    migrateLegacyHash(doc);
+    const seq = usersSeq(doc);
+    const stored = {
+        name: entry.name,
+        role: entry.role,
+        password_hash: hashPassword(entry.password),
+    };
+    const at = seq.items.findIndex((item) => nameOf(item) === entry.name);
+    const node = doc.createNode(stored);
+    if (at === -1)
+        seq.add(node);
+    else
+        seq.items[at] = node;
+    await writeFile(path, serializeYaml(doc), "utf8");
+    return { created: at === -1 };
+}
+/**
+ * Takes an account out of config.yml, leaving the rest of the file alone.
+ *
+ * Returns false when no account carried that name, so the caller can answer 404
+ * rather than rewrite the file to say what it already said.
+ */
+export async function removeUserFromConfig(path, name) {
+    const doc = await open(path);
+    migrateLegacyHash(doc);
+    const users = doc.getIn(["server", "users"]);
+    if (!(users instanceof YAMLSeq))
+        return false;
+    const at = users.items.findIndex((item) => nameOf(item) === name);
+    if (at === -1)
+        return false;
+    users.items.splice(at, 1);
+    await writeFile(path, serializeYaml(doc), "utf8");
+    return true;
+}
+/**
+ * Does this file already declare somebody, in either of the two forms?
+ *
+ * Asked before a question is put to the user rather than after: `laneyard setup`
+ * only asks for an admin's name on a machine that has none, and asking anyway
+ * and then ignoring the answer would be worse than not asking.
+ */
+export async function hasAccount(path) {
+    const doc = await open(path);
+    return doc.hasIn(["server", "password_hash"]) || doc.hasIn(["server", "users"]);
+}
+/**
+ * Creates the first admin if the file declares no account at all.
+ *
+ * Returns the generated password, once, for the caller to print — or null when
+ * an account already existed and nothing was written. The password is generated
+ * rather than asked for because this runs inside `laneyard setup`, where a
+ * prompt for a password would be one more thing to invent while trying to do
+ * something else entirely.
+ */
+export async function ensureFirstAdmin(path, name) {
+    const doc = await open(path);
+    if (doc.hasIn(["server", "password_hash"]) || doc.hasIn(["server", "users"]))
+        return null;
+    const password = randomBytes(9).toString("base64url");
+    // The `users` form, never a bare `password_hash`: writing the legacy shape on
+    // a fresh machine would mean every new installation immediately needs the
+    // migration above the first time someone adds a colleague.
+    doc.setIn(["server", "users"], doc.createNode([{ name, role: "admin", password_hash: hashPassword(password) }]));
+    await writeFile(path, serializeYaml(doc), "utf8");
+    return password;
+}