laneyard 0.2.0 → 0.3.0

package/README.md

@@ -58,14 +58,15 @@ Then, from a project you already build with fastlane:
 
 ```bash
 cd ~/code/your-app
-laneyard add     # adopt this project
+laneyard setup   # answer a few questions about this project
 laneyard         # start the server
 ```
 
-`laneyard add` inspects what is there — the `fastlane` directory even when nested in a monorepo, a
-`Gemfile`, an Xcode project or a Gradle build — writes the matching block into
-`~/.laneyard/config.yml`, and prints a generated server password once. Write it down; it is not
-shown again.
+`laneyard setup` inspects what is there — the `fastlane` directory even when nested in a monorepo, a
+`Gemfile`, an Xcode project or a Gradle build — and writes the matching block into
+`~/.laneyard/config.yml`. On a machine that has no account yet, it also creates the first admin:
+it asks what to call it and prints its generated password once. Write it down; it is not shown
+again, and nothing stores it.
 
 <details>
 <summary>Running from source instead</summary>
@@ -95,7 +96,9 @@ Laneyard means copying one file, and restoring it means copying it back.
 server:
   port: 7890
   bind: 0.0.0.0
-  password_hash: "scrypt$…"      # written by `laneyard add`
+  users:                         # written by `laneyard setup`, see Accounts
+    - { name: martin, role: admin, password_hash: "scrypt$…" }
+    - { name: lea, role: builder, password_hash: "scrypt$…" }
   max_concurrent_runs: 1         # only 1 is accepted, see below
   retention: { runs: 50, artifact_days: 30 }
 
@@ -112,9 +115,56 @@ a time across every project — parallel runs would need a working directory per
 not exist yet. A larger number is refused when the file loads rather than silently ignored, so a
 server is never configured for builds that never happen.
 
-### `laneyard.yml` — optional, committed in your repository
+### Accounts
 
-Build behaviour belongs next to the code, so it can be versioned with it:
+Everyone who signs in has a name, a password and one of two roles. Two, because a third role is
+easy to add and impossible to remove.
+
+| | **admin** | **builder** |
+|---|---|---|
+| start a build, watch it, cancel it | ✓ | ✓ |
+| download artifacts, read logs and the Fastfile | ✓ | ✓ |
+| see the readiness checklist | ✓ | ✓ |
+| read and write secrets | ✓ | |
+| save, commit and push the Fastfile | ✓ | |
+| remove a project | ✓ | |
+| manage accounts | ✓ | |
+
+A builder is what you give someone who ships without being trusted with the signing chain: they
+can press the button and watch what happens, and they never see a credential.
+
+The interface shows a builder only what a builder can use — the secrets, fastfile and settings
+tabs are not drawn, and neither is the accounts screen. That is courtesy, not security: the
+server refuses those routes on its own, whatever the browser was shown, and the test suite
+proves it for every verb and every spelling of the address.
+
+Add and remove accounts from the accounts screen, or from the command line:
+
+```bash
+echo "$PASSWORD" | laneyard user add lea --role builder
+```
+
+The password is read from standard input, never taken as an argument — an argument lands in your
+shell history. Without `--role`, the account is a builder.
+
+Two things are refused, in the API and on the command line alike: removing the last admin, and
+demoting the last admin. A server nobody can administer cannot be repaired from the interface.
+
+Removing an account ends its sessions immediately — "remove the account" and "revoke access" are
+the same act. So does editing `config.yml` by hand: every request looks the account up again, so
+a demotion takes effect at once rather than at the next restart.
+
+**Upgrading from 0.2.** An existing `server.password_hash` keeps working, unedited. It is read as
+a single admin account called `admin` — sign in with that name and the password you already have.
+The first time you add someone, the file is rewritten into the `users` form above, comments and
+all. Do not write both forms: a file holding a `password_hash` *and* a `users` list is refused at
+load, because there is no obvious winner.
+
+### `laneyard.yml` — in your repository, and committed
+
+Build behaviour belongs next to the code, so it can be versioned with it — `laneyard setup`
+writes this file for you, and you should commit it. A colleague who clones the repository then
+builds it the same way, without configuring anything.
 
 ```yaml
 fastlane_dir: fastlane
@@ -123,8 +173,13 @@ timeout_minutes: 60
 artifact_globs:
   - "build/**/*.ipa"
   - "build/**/*.app.dSYM.zip"
+platforms: [ios]                 # or `[android]`, or both
 ```
 
+`platforms` decides which half of the readiness checklist applies: an Android project is never
+asked for an App Store Connect key. Left out, Laneyard looks at the repository — an Xcode project
+means iOS, a Gradle build means Android — and reports what it found rather than assuming.
+
 Field by field, the repository file wins over the server block, which wins over the defaults. Any
 field of `laneyard.yml` may also be written in the server block, so a repository you would rather
 not touch can be configured entirely from `config.yml`.
@@ -146,6 +201,14 @@ The value is never an argument: a command line ends up in `~/.zsh_history` and i
 `ps`. Typing the command alone leaves you at a blank line — type or paste the value, then
 `Ctrl-D`.
 
+**Two of them are files.** An App Store Connect key arrives as a `.p8` and a Play Store service
+account as a JSON file, and pasting either into a text field is the moment you are most likely to
+paste it somewhere else by accident. The Secrets tab takes the file directly — *app store connect
+key* and *play store service account*, beside the value field. Your browser reads it and sends its
+text to the same route a typed value goes through, under the name fastlane and the readiness
+checklist both look for: `APP_STORE_CONNECT_API_KEY_P8` and `SUPPLY_JSON_KEY_DATA`. Nothing is
+uploaded, nothing is written to disk on the way, and the page only ever shows the file's name.
+
 A secret becomes an environment variable for every run of the project it belongs to. Without
 `--project` it applies to every project; a project secret of the same name wins over a global
 one. Secrets are kept out of the logs unless you pass `--no-mask`, and a masked value must be at
@@ -153,18 +216,34 @@ least four characters long — see below.
 
 ### Readiness
 
-Every project has a Readiness tab: five checks on what stands between it and a build that runs
-while nobody watches.
+Every project has a Readiness tab: what stands between it and a build that runs while nobody
+watches. Only the checks that apply to the project are shown — an Android project is never asked
+for an App Store Connect key, because one irrelevant warning teaches you to ignore the screen.
+
+Always:
 
 - **the repository** answers `git ls-remote` without asking for credentials — a run that meets a
   password prompt does not fail, it waits;
 - **dependencies** are installable: `bundle check` against your Gemfile, or the `fastlane` a run
   would otherwise find on the PATH;
+- **no lane calls an action known to stop and ask** — `prompt`, `sigh`, `cert`, a writable
+  `match`, an upload waiting for its summary to be confirmed.
+
+On iOS:
+
 - **App Store Connect** has an API key in the vault rather than a `FASTLANE_SESSION`, which
   expires and takes the next night's build with it;
 - **match** has its `MATCH_PASSWORD` stored and is called `readonly`, so it fetches certificates
-  instead of trying to create them;
-- **no lane calls an action known to stop and ask** — `prompt`, `sigh`, a writable `match`.
+  instead of trying to create them.
+
+On Android:
+
+- **the keystore** is reachable without a prompt: a lane handing `gradle` a `storeFile` needs a
+  passphrase, and one that is neither in the call nor in the vault makes gradle stop and ask;
+- **the Play Store service account** is in the vault when a lane calls `upload_to_play_store`.
+
+Like the iOS ones, the Android checks read **literal arguments only**. `gradle(storePassword:
+ENV["PW"])` is reported as undetermined, never guessed at: a checklist that guesses gets believed.
 
 They run when you open the tab or press refresh, never on their own: they shell out to git and to
 bundler. The time of the last run is on screen, because a stale green tick is worse than a red
@@ -204,15 +283,40 @@ Below the editor is what git makes of the workspace: the diff, a message field,
 `push`. A commit stages exactly the files that changed and never `git add -A` — a build leaves
 artifacts and reports scattered around, and none of them belong in your history.
 
+### Removing a project
+
+Every project has a Settings tab, and the one thing on it is removal. It takes the project's block
+out of `config.yml` — through the YAML document, so your comments and your key order survive —
+and stops showing it. It is confirmed by typing the project's name: it is the one destructive
+action in Laneyard, and a dialogue you can click through is not a confirmation.
+
+What it does *not* do is most of the point, because "delete" elsewhere usually means the opposite:
+
+- **the runs stay.** Every build that project ever ran keeps its page, its log and its artifacts,
+  each still at its own address. Removing a project means stop showing it, not destroy its past;
+- **the clone and the artifacts stay on disk.** Their paths are printed when it is done, so you
+  can remove them yourself. Nothing is deleted from a web page on one click;
+- **the secrets stay in the vault**, encrypted and unreachable, and come back if you add the
+  project again under the same name;
+- **the repository is untouched.** Its `laneyard.yml`, its Fastfile and its history are the
+  repository's, not Laneyard's.
+
+Removal is refused while a run of that project is in flight — that run is using the workspace. A
+run still waiting in the queue will not start: it ends as failed, saying its project is gone.
+
 ## Security
 
 Read this before putting Laneyard on a network.
 
 - **It is built for a local network, not the internet.** It listens on `0.0.0.0` so you can reach
-  it from your laptop, behind one password. Do not expose it publicly. If you need remote access,
+  it from your laptop, behind a password. Do not expose it publicly. If you need remote access,
   put it behind a VPN or an SSH tunnel.
-- **The password** is stored as an scrypt hash and repeated failures are throttled. Sessions live
-  in memory and do not survive a restart.
+- **Passwords** are stored as scrypt hashes and repeated failures are throttled, per account, so
+  hammering one name cannot lock out the others. Sessions live in memory and do not survive a
+  restart.
+- **A role is enforced by the server, not by the interface.** One table names the routes that
+  require an admin, and one hook is the only thing that reads it — there is no permission check
+  hidden inside a handler. What a builder is not shown is also what a builder is refused.
 - **Secrets are encrypted at rest.** Values are stored with AES-256-GCM under a key kept in
   `~/.laneyard/key` — outside the database, mode `600`, and Laneyard refuses to start if anyone
   else can read it. Someone who walks off with `laneyard.db` gets ciphertext. Nothing else in the
@@ -249,6 +353,9 @@ What this does *not* cover, stated plainly:
 - `✓` build queue, cancellation, timeouts surfaced in the UI
 - `✓` a checklist that gets a project running unattended
 - `✓` edit the Fastfile in the browser, verified on every save
+- `✓` store a signing credential straight from its `.p8` or JSON file
+- `✓` remove a project from the interface, without touching its history
+- `✓` named accounts, with a builder role that never sees a credential
 - `○` git-triggered and scheduled builds
 
 Two things worth knowing today: listing lanes does not fetch the repository, so a lane you have

package/dist/src/cli/detect.js

@@ -1,8 +1,9 @@
 import { execFile } from "node:child_process";
-import { access } from "node:fs/promises";
+import { access, realpath } from "node:fs/promises";
 import { basename, join, relative, sep } from "node:path";
 import { promisify } from "node:util";
 import { glob } from "tinyglobby";
+import { detectPlatforms } from "../heuristics/platforms.js";
 const exec = promisify(execFile);
 const exists = async (p) => {
     try {
@@ -30,14 +31,44 @@ function slugify(name) {
         .replace(/^-+|-+$/g, "");
     return s === "" ? "project" : s;
 }
+/** `git@host:owner/name.git` or `https://host/owner/name.git` → `name`. */
+function repositoryName(url) {
+    if (!url)
+        return null;
+    const last = url.replace(/\/+$/, "").split(/[/:]/).pop();
+    if (!last)
+        return null;
+    const name = last.replace(/\.git$/, "");
+    return name === "" ? null : name;
+}
+/** The globbing `heuristics/platforms.ts` asks for, bound to one directory. */
+const findIn = (dir) => (globs, { onlyDirectories }) => glob(globs, onlyDirectories ? { cwd: dir, onlyDirectories: true } : { cwd: dir, onlyFiles: true });
+/** Turns an absolute path into a repository-relative one, with forward slashes. */
+const toRepoPath = (root, absolute) => relative(root, absolute).split(sep).join("/");
 /**
  * Inspects an existing project and proposes a configuration.
  *
- * Decides nothing irreversible: everything it returns is a proposal the
- * user sees and can correct before it's written.
+ * **Every path it reports is relative to the repository root, not to the
+ * directory the command was run in.** That distinction is the whole difficulty:
+ * Laneyard clones the repository, so a Fastfile at `app/fastlane` is at
+ * `app/fastlane` in the workspace no matter which folder someone happened to
+ * be standing in when they ran `laneyard setup`. Measuring from the current
+ * directory produced a configuration that looked right and pointed nowhere.
+ *
+ * Decides nothing irreversible: everything it returns is a proposal the user
+ * sees and can correct before it's written.
  */
 export async function detectProject(dir) {
-    // The Fastfile can be at the root or under a subfolder, for monorepos.
+    // Without a repository there is nothing to clone; `runAddCommand` refuses
+    // shortly after, so falling back to `dir` here only keeps this function total.
+    // Both sides are resolved before being compared: on macOS the temporary
+    // directory is a symlink, and git always answers with the real path — so a
+    // raw comparison yields a nonsense `../../private/...` relative path.
+    const here = await realpath(dir).catch(() => dir);
+    const root = await realpath((await gitOr(["rev-parse", "--show-toplevel"], dir, null)) ?? dir).catch(() => dir);
+    const subPath = toRepoPath(root, here);
+    // Look from where the user is standing — that is what they meant by "this
+    // project" — but report what is found relative to the repository root.
     const fastfiles = await glob(["fastlane/Fastfile", "*/fastlane/Fastfile", "*/*/fastlane/Fastfile"], {
         cwd: dir,
         absolute: true,
@@ -45,26 +76,39 @@ export async function detectProject(dir) {
     });
     const fastfile = fastfiles.sort((a, b) => a.length - b.length)[0] ?? null;
     const fastlaneDir = fastfile
-        ? relative(dir, join(fastfile, "..")).split(sep).join("/")
+        ? toRepoPath(root, await realpath(join(fastfile, "..")).catch(() => join(fastfile, "..")))
         : null;
-    const isIos = (await glob(["*.xcodeproj", "*.xcworkspace", "*/*.xcodeproj"], { cwd: dir, onlyDirectories: true }))
-        .length > 0;
-    const isAndroid = (await glob(["build.gradle", "build.gradle.kts", "*/build.gradle", "*/build.gradle.kts"], {
-        cwd: dir,
-        onlyFiles: true,
-    })).length > 0;
+    const platforms = await detectPlatforms(findIn(dir));
+    const isIos = platforms.includes("ios");
+    const isAndroid = platforms.includes("android");
+    // Artifact patterns are anchored to the sub-project too. In a monorepo an
+    // unanchored `**/*.ipa` would collect a sibling app's build as if it were
+    // this one's — and nothing downstream would notice.
+    const prefix = subPath === "" ? "" : `${subPath}/`;
     const artifactGlobs = [];
     if (isIos)
-        artifactGlobs.push("**/*.ipa", "**/*.app.dSYM.zip");
+        artifactGlobs.push(`${prefix}**/*.ipa`, `${prefix}**/*.app.dSYM.zip`);
     if (isAndroid)
-        artifactGlobs.push("**/*.apk", "**/*.aab");
+        artifactGlobs.push(`${prefix}**/*.apk`, `${prefix}**/*.aab`);
+    const gitUrl = await gitOr(["remote", "get-url", "origin"], dir, null);
+    // The slug names the repository, and the sub-project when there is one: two
+    // apps in the same monorepo must not both want to be called `app`.
+    //
+    // The name comes from the remote rather than the local folder, because the
+    // folder is an accident of where someone cloned. `…/popotheque.git` checked
+    // out into `~/work/current` should still be called `popotheque`.
+    const repoName = repositoryName(gitUrl) ?? basename(root);
+    const slug = slugify(subPath === "" ? repoName : `${repoName}-${subPath}`);
     return {
-        slug: slugify(basename(dir)),
-        gitUrl: await gitOr(["remote", "get-url", "origin"], dir, null),
+        slug,
+        gitUrl,
         defaultBranch: (await gitOr(["rev-parse", "--abbrev-ref", "HEAD"], dir, "main")) ?? "main",
         fastlaneDir,
+        // A Gemfile beside the Fastfile is the one fastlane will use, not one at the
+        // repository root — `bundle exec` runs from the sub-project.
         runtime: (await exists(join(dir, "Gemfile"))) ? "bundle" : "system",
         artifactGlobs,
-        platform: isIos ? "ios" : isAndroid ? "android" : "unknown",
+        platforms,
+        subPath,
     };
 }

package/dist/src/cli/prompt.js

@@ -0,0 +1,36 @@
+import { createInterface } from "node:readline/promises";
+/** Reads from the real terminal. */
+export function terminalAsker() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return {
+        async ask(label, proposed, hint) {
+            if (hint)
+                process.stdout.write(`\n  ${hint}\n`);
+            // The proposal is shown in the prompt rather than typed for the user:
+            // pressing Return accepts it, which is what someone does nine times out
+            // of ten, and correcting it costs one line.
+            const answer = (await rl.question(`  ${label} [${proposed}]: `)).trim();
+            return answer === "" ? proposed : answer;
+        },
+        async confirm(question, defaultYes) {
+            const suffix = defaultYes ? "[Y/n]" : "[y/N]";
+            const answer = (await rl.question(`${question} ${suffix} `)).trim().toLowerCase();
+            if (answer === "")
+                return defaultYes;
+            return answer.startsWith("y");
+        },
+        close() {
+            rl.close();
+        },
+    };
+}
+/** Accepts every proposal without asking. Used by `--yes` and by the tests. */
+export const acceptingAsker = {
+    async ask(_label, proposed) {
+        return proposed;
+    },
+    async confirm(_question, defaultYes) {
+        return defaultYes;
+    },
+    close() { },
+};

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");
+}