laneyard 0.2.0 → 0.4.0

package/dist/src/cli/secret-import.js

@@ -0,0 +1,162 @@
+import { access, readFile } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { parseEnvExample } from "../heuristics/env-example.js";
+/**
+ * Bringing an existing `fastlane/.env` into the vault.
+ *
+ * Every project that already builds has its variables somewhere, and that
+ * somewhere is almost always `fastlane/.env` — gitignored, on one laptop, and
+ * therefore absent from the clone a build server works from. Typing eight
+ * values into a web form to reproduce a file that is already on disk is a poor
+ * way to start, and the sort of chore where one typo costs an evening.
+ *
+ * This runs from the CLI and not from the server on purpose: the `.env` exists
+ * where the working copy is, and the server only ever sees a clone.
+ *
+ * Values are never printed, never logged, and never passed as arguments. What
+ * the command shows is names.
+ */
+/**
+ * The variables whose value is a *path*, and the name their *contents* belong
+ * under.
+ *
+ * This is the translation that makes an import worth doing. `SUPPLY_JSON_KEY`
+ * points at a service account JSON on this laptop; copied verbatim into the
+ * vault it would point at nothing on the build machine, and the run would fail
+ * exactly as it does today. What has to travel is the file, so the file is
+ * read and stored under `SUPPLY_JSON_KEY_DATA` — a name supply reads on its
+ * own, verified against fastlane 2.237.
+ *
+ * There is no such entry for a `.p8`. `APP_STORE_CONNECT_API_KEY_P8` was one —
+ * an earlier version of this interface invented it, no action in fastlane has
+ * ever declared it, and the interface has since dropped it. See `P8_PATH_NAMES`
+ * for what a `.p8` path becomes instead.
+ */
+export const PATH_TO_CONTENTS = {
+    SUPPLY_JSON_KEY: "SUPPLY_JSON_KEY_DATA",
+    GOOGLE_APPLICATION_CREDENTIALS: "SUPPLY_JSON_KEY_DATA",
+};
+/**
+ * Variables that name a `.p8` the way projects and this interface's own
+ * earlier version did.
+ *
+ * None of them is a name fastlane reads: the App Store Connect action takes
+ * its key from `key_id`, `issuer_id` and a file, not from an environment
+ * variable an import could invent on its own. What this command can do
+ * honestly is find the file and say where it belongs — an App Store Connect
+ * key block, uploaded from the secrets tab with the two fields the file alone
+ * cannot supply.
+ */
+export const P8_PATH_NAMES = new Set([
+    "ASC_KEY_FILEPATH",
+    "APP_STORE_CONNECT_API_KEY_PATH",
+    "APP_STORE_CONNECT_API_KEY_FILEPATH",
+]);
+/**
+ * Reads a `.env` into a name → value map.
+ *
+ * Shares `parseEnvExample`'s idea of what a line is, and adds the values, which
+ * that one deliberately drops. Quotes are stripped because a `.env` written by
+ * hand often has them and fastlane's own dotenv strips them too — a value that
+ * silently kept its quotes is a credential that never works, with nothing on
+ * screen to say why.
+ */
+export function parseEnvFile(content) {
+    const out = new Map();
+    for (const name of parseEnvExample(content)) {
+        // Re-scan for this name's value; `parseEnvExample` already vouched for the
+        // name, so this only has to find the last assignment, the way dotenv does.
+        for (const raw of content.split("\n")) {
+            const line = raw.trim().replace(/^export\s+/, "");
+            const eq = line.indexOf("=");
+            if (eq <= 0 || line.slice(0, eq).trim() !== name)
+                continue;
+            let value = line.slice(eq + 1).trim();
+            const quoted = /^(["'])(.*)\1$/.exec(value);
+            if (quoted)
+                value = quoted[2];
+            out.set(name, value);
+        }
+    }
+    return out;
+}
+/**
+ * Decides what would be stored, without storing anything.
+ *
+ * Separate from the writing so the command can show its work first. An import
+ * that reads eight files and writes eight secrets before saying a word is one
+ * nobody can check.
+ */
+export async function planImport(env, cwd, existingKeys) {
+    const planned = [];
+    const already = new Set(existingKeys);
+    for (const [name, value] of env) {
+        if (value === "")
+            continue;
+        if (P8_PATH_NAMES.has(name)) {
+            const path = isAbsolute(value) ? value : resolve(cwd, value);
+            const found = await access(path)
+                .then(() => true)
+                .catch(() => false);
+            if (!found) {
+                // Same handling as any other missing file: reported, not skipped in
+                // silence, because it is the credential the project most needs.
+                planned.push({ key: name, kind: "unresolved-path", path, value });
+                continue;
+            }
+            // The file is real, but nothing is stored under `name` — there is
+            // nowhere fastlane would read it from. Left to the caller to say what
+            // to do instead, in the same voice as the rest of the plan.
+            planned.push({ key: name, kind: "suggest-block", path, value });
+            continue;
+        }
+        const contentsKey = PATH_TO_CONTENTS[name];
+        if (contentsKey) {
+            const path = isAbsolute(value) ? value : resolve(cwd, value);
+            const contents = await readFile(path, "utf8").catch(() => null);
+            if (contents === null) {
+                // Named a file that is not there. Reported rather than skipped: it is
+                // the credential the project most needs, and silence would read as
+                // success.
+                planned.push({ key: name, kind: "unresolved-path", path, value });
+                continue;
+            }
+            planned.push({
+                key: contentsKey,
+                ...(contentsKey === name ? {} : { from: name }),
+                kind: "file-contents",
+                path,
+                value: contents,
+            });
+            continue;
+        }
+        planned.push({ key: name, kind: "value", value });
+    }
+    return {
+        planned,
+        replacing: planned
+            .filter((p) => p.kind !== "unresolved-path" && p.kind !== "suggest-block" && already.has(p.key))
+            .map((p) => p.key),
+    };
+}
+/**
+ * Writes the plan into the vault.
+ *
+ * Everything is masked. A value that came out of a `.env` is a credential by
+ * assumption — that is what the file is for — and the one that turns out not to
+ * be secret costs a redacted line in a log, while the reverse costs a leak.
+ */
+export async function applyImport(vault, slug, plan) {
+    let stored = 0;
+    for (const item of plan.planned) {
+        if (item.kind === "unresolved-path" || item.kind === "suggest-block")
+            continue;
+        await vault.set(slug, item.key, item.value, true);
+        stored += 1;
+    }
+    return stored;
+}
+/** Where a project's `.env` files live, in the order dotenv itself reads them. */
+export function envFilesIn(fastlaneDir) {
+    return [join(fastlaneDir, ".env.default"), join(fastlaneDir, ".env")];
+}

package/dist/src/cli/secret.js

@@ -1,17 +1,29 @@
+import { execFile } from "node:child_process";
 import { join } from "node:path";
+import { promisify } from "node:util";
+import { readFile } from "node:fs/promises";
+import { applyImport, envFilesIn, parseEnvFile, planImport } from "./secret-import.js";
 import { ConfigStore } from "../config/store.js";
 import { openDatabase } from "../db/open.js";
+import { CredentialStore } from "../db/credentials.js";
 import { SecretStore } from "../db/secrets.js";
 import { MIN_LENGTH as MIN_REDACTABLE } from "../logs/redact.js";
 import { Vault } from "../secrets/vault.js";
 /** Same rule as the API: what cannot become an environment variable is refused here too. */
 const VALID_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
 export const SECRET_USAGE = `laneyard secret set <NAME> [--project <slug>] [--no-mask]
+laneyard secret import --project <slug> [--yes]
 
 The value is read from standard input, never from an argument:
 
   laneyard secret set MATCH_PASSWORD --project app
   echo "$TOKEN" | laneyard secret set GITHUB_TOKEN
+
+\`import\` reads this project's fastlane/.env and stores what it finds. A
+variable naming a service account JSON has the *file* stored, under the name
+fastlane looks for — a path does not travel to a build machine. A variable
+naming a .p8 is left alone and reported instead: that credential belongs in a
+signing block from the secrets tab, not in a loose variable.
 `;
 /**
  * Reads standard input whole.
@@ -69,6 +81,9 @@ function parse(args) {
  */
 export async function runSecretCommand(home, args, io) {
     const [subcommand, ...rest] = args;
+    if (subcommand === "import") {
+        return runSecretImport(home, rest, io);
+    }
     if (subcommand !== "set") {
         io.err(subcommand === undefined ? `${SECRET_USAGE}` : `Unknown subcommand: ${subcommand}\n\n${SECRET_USAGE}`);
         return 1;
@@ -121,7 +136,7 @@ export async function runSecretCommand(home, args, io) {
     }
     const db = openDatabase(join(home, "laneyard.db"));
     try {
-        const vault = await Vault.open(home, new SecretStore(db));
+        const vault = await Vault.open(home, new SecretStore(db), new CredentialStore(db));
         await vault.set(parsed.project, parsed.key, value, parsed.masked);
     }
     finally {
@@ -131,3 +146,149 @@ export async function runSecretCommand(home, args, io) {
         `  ${parsed.masked ? "kept out of the logs" : "shown in the logs"}\n`);
     return 0;
 }
+/**
+ * `laneyard secret import` — the existing `.env` into the vault.
+ *
+ * Shows what it would do before doing it, in names only. An import that reads
+ * eight files and writes eight secrets before saying a word is one nobody can
+ * check, and this is the one command that handles every credential a project
+ * has at once.
+ */
+async function runSecretImport(home, args, io) {
+    let project = null;
+    let yes = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--project" || arg === "-p") {
+            const next = args[i + 1];
+            if (next === undefined || next.startsWith("-")) {
+                io.err("--project needs a slug.\n");
+                return 1;
+            }
+            project = next;
+            i += 1;
+        }
+        else if (arg === "--yes" || arg === "-y") {
+            yes = true;
+        }
+        else {
+            io.err(`Unknown option: ${arg}\n\n${SECRET_USAGE}`);
+            return 1;
+        }
+    }
+    if (project === null) {
+        io.err("Which project? Give it with --project <slug>.\n");
+        return 1;
+    }
+    const config = new ConfigStore(join(home, "config.yml"));
+    const loaded = await config.load();
+    if (!loaded.ok) {
+        io.err(`Unreadable configuration in ${join(home, "config.yml")}: ${loaded.error}\n`);
+        return 1;
+    }
+    const entry = config.project(project);
+    if (!entry) {
+        const known = config.projects().map((p) => p.slug);
+        io.err(`Unknown project: "${project}".` +
+            (known.length > 0 ? ` Known projects: ${known.join(", ")}.` : " No project is declared yet.") +
+            "\n");
+        return 1;
+    }
+    // Read from the working copy this command was run in — the only place a
+    // gitignored `.env` exists; the server's clone never has one.
+    //
+    // Resolved against the repository root, not the current directory:
+    // `fastlane_dir` is recorded relative to the root, so running this from
+    // `app/` would otherwise look for `app/app/fastlane/.env`. The same
+    // confusion, one command along, as the one that produced an ENOENT in the
+    // lane list.
+    const fastlaneDir = entry.fastlane_dir ?? "fastlane";
+    const root = await repositoryRoot(process.cwd());
+    const env = new Map();
+    const readFrom = [];
+    for (const file of envFilesIn(fastlaneDir)) {
+        const text = await readFile(join(root, file), "utf8").catch(() => null);
+        if (text === null)
+            continue;
+        readFrom.push(file);
+        for (const [k, v] of parseEnvFile(text))
+            env.set(k, v);
+    }
+    if (readFrom.length === 0) {
+        io.err(`No ${fastlaneDir}/.env under ${root}. Run this from the working copy that has one — ` +
+            "it is the file that never reaches a clone, which is the whole reason for this command.\n");
+        return 1;
+    }
+    const db = openDatabase(join(home, "laneyard.db"));
+    try {
+        const vault = await Vault.open(home, new SecretStore(db), new CredentialStore(db));
+        // Paths inside a `.env` are written relative to where fastlane runs, which
+        // is the fastlane directory's parent — the app, not the repository root.
+        const plan = await planImport(env, join(root, fastlaneDir, ".."), vault.list(project).map((s) => s.key));
+        if (plan.planned.length === 0) {
+            io.out(`Nothing to import from ${readFrom.join(" and ")}.\n`);
+            return 0;
+        }
+        io.out(`\nFrom ${readFrom.join(" and ")}, into "${project}":\n\n`);
+        for (const item of plan.planned) {
+            if (item.kind === "unresolved-path") {
+                io.out(`  ✗ ${item.key} — names ${item.path}, which is not there. Skipped.\n`);
+            }
+            else if (item.kind === "suggest-block") {
+                io.out(`  ▸ ${item.key} names ${item.path} — no action in fastlane reads that variable. ` +
+                    "Upload the `.p8` as an App Store Connect key block from the secrets tab instead, with " +
+                    "its key id and issuer id. Not imported here.\n");
+            }
+            else if (item.kind === "file-contents") {
+                io.out(`  ● ${item.key}${item.from ? ` (the contents of ${item.from})` : ""}\n`);
+            }
+            else {
+                io.out(`  ● ${item.key}\n`);
+            }
+        }
+        if (plan.replacing.length > 0) {
+            io.out(`\n  ${plan.replacing.join(", ")} already in the vault — they will be replaced.\n`);
+        }
+        const skipped = plan.planned.filter((p) => p.kind === "unresolved-path");
+        if (skipped.length > 0) {
+            io.out("\n  A skipped file is the credential this project most needs. Check the path.\n");
+        }
+        if (!yes) {
+            io.out("\nNothing is written yet. Run it again with --yes to store these.\n");
+            return 0;
+        }
+        const stored = await applyImport(vault, project, plan);
+        io.out(`\n✓ Stored ${stored} ${stored === 1 ? "secret" : "secrets"}, all kept out of the logs.\n`);
+        // Said here because it is easy to assume an import leaves lanes with
+        // homework. It does not: `key_filepath:` and `json_key:` are the supported
+        // forms, not a stopgap. A signing credential block writes its file to disk
+        // for the length of a run, so a lane that names a path keeps reading a
+        // real one, unedited.
+        io.out("\nNothing in your lanes needs to change. `key_filepath:` and `json_key:` keep working as " +
+            "written. From here, a `.p8` or a service account JSON belongs in a signing credential block " +
+            "from the secrets tab, not as a loose variable in this file.\n");
+        return 0;
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * The repository root, or the directory given if this is not a repository.
+ *
+ * `fastlane_dir` is recorded relative to the root — that is what the clone is
+ * measured from — so anything resolving it has to agree about where the root is,
+ * whichever sub-directory the command happens to be run from.
+ */
+async function repositoryRoot(from) {
+    try {
+        const { stdout } = await promisify(execFile)("git", ["rev-parse", "--show-toplevel"], {
+            cwd: from,
+            timeout: 5_000,
+        });
+        return stdout.trim() || from;
+    }
+    catch {
+        return from;
+    }
+}

package/dist/src/cli/setup.js

@@ -0,0 +1,319 @@
+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);
+    // An entry of the same name is updated, not refused.
+    //
+    // Setup prints "Continuing replaces its entry" before asking anything, and
+    // then this threw — so the one way to correct a stale entry, running setup
+    // again, was the one thing that could not be done. A project written by an
+    // older version and missing a field it now needs was unfixable except by hand.
+    //
+    // Field by field rather than wholesale, though the warning says "replaces":
+    // an entry may carry things setup knows nothing about — a `git_auth` pointing
+    // at an SSH key, a raised `timeout_minutes` — and losing those silently, on a
+    // command someone ran to fix something else, would be its own bug.
+    const existing = seq.items.find((item) => item.get?.("slug") === entry.slug);
+    if (existing?.set) {
+        for (const [key, value] of Object.entries(entry))
+            existing.set(key, value);
+    }
+    else {
+        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 updates its entry, keeping anything you added by hand.\n") +
+                dim("  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,
+            // Written on this machine too, and only when it is not the default,
+            // because of the gap between the two files. Laneyard builds from a clone
+            // of the remote, so nothing written into the working copy reaches it
+            // until `laneyard.yml` is committed and pushed — and until then
+            // `fastlane_dir` falls back to `fastlane`, which in a monorepo is not
+            // where anything is. The project was unreadable from the moment setup
+            // finished until a git push, with an ENOENT for an explanation.
+            //
+            // This is not a second source of truth: the repository file wins the
+            // moment it lands, which is the precedence `config.yml` already
+            // documents and the schema already allows. It is the value setup just
+            // proposed and the user just accepted, kept where it is useful until the
+            // authoritative copy arrives.
+            //
+            // Omitted when it *is* the default, so an ordinary project's block stays
+            // about how the project is reached and nothing else.
+            // Both of the fields the sidecar needs before it can read anything, and
+            // only when they are not already the default. `runtime` belongs here for
+            // exactly the same reason as `fastlane_dir`: without it the sidecar is
+            // launched under `bundle exec` and a project that uses a system fastlane
+            // fails with "Could not locate Gemfile" — the same bootstrap gap, one
+            // field along.
+            ...(fastlaneDir === "fastlane" ? {} : { fastlane_dir: fastlaneDir }),
+            ...(runtime === "bundle" ? {} : { runtime }),
+        });
+        // 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");
+}