laneyard 0.2.0 → 0.3.0

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

package/dist/src/config/load.js

@@ -1,6 +1,13 @@
 import { readFile } from "node:fs/promises";
 import { parse as parseYaml } from "yaml";
 import { repoConfigSchema, serverConfigSchema } from "./schema.js";
+/**
+ * The name a lone `password_hash` is read under.
+ *
+ * Also the name the legacy `{ password }` login form authenticates as, which is
+ * what lets a 0.2 installation upgrade without anyone editing a file.
+ */
+export const LEGACY_ADMIN_NAME = "admin";
 /** Reads and validates a YAML file. Never fails by throwing: the caller decides. */
 async function loadYamlFile(path, schema) {
     let raw;
@@ -26,10 +33,59 @@ async function loadYamlFile(path, schema) {
     }
     return { ok: true, config: parsed.data };
 }
+/**
+ * Folds both ways of declaring accounts into the one the rest of the code sees.
+ *
+ * Every refusal here is a locked room avoided: a server with no account, or
+ * with none that can administer it, is one nobody can fix from the interface.
+ */
+function normaliseUsers(server) {
+    const { password_hash, users } = server;
+    if (password_hash !== undefined && users !== undefined) {
+        return {
+            ok: false,
+            error: "server.password_hash and server.users both set — they are two ways to say the same " +
+                "thing and there is no obvious winner. Keep server.users and drop server.password_hash.",
+        };
+    }
+    if (password_hash !== undefined) {
+        return {
+            ok: true,
+            users: [{ name: LEGACY_ADMIN_NAME, role: "admin", password_hash }],
+        };
+    }
+    if (users === undefined) {
+        return {
+            ok: false,
+            error: "server.users is missing — without an account nobody can log in.",
+        };
+    }
+    if (users.length === 0) {
+        return { ok: false, error: "server.users is empty — declare at least one admin account." };
+    }
+    const seen = new Set();
+    for (const u of users) {
+        if (seen.has(u.name)) {
+            return { ok: false, error: `duplicate user: ${u.name}` };
+        }
+        seen.add(u.name);
+    }
+    if (!users.some((u) => u.role === "admin")) {
+        return {
+            ok: false,
+            error: "server.users has no admin — a server nobody can administer is a locked room.",
+        };
+    }
+    return { ok: true, users };
+}
 export async function loadServerConfig(path) {
     const res = await loadYamlFile(path, serverConfigSchema);
     if (!res.ok)
         return res;
+    const accounts = normaliseUsers(res.config.server);
+    if (!accounts.ok) {
+        return { ok: false, error: `Invalid configuration in ${path} — ${accounts.error}` };
+    }
     const seen = new Set();
     for (const p of res.config.projects) {
         if (seen.has(p.slug)) {
@@ -39,7 +95,11 @@ export async function loadServerConfig(path) {
     }
     // The display name falls back to the slug rather than being optional everywhere downstream.
     const projects = res.config.projects.map((p) => ({ ...p, name: p.name ?? p.slug }));
-    return { ok: true, config: { ...res.config, projects } };
+    // `password_hash` is dropped rather than carried along: it has been folded
+    // into `users`, and leaving it in place would give downstream code a second
+    // source of truth to disagree with.
+    const { password_hash: _dropped, ...server } = res.config.server;
+    return { ok: true, config: { server: { ...server, users: accounts.users }, projects } };
 }
 export async function loadRepoConfig(path) {
     return loadYamlFile(path, repoConfigSchema);

package/dist/src/config/schema.js

@@ -7,6 +7,11 @@ export const projectSettingsSchema = z.object({
     interactive_default: z.boolean().default(false),
     artifact_globs: z.array(z.string()).default([]),
     required_secrets: z.array(z.string()).default([]),
+    // What this project builds for. No default: absent means "nobody said", and
+    // the readiness checklist falls back to looking at the repository. Setting it
+    // is how a repository that happens to carry an Xcode project it never builds
+    // stops being asked for App Store Connect credentials.
+    platforms: z.array(z.enum(["ios", "android"])).optional(),
     retention: z
         .object({
         runs: z.number().int().positive(),
@@ -39,11 +44,31 @@ export const projectEntrySchema = projectSettingsInputSchema.extend({
     notify_browser: z.boolean().default(true),
     webhook_url: z.string().optional(),
 });
+/**
+ * Two roles, and only two.
+ *
+ * A third is easy to add and impossible to remove. These two cover the case
+ * that prompted them — someone who ships without being trusted with the
+ * signing chain — and two can be held in a reader's head.
+ */
+export const userRoleSchema = z.enum(["admin", "builder"]);
+export const userEntrySchema = z.object({
+    // The name is typed into a login form and printed in a status bar; keeping it
+    // to a plain identifier avoids a name that reads differently than it is stored.
+    name: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/, "name: letters, digits, dot, dash, underscore"),
+    role: userRoleSchema,
+    password_hash: z.string().min(1),
+});
 export const serverConfigSchema = z.object({
     server: z.object({
         port: z.number().int().positive().default(7890),
         bind: z.string().default("0.0.0.0"),
-        password_hash: z.string().min(1),
+        // Both optional in the file, exactly one required by the loader. The old
+        // single-password form is what a 0.2 installation has on disk, and it must
+        // keep working unedited; `load.ts` normalises it into `users` so that
+        // nothing downstream ever learns which of the two forms was written.
+        password_hash: z.string().min(1).optional(),
+        users: z.array(userEntrySchema).optional(),
         // Only 1 is accepted. Runs share one working directory per project, so a
         // higher number would promise parallel builds that never happen — the
         // queue drains one run at a time, whatever this says. Refusing at load

package/dist/src/config/store.js

@@ -42,6 +42,16 @@ export class ConfigStore {
             watcher.close();
         };
     }
+    /**
+     * The file this store reads.
+     *
+     * Exposed because removing a project edits that very file: the route would
+     * otherwise have to rebuild the path from the data root and hope the two
+     * agree, which is exactly the kind of duplicated assumption that drifts.
+     */
+    configPath() {
+        return this.path;
+    }
     server() {
         return this.config?.server ?? null;
     }

package/dist/src/config/yaml.js

@@ -0,0 +1,14 @@
+/**
+ * A YAML document back as text, with the line width left alone.
+ *
+ * The default folds anything past eighty columns, which means writing one
+ * project rewraps the password hash someone else's line already held — a
+ * hand-written file coming back out changed where nobody touched it. A git url
+ * or a scrypt hash is a single token; breaking it makes the file harder to read
+ * and harder to grep, and gains nothing.
+ *
+ * Shared, because config.yml is now edited from three places — setting up a
+ * project, adding an account, removing one — and a file that comes back
+ * differently depending on which of them touched it is a file nobody trusts.
+ */
+export const serializeYaml = (doc) => doc.toString({ lineWidth: 0 });

package/dist/src/heuristics/blocking-actions.js

@@ -21,6 +21,26 @@ export const BLOCKING_RULES = [
         because: "renews provisioning profiles, which needs an Apple account interactively",
         fix: "Use `match` in readonly mode instead, with profiles stored in a repository.",
     },
+    {
+        action: "cert",
+        because: "creates or downloads a signing certificate, which needs an Apple account interactively",
+        fix: "Use `match` in readonly mode instead, with certificates stored in a repository.",
+    },
+    // `deliver` renders an HTML summary and waits for a yes before uploading.
+    // Only reported when the lane says `force: false` outright: the default is
+    // not something the sidecar reports, and inventing one would be a guess.
+    {
+        action: "deliver",
+        when: { arg: "force", equals: false },
+        because: "shows a summary and waits for it to be confirmed before uploading",
+        fix: "Pass `force: true` so it uploads without asking.",
+    },
+    {
+        action: "upload_to_app_store",
+        when: { arg: "force", equals: false },
+        because: "shows a summary and waits for it to be confirmed before uploading",
+        fix: "Pass `force: true` so it uploads without asking.",
+    },
 ];
 /**
  * Applies the table to the actions a lane calls.

package/dist/src/heuristics/platforms.js

@@ -0,0 +1,77 @@
+/**
+ * Which platforms a project builds for.
+ *
+ * Named knowledge of mobile toolchains — that `.xcodeproj` means Xcode, that
+ * `build.gradle` means Gradle — hence its place in this module, and the
+ * boundary that comes with it: nothing here refuses anything. It answers a
+ * question; `setup` writes the answer down and the checklist reads it.
+ *
+ * It lives here rather than in `cli/detect.ts` because two callers need the
+ * same answer. Setup proposes a configuration from it, and the checklist
+ * decides which sections apply from it. Two copies of this reasoning would be
+ * free to disagree about the same repository, and the checklist would be the
+ * one that looked wrong.
+ */
+/**
+ * What a repository looks like from the outside, as a table.
+ *
+ * The depth is deliberate: an app in a monorepo sits one level down
+ * (`android/build.gradle`, `ios/App.xcodeproj`), which is where Flutter and
+ * React Native put them.
+ */
+export const PLATFORM_MARKERS = [
+    {
+        platform: "ios",
+        globs: ["*.xcodeproj", "*.xcworkspace", "*/*.xcodeproj", "*/*.xcworkspace"],
+        onlyDirectories: true,
+    },
+    {
+        platform: "android",
+        globs: ["build.gradle", "build.gradle.kts", "*/build.gradle", "*/build.gradle.kts"],
+        onlyDirectories: false,
+    },
+];
+/**
+ * What the repository contains.
+ *
+ * Never throws. An absent clone is a reason to answer "nothing found", not to
+ * fail the checklist that was about to explain why the clone is absent.
+ */
+export async function detectPlatforms(find) {
+    const found = [];
+    // Sequential, and in the table's order, so the answer is stable: this list
+    // decides the order of the sections someone reads.
+    for (const marker of PLATFORM_MARKERS) {
+        try {
+            const paths = await find(marker.globs, { onlyDirectories: marker.onlyDirectories });
+            if (paths.length > 0)
+                found.push(marker.platform);
+        }
+        catch {
+            // A marker that cannot be looked for is simply not found.
+        }
+    }
+    return found;
+}
+/**
+ * The configuration first, then the repository.
+ *
+ * An empty configured list counts as saying nothing: `platforms: []` is what a
+ * commented-out line leaves behind, and reading it as "this project builds for
+ * nothing" would silently empty the checklist.
+ */
+export function platformsOf(configured, detected) {
+    const chosen = configured && configured.length > 0 ? configured : detected;
+    // Normalised through the table: a hand-written `[android, ios]` must not
+    // reorder the screen, and a platform named twice must not appear twice.
+    return PLATFORM_MARKERS.map((m) => m.platform).filter((p) => chosen.includes(p));
+}
+/** The two steps in one call, for callers that have a directory to look at. */
+export async function resolvePlatforms(configured, find) {
+    // The repository is only listed when the configuration did not answer:
+    // globbing a workspace costs a directory walk, and a project that says what
+    // it builds for should not pay for one.
+    if (configured && configured.length > 0)
+        return platformsOf(configured, []);
+    return platformsOf(undefined, await detectPlatforms(find));
+}