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

package/src/modules/settings/__tests__/setup.routes.managed-phase.test.ts

@@ -0,0 +1,233 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs/promises';
+import type { Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import express from 'express';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { testKbContext } from '../../../__tests__/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 { KbStartupRunner } from '../../workspace/startup/kb-startup-runner.js';
+import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
+import { TemplateFilesStep } from '../../workspace/startup/steps/template-files.step.js';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import { defaultKbTemplateDir } from '../../../assets.js';
+import type { Database } from '../../database/connection.js';
+import type { IAdminAccessService } from '../../admin/admin.interface.js';
+import type { KbContext } from '../../../shared/kb-context.js';
+
+/**
+ * A repository the deployment keeps, and the REAL startup phase, wired the
+ * way the composition root wires them: the phase asks the repository source
+ * where the repository is, and git runs with what the source presents.
+ *
+ * A fake phase proves the routes chose the right address. It cannot see
+ * whether a bare repository on a disk is something the phase can seed,
+ * clone and push to, or what happens to the working copies of a repository
+ * the deployment has moved away from. This looks at the disk afterwards.
+ */
+
+const execFileAsync = promisify(execFile);
+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;
+
+const gitEnv = {
+  ...process.env,
+  GIT_AUTHOR_NAME: 'Test',
+  GIT_AUTHOR_EMAIL: 't@x.com',
+  GIT_COMMITTER_NAME: 'Test',
+  GIT_COMMITTER_EMAIL: 't@x.com',
+};
+const git = async (cwd: string, args: string[]) =>
+  (await execFileAsync('git', args, { cwd, env: gitEnv })).stdout.toString().trim();
+
+let root: string;
+let server: HttpServer | null = null;
+let savedEnv: Partial<Record<(typeof KB_ENV)[number], string | undefined>> = {};
+
+beforeEach(async () => {
+  savedEnv = {};
+  for (const k of KB_ENV) {
+    savedEnv[k] = process.env[k];
+    delete process.env[k];
+  }
+  root = await fs.mkdtemp(path.join(os.tmpdir(), 'setup-managed-phase-'));
+});
+
+afterEach(async () => {
+  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;
+  }
+  await fs.rm(root, { recursive: true, force: true });
+});
+
+/** A deployment: its settings, its repository source, the real phase, and the setup routes over them. */
+function boot(kb: KbContext) {
+  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 managed = new ManagedRepository(path.join(root, 'backups', 'managed-repository'));
+  // A deployment reaching a repository by its address has one on a host; here
+  // it is a folder, which the source hands over as it would hand a URL.
+  const hosted = path.join(root, 'hosted.git');
+  const source = new RepositorySource({
+    read: (key) => (key === 'kbRepoUrl' && settings.resolve('kbRepoUrl') ? hosted : settings.resolve(key)),
+    managed,
+  });
+  const gitRunner = new NodeGitRunner(60_000, source.credentials);
+  const workspacesRoot = path.join(root, 'workspaces');
+  const setAsideRoot = path.join(root, 'backups', 'replaced-working-copies');
+  const runner = new KbStartupRunner({
+    gitRunner,
+    kbRepoUrl: () => source.url(),
+    workspacesRoot,
+    setAsideRoot,
+    kbDirName: 'knowledge-base',
+    templateDir: defaultKbTemplateDir(),
+    defaultBranch: () => kb.defaultBranch,
+    protectedBranches: () => [...kb.protectedBranches],
+    seedAdminEmails: ['admin@example.com'],
+    // A step that works on every branch, so the phase makes each its working copy.
+    steps: [new TemplateFilesStep(new NodeFs(), kb)],
+    buildSeedTree: async (dir) => {
+      await fs.writeFile(path.join(dir, 'WELCOME.md'), 'seeded\n', 'utf8');
+      return ['WELCOME.md'];
+    },
+  });
+  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,
+      runner,
+      kb,
+      undefined,
+      async () => ({ outcome: 'connected', branches: ['main'], defaultBranch: 'main', empty: false }),
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      { source, ensureManaged: (branch) => managed.ensure(gitRunner, branch) },
+    ),
+  );
+  server = app.listen(0);
+  const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+  const save = async (entries: Record<string, string>) => {
+    const res = await fetch(`${base}/api/setup/settings`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ settings: entries }),
+    });
+    return { status: res.status, body: (await res.json()) as Record<string, unknown> };
+  };
+  const workingCopy = (branch: string) => path.join(workspacesRoot, encodeURIComponent(branch), 'knowledge-base');
+  return { save, managed, hosted, runner, source, workingCopy, setAsideRoot };
+}
+
+describe('the save that chooses a repository the deployment keeps', () => {
+  it('creates it, seeds it and clones from it, asking for nothing else', async () => {
+    const { save, managed, workingCopy } = boot(testKbContext({ branchModel: null }));
+    const { status, body } = await save({ gitMode: 'managed' });
+    expect(status, JSON.stringify(body)).toBe(200);
+    expect(body).toMatchObject({ complete: true, restartRequired: false });
+
+    // The repository is where the source says, bare, and holds the seed on the branch named for it.
+    expect(await git(managed.path, ['rev-parse', '--is-bare-repository'])).toBe('true');
+    expect(await git(managed.path, ['for-each-ref', '--format=%(refname)'])).toBe('refs/heads/main');
+    expect(await git(managed.path, ['ls-tree', '-r', '--name-only', 'main'])).toContain('WELCOME.md');
+
+    // The working copy is a clone of it, and carries no credential helper: there is no credential.
+    const copy = workingCopy('main');
+    expect(await git(copy, ['config', '--get', 'remote.origin.url'])).toBe(managed.path);
+    expect((await fs.readFile(path.join(copy, 'WELCOME.md'), 'utf8')).replace(/\r\n/g, '\n')).toBe('seeded\n');
+  });
+
+  it('takes a push from a working copy, like any remote', async () => {
+    const { save, managed, workingCopy } = boot(testKbContext({ branchModel: null }));
+    await save({ gitMode: 'managed' });
+    const copy = workingCopy('main');
+    await fs.writeFile(path.join(copy, 'note.md'), 'a change\n', 'utf8');
+    await git(copy, ['add', '-A']);
+    await git(copy, ['commit', '-m', 'a change']);
+    await git(copy, ['push', 'origin', 'main']);
+    expect(await git(managed.path, ['ls-tree', '-r', '--name-only', 'main'])).toContain('note.md');
+  });
+});
+
+describe('a deployment that moves to a repository it keeps', () => {
+  it('leaves the repository it had untouched and sets its working copies aside, unpushed work included', async () => {
+    const { save, managed, hosted, runner, source, workingCopy, setAsideRoot } = boot(
+      testKbContext({ branchModel: { defaultBranch: 'main', protectedBranches: ['main'] } }),
+    );
+    // A deployment on a repository of its own, set up and serving. The
+    // repository has a history of ITS OWN, written here and not by the
+    // startup phase: two empty repositories the phase seeds within the
+    // same second get the same first commit (same tree, same author, same
+    // time), and the phase would then read them, rightly, as one repository
+    // at two addresses, and keep the working copy instead of setting it
+    // aside. A fast machine did exactly that.
+    await git(root, ['init', '--bare', '-b', 'main', hosted]);
+    const theirs = path.join(root, 'theirs');
+    await fs.mkdir(theirs);
+    await git(theirs, ['init', '-b', 'main']);
+    await fs.writeFile(path.join(theirs, 'HANDBOOK.md'), 'what this organisation had before\n', 'utf8');
+    await git(theirs, ['add', '-A']);
+    await git(theirs, ['commit', '-m', 'the handbook']);
+    await git(theirs, ['push', hosted, 'main']);
+    const first = await save({ kbRepoUrl: 'https://git.example.com/acme/kb.git', gitToken: 'a-token', defaultBranch: 'main', protectedBranches: 'main' });
+    expect(first.status, JSON.stringify(first.body)).toBe(200);
+    const copy = workingCopy('main');
+    expect(await git(copy, ['config', '--get', 'remote.origin.url'])).toBe(hosted);
+    // Work that was committed and never pushed.
+    await fs.writeFile(path.join(copy, 'unpushed.md'), 'only here\n', 'utf8');
+    await git(copy, ['add', '-A']);
+    await git(copy, ['commit', '-m', 'never pushed']);
+    const hostedBefore = await git(hosted, ['for-each-ref']);
+
+    const moved = await save({ gitMode: 'managed' });
+    expect(moved.body).toMatchObject({ ok: true, restartRequired: true });
+    // Until the restart the working copy is where it was, and so is the
+    // deployment: the repository it has is the one it goes on talking to.
+    expect(await git(copy, ['config', '--get', 'remote.origin.url'])).toBe(hosted);
+    expect(source.url()).toBe(hosted);
+
+    // The restart: the deployment is built on the mode chosen, and the
+    // phase brings the working copies into line.
+    source.takeEffect();
+    await runner.runAll();
+
+    expect(await git(hosted, ['for-each-ref'])).toBe(hostedBefore);
+    expect(await git(copy, ['config', '--get', 'remote.origin.url'])).toBe(managed.path);
+    expect(await fs.access(path.join(copy, 'unpushed.md')).then(() => true, () => false)).toBe(false);
+    const managedHolds = await git(managed.path, ['ls-tree', '-r', '--name-only', 'main']);
+    expect(managedHolds).toContain('WELCOME.md');
+    // Nothing of one repository was pushed into the other.
+    expect(managedHolds).not.toContain('HANDBOOK.md');
+    expect(managedHolds).not.toContain('unpushed.md');
+
+    // What was set aside is whole: the commit nobody pushed is in it.
+    const [stamp] = await fs.readdir(setAsideRoot);
+    const kept = path.join(setAsideRoot, stamp!, encodeURIComponent('main'));
+    expect(await git(kept, ['log', '-1', '--format=%s'])).toBe('never pushed');
+    expect((await fs.readFile(path.join(kept, 'unpushed.md'), 'utf8')).replace(/\r\n/g, '\n')).toBe('only here\n');
+  });
+});

package/src/modules/settings/deployment-settings.service.ts

@@ -17,6 +17,7 @@ import { TokenCrypto } from '../../shared/token-crypto.js';
 import { assertKbDirNameFree } from '../kb-fs/repo-path.js';
 import { parseRetentionWindow } from '../audit/audit.contract.js';
 import { normalizeIssuerUrl } from './oidc-check.js';
+import { GIT_MODES, isGitMode } from './repository-source.js';
 
 /**
  * A setting an admin may set from the setup screen instead of the environment.
@@ -69,6 +70,17 @@ export interface SettingDef {
    * restart for a change that never happened.
    */
   unsetMeans?: string;
+  /**
+   * Written by the deployment itself, at the end of a flow that PROVED the
+   * value, and never taken from a save. What a GitHub App was given when it
+   * was registered, and which installation of it the admin was shown to
+   * hold, are facts somebody established; accepted from a form they would
+   * be claims, and the claim "installation 42 is mine" is one that reaches
+   * another organisation's repositories. A save that names one is refused,
+   * the setup screen is not told about it, and its value is read like any
+   * other's (the environment first), so an operator can still pin it.
+   */
+  internal?: boolean;
 }
 
 /**
@@ -99,6 +111,25 @@ export const validateHttpsRemote = (value: string): string | null => {
  * The core catalogue. Order is the order the setup screen renders them in.
  */
 export const CORE_SETTINGS: SettingDef[] = [
+  {
+    /**
+     * Which way the deployment is given its repository (see
+     * `RepositorySource`). Unset on a deployment configured before there was
+     * a choice, which is read as `token` when it has an address or a token,
+     * and as nothing chosen when it has neither.
+     *
+     * Restart-to-apply on a deployment that is running: its working copies
+     * were cloned from the repository it had, and they are brought into line
+     * with another one by the startup phase, at a moment when nobody is
+     * using them. The save that completes first-run setup runs that phase
+     * itself, and owes no restart.
+     */
+    key: 'gitMode',
+    envVar: 'GIT_MODE',
+    section: 'knowledge-base',
+    validate: (v) => (isGitMode(v) ? null : `Choose one of: ${GIT_MODES.join(', ')}.`),
+    restartToApply: true,
+  },
   {
     key: 'kbRepoUrl',
     envVar: 'KB_REPO_URL',
@@ -121,6 +152,59 @@ export const CORE_SETTINGS: SettingDef[] = [
     validate: (v) =>
       /^[A-Za-z0-9._-]+$/.test(v) ? null : 'Use only letters, digits, dot, underscore or hyphen.',
   },
+
+  /**
+   * A repository on GitHub, reached through a GitHub App (see
+   * `modules/github-app/`).
+   *
+   * THE REPOSITORY is the admin's to choose, among those the installation
+   * reaches, and is saved like any setting: a name the installation does not
+   * reach fails the connection check, since the only token presented to
+   * GitHub is the installation's.
+   *
+   * EVERYTHING ELSE is internal: the app's identity and keys, as GitHub
+   * issued them when the app was registered, and the installation, as
+   * GitHub confirmed the admin holds it. Each has a variable, so whoever
+   * operates the deployment can supply an app they registered themselves,
+   * and a host serving many deployments can supply one app for all of them.
+   */
+  {
+    key: 'githubRepository',
+    envVar: 'GITHUB_APP_REPOSITORY',
+    section: 'knowledge-base',
+    validate: (v) =>
+      /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\/[A-Za-z0-9._-]+$/.test(v) && !v.endsWith('.git')
+        ? null
+        : 'Name the repository as owner/name.',
+  },
+  { key: 'githubAppId', envVar: 'GITHUB_APP_ID', section: 'knowledge-base', internal: true, validate: (v) => (/^\d+$/.test(v) ? null : 'The app id is a number.') },
+  { key: 'githubAppSlug', envVar: 'GITHUB_APP_SLUG', section: 'knowledge-base', internal: true, validate: (v) => (/^[A-Za-z0-9-]+$/.test(v) ? null : 'The app slug is letters, digits and hyphens.') },
+  { key: 'githubAppPrivateKey', envVar: 'GITHUB_APP_PRIVATE_KEY', section: 'knowledge-base', internal: true, secret: true },
+  { key: 'githubAppClientId', envVar: 'GITHUB_APP_CLIENT_ID', section: 'knowledge-base', internal: true },
+  { key: 'githubAppClientSecret', envVar: 'GITHUB_APP_CLIENT_SECRET', section: 'knowledge-base', internal: true, secret: true },
+  {
+    /**
+     * Put in front of the state every round trip to GitHub carries, by a
+     * host that serves several deployments behind ONE app: GitHub sends the
+     * browser back to the one address registered for the app, and the host
+     * reads this to know which deployment to hand it to. Never stored.
+     */
+    key: 'githubAppStateTag',
+    envVar: 'GITHUB_APP_STATE_TAG',
+    section: 'knowledge-base',
+    internal: true,
+    validate: (v) => (/^[a-z0-9-]{1,63}$/.test(v) ? null : 'Lowercase letters, digits and hyphens.'),
+  },
+  { key: 'githubInstallationId', envVar: 'GITHUB_APP_INSTALLATION_ID', section: 'knowledge-base', internal: true, validate: (v) => (/^\d+$/.test(v) ? null : 'The installation id is a number.') },
+  /** Whose account the installation is on, as GitHub names it: shown, never trusted. */
+  { key: 'githubInstallationAccount', section: 'knowledge-base', internal: true },
+  /**
+   * The repositories the person who connected the installation could PUSH
+   * to with their own GitHub account, one `owner/name` a line, as GitHub
+   * listed them when they connected. The deployment may be pointed at one
+   * of these and at nothing else the installation reaches.
+   */
+  { key: 'githubRepositoriesPermitted', section: 'knowledge-base', internal: true },
   {
     key: 'kbDirName',
     envVar: 'KB_DIR_NAME',
@@ -583,7 +667,7 @@ export class DeploymentSettingsService {
    * replace it, which is all anyone needs to finish setup.
    */
   describe(): ResolvedSetting[] {
-    return this.definitions.map((def) => {
+    return this.definitions.filter((def) => !def.internal).map((def) => {
       const source = this.sourceOf(def.key);
       const base = {
         key: def.key,
@@ -616,8 +700,10 @@ export class DeploymentSettingsService {
   async save(
     entries: Record<string, string>,
     updatedBy: string | null,
+    /** Set by {@link record} alone: the batch is the deployment's own, and may name internal settings. */
+    by: 'admin' | 'deployment' = 'admin',
   ): Promise<{ restartRequired: boolean; restartKeys: string[] }> {
-    const { toWrite, toClear } = this.plan(entries);
+    const { toWrite, toClear } = this.plan(entries, by);
 
     /** The settings this save changed that a running server cannot pick up. */
     const restartKeys: string[] = [];
@@ -662,8 +748,22 @@ export class DeploymentSettingsService {
       toClear.includes(key) ? '' : (toWrite.find((w) => w.key === key)?.value ?? this.resolve(key));
   }
 
+  /**
+   * Store what the DEPLOYMENT established, internal settings included: the
+   * end of a flow that proved each value (see `SettingDef.internal`). The
+   * same validation, the same encryption, the same refusal of a setting the
+   * environment pins. Never reachable from a request body: the setup routes
+   * call {@link save}.
+   */
+  async record(entries: Record<string, string>, updatedBy: string | null): Promise<void> {
+    await this.save(entries, updatedBy, 'deployment');
+  }
+
   /** Validate a batch and return the writes (and the clears) it amounts to; throws on any problem. */
-  private plan(entries: Record<string, string>): {
+  private plan(
+    entries: Record<string, string>,
+    by: 'admin' | 'deployment' = 'admin',
+  ): {
     toWrite: { key: string; value: string; def: SettingDef }[];
     toClear: string[];
   } {
@@ -677,6 +777,12 @@ export class DeploymentSettingsService {
         problems[key] = 'Unknown setting.';
         continue;
       }
+      if (def.internal && by !== 'deployment') {
+        // Said the way an unknown setting is: what the deployment keeps for
+        // itself is not the form's to name, or to learn the names of.
+        problems[key] = 'Unknown setting.';
+        continue;
+      }
       if (this.sourceOf(key) === 'env') {
         problems[key] = `Set by the ${def.envVar} environment variable — change it there.`;
         continue;

package/src/modules/settings/managed-repository.ts

@@ -0,0 +1,68 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { IGitRunner } from '../../shared/git.contract.js';
+
+/** The folder the managed repository is kept in, under the root it is given. */
+export const MANAGED_REPOSITORY_DIR = 'knowledge-base.git';
+
+/** The branch a managed repository starts on when the deployment names none. */
+export const MANAGED_DEFAULT_BRANCH = 'main';
+
+/**
+ * The repository a deployment keeps FOR ITSELF, when its admin chose not to
+ * bring one: a bare git repository on the deployment's own disk.
+ *
+ * Nothing else about the deployment changes. Working copies are cloned from
+ * it, pushed to it and fetched from it exactly as they are from a
+ * repository on a host; it happens to be reached by a path, and to need no
+ * credential. An empty one is seeded by the startup phase like any empty
+ * remote.
+ *
+ * WHERE IT LIVES IS THE WHOLE DECISION. It is the only copy of the
+ * knowledge base that is not a working copy, so it has to be somewhere that
+ * survives the container and that nothing tidies up:
+ *
+ *  - not under the workspaces root, where the workspace service's orphan
+ *    sweep removes every folder that is not a known branch's;
+ *  - not in a new folder beside it, which every shipped compose file would
+ *    have to grow a volume for, and a deployment started from an older file
+ *    would lose on its next redeploy without a word.
+ *
+ * The composition root puts it under the BACKUPS root: a volume of its own
+ * in every compose file that has ever shipped, and one nothing sweeps.
+ */
+export class ManagedRepository {
+  /** The repository's folder: what git is given as the remote. */
+  readonly path: string;
+
+  constructor(private readonly root: string) {
+    this.path = path.join(root, MANAGED_REPOSITORY_DIR);
+  }
+
+  /** Whether the repository is there. A folder that is not a repository does not count. */
+  async exists(): Promise<boolean> {
+    return fs.access(path.join(this.path, 'HEAD')).then(
+      () => true,
+      () => false,
+    );
+  }
+
+  /**
+   * Make sure the repository exists, creating it empty when it does not.
+   * One that exists is left exactly as it is: this never re-initialises,
+   * and never touches a ref.
+   */
+  async ensure(runner: IGitRunner, initialBranch: string = MANAGED_DEFAULT_BRANCH): Promise<void> {
+    if (await this.exists()) return;
+    await fs.mkdir(this.root, { recursive: true });
+    // A folder that is there without being a repository is somebody's, and
+    // initialising over it would mix a repository into their files.
+    const entries = await fs.readdir(this.path).catch(() => null);
+    if (entries && entries.length > 0) {
+      throw new Error(
+        `${this.path} exists and is not a git repository. Move it away, or empty it, before choosing a managed repository.`,
+      );
+    }
+    await runner.run(this.root, ['init', '--bare', `--initial-branch=${initialBranch}`, this.path]);
+  }
+}

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

@@ -0,0 +1,197 @@
+import { DEFAULT_GIT_USERNAME, type GitCredentials } from '../../shared/git.contract.js';
+import type { ManagedRepository } from './managed-repository.js';
+
+/**
+ * The ways a deployment can be given the repository its knowledge base
+ * lives in, in the order the setup screen offers them.
+ *
+ *  - `managed`: the deployment keeps the repository itself.
+ *  - `github-app`: a repository on GitHub, reached through a GitHub App the
+ *    admin installed on it.
+ *  - `token`: any git host, by its address and an access token.
+ */
+export const GIT_MODES = ['managed', 'github-app', 'token'] as const;
+export type GitMode = (typeof GIT_MODES)[number];
+
+export function isGitMode(value: unknown): value is GitMode {
+  return typeof value === 'string' && (GIT_MODES as readonly string[]).includes(value);
+}
+
+/** Reads one setting as it is in effect, or as it would be after a save. */
+export type SettingReader = (key: string) => string;
+
+/**
+ * A repository reached through a GitHub App: which one, and the short-lived
+ * token the app is given for it. Implemented by the GitHub App module; the
+ * source only asks.
+ */
+export interface GitHubAppRepository {
+  /** `https://github.com/<owner>/<name>.git`, or empty while none is chosen. */
+  url(read: SettingReader): string;
+  /** The installation token in hand, or null when there is none to give. */
+  token(): string | null;
+  /**
+   * Make sure {@link token} answers with one that is still good. `asked`
+   * is for a caller waiting on the answer itself, who is told a failure.
+   */
+  prepare(opts?: { asked?: boolean }): Promise<void>;
+  /** Whether the deployment may be pointed at this repository (`owner/name`). */
+  permits(repository: string, read: SettingReader): boolean;
+  /** Whether the app, its installation and a repository are all there. */
+  answered(read: SettingReader): boolean;
+}
+
+export interface RepositorySourceOptions {
+  /** The deployment's settings, as they are in effect. */
+  read: SettingReader;
+  /**
+   * What the environment gives the token mode beyond the settings
+   * catalogue: the legacy spellings of the token variable, and the username
+   * a deployment configured there.
+   */
+  fallback?: { username?: string; token?: string };
+  managed: ManagedRepository;
+  githubApp?: GitHubAppRepository;
+}
+
+/**
+ * WHERE THE KNOWLEDGE BASE'S REPOSITORY IS, AND WHAT GIT PRESENTS TO IT —
+ * the one place that knows there is more than one answer.
+ *
+ * Everything that runs git asks for two things: an address to clone from,
+ * and a credential. Both used to be read straight from two settings, which
+ * is one way of having a repository. With three ways, each reader deciding
+ * for itself would be three places to disagree, so they all ask here, and
+ * what they get back is the same two things as before.
+ *
+ * TWO MODES, AND THEY ARE NOT ALWAYS THE SAME ONE.
+ *
+ *  - The mode IN EFFECT is the one this process is running on. Its working
+ *    copies are clones of that mode's repository, and every address and
+ *    credential this class hands out is that mode's. It is taken when the
+ *    source is built and changes only in {@link takeEffect}.
+ *  - The mode CHOSEN is what the settings say. A save changes it at once.
+ *
+ * They differ between the save that moves a serving deployment and the
+ * restart that save owes. Reading the mode live would move the process the
+ * moment the setting was stored: the new mode's credential presented to the
+ * old mode's repository, which every working copy still points at, and new
+ * branches cloned from a repository the startup phase has not prepared. So
+ * the process stays where it is until it is started again, which is what
+ * the setup screen tells the admin.
+ *
+ * WITHIN a mode the values are read live, as they always were: a rotated
+ * token is the one the next push carries.
+ *
+ * THE MODE IS INFERRED WHEN NOBODY CHOSE ONE. A deployment configured before
+ * there was a choice has an address and a token and no mode; it is in
+ * `token` mode, because that is what it has. One with nothing configured has
+ * no mode, and the setup screen offers the first.
+ */
+export class RepositorySource {
+  /** What git authenticates with, read on every call. */
+  readonly credentials: GitCredentials;
+  private inEffect: GitMode | null;
+
+  constructor(private readonly opts: RepositorySourceOptions) {
+    this.inEffect = this.chosen();
+    this.credentials = {
+      username: () => this.username(),
+      token: () => this.token(),
+      prepare: () => this.prepare(),
+    };
+  }
+
+  /**
+   * Without a reader, the mode IN EFFECT. With one, the mode a save of that
+   * reader's values would CHOOSE: the answer validation wants, about values
+   * that are not stored yet. Null: nothing is configured.
+   */
+  mode(read?: SettingReader): GitMode | null {
+    return read ? this.chosen(read) : this.inEffect;
+  }
+
+  /** The mode the settings say, which a restart would put in effect. */
+  chosen(read: SettingReader = this.opts.read): GitMode | null {
+    const named = read('gitMode').trim();
+    if (isGitMode(named)) return named;
+    return read('kbRepoUrl') || this.tokenIn(read) ? 'token' : null;
+  }
+
+  /**
+   * Put the mode chosen in effect. Called where nothing is using the mode
+   * that was: by a save made before the deployment was serving, which the
+   * startup phase follows. A process that is serving is never moved; it is
+   * restarted, and built on the mode chosen.
+   */
+  takeEffect(): void {
+    this.inEffect = this.chosen();
+  }
+
+  /** The address git clones from and pushes to. Empty while there is none. Asked as {@link mode} is. */
+  url(read?: SettingReader): string {
+    const from = read ?? this.opts.read;
+    switch (this.mode(read)) {
+      case 'managed':
+        return this.opts.managed.path;
+      case 'github-app':
+        return this.opts.githubApp?.url(from) ?? '';
+      case 'token':
+        return from('kbRepoUrl');
+      default:
+        return '';
+    }
+  }
+
+  /**
+   * Whether the repository half of setup is answered: there is somewhere to
+   * clone from and, where one is needed, something to present. Asked as
+   * {@link mode} is.
+   */
+  answered(read?: SettingReader): boolean {
+    const from = read ?? this.opts.read;
+    switch (this.mode(read)) {
+      case 'managed':
+        return true;
+      case 'github-app':
+        return this.opts.githubApp?.answered(from) ?? false;
+      case 'token':
+        return Boolean(from('kbRepoUrl') && this.tokenIn(from));
+      default:
+        return false;
+    }
+  }
+
+  private username(): string {
+    // Only a host that was given a token is given a name to go with it.
+    if (this.inEffect !== 'token') return DEFAULT_GIT_USERNAME;
+    return this.opts.read('gitUsername') || this.opts.fallback?.username || DEFAULT_GIT_USERNAME;
+  }
+
+  /**
+   * One mode's credential is never presented to another mode's repository:
+   * a deployment that moved to a managed repository still has its old
+   * token stored, and a path on its own disk has no use for it. The mode is
+   * the one IN EFFECT, because that is the repository git is talking to.
+   */
+  private token(): string | null {
+    switch (this.inEffect) {
+      case 'token':
+        return this.tokenIn(this.opts.read) || null;
+      case 'github-app':
+        return this.opts.githubApp?.token() ?? null;
+      default:
+        return null;
+    }
+  }
+
+  private async prepare(): Promise<void> {
+    if (this.inEffect === 'github-app') await this.opts.githubApp?.prepare();
+  }
+
+  private tokenIn(read: SettingReader): string {
+    // The fallback is the environment's, so it is in effect whatever a save brings.
+    return read('gitToken') || this.opts.fallback?.token || '';
+  }
+}
+