laneyard 0.1.0 → 0.3.0

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(),
@@ -27,8 +32,11 @@ export const projectEntrySchema = projectSettingsInputSchema.extend({
     default_branch: z.string().default("main"),
     git_auth: z
         .object({
-        kind: z.enum(["none", "ssh_key", "token"]),
-        /** File path if kind is ssh_key, secret name if kind is token. */
+        // `token` is not accepted yet. The workspace only knows how to use an SSH
+        // key, so accepting it would leave a project configured for something that
+        // silently never happens — worse than a clear refusal at load time.
+        kind: z.enum(["none", "ssh_key"]),
+        /** Path to the SSH key file. */
         ref: z.string().optional(),
     })
         .default({ kind: "none" }),
@@ -36,12 +44,47 @@ 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),
-        max_concurrent_runs: z.number().int().positive().default(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
+        // time is the honest answer, as with `git_auth: token`.
+        max_concurrent_runs: z
+            .number()
+            .int()
+            .positive()
+            // Refined on the field itself, so zod reports `server.max_concurrent_runs`
+            // on its own: `load.ts` prefixes the message with that path, and an error
+            // saying `(root)` would leave the reader hunting for the field.
+            .refine((n) => n === 1, {
+            message: "only 1 is supported: runs are executed one at a time, and accepting more would " +
+                "promise parallel builds that never happen",
+        })
+            .default(1),
         retention: z
             .object({
             runs: z.number().int().positive().default(50),

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/db/cache.js

@@ -3,20 +3,20 @@ export class CacheStore {
     constructor(db) {
         this.db = db;
     }
-    get(slug, hash) {
+    get(slug, kind, hash) {
         const row = this.db
-            .prepare("SELECT payload FROM introspection_cache WHERE project_slug = ? AND config_hash = ?")
-            .get(slug, hash);
+            .prepare("SELECT payload FROM introspection_cache WHERE project_slug = ? AND kind = ? AND config_hash = ?")
+            .get(slug, kind, hash);
         return row ? JSON.parse(row.payload) : null;
     }
-    put(slug, hash, payload) {
+    put(slug, kind, hash, payload) {
         this.db
-            .prepare(`INSERT INTO introspection_cache (project_slug, config_hash, payload, fetched_at)
-         VALUES (?, ?, ?, ?)
-         ON CONFLICT (project_slug) DO UPDATE
+            .prepare(`INSERT INTO introspection_cache (project_slug, kind, config_hash, payload, fetched_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT (project_slug, kind) DO UPDATE
            SET config_hash = excluded.config_hash,
                payload = excluded.payload,
                fetched_at = excluded.fetched_at`)
-            .run(slug, hash, JSON.stringify(payload), new Date().toISOString());
+            .run(slug, kind, hash, JSON.stringify(payload), new Date().toISOString());
     }
 }

package/dist/src/db/open.js

@@ -6,7 +6,22 @@ export function openDatabase(path) {
     const db = new Database(path);
     db.pragma("journal_mode = WAL");
     db.pragma("foreign_keys = ON");
+    migrateIntrospectionCache(db);
     const here = dirname(fileURLToPath(import.meta.url));
     db.exec(readFileSync(join(here, "schema.sql"), "utf8"));
     return db;
 }
+/**
+ * Rebuilds the introspection cache when it predates the `kind` column.
+ *
+ * `CREATE TABLE IF NOT EXISTS` leaves an existing table alone, so a database
+ * written by 0.1.0 would keep the old single-key shape and collide. Dropping is
+ * the right answer here and only here: this table is a cache, and losing it
+ * costs one slow read.
+ */
+function migrateIntrospectionCache(db) {
+    const columns = db.prepare("PRAGMA table_info(introspection_cache)").all();
+    if (columns.length > 0 && !columns.some((c) => c.name === "kind")) {
+        db.exec("DROP TABLE introspection_cache");
+    }
+}

package/dist/src/db/runs.js

@@ -1,5 +1,5 @@
-/** A run is active until it reaches a terminal state. */
-const ACTIVE = ["queued", "preparing", "running"];
+/** Statuses that mean a run has begun and cannot survive the process that started it. */
+const IN_FLIGHT = ["preparing", "running"];
 const toRun = (r) => ({
     id: r.id,
     projectSlug: r.project_slug,
@@ -52,12 +52,57 @@ export class RunStore {
             .prepare("UPDATE run SET status = ?, finished_at = ?, exit_code = ?, error_summary = ? WHERE id = ?")
             .run(r.status, now(), r.exitCode, r.errorSummary, id);
     }
-    /** At startup: no run can still be in progress, the process that carried it is dead. */
-    interruptActive() {
-        const placeholders = ACTIVE.map(() => "?").join(", ");
+    /** Runs waiting to start, oldest first. Insertion order is the queue. */
+    queued() {
+        const rows = this.db
+            .prepare("SELECT * FROM run WHERE status = 'queued' ORDER BY id")
+            .all();
+        return rows.map(toRun);
+    }
+    /** 1 for the next to start, null if the run is not waiting. */
+    queuePosition(id) {
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS ahead FROM run
+         WHERE status = 'queued' AND id <= ?
+           AND EXISTS (SELECT 1 FROM run r2 WHERE r2.id = ? AND r2.status = 'queued')`)
+            .get(id, id);
+        return row.ahead === 0 ? null : row.ahead;
+    }
+    /** How many runs have begun. The worker consults it before taking the next. */
+    activeCount() {
+        const placeholders = IN_FLIGHT.map(() => "?").join(", ");
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS n FROM run WHERE status IN (${placeholders})`)
+            .get(...IN_FLIGHT);
+        return row.n;
+    }
+    /**
+     * True if this project has a run that has begun and not yet finished.
+     *
+     * Used to refuse a Fastfile write while it's true: that run is reading the
+     * very file the write would replace, the same reason `prepare` refuses to
+     * touch a dirty workspace.
+     */
+    hasActiveRun(slug) {
+        const placeholders = IN_FLIGHT.map(() => "?").join(", ");
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS n FROM run WHERE project_slug = ? AND status IN (${placeholders})`)
+            .get(slug, ...IN_FLIGHT);
+        return row.n > 0;
+    }
+    /**
+     * Marks as interrupted every run that had begun, leaving queued ones alone.
+     *
+     * A run that started cannot survive the process that spawned it — its
+     * pseudo-terminal died with it. A queued run never began: it still means
+     * exactly what it meant, and dropping it would be a silent surprise for
+     * someone who queued three builds and restarted the server.
+     */
+    interruptInFlight() {
+        const placeholders = IN_FLIGHT.map(() => "?").join(", ");
         const res = this.db
             .prepare(`UPDATE run SET status = 'interrupted', finished_at = ? WHERE status IN (${placeholders})`)
-            .run(now(), ...ACTIVE);
+            .run(now(), ...IN_FLIGHT);
         return res.changes;
     }
     replaceSteps(runId, steps) {

package/dist/src/db/schema.sql

@@ -37,9 +37,27 @@ CREATE TABLE IF NOT EXISTS artifact (
   kind     TEXT    NOT NULL
 );
 
+-- `kind` is part of the key because more than one reader caches per project —
+-- lanes and the actions each lane calls. Without it the second write overwrites
+-- the first, and the next read returns a payload of the wrong shape rather than
+-- missing the cache.
 CREATE TABLE IF NOT EXISTS introspection_cache (
-  project_slug TEXT PRIMARY KEY,
+  project_slug TEXT NOT NULL,
+  kind         TEXT NOT NULL,
   config_hash  TEXT NOT NULL,
   payload      TEXT NOT NULL,
-  fetched_at   TEXT NOT NULL
+  fetched_at   TEXT NOT NULL,
+  PRIMARY KEY (project_slug, kind)
+);
+
+-- A global secret is stored with an empty project_slug rather than NULL:
+-- SQLite considers two NULLs distinct in a UNIQUE index, so NULL would let the
+-- same global name be inserted twice.
+CREATE TABLE IF NOT EXISTS secret (
+  project_slug TEXT    NOT NULL DEFAULT '',
+  key          TEXT    NOT NULL,
+  value_enc    TEXT    NOT NULL,
+  masked       INTEGER NOT NULL DEFAULT 1,
+  updated_at   TEXT    NOT NULL,
+  PRIMARY KEY (project_slug, key)
 );

package/dist/src/db/secrets.js

@@ -0,0 +1,64 @@
+const GLOBAL = "";
+/**
+ * Stores encrypted secrets. Knows nothing about encryption itself: it takes and
+ * returns ciphertext, so a bug here cannot leak a plaintext value.
+ *
+ * A project secret shadows a global one of the same name — the same precedence
+ * as the configuration, and the least surprising rule.
+ */
+export class SecretStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    set(projectSlug, key, valueEnc, masked) {
+        this.db
+            .prepare(`INSERT INTO secret (project_slug, key, value_enc, masked, updated_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT (project_slug, key) DO UPDATE
+           SET value_enc = excluded.value_enc,
+               masked = excluded.masked,
+               updated_at = excluded.updated_at`)
+            .run(projectSlug ?? GLOBAL, key, valueEnc, masked ? 1 : 0, new Date().toISOString());
+    }
+    /** Rows that apply to a project, project scope winning over global. */
+    applicable(projectSlug) {
+        const rows = this.db
+            .prepare("SELECT * FROM secret WHERE project_slug IN (?, ?) ORDER BY key")
+            .all(projectSlug, GLOBAL);
+        const byKey = new Map();
+        for (const row of rows) {
+            const existing = byKey.get(row.key);
+            if (!existing || row.project_slug !== GLOBAL)
+                byKey.set(row.key, row);
+        }
+        return [...byKey.values()].sort((a, b) => a.key.localeCompare(b.key));
+    }
+    list(projectSlug) {
+        return this.applicable(projectSlug).map((row) => ({
+            key: row.key,
+            masked: row.masked === 1,
+            scope: row.project_slug === GLOBAL ? "global" : "project",
+        }));
+    }
+    listGlobal() {
+        const rows = this.db
+            .prepare("SELECT * FROM secret WHERE project_slug = ? ORDER BY key")
+            .all(GLOBAL);
+        return rows.map((row) => ({ key: row.key, masked: row.masked === 1, scope: "global" }));
+    }
+    /** Ciphertext by name, for the vault to decrypt. */
+    encrypted(projectSlug) {
+        return Object.fromEntries(this.applicable(projectSlug).map((row) => [row.key, row.value_enc]));
+    }
+    /** Which of the applicable secrets should be kept out of the logs. */
+    maskedKeys(projectSlug) {
+        return new Set(this.applicable(projectSlug).filter((r) => r.masked === 1).map((r) => r.key));
+    }
+    remove(projectSlug, key) {
+        const res = this.db
+            .prepare("DELETE FROM secret WHERE project_slug = ? AND key = ?")
+            .run(projectSlug ?? GLOBAL, key);
+        return res.changes > 0;
+    }
+}

package/dist/src/fastfile/store.js

@@ -0,0 +1,53 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+const DEFAULT_FASTLANE_DIR = "fastlane";
+/**
+ * Reads and writes the Fastfile byte-for-byte.
+ *
+ * A file written by hand must never come back mangled: no reformatting, no
+ * trailing-newline fixing, no reordering. Someone may have spent a long time
+ * on that file, so `write` keeps the previous content only in memory — never
+ * in a sibling file, which would show up as an untracked file in the git
+ * workspace and eventually get committed by someone in a hurry — and puts it
+ * back the moment the injected verifier says the new content doesn't hold up.
+ */
+export class FastfileStore {
+    async read(workspacePath, fastlaneDir = DEFAULT_FASTLANE_DIR) {
+        return readFile(this.resolvePath(workspacePath, fastlaneDir), "utf8");
+    }
+    /**
+     * Writes `content` verbatim, then verifies it. On failure, the previous
+     * content is written back before returning, so the workspace never lands
+     * between the old file and the new one.
+     */
+    async write(workspacePath, content, verify, fastlaneDir = DEFAULT_FASTLANE_DIR) {
+        const path = this.resolvePath(workspacePath, fastlaneDir);
+        const previous = await readFile(path, "utf8");
+        await writeFile(path, content, "utf8");
+        const result = await verify();
+        if (!result.ok) {
+            // Whatever broke, the file on disk goes back to exactly what it was
+            // before this call — a stray backup file would be a second thing to
+            // clean up and forget about.
+            await writeFile(path, previous, "utf8");
+        }
+        return result;
+    }
+    /**
+     * Resolves the Fastfile's path, refusing to leave the workspace.
+     *
+     * `fastlaneDir` comes from configuration — the project's own
+     * `laneyard.yml`, or the server's `config.yml` — and a value like
+     * `../../etc` must not turn an editor into a way to write anywhere on the
+     * machine.
+     */
+    resolvePath(workspacePath, fastlaneDir) {
+        const root = resolve(workspacePath);
+        const full = resolve(root, fastlaneDir, "Fastfile");
+        const rel = relative(root, full);
+        if (rel.startsWith("..") || isAbsolute(rel)) {
+            throw new Error(`fastlane_dir resolves outside the workspace: ${fastlaneDir}`);
+        }
+        return full;
+    }
+}

package/dist/src/git/workspace.js

@@ -29,16 +29,33 @@ export class Workspace {
      *
      * An HTTPS URL can carry a password — `https://user:token@github.com/…`
      * is perfectly legal in `config.yml`. But git errors end up in the run's
-     * log file. General secret redaction comes at the next milestone; this
-     * particular leak comes from our own formatting, and is fixed here.
+     * log file. The vault's redaction does not help here: the repository URL is
+     * configuration, not a stored secret, so this leak — which comes from our own
+     * formatting — has to be closed on the spot.
      */
     redact(text) {
         return text.split(this.gitUrl).join("<repository>");
     }
-    async git(args, cwd = this.path) {
+    async git(args, cwd = this.path, timeout) {
+        return (await this.gitRaw(args, cwd, timeout)).trim();
+    }
+    /**
+     * Same as `git`, but without trimming the output.
+     *
+     * `status --porcelain` output is column-sensitive: its first two characters
+     * are a status code that can themselves be a literal space. Trimming the
+     * whole blob — fine for a commit hash or a single config value — would eat
+     * that leading space and misalign every line parsed after it.
+     */
+    async gitRaw(args, cwd = this.path, timeout) {
         try {
-            const { stdout } = await exec("git", args, { cwd, env: this.env(), maxBuffer: 32 * 1024 * 1024 });
-            return stdout.trim();
+            const { stdout } = await exec("git", args, {
+                cwd,
+                env: this.env(),
+                maxBuffer: 32 * 1024 * 1024,
+                ...(timeout === undefined ? {} : { timeout }),
+            });
+            return stdout;
         }
         catch (cause) {
             const err = cause;
@@ -46,6 +63,18 @@ export class Workspace {
             throw new Error(`git ${this.redact(args.join(" "))} failed: ${this.redact(detail)}`);
         }
     }
+    /**
+     * Asks the remote for its branches, and nothing else.
+     *
+     * Reads no working copy and writes nothing, so it answers the one question
+     * the readiness checklist asks: would a run reach this repository on its own?
+     * The timeout matters as much as the exit code — with `GIT_TERMINAL_PROMPT=0`
+     * git gives up on a credentials prompt, but a host that never answers would
+     * otherwise hang the checklist exactly the way it hangs a run at 2am.
+     */
+    async probeRemote(timeoutMs = 10_000) {
+        await this.git(["ls-remote", "--heads", this.gitUrl], process.cwd(), timeoutMs);
+    }
     async exists() {
         try {
             await access(join(this.path, ".git"));
@@ -71,6 +100,67 @@ export class Workspace {
     async headSha() {
         return this.git(["rev-parse", "HEAD"]);
     }
+    /**
+     * Paths with uncommitted changes, tracked only — the same rule as
+     * `isDirty`, for the same reason: a build scatters untracked files around,
+     * and listing them here would bury the change someone actually made.
+     */
+    async status() {
+        const raw = await this.gitRaw(["status", "--porcelain", "--untracked-files=no"]);
+        // Porcelain v1: two status letters, a space, then the path. The trailing
+        // split produces one empty element for the final newline; drop it rather
+        // than turn it into a bogus empty path.
+        return raw
+            .split("\n")
+            .filter((line) => line.length > 0)
+            .map((line) => line.slice(3));
+    }
+    /** The unified diff of uncommitted changes, as text. Every path if none is given. */
+    async diff(path) {
+        return this.git(path === undefined ? ["diff"] : ["diff", "--", path]);
+    }
+    /**
+     * Stages exactly the given paths and commits them — never `git add -A`. A
+     * build leaves files scattered in the workspace, and committing them
+     * because they happened to be there is how something ends up in someone's
+     * release.
+     *
+     * Commits under the repository's own git identity if it has one; otherwise
+     * as `Laneyard <laneyard@localhost>`, because a commit from a name nobody
+     * recognises is worse than one that admits what made it. The identity
+     * actually used is returned so the interface can say so.
+     */
+    async commit(message, paths) {
+        if (paths.length === 0)
+            throw new Error("commit: no paths given");
+        await this.git(["add", "--", ...paths]);
+        const identity = await this.gitIdentity();
+        const author = identity ?? "Laneyard <laneyard@localhost>";
+        const asLaneyard = identity
+            ? []
+            : ["-c", "user.name=Laneyard", "-c", "user.email=laneyard@localhost"];
+        await this.git([...asLaneyard, "commit", "-m", message]);
+        return { author };
+    }
+    /**
+     * `name <email>` from the repository's own git configuration — local or
+     * global, however git itself resolves it for this workspace — or null if
+     * none is set at all.
+     */
+    async gitIdentity() {
+        try {
+            const name = await this.git(["config", "user.name"]);
+            const email = await this.git(["config", "user.email"]);
+            return name && email ? `${name} <${email}>` : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Pushes the branch, surfacing git's own message on failure rather than a generic one. */
+    async push(branch) {
+        await this.git(["push", "origin", branch]);
+    }
     /**
      * Guarantees the clone is present, without touching the current branch.
      *

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

@@ -0,0 +1,65 @@
+export const BLOCKING_RULES = [
+    {
+        action: "prompt",
+        because: "asks a question and waits for an answer",
+        fix: "Remove it from the lane, or give it a default that applies when `CI` is set.",
+    },
+    {
+        action: "match",
+        when: { arg: "readonly", equals: false },
+        because: "may create certificates, which needs an Apple account interactively",
+        fix: "Pass `readonly: true` so it only fetches what already exists.",
+    },
+    {
+        action: "sync_code_signing",
+        when: { arg: "readonly", equals: false },
+        because: "may create certificates, which needs an Apple account interactively",
+        fix: "Pass `readonly: true` so it only fetches what already exists.",
+    },
+    {
+        action: "sigh",
+        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.
+ *
+ * A rule whose `when` names an argument the lane didn't pass literally is not
+ * reported: the sidecar already dropped that argument rather than guess at
+ * it (see `ruby/introspect.rb`), so `arg in action.args` is false and the
+ * rule stays silent instead of pretending to know the answer.
+ */
+export function findBlockingActions(actions) {
+    const findings = [];
+    for (const action of actions) {
+        for (const rule of BLOCKING_RULES) {
+            if (rule.action !== action.name)
+                continue;
+            if (rule.when && action.args[rule.when.arg] !== rule.when.equals)
+                continue;
+            findings.push({ action: rule.action, because: rule.because, fix: rule.fix });
+        }
+    }
+    return findings;
+}