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

package/src/modules/settings/__tests__/setup.routes.repository-change.test.ts

@@ -0,0 +1,390 @@
+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 { createSetupRoutes, type RepositoryChangeRequests } from '../setup.routes.js';
+import { DeploymentSettingsService } from '../deployment-settings.service.js';
+import type { Database } from '../../database/connection.js';
+import type { IAdminAccessService } from '../../admin/admin.interface.js';
+import type { ConnectionCheck, RepositoryConnection } from '../connection-check.js';
+
+/**
+ * Saving a DIFFERENT knowledge-base repository.
+ *
+ * Every working copy on this server fetches through the address stored in its
+ * own clone, so pointing the deployment somewhere else means deleting and
+ * re-cloning all of them — and losing anything committed here and never
+ * pushed. On 2026-09-28 that happened with no warning, no re-clone, and a
+ * boot that then crash-looped against the repository that was gone.
+ *
+ * So: the save is REFUSED until the admin confirms, the confirmation says how
+ * many change requests are open and what to do with them, and a confirmed
+ * save runs the KB startup phase — which is what replaces the working copies
+ * — even though the deployment was complete and healthy.
+ */
+
+const ENC_KEY = 'kToAi8FXWDpDn3A6yQ/60O39bv05N7XzVOIu/0CJrFc=';
+const KB_ENV = ['KB_REPO_URL', 'GIT_TOKEN', 'GIT_USERNAME', 'KB_DIR_NAME', 'GITHUB_TOKEN'] as const;
+const REPO = 'https://example.com/acme/kb.git';
+
+let server: HttpServer | null = null;
+let savedEnv: Partial<Record<(typeof KB_ENV)[number], string | undefined>> = {};
+/** Set by the one test about a close the database will not do. Reset per test. */
+let failTheClose = false;
+
+beforeEach(() => {
+  failTheClose = false;
+  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 remote answers for whatever it is asked about. */
+const connected = async (connection: RepositoryConnection): Promise<ConnectionCheck> => {
+  void connection;
+  return { outcome: 'connected', branches: ['main'], defaultBranch: 'main', empty: false };
+};
+
+function listen(openChangeRequests: number) {
+  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);
+  /** Every run of the KB startup phase — the thing that replaces the clones. */
+  const phaseRuns = { count: 0 };
+  const closes = { count: 0 };
+  /** Set by the one test about a move whose startup phase fails. */
+  const phase = { fail: false };
+  /** What happened, in order: the commit worker held and let go, and the phase between. */
+  const events: string[] = [];
+  const changeRequests: RepositoryChangeRequests = {
+    async countOpen() {
+      return openChangeRequests;
+    },
+    async closeAsRepositoryReplaced() {
+      closes.count += 1;
+      if (failTheClose) throw new Error('change_requests is down');
+      return openChangeRequests;
+    },
+    async whileCommitsHeld(work) {
+      // What was stored at the moment the hold began: the hold must come first.
+      events.push(`commits held on ${settings.resolve('kbRepoUrl')}`);
+      try {
+        return await work();
+      } finally {
+        events.push('commits released');
+      }
+    },
+  };
+  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,
+      {
+        async runAll() {
+          phaseRuns.count += 1;
+          events.push('phase');
+          if (phase.fail) throw new Error('git fetch failed: repository not found');
+        },
+      },
+      testKbContext(),
+      undefined,
+      connected,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      // No alternative way of being given a repository: this suite is about the
+      // one that has always been there, an address and a token.
+      undefined,
+      changeRequests,
+    ),
+  );
+  server = app.listen(0);
+  const { port } = server.address() as AddressInfo;
+  return { base: `http://127.0.0.1:${port}`, settings, phaseRuns, closes, events, phase };
+}
+
+const post = (base: string, body: unknown) =>
+  fetch(`${base}/api/setup/settings`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+
+/** A deployment that has been running against REPO for a while. */
+async function configured(openChangeRequests = 0) {
+  const harness = listen(openChangeRequests);
+  await harness.settings.save({ kbRepoUrl: REPO, gitToken: 'ghp_old' }, null);
+  // The save above is not what this suite counts.
+  harness.phaseRuns.count = 0;
+  return harness;
+}
+
+describe('a save that changes the knowledge-base repository', () => {
+  it('is refused until the admin confirms, and stores nothing meanwhile', async () => {
+    const { base, settings, phaseRuns } = await configured(0);
+
+    const res = await post(base, {
+      settings: { kbRepoUrl: 'https://example.com/acme/replacement.git', gitToken: 'ghp_new' },
+    });
+
+    expect(res.status).toBe(409);
+    expect(await res.json()).toMatchObject({ repositoryChange: { openChangeRequests: 0 } });
+    // Nothing saved, nothing replaced: a refused save destroys nothing.
+    expect(settings.resolve('kbRepoUrl')).toBe(REPO);
+    expect(phaseRuns.count).toBe(0);
+  });
+
+  it('says how many change requests are open, so the choice is about a number', async () => {
+    const { base } = await configured(3);
+    const res = await post(base, {
+      settings: { kbRepoUrl: 'https://example.com/acme/replacement.git', gitToken: 'ghp_new' },
+    });
+    expect(res.status).toBe(409);
+    expect((await res.json()).repositoryChange.openChangeRequests).toBe(3);
+  });
+
+  it('confirmed with "keep": saves, replaces the working copies, and closes nothing', async () => {
+    const { base, settings, phaseRuns, closes } = await configured(3);
+    const replacement = 'https://example.com/acme/replacement.git';
+
+    const res = await post(base, {
+      settings: { kbRepoUrl: replacement, gitToken: 'ghp_new' },
+      confirmRepositoryChange: 'keep',
+    });
+
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({
+      repositoryChange: { choice: 'keep', closedChangeRequests: 0 },
+    });
+    expect(settings.resolve('kbRepoUrl')).toBe(replacement);
+    // The phase is what deletes the clones of the old repository and makes new
+    // ones — on the SAVE, not only at the next boot.
+    expect(phaseRuns.count).toBe(1);
+    expect(closes.count).toBe(0);
+  });
+
+  it('confirmed with "close": closes the open requests as repository replaced', async () => {
+    const { base, phaseRuns, closes } = await configured(3);
+
+    const res = await post(base, {
+      settings: { kbRepoUrl: 'https://example.com/acme/replacement.git', gitToken: 'ghp_new' },
+      confirmRepositoryChange: 'close',
+    });
+
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({
+      repositoryChange: { choice: 'close', closedChangeRequests: 3 },
+    });
+    expect(closes.count).toBe(1);
+    expect(phaseRuns.count).toBe(1);
+  });
+
+  /**
+   * A close that cannot be done is a PRECONDITION that failed, not a detail of
+   * an otherwise successful save. Stored anyway, the address would now match,
+   * so the next save would see no change, ask nothing, and never retry the
+   * close — leaving those requests open on branches the new repository does not
+   * have, their file locks refusing paths to everyone, with nothing the admin
+   * could press to fix it.
+   */
+  it('refuses the whole save, saying why, when the requests cannot be closed', async () => {
+    const { base, settings, phaseRuns } = await configured(3);
+    failTheClose = true;
+
+    const res = await post(base, {
+      settings: { kbRepoUrl: 'https://example.com/acme/replacement.git', gitToken: 'ghp_new' },
+      confirmRepositoryChange: 'close',
+    });
+
+    expect(res.status).toBe(500);
+    expect((await res.json()).error).toMatch(/could not be closed/);
+    // Nothing stored, no working copy touched: the admin can press Save again.
+    expect(settings.resolve('kbRepoUrl')).toBe(REPO);
+    expect(phaseRuns.count).toBe(0);
+  });
+});
+
+/**
+ * An answer stands for the count it was given about. The screen sends "keep"
+ * when there was nothing to choose; a request opened while the question
+ * stood must not be decided by that.
+ */
+describe('an answer given about a count that has since changed', () => {
+  it('is asked again, with the count as it is now', async () => {
+    const { base, settings, phaseRuns } = await configured(1);
+    const res = await post(base, {
+      settings: { kbRepoUrl: 'https://example.com/acme/replacement.git', gitToken: 'ghp_new' },
+      confirmRepositoryChange: 'keep',
+      seenOpenChangeRequests: 0,
+    });
+    expect(res.status).toBe(409);
+    expect((await res.json()).repositoryChange.openChangeRequests).toBe(1);
+    expect(settings.resolve('kbRepoUrl')).toBe(REPO);
+    expect(phaseRuns.count).toBe(0);
+  });
+
+  it('goes through when the count is the one the answer was given about', async () => {
+    const { base } = await configured(1);
+    const res = await post(base, {
+      settings: { kbRepoUrl: 'https://example.com/acme/replacement.git', gitToken: 'ghp_new' },
+      confirmRepositoryChange: 'keep',
+      seenOpenChangeRequests: 1,
+    });
+    expect(res.status).toBe(200);
+  });
+});
+
+/**
+ * A move that fails part-way leaves the deployment gated with the failure
+ * standing. It has served all the same, and its open change requests are the
+ * proof: the save that tries again must still ask what becomes of them.
+ */
+describe('a move tried again after one that failed part-way', () => {
+  it('still asks, because change requests are open', async () => {
+    const { base, phase } = await configured(2);
+    phase.fail = true;
+    const failed = await post(base, {
+      settings: { kbRepoUrl: 'https://example.com/acme/replacement.git', gitToken: 'ghp_new' },
+      confirmRepositoryChange: 'keep',
+    });
+    expect(failed.status).toBe(500);
+    expect(await failed.json()).toHaveProperty('kbInit');
+
+    phase.fail = false;
+    const again = await post(base, {
+      settings: { kbRepoUrl: 'https://example.com/acme/third.git', gitToken: 'ghp_new' },
+    });
+    expect(again.status).toBe(409);
+    expect((await again.json()).repositoryChange.openChangeRequests).toBe(2);
+  });
+});
+
+describe('a save that does NOT change the repository', () => {
+  it('goes straight through, and runs no startup phase', async () => {
+    const { base, phaseRuns, closes } = await configured(2);
+
+    // The same address, with something else edited beside it.
+    const res = await post(base, { settings: { kbRepoUrl: REPO, gitUsername: 'oauth2' } });
+
+    expect(res.status).toBe(200);
+    expect(await res.json()).not.toHaveProperty('repositoryChange');
+    // A complete, healthy deployment's clones are of the configured
+    // repository: re-cloning them would be maintenance over live work.
+    expect(phaseRuns.count).toBe(0);
+    expect(closes.count).toBe(0);
+  });
+
+  it('treats a trailing slash, a .git suffix and the host’s letter case as the same address', async () => {
+    for (const spelling of [
+      'https://example.com/acme/kb',
+      'https://example.com/acme/kb/',
+      'https://EXAMPLE.com/acme/kb.git',
+      'https://example.com/acme/kb.git/',
+    ]) {
+      const { base, settings, phaseRuns } = await configured(2);
+      const res = await post(base, { settings: { kbRepoUrl: spelling } });
+      expect({ spelling, status: res.status }).toEqual({ spelling, status: 200 });
+      // Stored as typed — it is the same repository, not a correction.
+      expect(settings.resolve('kbRepoUrl')).toBe(spelling);
+      expect({ spelling, runs: phaseRuns.count }).toEqual({ spelling, runs: 0 });
+      server?.close();
+      server = null;
+    }
+  });
+
+  it('never asks the token question over a spelling, since it is the same repository', async () => {
+    const { base } = await configured(0);
+    // No token supplied. A DIFFERENT repository would be refused here — the
+    // stored token only ever goes to the repository it was saved for.
+    const res = await post(base, { settings: { kbRepoUrl: 'https://example.com/acme/kb/' } });
+    expect(res.status).toBe(200);
+  });
+});
+
+describe('first-run setup', () => {
+  it('asks nothing: there is no configured address and no working copy to lose', async () => {
+    const { base, settings, phaseRuns } = listen(0);
+    const res = await post(base, { settings: { kbRepoUrl: REPO, gitToken: 'ghp_new' } });
+    expect(res.status).toBe(200);
+    expect(settings.resolve('kbRepoUrl')).toBe(REPO);
+    // The completion transition runs the phase, as it always has.
+    expect(phaseRuns.count).toBe(1);
+  });
+});
+
+/**
+ * The move runs while the deployment is serving. A commit worker left
+ * running would write into a working copy that is being renamed away, or
+ * into the fresh clone of a repository the commit was never meant for.
+ */
+describe('the commit worker, while a deployment is moved', () => {
+  /**
+   * Held BEFORE the new address is stored, not only around the phase. The
+   * way chosen takes effect with the store, and a worker still running in
+   * between would push a queued commit from a copy of the repository being
+   * left with the credential of the one moved to.
+   */
+  it('is held from before the address is stored until the startup phase has run', async () => {
+    const { base, events } = await configured(0);
+    events.length = 0;
+    const res = await post(base, {
+      settings: { kbRepoUrl: 'https://example.com/acme/another.git', gitToken: 'ghp_new' },
+      confirmRepositoryChange: 'keep',
+    });
+    expect(res.status).toBe(200);
+    expect(events).toEqual([`commits held on ${REPO}`, 'phase', 'commits released']);
+  });
+
+  it('is let go when the confirmed move is refused after all', async () => {
+    const { base, events } = await configured(2);
+    events.length = 0;
+    failTheClose = true;
+    const res = await post(base, {
+      settings: { kbRepoUrl: 'https://example.com/acme/another.git', gitToken: 'ghp_new' },
+      confirmRepositoryChange: 'close',
+    });
+    expect(res.status).toBe(500);
+    expect(events).toEqual([`commits held on ${REPO}`, 'commits released']);
+  });
+
+  it('is not touched by a save that moves nothing', async () => {
+    const { base, events } = await configured(0);
+    events.length = 0;
+    const res = await post(base, { settings: { kbSyncSecret: 'a-secret-of-sixteen-or-more' } });
+    expect(res.status).toBe(200);
+    expect(events).toEqual([]);
+  });
+
+  it('is not held by a move that was only asked about', async () => {
+    const { base, events } = await configured(0);
+    events.length = 0;
+    const res = await post(base, { settings: { kbRepoUrl: 'https://example.com/acme/another.git', gitToken: 'ghp_new' } });
+    expect(res.status).toBe(409);
+    expect(events).toEqual([]);
+  });
+});

package/src/modules/settings/__tests__/setup.routes.test.ts

@@ -780,8 +780,11 @@ describe('POST /setup/settings — the connection is checked before it is stored
     const { base, settings } = listen(true, undefined, remote.check);
     await settings.save({ kbRepoUrl: REPO, gitToken: 'ghp_old' }, null);
     const moved = 'https://example.com/acme/moved.git';
+    // A different repository replaces every working copy, so the save is
+    // refused until the admin confirms — the address is checked all the same.
     const res = await post(base, '/api/setup/settings', {
       settings: { kbRepoUrl: moved, gitToken: 'ghp_new' },
+      confirmRepositoryChange: 'keep',
     });
     expect(res.status).toBe(200);
     expect(remote.asked).toEqual([{ url: moved, token: 'ghp_new', username: 'x-access-token' }]);

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

@@ -14,9 +14,10 @@ import {
 } from '@bevel-software/platform-shared';
 import { createHmac } from 'node:crypto';
 import { TokenCrypto } from '../../shared/token-crypto.js';
-import { assertKbDirNameFree } from '../kb-fs/repo-path.js';
+import { assertKbDirNameFree, hasControlCharacter } 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,15 +152,73 @@ 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',
     section: 'knowledge-base',
     // Joined with workspace paths, so a separator or `..` would let it escape
-    // the workspace directory.
+    // the workspace directory — and a control character would be PREFIXED onto
+    // every path, where a line break is a separator to git's `cat-file
+    // --batch` and would make the normaliser emit a path it refuses from a
+    // caller (see `hasControlCharacter`).
     validate: (v) =>
       v && v !== '.' && v !== '..' && !v.includes('/') && !v.includes('\\')
-        ? null
+        ? hasControlCharacter(v)
+          ? 'Use a single folder name — no line breaks or other invisible characters.'
+          : null
         : 'Use a single folder name — no slashes.',
     // Copied into a dozen services when they are constructed. A running server
     // keeps the name it started with.
@@ -583,7 +672,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 +705,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 +753,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 +782,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]);
+  }
+}