@bevel-software/platform-core-backend 0.21.0 → 0.23.0

package/src/modules/settings/__tests__/repository-source.test.ts

@@ -0,0 +1,191 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
+import { ManagedRepository, MANAGED_REPOSITORY_DIR } from '../managed-repository.js';
+import { RepositorySource, type GitHubAppRepository } from '../repository-source.js';
+
+let root: string;
+
+beforeEach(async () => {
+  root = await fs.mkdtemp(path.join(os.tmpdir(), 'hexis-managed-'));
+});
+
+afterEach(async () => {
+  await fs.rm(root, { recursive: true, force: true });
+});
+
+const reading = (values: Record<string, string>) => (key: string) => values[key] ?? '';
+
+function source(values: Record<string, string>, extra: { fallbackToken?: string; githubApp?: GitHubAppRepository } = {}) {
+  const managed = new ManagedRepository(path.join(root, 'managed-repository'));
+  return {
+    managed,
+    source: new RepositorySource({
+      read: reading(values),
+      fallback: { username: 'x-access-token', token: extra.fallbackToken ?? '' },
+      managed,
+      ...(extra.githubApp ? { githubApp: extra.githubApp } : {}),
+    }),
+  };
+}
+
+const HOSTED = { kbRepoUrl: 'https://git.example.com/acme/kb.git', gitToken: 'the-token', gitUsername: 'oauth2' };
+
+describe('RepositorySource: which way a deployment has its repository', () => {
+  it('has none while nothing is configured', () => {
+    const { source: s } = source({});
+    expect(s.mode()).toBeNull();
+    expect(s.url()).toBe('');
+    expect(s.answered()).toBe(false);
+    expect(s.credentials.token()).toBeNull();
+  });
+
+  it('reads a deployment configured before there was a choice as what it has: an address and a token', () => {
+    const { source: s } = source(HOSTED);
+    expect(s.mode()).toBe('token');
+    expect(s.url()).toBe(HOSTED.kbRepoUrl);
+    expect(s.credentials.token()).toBe('the-token');
+    expect(s.credentials.username()).toBe('oauth2');
+    expect(s.answered()).toBe(true);
+  });
+
+  it('reads a token the environment spells the old way', () => {
+    const { source: s } = source({ kbRepoUrl: HOSTED.kbRepoUrl }, { fallbackToken: 'from-GITHUB_TOKEN' });
+    expect(s.mode()).toBe('token');
+    expect(s.credentials.token()).toBe('from-GITHUB_TOKEN');
+    expect(s.answered()).toBe(true);
+  });
+
+  it('is not answered by half of an address and a token', () => {
+    expect(source({ kbRepoUrl: HOSTED.kbRepoUrl }).source.answered()).toBe(false);
+    expect(source({ gitToken: 'the-token' }).source.answered()).toBe(false);
+  });
+
+  it('ignores a mode it does not know, and reads what is configured', () => {
+    expect(source({ ...HOSTED, gitMode: 'carrier-pigeon' }).source.mode()).toBe('token');
+  });
+
+  it('answers for the values a save would put in effect, without the save', () => {
+    const { source: s, managed } = source(HOSTED);
+    const after = reading({ ...HOSTED, gitMode: 'managed' });
+    expect(s.mode(after)).toBe('managed');
+    expect(s.url(after)).toBe(managed.path);
+    // What is in effect has not moved.
+    expect(s.mode()).toBe('token');
+  });
+});
+
+describe('RepositorySource: a repository the deployment keeps', () => {
+  it('is reached by its path, and presented nothing', () => {
+    const { source: s, managed } = source({ gitMode: 'managed' });
+    expect(s.url()).toBe(managed.path);
+    expect(s.url()).toBe(path.join(root, 'managed-repository', MANAGED_REPOSITORY_DIR));
+    expect(s.answered()).toBe(true);
+    expect(s.credentials.token()).toBeNull();
+  });
+
+  /**
+   * One mode's credential is never presented to another mode's repository.
+   * A deployment that moved still has its old token stored, and it must not
+   * ride along in the environment of every git call made against a folder.
+   */
+  it('is never presented the token of the repository the deployment had before', () => {
+    const { source: s } = source({ ...HOSTED, gitMode: 'managed' }, { fallbackToken: 'from-the-environment' });
+    expect(s.credentials.token()).toBeNull();
+    expect(s.credentials.username()).toBe('x-access-token');
+  });
+});
+
+describe('RepositorySource: a repository reached through a GitHub App', () => {
+  const app = (overrides: Partial<GitHubAppRepository> = {}): GitHubAppRepository => ({
+    url: () => 'https://github.com/acme/kb.git',
+    token: () => 'an-installation-token',
+    prepare: async () => undefined,
+    answered: () => true,
+    ...overrides,
+  });
+
+  it('asks the app for the address and the token', () => {
+    const { source: s } = source({ gitMode: 'github-app', gitToken: 'a-leftover' }, { githubApp: app() });
+    expect(s.url()).toBe('https://github.com/acme/kb.git');
+    expect(s.credentials.token()).toBe('an-installation-token');
+    expect(s.credentials.username()).toBe('x-access-token');
+    expect(s.answered()).toBe(true);
+  });
+
+  it('renews the token before git is run, and only in this mode', async () => {
+    let renewed = 0;
+    const githubApp = app({ prepare: async () => void (renewed += 1) });
+    await source({ gitMode: 'github-app' }, { githubApp }).source.credentials.prepare?.();
+    await source(HOSTED, { githubApp }).source.credentials.prepare?.();
+    await source({ gitMode: 'managed' }, { githubApp }).source.credentials.prepare?.();
+    expect(renewed).toBe(1);
+  });
+
+  it('is unanswered on a deployment that has no such app', () => {
+    const { source: s } = source({ gitMode: 'github-app' });
+    expect(s.answered()).toBe(false);
+    expect(s.url()).toBe('');
+    expect(s.credentials.token()).toBeNull();
+  });
+});
+
+describe('ManagedRepository', () => {
+  const runner = new NodeGitRunner(30_000);
+  const git = async (cwd: string, ...args: string[]) => (await runner.run(cwd, args)).stdout.trim();
+
+  it('is created empty, bare, on the branch it is given', async () => {
+    const managed = new ManagedRepository(path.join(root, 'managed-repository'));
+    expect(await managed.exists()).toBe(false);
+    await managed.ensure(runner, 'trunk');
+    expect(await managed.exists()).toBe(true);
+    expect(await git(managed.path, 'rev-parse', '--is-bare-repository')).toBe('true');
+    expect(await git(managed.path, 'symbolic-ref', 'HEAD')).toBe('refs/heads/trunk');
+    expect(await git(managed.path, 'for-each-ref')).toBe('');
+  });
+
+  it('is cloned from, pushed to and fetched from like any remote', async () => {
+    const managed = new ManagedRepository(path.join(root, 'managed-repository'));
+    await managed.ensure(runner);
+    const one = path.join(root, 'one');
+    await fs.mkdir(one);
+    await git(one, 'init', '--initial-branch=main');
+    await fs.writeFile(path.join(one, 'README.md'), 'hello\n');
+    await git(one, 'add', '.');
+    await git(one, '-c', 'user.name=t', '-c', 'user.email=t@example.test', 'commit', '-m', 'first');
+    await git(one, 'push', managed.path, 'main');
+
+    const two = path.join(root, 'two');
+    await git(root, 'clone', '-b', 'main', managed.path, two);
+    // Whatever this machine's git makes of line endings on checkout.
+    expect((await fs.readFile(path.join(two, 'README.md'), 'utf8')).replace(/\r\n/g, '\n')).toBe('hello\n');
+    expect(await git(two, 'config', '--get', 'remote.origin.url')).toBe(managed.path);
+  });
+
+  it('is left exactly as it is when it already exists', async () => {
+    const managed = new ManagedRepository(path.join(root, 'managed-repository'));
+    await managed.ensure(runner);
+    const work = path.join(root, 'work');
+    await fs.mkdir(work);
+    await git(work, 'init', '--initial-branch=main');
+    await fs.writeFile(path.join(work, 'a.md'), 'a\n');
+    await git(work, 'add', '.');
+    await git(work, '-c', 'user.name=t', '-c', 'user.email=t@example.test', 'commit', '-m', 'first');
+    await git(work, 'push', managed.path, 'main');
+    const before = await git(managed.path, 'for-each-ref');
+
+    await managed.ensure(runner, 'another-branch');
+    expect(await git(managed.path, 'for-each-ref')).toBe(before);
+    expect(await git(managed.path, 'symbolic-ref', 'HEAD')).toBe('refs/heads/main');
+  });
+
+  it('refuses a folder that holds something that is not a repository', async () => {
+    const managed = new ManagedRepository(path.join(root, 'managed-repository'));
+    await fs.mkdir(managed.path, { recursive: true });
+    await fs.writeFile(path.join(managed.path, 'somebody.txt'), 'theirs');
+    await expect(managed.ensure(runner)).rejects.toThrow(/is not a git repository/);
+    expect(await fs.readFile(path.join(managed.path, 'somebody.txt'), 'utf8')).toBe('theirs');
+  });
+});

package/src/modules/settings/__tests__/setup.routes.git-mode.test.ts

@@ -0,0 +1,386 @@
+import type { Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+import type { KbContext } from '../../../shared/kb-context.js';
+import { createSetupRoutes } from '../setup.routes.js';
+import { DeploymentSettingsService } from '../deployment-settings.service.js';
+import { ManagedRepository } from '../managed-repository.js';
+import { RepositorySource } from '../repository-source.js';
+import type { Database } from '../../database/connection.js';
+import type { IAdminAccessService } from '../../admin/admin.interface.js';
+import type { ConnectionCheck, RepositoryConnection } from '../connection-check.js';
+
+const ENC_KEY = 'kToAi8FXWDpDn3A6yQ/60O39bv05N7XzVOIu/0CJrFc=';
+const KB_ENV = ['KB_REPO_URL', 'GIT_TOKEN', 'GIT_USERNAME', 'GIT_MODE', 'GITHUB_TOKEN', 'DEFAULT_BRANCH', 'PROTECTED_BRANCHES'] as const;
+
+let server: HttpServer | null = null;
+let savedEnv: Partial<Record<(typeof KB_ENV)[number], string | undefined>> = {};
+
+beforeEach(() => {
+  savedEnv = {};
+  for (const k of KB_ENV) {
+    savedEnv[k] = process.env[k];
+    delete process.env[k];
+  }
+});
+
+afterEach(() => {
+  server?.close();
+  server = null;
+  for (const k of KB_ENV) {
+    const original = savedEnv[k];
+    if (original === undefined) delete process.env[k];
+    else process.env[k] = original;
+  }
+});
+
+/**
+ * The setup router with the choice of repository, over settings that are
+ * stored in memory. The managed repository is a stand-in that records being
+ * asked for; the startup phase and the remote are stand-ins that count.
+ */
+function listen(
+  opts: {
+    kb?: KbContext;
+    ensureFails?: boolean;
+    stored?: Record<string, string>;
+    /** The addresses the startup phase cannot reach. */
+    unreachable?: (url: string) => boolean;
+    /** The deployment booted onto a repository it could not reach, and came up gated. */
+    bootFailed?: boolean;
+  } = {},
+) {
+  const db = {
+    select: () => ({ from: () => Promise.resolve([]) }),
+    insert: () => ({ values: () => ({ onConflictDoUpdate: () => Promise.resolve() }) }),
+    delete: () => ({ where: () => Promise.resolve() }),
+  } as unknown as Database;
+  const settings = new DeploymentSettingsService(db, ENC_KEY);
+  const kb = opts.kb ?? testKbContext({ branchModel: null });
+  const managed = new ManagedRepository('/data/backups/managed-repository');
+  const source = new RepositorySource({ read: (key) => settings.resolve(key), managed });
+  const ensured: string[] = [];
+  const probed: RepositoryConnection[] = [];
+  let phaseRuns = 0;
+  /** The address the startup phase found configured when it ran. */
+  const phaseSaw: string[] = [];
+  /** Stands until the deployment is pointed somewhere the phase can reach. */
+  let bootFailed = opts.bootFailed ?? false;
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.userEmail = 'root@example.com';
+    req.userId = 'user-1';
+    next();
+  });
+  app.use(
+    '/api',
+    createSetupRoutes(
+      settings,
+      { isAdmin: async () => true } as IAdminAccessService,
+      {
+        runAll: async () => {
+          phaseRuns += 1;
+          phaseSaw.push(source.url());
+          if (opts.unreachable?.(source.url())) throw new Error(`fatal: repository '${source.url()}' not found`);
+          bootFailed = false;
+        },
+        // A boot that survived an unreachable repository, as the runner reports it.
+        ...(opts.bootFailed ? { lastFailure: () => (bootFailed ? 'fatal: unable to access the repository' : null) } : {}),
+      },
+      kb,
+      undefined,
+      async (connection): Promise<ConnectionCheck> => {
+        probed.push(connection);
+        return { outcome: 'connected', branches: ['main'], defaultBranch: 'main', empty: false };
+      },
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      {
+        source,
+        ensureManaged: async (branch) => {
+          if (opts.ensureFails) throw new Error('EACCES: permission denied, mkdir /data/backups');
+          ensured.push(branch);
+        },
+      },
+    ),
+  );
+  server = app.listen(0);
+  const { port } = server.address() as AddressInfo;
+  const base = `http://127.0.0.1:${port}`;
+  /** `confirm` is the admin's answer to the question a move is asked, when they have given one. */
+  const save = (entries: Record<string, string>, confirm?: 'keep' | 'close') =>
+    fetch(`${base}/api/setup/settings`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ settings: entries, ...(confirm ? { confirmRepositoryChange: confirm } : {}) }),
+    });
+  const status = async () => (await fetch(`${base}/api/setup/status`)).json() as Promise<Record<string, unknown>>;
+  return { save, status, settings, source, managed, ensured, probed, kb, phase: { runs: () => phaseRuns, saw: phaseSaw } };
+}
+
+const HOSTED = { kbRepoUrl: 'https://git.example.com/acme/kb.git', gitToken: 'the-token' };
+const BRANCHES = { defaultBranch: 'main', protectedBranches: 'main' };
+
+describe('setup status: the choice of repository', () => {
+  it('offers the ways there are, and says none is chosen on a new deployment', async () => {
+    const { status } = listen();
+    expect(await status()).toMatchObject({ complete: false, repository: { mode: null, modes: ['managed', 'token'] } });
+  });
+
+  it('says a deployment configured before there was a choice is on the way it has', async () => {
+    const { status, save } = listen({ kb: testKbContext() });
+    await save({ ...HOSTED, ...BRANCHES });
+    expect(await status()).toMatchObject({ repository: { mode: 'token' } });
+  });
+});
+
+describe('choosing a repository the deployment keeps', () => {
+  it('finishes setup on that choice alone', async () => {
+    const { save, ensured, probed, phase, managed, kb } = listen();
+    const res = await save({ gitMode: 'managed' });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body).toMatchObject({ ok: true, complete: true, restartRequired: false, repository: { mode: 'managed' } });
+    // The repository was there before the save pointed everything at it,
+    expect(ensured).toEqual(['main']);
+    // no host was asked anything,
+    expect(probed).toEqual([]);
+    // and the startup phase ran against it, on the branches named for it.
+    expect(phase.runs()).toBe(1);
+    expect(phase.saw).toEqual([managed.path]);
+    expect(kb.defaultBranch).toBe('main');
+    expect([...kb.protectedBranches]).toEqual(['main']);
+  });
+
+  it('keeps the branches an admin named over its own', async () => {
+    const { save, ensured, settings } = listen();
+    const res = await save({ gitMode: 'managed', defaultBranch: 'live', protectedBranches: 'live, draft' });
+    expect(res.status).toBe(200);
+    expect(ensured).toEqual(['live']);
+    expect(settings.resolve('defaultBranch')).toBe('live');
+    expect(settings.resolve('protectedBranches')).toBe('live, draft');
+  });
+
+  it('names no branches for any other way: a repository that exists is asked for its own', async () => {
+    const { save, settings } = listen();
+    await save({ ...HOSTED, gitMode: 'token' });
+    expect(settings.resolve('defaultBranch')).toBe('');
+    expect(settings.resolve('protectedBranches')).toBe('');
+  });
+
+  it('refuses the choice when the repository cannot be created, and stores nothing', async () => {
+    const { save, settings, phase } = listen({ ensureFails: true });
+    const res = await save({ gitMode: 'managed' });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string; problems: Record<string, string> };
+    expect(body.problems.gitMode).toMatch(/could not be created/);
+    // What the disk said stays in the log.
+    expect(JSON.stringify(body)).not.toMatch(/EACCES|\/data\/backups/);
+    expect(settings.resolve('gitMode')).toBe('');
+    expect(phase.runs()).toBe(0);
+  });
+
+  it('refuses a way it does not know', async () => {
+    const { save } = listen();
+    const res = await save({ gitMode: 'carrier-pigeon' });
+    expect(res.status).toBe(400);
+    expect(((await res.json()) as { problems: Record<string, string> }).problems.gitMode).toMatch(/managed, github-app, token/);
+  });
+});
+
+describe('a deployment that is serving moves to another repository', () => {
+  async function serving() {
+    const mounted = listen({ kb: testKbContext() });
+    await mounted.save({ ...HOSTED, ...BRANCHES });
+    return mounted;
+  }
+
+  /**
+   * A move is asked about before anything is stored: the save is refused
+   * until the answer comes back, naming the way left and the way moved to.
+   * Refused, it has changed nothing — the deployment is where it was.
+   */
+  it('is asked first, and until it answers nothing has moved', async () => {
+    const { save, status, phase, source, settings } = await serving();
+    const runsBefore = phase.runs();
+    const res = await save({ gitMode: 'managed' });
+    expect(res.status).toBe(409);
+    expect(await res.json()).toMatchObject({ repositoryChange: { openChangeRequests: 0, from: 'token', to: 'managed' } });
+    expect(settings.resolve('gitMode')).toBe('');
+    expect(source.mode()).toBe('token');
+    expect(source.url()).toBe(HOSTED.kbRepoUrl);
+    expect(phase.runs()).toBe(runsBefore);
+    expect(await status()).toMatchObject({ complete: true, repository: { mode: 'token', chosen: 'token' } });
+  });
+
+  /**
+   * Confirmed, the move takes effect ON THE SAVE: the way chosen is the way
+   * in effect, the startup phase runs against the repository moved to, and
+   * no restart is owed. It once waited for the next start, which an admin of
+   * a hosted workspace has no way to give.
+   */
+  it('moves on the save once confirmed, and owes no restart', async () => {
+    const { save, status, phase, ensured, managed, source } = await serving();
+    const runsBefore = phase.runs();
+    const res = await save({ gitMode: 'managed' }, 'keep');
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(res.status, JSON.stringify(body)).toBe(200);
+    expect(body).toMatchObject({
+      ok: true,
+      complete: true,
+      restartRequired: false,
+      repository: { mode: 'managed', chosen: 'managed' },
+      repositoryChange: { choice: 'keep' },
+    });
+    expect(ensured).toHaveLength(1);
+    // The phase that sets the old working copies aside ran, against the repository moved to.
+    expect(phase.runs()).toBe(runsBefore + 1);
+    expect(phase.saw.at(-1)).toBe(managed.path);
+    expect(source.url()).toBe(managed.path);
+    expect(await status()).toMatchObject({ complete: true, repository: { mode: 'managed', chosen: 'managed' } });
+  });
+
+  /** One way's credential is never presented to another way's repository. */
+  it('presents the repository moved to nothing of the one that was left', async () => {
+    const { save, source } = await serving();
+    expect(source.credentials.token()).toBe('the-token');
+    await save({ gitMode: 'managed' }, 'keep');
+    expect(source.credentials.token()).toBeNull();
+  });
+
+  it('owes nothing through later saves about other things, and is not asked again', async () => {
+    const { save } = await serving();
+    await save({ gitMode: 'managed' }, 'keep');
+    const res = await save({ kbSyncSecret: 'a-secret-of-sixteen-or-more' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ ok: true, restartRequired: false, repository: { mode: 'managed', chosen: 'managed' } });
+  });
+
+  it('is asked again to move back: that is a move too', async () => {
+    const { save, source } = await serving();
+    await save({ gitMode: 'managed' }, 'keep');
+    const back = await save({ gitMode: 'token' });
+    expect(back.status).toBe(409);
+    expect(await back.json()).toMatchObject({ repositoryChange: { from: 'managed', to: 'token' } });
+    const done = await save({ gitMode: 'token' }, 'keep');
+    expect(await done.json()).toMatchObject({ ok: true, restartRequired: false, repository: { mode: 'token', chosen: 'token' } });
+    expect(source.url()).toBe(HOSTED.kbRepoUrl);
+  });
+
+  /** Another address under the same way is the same question, with the same answer. */
+  it('asks the same of another address under the way it is on', async () => {
+    const { save, source, phase } = await serving();
+    const moved = { kbRepoUrl: 'https://git.example.com/acme/another.git', gitToken: 'another-token' };
+    const asked = await save(moved);
+    expect(asked.status).toBe(409);
+    expect(await asked.json()).toMatchObject({ repositoryChange: { from: 'token', to: 'token' } });
+    const runsBefore = phase.runs();
+    const done = await save(moved, 'close');
+    expect(await done.json()).toMatchObject({ ok: true, restartRequired: false, repositoryChange: { choice: 'close' } });
+    expect(phase.runs()).toBe(runsBefore + 1);
+    expect(source.url()).toBe(moved.kbRepoUrl);
+  });
+
+  it('asks nothing of a save that only spells the same address another way', async () => {
+    const { save } = await serving();
+    const res = await save({ kbRepoUrl: 'https://GIT.example.com/acme/kb/' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).not.toHaveProperty('repositoryChange');
+  });
+
+  it('owes none for naming the way it was already on', async () => {
+    const { save, probed } = await serving();
+    const asked = probed.length;
+    const body = (await (await save({ gitMode: 'token' })).json()) as Record<string, unknown>;
+    expect(body).toMatchObject({ ok: true, restartRequired: false, repository: { mode: 'token', chosen: 'token' } });
+    expect(probed).toHaveLength(asked);
+  });
+});
+
+/**
+ * Behind a shut gate nothing is running on the way in effect, however
+ * completely the settings were answered, so a deployment there is got out of
+ * a repository that does not work by choosing one that does. One that never
+ * served is not even asked: there is no repository anyone worked on to
+ * leave. One that served before its boot failed is asked, as any move is.
+ */
+describe('a deployment that answered everything and serves nobody', () => {
+  const isHosted = (url: string) => url === HOSTED.kbRepoUrl;
+
+  it('is got going by choosing another way, when its first initialisation failed', async () => {
+    const { save, status, phase, managed, source } = listen({ kb: testKbContext(), unreachable: isHosted });
+    // First run: an address and a token, accepted, and a first clone that fails.
+    const first = await save({ ...HOSTED, ...BRANCHES });
+    expect(first.status).toBe(500);
+    expect(await status()).toMatchObject({ complete: false, kbInit: expect.any(Object), repository: { mode: 'token' } });
+
+    const second = await save({ gitMode: 'managed' });
+    const body = (await second.json()) as Record<string, unknown>;
+    expect(second.status, JSON.stringify(body)).toBe(200);
+    // The retry ran against the repository that was chosen, not the one that had just failed,
+    expect(phase.saw).toEqual([HOSTED.kbRepoUrl, managed.path]);
+    // nothing is owed, and the gate is open.
+    expect(body).toMatchObject({ complete: true, restartRequired: false, repository: { mode: 'managed', chosen: 'managed' } });
+    expect(source.credentials.token()).toBeNull();
+    expect(await status()).toMatchObject({ complete: true });
+    expect(await status()).not.toHaveProperty('kbInit');
+  });
+
+  it('is got going the same way when it booted onto a repository it could not reach', async () => {
+    Object.assign(process.env, { KB_REPO_URL: HOSTED.kbRepoUrl, GIT_TOKEN: HOSTED.gitToken, DEFAULT_BRANCH: 'main', PROTECTED_BRANCHES: 'main' });
+    const { save, status, phase, managed } = listen({ kb: testKbContext(), bootFailed: true, unreachable: isHosted });
+    expect(await status()).toMatchObject({ complete: false, repository: { mode: 'token' } });
+
+    // It served before this boot, so there may be work on the repository it
+    // leaves: it is asked, and nothing moves until it answers.
+    const asked = await save({ gitMode: 'managed' });
+    expect(asked.status).toBe(409);
+    expect(phase.saw).toEqual([]);
+
+    const body = (await (await save({ gitMode: 'managed' }, 'keep')).json()) as Record<string, unknown>;
+    expect(phase.saw).toEqual([managed.path]);
+    expect(body).toMatchObject({ complete: true, restartRequired: false, repository: { mode: 'managed', chosen: 'managed' } });
+  });
+});
+
+describe('a deployment whose way is chosen by the environment', () => {
+  it('says which variable chose', async () => {
+    process.env.GIT_MODE = 'managed';
+    const { status } = listen();
+    expect(await status()).toMatchObject({ repository: { mode: 'managed', chosen: 'managed', pinned: 'GIT_MODE' } });
+  });
+
+  it('says nothing of the kind when the admin chose', async () => {
+    const { save, status } = listen();
+    await save({ gitMode: 'managed' });
+    expect(((await status()) as { repository: object }).repository).not.toHaveProperty('pinned');
+  });
+});
+
+describe('a mount without the choice', () => {
+  it('is the one way there was: an address and a token', async () => {
+    const db = {
+      select: () => ({ from: () => Promise.resolve([]) }),
+      insert: () => ({ values: () => ({ onConflictDoUpdate: () => Promise.resolve() }) }),
+      delete: () => ({ where: () => Promise.resolve() }),
+    } as unknown as Database;
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    const app = express();
+    app.use(express.json());
+    app.use((req, _res, next) => {
+      req.userEmail = 'root@example.com';
+      next();
+    });
+    app.use('/api', createSetupRoutes(settings, { isAdmin: async () => true } as IAdminAccessService, { runAll: async () => {} }, testKbContext()));
+    server = app.listen(0);
+    const { port } = server.address() as AddressInfo;
+    const status = (await (await fetch(`http://127.0.0.1:${port}/api/setup/status`)).json()) as Record<string, unknown>;
+    expect(status).not.toHaveProperty('repository');
+    expect(status.complete).toBe(false);
+  });
+});