laneyard 0.6.1 → 0.8.0

package/dist/src/runner/env-file.js

@@ -0,0 +1,144 @@
+/**
+ * The environment file a build reads from disk.
+ *
+ * A project's own `.env` — the one its app reads, not the one fastlane reads —
+ * is gitignored, and Laneyard builds from a clone, so it is never there. The
+ * vault does not answer that on its own: a stored secret becomes an environment
+ * variable of the run, which is enough for fastlane and enough for a Fastfile
+ * that forwards values itself, and no use at all to anything that reads a
+ * *file*. `flutter_dotenv` bundles `.env` as an asset,
+ * `--dart-define-from-file=config.json` reads a path at compile time, an
+ * `.xcconfig` is a file by definition. None of them looks at the environment,
+ * and none of them fails loudly — they produce an app configured with nothing.
+ *
+ * So the variables a project ticks are rendered into a file at the path its
+ * `laneyard.yml` names, for the length of one run, and removed afterwards. The
+ * ticking decides membership of this file and nothing else: a ticked secret
+ * still reaches the run as an environment variable like every other one.
+ */
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { LANEYARD_MARKER } from "./gradle-properties.js";
+/**
+ * Whether a value can be written bare.
+ *
+ * Anything outside this set is quoted. The set is deliberately narrow — a bare
+ * line is a convenience, and being wrong about it costs a value silently read
+ * back short. `#` starts a comment, whitespace at either end is trimmed by most
+ * readers, and a quote or backslash is an escape somebody has to interpret.
+ */
+const BARE = /^[A-Za-z0-9_./:@+-]*$/;
+/**
+ * Escapes a value for a double-quoted dotenv line.
+ *
+ * Backslash first, or every escape this function then writes would be escaped
+ * again by its own output. Newlines become `\n` rather than being written
+ * literally: a line break inside a value ends the line, and the parser reads a
+ * truncated value and a second variable that does not exist. A private key
+ * pasted into a variable is where that happens for real.
+ */
+function escape(value) {
+    return value
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\r/g, "\\r")
+        .replace(/\n/g, "\\n");
+}
+/**
+ * Renders variables as dotenv text.
+ *
+ * Sorted by name, so a diff between two runs shows what changed rather than
+ * what moved. Pure, and tested against a parser rather than against itself:
+ * the property worth having is "a reader gets back what went in", and a test
+ * written against this function's own idea of the format would pass however
+ * wrong that idea was.
+ */
+export function renderDotenv(values) {
+    return Object.keys(values)
+        .sort()
+        .map((key) => dotenvLine(key, values[key]))
+        .join("");
+}
+/**
+ * One `KEY=value` line, quoted if the value needs it.
+ *
+ * Exported for the preview the secrets screen shows, which renders a stand-in
+ * for every masked value rather than the value. It has to compose its own lines
+ * — a row of dots is not ASCII, so it would come back quoted, and the quotes
+ * would be a claim about the real value that nobody can check. It still goes
+ * through this function for everything it does show, so the preview and the
+ * file cannot drift apart in how they write a line.
+ */
+export function dotenvLine(key, value) {
+    return `${key}=${BARE.test(value) ? value : `"${escape(value)}"`}\n`;
+}
+/** The first line of a file, or null when there is no file to read. */
+async function firstLine(path) {
+    const text = await readFile(path, "utf8").catch(() => null);
+    return text === null ? null : (text.split("\n")[0] ?? "");
+}
+/** Whether this file is one Laneyard wrote, and may therefore replace or remove. */
+async function ours(path) {
+    const line = await firstLine(path);
+    return line === null || line.trimEnd() === LANEYARD_MARKER;
+}
+/**
+ * Writes the environment file, and returns its path — or null, having written
+ * nothing.
+ *
+ * Null has two causes and neither is an error: the project names no `env_file`,
+ * or a file is already there that Laneyard did not write. That second one is
+ * the important guard. The path points into a clone the user can work in by
+ * hand, and a `.env` they put there themselves is their build's real
+ * configuration — overwriting it would replace something that works with
+ * something assembled from a checklist. It is left exactly as it is.
+ *
+ * The marker is the first line, so the file says what it is to anyone who opens
+ * it, and so this function can tell its own output from a person's on the next
+ * run. `#` is a comment in dotenv, which is the reason dotenv is the only
+ * format for now: JSON has nowhere to put a line like this.
+ */
+export async function writeEnvFile(appRoot, envFile, values) {
+    if (envFile === undefined)
+        return null;
+    const path = join(appRoot, envFile);
+    if (!(await ours(path)))
+        return null;
+    await mkdir(dirname(path), { recursive: true });
+    // The mode is set twice, as in `materialise.ts` and `gradle-properties.ts`:
+    // `writeFile`'s mode is masked by the process umask, and ignored outright for
+    // a file that already exists. This one holds whatever the vault held.
+    await writeFile(path, `${LANEYARD_MARKER}\n${renderDotenv(values)}`, { mode: 0o600 });
+    await chmod(path, 0o600);
+    return path;
+}
+/**
+ * Removes a file this run wrote, and only such a file.
+ *
+ * Called from the run's `finally`, so the values do not outlive the build that
+ * needed them. Takes null so the caller can hand it whatever `writeEnvFile`
+ * returned without a branch of its own.
+ */
+export async function removeEnvFile(path) {
+    if (path === null)
+        return;
+    if ((await firstLine(path))?.trimEnd() !== LANEYARD_MARKER)
+        return;
+    await rm(path, { force: true }).catch(() => { });
+}
+/**
+ * Removes a marked file left where this run would write one.
+ *
+ * A run killed between writing the file and reaching its `finally` — an
+ * unplugged server, a `kill -9` — leaves values in a working tree that is kept
+ * between runs. Nothing at that moment can clean up after itself, so the next
+ * run does it first.
+ *
+ * Silent about everything: a workspace that was never cloned has nothing to
+ * sweep, and a sweep that failed must not be the reason a build did not start.
+ */
+export async function sweepEnvFile(appRoot, envFile) {
+    if (envFile === undefined)
+        return;
+    await removeEnvFile(join(appRoot, envFile)).catch(() => { });
+}

package/dist/src/runner/orchestrate.js

@@ -4,8 +4,10 @@ import { gitEnvFor, Workspace } from "../git/workspace.js";
 import { summarizeFailure } from "../heuristics/error-summary.js";
 import { appRootOf, searchDir } from "../heuristics/platforms.js";
 import { Redactor, scrub } from "../logs/redact.js";
+import { assertFastlaneDir } from "../sidecar/fastlane-dir.js";
 import { collectArtifacts } from "./artifacts.js";
 import { removeGradleProperties, sweepGradleProperties, writeGradleProperties, } from "./gradle-properties.js";
+import { removeEnvFile, sweepEnvFile, writeEnvFile } from "./env-file.js";
 import { LiveStepTracker } from "./live-steps.js";
 import { startPty } from "./pty.js";
 import { readReport } from "./report.js";
@@ -30,13 +32,14 @@ import { readReport } from "./report.js";
  * inside the run and has to be visible to a `finally` wrapped around all of it.
  */
 export async function executeRun(opts) {
-    const wrote = { properties: null };
+    const wrote = { properties: null, envFile: null };
     try {
         return await execute(opts, wrote);
     }
     finally {
         // Guarded by the marker, so a file the user replaced mid-run survives.
         await removeGradleProperties(wrote.properties).catch(() => { });
+        await removeEnvFile(wrote.envFile).catch(() => { });
         // Deliberately swallowed: by now the log writer is closed and the run's
         // verdict is recorded, so there is nowhere left to report this without
         // rewriting a finished run's outcome as a failure it did not have. A
@@ -122,10 +125,25 @@ async function execute(opts, wrote) {
     // the next run is the first moment anything can. Its failure is not reported
     // — a leftover that resists removal is a broken disk, not a broken build, and
     // saying so here would fail a run for a file it has not needed yet.
-    const androidRoot = searchDir(opts.workspacePath, appRootOf(settings.fastlane_dir));
-    await sweepGradleProperties(androidRoot, opts.androidKeystore).catch(() => { });
+    //
+    // The app's own directory, which is the parent of the configured fastlane
+    // folder: the repository root for a plain app, `app/` for one in a monorepo.
+    // It is where the properties file goes and, below, where fastlane is started.
+    const appRoot = searchDir(opts.workspacePath, appRootOf(settings.fastlane_dir));
+    // Before any of that, and before fastlane: a clone without the folder is the
+    // one failure fastlane reports worst. It asks whether to set a project up,
+    // finds nobody to answer, and prints a Ruby backtrace and a list of GitHub
+    // issues over the sentence that mattered. This says it in one line instead.
+    try {
+        await assertFastlaneDir(opts.workspacePath, settings.fastlane_dir);
+    }
+    catch (cause) {
+        return fail(cause.message);
+    }
+    await sweepGradleProperties(appRoot, opts.androidKeystore).catch(() => { });
+    await sweepEnvFile(appRoot, settings.env_file).catch(() => { });
     try {
-        wrote.properties = await writeGradleProperties(androidRoot, opts.androidKeystore);
+        wrote.properties = await writeGradleProperties(appRoot, opts.androidKeystore);
     }
     catch (cause) {
         // Failing the run rather than carrying on. Carrying on is what produces the
@@ -133,6 +151,16 @@ async function execute(opts, wrote) {
         // succeeds, signed with the debug key, rejected by the store days later.
         return fail(`Could not write the signing properties file: ${cause.message}`);
     }
+    try {
+        wrote.envFile = await writeEnvFile(appRoot, settings.env_file, opts.envFileValues ?? {});
+    }
+    catch (cause) {
+        // Failing for the same reason, and it is the same shape of failure. A build
+        // that carries on without the file it was configured to read does not stop:
+        // it produces an app pointed at nothing, which is discovered by a person
+        // opening it rather than by this run.
+        return fail(`Could not write the environment file: ${cause.message}`);
+    }
     // Cancelled during preparation: fastlane never gets to start.
     if (opts.signal?.aborted) {
         return finishAs("cancelled", "Cancelled");
@@ -162,7 +190,13 @@ async function execute(opts, wrote) {
         args: useBundle
             ? ["exec", "fastlane", ...laneArgs(opts)]
             : laneArgs(opts),
-        cwd: opts.workspacePath,
+        // The app's directory, not the repository root. fastlane looks for
+        // `fastlane/` in the directory it was started from and nowhere else — no
+        // walking up, no looking down — so a project whose Fastfile sits in
+        // `app/fastlane` has to be started from `app`. Started from the root it
+        // finds nothing and offers to set fastlane up, which on a build server
+        // means a crash: there is nobody there to answer the question.
+        cwd: appRoot,
         env: {
             ...opts.env,
             ...(opts.secrets ?? {}),

package/dist/src/secrets/vault.js

@@ -21,8 +21,8 @@ export class Vault {
     static async open(home, store, credentials) {
         return new Vault(await loadOrCreateKey(home), store, credentials);
     }
-    async set(projectSlug, key, value, masked) {
-        this.store.set(projectSlug, key, encrypt(value, this.key), masked);
+    async set(projectSlug, key, value, masked, inEnvFile = false) {
+        this.store.set(projectSlug, key, encrypt(value, this.key), masked, inEnvFile);
     }
     remove(projectSlug, key) {
         return this.store.remove(projectSlug, key);
@@ -30,23 +30,41 @@ export class Vault {
     list(projectSlug) {
         return this.store.list(projectSlug);
     }
-    listGlobal() {
-        return this.store.listGlobal();
-    }
     /**
-     * What the vault holds under one project's own name — secrets and signing
-     * blocks — and nothing global.
+     * The same listing, with the value attached wherever there is nothing to hide.
+     *
+     * The rule is the user's own tick box and nothing else: `masked` means "keep
+     * this out of the build logs", and a value carrying it is never returned,
+     * whoever asks. A value without it is printed verbatim in every log the lane
+     * produces — hiding it on the one screen where you might want to check it
+     * protects nothing and costs the check.
+     *
+     * That is why this is not `list`. Everything else in the server asks a
+     * question about names — is this one stored, is that one missing — and it
+     * would be a poor trade to hand all of them plaintext for it. One method, one
+     * caller, and `list` stays the answer to "what is here".
      *
-     * Its own method rather than a filter over `list`, because the question is a
-     * different one: `list` is "what would a run of this project see", and this is
-     * "what would be left behind if the project went away". A global secret is in
-     * the first answer and must never be in the second.
+     * A masked value stays out even though `reveal` would now return it: a secret
+     * is readable on request, one key at a time, and that is not the same as
+     * putting every secret a project holds into a browser because someone opened
+     * a tab.
+     *
+     * A row that will not decrypt loses its value and keeps its name, the same
+     * leniency `resolve` takes: a rotated key should cost one line of one screen,
+     * not the screen.
      */
-    ownedBy(projectSlug) {
-        return {
-            secrets: this.store.listOwn(projectSlug),
-            credentials: this.credentials.listOwn(projectSlug),
-        };
+    listWithValues(projectSlug) {
+        return this.store.list(projectSlug).map((summary) => {
+            if (summary.masked)
+                return summary;
+            try {
+                const value = this.reveal(projectSlug, summary.key);
+                return value === null ? summary : { ...summary, value };
+            }
+            catch {
+                return summary;
+            }
+        });
     }
     /**
      * Forgets everything stored under one project's name.
@@ -56,13 +74,15 @@ export class Vault {
      * covers all of it. What it forgets is Laneyard's own encrypted copy — the
      * `.p8` and the keystore that went in are still wherever the user keeps them.
      *
-     * Scoped by slug, so a global secret or a global signing block survives it:
-     * those are read by every project and are never one project's to remove.
+     * There is nothing it has to leave behind. Everything a project sees is a row
+     * under its own slug, so "what would a run see" and "what would be left if the
+     * project went away" are now the same question — which is most of the point of
+     * having one scope.
      */
     forget(projectSlug) {
         return {
-            secrets: this.store.removeAllOwn(projectSlug),
-            credentials: this.credentials.removeAllOwn(projectSlug),
+            secrets: this.store.removeAll(projectSlug),
+            credentials: this.credentials.removeAll(projectSlug),
         };
     }
     /**
@@ -75,7 +95,7 @@ export class Vault {
         return scrub(text, this.maskedValues(projectSlug));
     }
     /**
-     * Every secret that applies to a project, ready to become environment variables.
+     * Every secret a project holds, ready to become environment variables.
      *
      * A row that will not decrypt is skipped rather than thrown: a key that was
      * rotated or a corrupted row should cost one variable, not the whole build.
@@ -94,35 +114,53 @@ export class Vault {
         return out;
     }
     /**
-     * One value, in the clear — and only when it was never declared secret.
+     * One value, in the clear, whether or not it is masked.
      *
-     * The refusal is the point. This vault has been write-only since it was
-     * written: the server never sent a value back, so the interface had nothing to
-     * uncover and no browser ever held one. That is worth keeping for anything
-     * anyone called a secret.
+     * This used to refuse a masked value outright: the vault was write-only, no
+     * route ever sent one back, and the secrets screen offered nothing to press.
+     * The property was real and it was worth less than it looked. `masked` means
+     * "keep this out of the build logs" — it is about what a run prints, and it
+     * was doing double duty as "and nobody may ever look at it again", which
+     * nobody asked for. A passphrase stored six months ago and now suspected of a
+     * typo could only be replaced, never checked, and replacing a credential you
+     * cannot read is how the wrong one gets stored twice.
      *
-     * But not everything stored here is one. `APP_VERSION`, `SENTRY_ORG`, an
-     * issuer id — those are identifiers, and being unable to check what was stored
-     * makes an import something you have to take on faith. The line between the
-     * two already existed and is the user's own: `masked` is "keep this out of the
-     * logs". A value that carries it is never returned, whoever asks.
+     * What the refusal actually bought was narrow, because everything around it
+     * still holds: the screen is admin-only, one key is read per request, and a
+     * masked value is still absent from `listWithValues`, so opening the page puts
+     * none of them in a browser. What is gone is only the guarantee that a value
+     * never leaves the server — which was never what protected it. Redaction of
+     * the logs is untouched and is the property that matters.
      *
-     * Returns null for an unknown key, and throws for a masked one — a caller
-     * that forgot to check must fail loudly rather than leak.
+     * Returns null for an unknown key.
      */
     reveal(projectSlug, key) {
         const row = this.store.find(projectSlug, key);
         if (!row)
             return null;
-        if (row.masked) {
-            throw new Error(`${key} is kept out of the logs, so its value is never sent back.`);
-        }
         return decrypt(row.valueEnc, this.key);
     }
     /** Flips whether a value is kept out of the logs, leaving the value alone. */
     setMasked(projectSlug, key, masked) {
         return this.store.setMasked(projectSlug, key, masked);
     }
+    /** Flips whether a value is written into the environment file. */
+    setInEnvFile(projectSlug, key, inEnvFile) {
+        return this.store.setInEnvFile(projectSlug, key, inEnvFile);
+    }
+    /**
+     * The variables that go in the environment file, in the clear, ready to be
+     * rendered.
+     *
+     * Decrypted here rather than in the writer, so plaintext stays inside this one
+     * file — the property the whole module exists to make checkable by reading.
+     * A row that will not decrypt is skipped, the same leniency `resolve` takes:
+     * the build then fails on its own terms rather than on a rotated key.
+     */
+    envFileValues(projectSlug) {
+        const wanted = new Set(this.store.envFileKeys(projectSlug));
+        return Object.fromEntries(Object.entries(this.resolve(projectSlug)).filter(([key]) => wanted.has(key)));
+    }
     /**
      * Stores a signing block: the file, and the fields that make it usable.
      *
@@ -140,7 +178,7 @@ export class Vault {
         });
     }
     /**
-     * One block that applies to a project, in the clear, or undefined if there is none.
+     * One of a project's blocks, in the clear, or undefined if there is none.
      *
      * Unlike `resolve`, an unreadable row throws. The leniency there is earned: a
      * missing variable makes fastlane stop and say which one. A block that quietly
@@ -168,9 +206,6 @@ export class Vault {
     listCredentials(projectSlug) {
         return this.credentials.list(projectSlug);
     }
-    listGlobalCredentials() {
-        return this.credentials.listGlobal();
-    }
     removeCredential(projectSlug, kind) {
         return this.credentials.remove(projectSlug, kind);
     }

package/dist/src/server/app.js

@@ -98,6 +98,10 @@ export async function buildApp(deps) {
             },
             env: process.env,
             secrets: ctx.vault.resolve(slug),
+            // A subset of the line above, not a second source. The tick decides which
+            // variables are also written into the file the build reads from disk;
+            // every one of them still reaches the run through the environment.
+            envFileValues: ctx.vault.envFileValues(slug),
             credentialEnv: credentials.env,
             androidKeystore: credentials.keystore,
             cleanup: credentials.cleanup,

package/dist/src/server/routes/credentials.js

@@ -14,7 +14,6 @@ import { CREDENTIAL_KINDS, defaultVarNames, fieldsOf } from "../../credentials/k
 /** POSIX environment variable names. Anything else would never reach fastlane. */
 const VALID_VAR = /^[A-Za-z_][A-Za-z0-9_]*$/;
 export async function registerCredentialRoutes(app, ctx) {
-    app.get("/api/credentials", async () => ctx.vault.listGlobalCredentials());
     app.get("/api/projects/:slug/credentials", async (req, reply) => {
         const { slug } = req.params;
         if (!ctx.config.project(slug))
@@ -82,24 +81,12 @@ export async function registerCredentialRoutes(app, ctx) {
         await ctx.vault.setCredential(slug, spec.kind, { fileName, fileBytes, fields: kept, varNames: names });
         return reply.code(204).send();
     };
-    app.put("/api/credentials/:kind", async (req, reply) => put(null, req.params.kind, req.body, reply));
     app.put("/api/projects/:slug/credentials/:kind", async (req, reply) => {
         const { slug, kind } = req.params;
         if (!ctx.config.project(slug))
             return reply.code(404).send({ error: "Unknown project" });
         return put(slug, kind, req.body, reply);
     });
-    app.delete("/api/credentials/:kind", async (req, reply) => {
-        const { kind } = req.params;
-        const removed = ctx.vault.removeCredential(null, kind);
-        return removed ? reply.code(204).send() : reply.code(404).send({ error: "Unknown credential" });
-    });
-    /**
-     * Removes this project's own block, and only that one. A global block that
-     * was shadowed comes back into view, which is the deletion someone asked for:
-     * they are undoing an override, not deleting everyone's key from inside one
-     * project.
-     */
     app.delete("/api/projects/:slug/credentials/:kind", async (req, reply) => {
         const { slug, kind } = req.params;
         const removed = ctx.vault.removeCredential(slug, kind);

package/dist/src/server/routes/fastfile.js

@@ -46,7 +46,7 @@ export async function registerFastfileRoutes(app, ctx) {
             // uncommitted or gitignored, or a stray local copy. `store.read` would
             // surface that as a bare ENOENT; this turns it into the same sentence the
             // sidecar gives, naming the directory and how to fix it.
-            await assertFastlaneDir(join(r.workspacePath, r.fastlaneDir), r.fastlaneDir);
+            await assertFastlaneDir(r.workspacePath, r.fastlaneDir);
             const [content, dirty, diff] = await Promise.all([
                 store.read(r.workspacePath, r.fastlaneDir),
                 r.workspace.isDirty(),

package/dist/src/server/routes/projects.js

@@ -1,4 +1,5 @@
 import { accountMayReach } from "../permissions.js";
+import { Workspace } from "../../git/workspace.js";
 import { removeProjectData } from "../../data/remove-project.js";
 export async function registerProjectRoutes(app, ctx) {
     // The listing every account is shown, filtered to what it may reach. This is
@@ -41,9 +42,6 @@ export async function registerProjectRoutes(app, ctx) {
      *    `.p8` or a keystore; the file that went in is still in the password
      *    manager or the safe it came from. The answer says so, the way
      *    `uninstall` does, so nobody is left thinking their keystore is gone.
-     *  - global secrets and global signing blocks. They are read by every project
-     *    on the machine, not this one's to take — `vault.forget` touches only
-     *    slug-scoped rows, and the answer counts the global ones it left alone.
      *
      * The confirmation is the project's own slug, sent back as `?confirm=`.
      * Without a match nothing is removed: a bare DELETE is a refusal, not a
@@ -72,12 +70,6 @@ export async function registerProjectRoutes(app, ctx) {
                 error: `"${slug}" has a run in flight. Wait for it to finish, or cancel it, then remove the project.`,
             });
         }
-        // The global counts are read now — the last moment anyone is looking — so
-        // the answer can say what it left alone. They are shared by every project
-        // and survive one of them going away, which is why the removal never takes
-        // them and the reply names them apart.
-        const globalSecrets = ctx.vault.listGlobal().length;
-        const globalSigningBlocks = ctx.vault.listGlobalCredentials().length;
         // The removal itself lives in one place, shared with `laneyard remove`: the
         // route confirms and shapes the reply, the core does the deleting.
         const result = await removeProjectData({
@@ -108,13 +100,6 @@ export async function registerProjectRoutes(app, ctx) {
                 secrets: result.secrets,
                 signingBlocks: result.signingBlocks,
             },
-            // Named, not removed. The git remote and the credential originals are the
-            // user's and are never touched here; the global rows are shared by every
-            // project and survive one of them going away.
-            untouched: {
-                globalSecrets,
-                globalSigningBlocks,
-            },
         });
     });
     app.get("/api/projects/:slug/lanes", async (req, reply) => {
@@ -135,6 +120,64 @@ export async function registerProjectRoutes(app, ctx) {
             return reply.code(503).send({ error: cause.message });
         }
     });
+    /**
+     * Brings the clone up to the remote, without building anything.
+     *
+     * Everything that reads the repository outside a run — the lanes, the
+     * checklist, the names a lane is missing — goes through `ensureCloned`, which
+     * does nothing at all once the directory exists. Only a run fetched. So a
+     * project whose first run failed early answered from that first commit
+     * indefinitely, and the screens said so with the confidence of something just
+     * looked up: a variable a Fastfile had stopped reading was still asked for,
+     * days after the commit that stopped reading it.
+     *
+     * Deliberately not a fetch hidden inside those reads. Going out to a git
+     * remote is seconds and a network, and putting it behind opening a tab would
+     * make every one of them slow and occasionally fail for a reason that has
+     * nothing to do with what was asked. It is a button, and this is what it
+     * presses.
+     *
+     * `prepare` and not a bare fetch: the point is to show what the next run would
+     * see, and `prepare` is exactly what the next run calls. It clones when there
+     * is nothing yet, which makes the button a way in for a project between
+     * `setup` and its first build rather than a refusal.
+     *
+     * Not admin-only. A builder starts runs, and a run fetches — refusing them the
+     * same fetch on its own would protect nothing.
+     */
+    app.post("/api/projects/:slug/fetch", async (req, reply) => {
+        const { slug } = req.params;
+        const entry = ctx.config.project(slug);
+        if (!entry)
+            return reply.code(404).send({ error: "Unknown project" });
+        // A run that has begun is reading the very files this would move under it —
+        // the same reason a Fastfile write is refused while one is in flight.
+        if (ctx.runs.hasActiveRun(slug)) {
+            return reply.code(409).send({
+                error: "A run of this project is in flight. Its workspace is in use until it finishes.",
+            });
+        }
+        const branch = entry.default_branch;
+        const workspace = new Workspace(ctx.workspacePath(slug), entry.git_url, entry.git_auth);
+        // Refused rather than lost. `prepare` moves the branch onto origin's, and
+        // the Fastfile tab commits without pushing by design, so this is a state the
+        // product hands people itself.
+        const unpushed = await workspace.unpushedCount(branch);
+        if (unpushed > 0) {
+            return reply.code(409).send({
+                error: `The workspace holds ${unpushed} commit${unpushed === 1 ? "" : "s"} that ${unpushed === 1 ? "has" : "have"} not been pushed. ` + "Push from the fastfile tab, or they would be left behind.",
+            });
+        }
+        try {
+            const commitSha = await workspace.prepare(branch);
+            return { branch, commitSha };
+        }
+        catch (cause) {
+            // A dirty workspace, an unreachable remote, a branch that is not there:
+            // git's own sentence is the only thing that explains any of them.
+            return reply.code(409).send({ error: cause.message });
+        }
+    });
     app.get("/api/projects/:slug/runs", async (req, reply) => {
         const { slug } = req.params;
         if (!ctx.config.project(slug))

package/dist/src/server/routes/readiness.js

@@ -228,9 +228,8 @@ export async function registerReadinessRoutes(app, ctx) {
             },
             // Names only: the vault never hands a value to anything but a run.
             secretKeys: ctx.vault.list(slug).map((s) => s.key),
-            // Which blocks apply, resolved the way a run resolves them — a project's
-            // own shadowing a global one — so the checklist and the run cannot
-            // disagree about whether a credential exists.
+            // Which blocks this project holds, read the way a run reads them, so the
+            // checklist and the run cannot disagree about whether a credential exists.
             blocks: ctx.vault.listCredentials(slug).map((c) => c.kind),
             // And the names those blocks will export, which the environment check
             // counts as supplied — Laneyard writes the file and sets the variable