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

package/src/modules/workspace/startup/kb-startup-runner.ts

@@ -1,6 +1,5 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { isBranchModelConfigured } from '@bevel-software/platform-shared';
 import { logger } from '../../../shared/logging.js';
 
 // `startupLog` rather than `log`: `retryUntilMaintained` takes a `log`
@@ -19,6 +18,7 @@ import {
   type GitFailure,
 } from '../../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../../shared/redact-secret.js';
+import { normalizeRepositoryAddress, sameRepository } from '../../kb-fs/remote-url.js';
 
 /**
  * The KB startup phase: run every registered {@link OnServerStart} step, in
@@ -44,17 +44,24 @@ import { redactSecret, urlQuerySecrets } from '../../../shared/redact-secret.js'
  */
 
 export interface KbStartupRunnerOptions {
-  /** How git is run — see `shared/git.contract.ts`. */
+  /**
+   * How git is run — see `shared/git.contract.ts`. It carries the credentials
+   * every command of the phase authenticates with, and the token the phase
+   * scrubs from every message it throws or logs.
+   */
   gitRunner: IGitRunner;
   kbRepoUrl: () => string;
-  gitUsername: () => string;
+  workspacesRoot: string;
   /**
-   * The git token in effect (settings-stored or environment), scrubbed from
-   * every message the phase throws or logs. Optional: `GITHUB_TOKEN` and its
-   * aliases are scrubbed regardless.
+   * Where a working copy of a repository that is no longer the configured
+   * one is moved to, under a folder named for the moment it happened — see
+   * `reconcileClonesWithConfiguredRepository`. NOT under `workspacesRoot`:
+   * the workspace service's orphan sweep removes every folder there that is
+   * not a known branch's, and what is set aside has to outlive that sweep.
+   * The composition root names a folder under the backups root, which is a
+   * persistent volume of its own. Default: a sibling of `workspacesRoot`.
    */
-  gitToken?: () => string;
-  workspacesRoot: string;
+  setAsideRoot?: string;
   kbDirName: string;
   templateDir: string;
   defaultBranch: () => string;
@@ -131,7 +138,7 @@ export class KbStartupRunner {
    * them without the URL around them.
    */
   private redact(text: string): string {
-    return redactSecret(text, [this.opts.gitToken?.(), ...urlQuerySecrets(this.opts.kbRepoUrl())]);
+    return redactSecret(text, [this.opts.gitRunner.credentials.token(), ...urlQuerySecrets(this.opts.kbRepoUrl())]);
   }
 
   /**
@@ -260,7 +267,8 @@ export class KbStartupRunner {
   }
 
   private async runAllOnce(): Promise<void> {
-    if (!isBranchModelConfigured()) {
+    // An empty default branch IS the unconfigured model (see `KbContext`).
+    if (!this.opts.defaultBranch()) {
       startupLog.info('branch model not configured yet — phase skipped until setup completes.');
       return;
     }
@@ -304,6 +312,10 @@ export class KbStartupRunner {
         );
       }
       const heads = await this.ensureRemote();
+      // AFTER the remote answered: the configured address is known to be a
+      // repository we can reach, so a clone of a different one is stale, not
+      // a casualty of a typo in the address.
+      await this.reconcileClonesWithConfiguredRepository();
       const ctx = this.buildContext(heads, handles);
 
       for (const step of this.opts.steps) {
@@ -389,13 +401,12 @@ export class KbStartupRunner {
    */
   private async ensureRemote(): Promise<Set<string>> {
     const url = this.opts.kbRepoUrl();
-    const user = this.opts.gitUsername();
     // The first question asked of the remote, and the one that answers
     // "can we get there at all". Everything after it — seeding, pushing —
     // fails for reasons of ours; this fails for reasons of the host's.
     let heads: Set<string>;
     try {
-      heads = await lsRemoteHeads(this.opts.gitRunner, url, user);
+      heads = await lsRemoteHeads(this.opts.gitRunner, url);
       this.remoteContact = { at: Date.now(), ok: true };
     } catch (err) {
       // Git that never ran — no executable, a spawn refused — is a fact about
@@ -423,23 +434,23 @@ export class KbStartupRunner {
         );
       }
       const seededByOther = await withTempDir(async (dir) => {
-        await git(this.opts.gitRunner, dir, user,['init', '-b', defaultBranch]);
-        await stampIdentity(this.opts.gitRunner, dir, user);
+        await git(this.opts.gitRunner, dir, ['init', '-b', defaultBranch]);
+        await stampIdentity(this.opts.gitRunner, dir);
         const generated = await this.opts.buildSeedTree(dir);
-        await git(this.opts.gitRunner, dir, user,['add', '-A']);
+        await git(this.opts.gitRunner, dir, ['add', '-A']);
         // The template may ship a `.gitignore` whose rules happen to match a
         // GENERATED seed file (roles.yaml, a reserved root's .gitkeep) —
         // `add -A` would silently drop it from the seed commit. Force-add
         // exactly what the builder generated; `-f` on an already-staged path
         // is a no-op.
-        if (generated.length > 0) await git(this.opts.gitRunner, dir, user,['add', '-f', '--', ...generated]);
-        await git(this.opts.gitRunner, dir, user,['commit', '-m', 'Seed knowledge base from Bevel template']);
+        if (generated.length > 0) await git(this.opts.gitRunner, dir, ['add', '-f', '--', ...generated]);
+        await git(this.opts.gitRunner, dir, ['commit', '-m', 'Seed knowledge base from Bevel template']);
         for (const b of protectedBranches) {
-          if (b !== defaultBranch) await git(this.opts.gitRunner, dir, user,['branch', b]);
+          if (b !== defaultBranch) await git(this.opts.gitRunner, dir, ['branch', b]);
         }
-        await git(this.opts.gitRunner, dir, user,['remote', 'add', 'origin', url]);
+        await git(this.opts.gitRunner, dir, ['remote', 'add', 'origin', url]);
         try {
-          await git(this.opts.gitRunner, dir, user,['push', '-u', 'origin', ...protectedBranches]);
+          await git(this.opts.gitRunner, dir, ['push', '-u', 'origin', ...protectedBranches]);
           return null;
         } catch (err) {
           // Two replicas racing to seed the same empty remote: both saw it
@@ -452,7 +463,7 @@ export class KbStartupRunner {
           // who seeded. A foreign seed is just an "existing remote"
           // discovered late, the same contract as a repo populated before
           // boot.
-          const reread = await lsRemoteHeads(this.opts.gitRunner, url, user);
+          const reread = await lsRemoteHeads(this.opts.gitRunner, url);
           if (protectedBranches.every((b) => reread.has(b))) return reread;
           throw err;
         }
@@ -473,8 +484,8 @@ export class KbStartupRunner {
     for (const b of protectedBranches) {
       if (heads.has(b)) continue;
       await withTempDir(async (dir) => {
-        await git(this.opts.gitRunner, dir, user,['clone', '--depth', '1', '-b', base, url, 'seed']);
-        await git(this.opts.gitRunner, path.join(dir, 'seed'), user,['push', 'origin', `HEAD:refs/heads/${b}`]);
+        await git(this.opts.gitRunner, dir, ['clone', '--depth', '1', '-b', base, url, 'seed']);
+        await git(this.opts.gitRunner, path.join(dir, 'seed'), ['push', 'origin', `HEAD:refs/heads/${b}`]);
       });
       heads.add(b);
       startupLog.info(`created missing protected branch "${b}" from "${base}"`);
@@ -505,6 +516,150 @@ export class KbStartupRunner {
     };
   }
 
+  /**
+   * Bring every working copy on disk into line with the configured
+   * repository, WITHOUT DELETING ANYTHING.
+   *
+   * A clone fetches and pushes through the address stored in its own
+   * `remote.origin.url`, which nothing updates when the configured address
+   * changes. After an operator replaced the repository (2026-09-28: the old
+   * one deleted, a new one saved on the setup screen) every surviving clone
+   * kept asking the old address: Save and Retry failed, and the restart
+   * stopped the boot on `repository … not found`, taking the setup screen
+   * with it.
+   *
+   * A clone whose address differs from the configured one is one of two
+   * things, and the histories say which:
+   *
+   *  - THE SAME REPOSITORY AT A NEW ADDRESS — moved, renamed, mirrored. The
+   *    one change the setup screen tells an admin to make ("only change this
+   *    if the same repository was moved or renamed"). Its history is on the
+   *    configured remote, so the clone is pointed at the new address and
+   *    kept, unpushed commits included: they are pushed where they belonged
+   *    all along.
+   *  - ANOTHER REPOSITORY. Re-pointing it would push one repository's
+   *    commits into the other, so it cannot stay where the workspace service
+   *    would adopt it. It is MOVED to {@link KbStartupRunnerOptions.setAsideRoot}
+   *    and the log says where. Never removed: when the old repository is gone
+   *    — as it was that day — these clones are the last copy of the
+   *    knowledge base that exists, and the unpushed work in them exists
+   *    nowhere else at all.
+   *
+   * Every clone under the workspaces root, not only the branches this phase
+   * touches: the workspace service adopts whatever it finds there. A clone
+   * whose address cannot be read is left where it is — "could not tell" is
+   * no reason to move someone's work. One that cannot be set aside stops the
+   * boot with the reason: leaving it would fail the boot a step later with
+   * git's words about a repository nobody configured.
+   */
+  private async reconcileClonesWithConfiguredRepository(): Promise<void> {
+    const configured = this.opts.kbRepoUrl();
+    let entries: import('node:fs').Dirent[];
+    try {
+      entries = await fs.readdir(this.opts.workspacesRoot, { withFileTypes: true });
+    } catch {
+      return; // no workspaces yet
+    }
+    // One folder per run, so what was set aside together stays together.
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const setAsideRoot =
+      this.opts.setAsideRoot ?? path.resolve(this.opts.workspacesRoot, '..', 'replaced-working-copies');
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const repoDir = path.join(this.opts.workspacesRoot, entry.name, this.opts.kbDirName);
+      const hasGit = await fs.access(path.join(repoDir, '.git')).then(() => true, () => false);
+      if (!hasGit) continue;
+      let origin: string;
+      try {
+        origin = (await git(this.opts.gitRunner, repoDir, ['config', '--get', 'remote.origin.url'])).trim();
+      } catch {
+        continue;
+      }
+      if (origin === '' || sameRepository(origin, configured)) continue;
+      // The normalized form carries no userinfo, and the scrub covers the rest.
+      const was = this.redact(normalizeRepositoryAddress(origin));
+      if (await this.sharesHistoryWithConfigured(repoDir, configured)) {
+        await git(this.opts.gitRunner, repoDir, ['remote', 'set-url', 'origin', configured]);
+        startupLog.warn(
+          `working copy "${entry.name}" was cloned from ${was}, whose history the configured repository holds: ` +
+            'the same repository at a new address. Pointed at the configured address and kept, unpushed work included.',
+        );
+        continue;
+      }
+      const kept = path.join(setAsideRoot, stamp, entry.name);
+      await this.setAside(repoDir, kept);
+      startupLog.warn(
+        `working copy "${entry.name}" is a clone of another repository (${was}). Set aside at ${kept}; nothing was ` +
+          'deleted, and it will be cloned fresh from the configured one. Work that was never pushed is in that ' +
+          'folder: `git log` there shows it, and `git push <address> <branch>` from there sends it to a repository.',
+      );
+    }
+  }
+
+  /**
+   * Whether the configured repository holds history this clone has too —
+   * asked of git, not guessed from the two addresses. The configured
+   * remote's branches are fetched under a namespace of their own and the
+   * clone's HEAD is tested for a common ancestor with any of them.
+   *
+   * "Could not tell" answers false: a fetch that fails, a clone with no
+   * commit to compare. False sets the clone aside, which loses nothing, where
+   * a wrong true would push a stranger's commits into the configured
+   * repository.
+   */
+  private async sharesHistoryWithConfigured(repoDir: string, configured: string): Promise<boolean> {
+    const probe = 'refs/hexis-probe';
+    let theirs: string[] = [];
+    try {
+      await git(this.opts.gitRunner, repoDir, ['fetch', '--no-tags', '--quiet', configured, `+refs/heads/*:${probe}/*`]);
+      theirs = (await git(this.opts.gitRunner, repoDir, ['for-each-ref', '--format=%(refname)', `${probe}/`]))
+        .split('\n')
+        .map((ref) => ref.trim())
+        .filter(Boolean);
+      if (theirs.length === 0) return false;
+      // One question for all of them: a common ancestor of HEAD and ANY of
+      // their branches is a common ancestor of HEAD and their merge. Capped,
+      // so a remote with thousands of branches cannot outgrow a command line.
+      await git(this.opts.gitRunner, repoDir, ['merge-base', 'HEAD', ...theirs.slice(0, 200)]);
+      return true;
+    } catch {
+      return false;
+    } finally {
+      // The probe leaves nothing behind in a clone that stays in use.
+      for (const ref of theirs) {
+        await git(this.opts.gitRunner, repoDir, ['update-ref', '-d', ref]).catch(() => undefined);
+      }
+    }
+  }
+
+  /**
+   * Move a working copy out of the workspaces root, whole. A rename where
+   * the two folders share a volume; a copy and then a removal where they do
+   * not (the backups root is a volume of its own in the shipped compose
+   * files), with the original removed only once the copy is complete.
+   */
+  private async setAside(repoDir: string, dest: string): Promise<void> {
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    try {
+      await fs.rename(repoDir, dest);
+      return;
+    } catch {
+      // Another volume, or a handle held open on it: copy instead.
+    }
+    try {
+      await fs.cp(repoDir, dest, { recursive: true, errorOnExist: true, force: false, verbatimSymlinks: true });
+    } catch (err) {
+      await fs.rm(dest, { recursive: true, force: true }).catch(() => undefined);
+      throw new Error(
+        `Could not set aside the working copy at ${repoDir}, a clone of a repository that is no longer the ` +
+          `configured one, into ${dest}: ${err instanceof Error ? err.message : String(err)}. Nothing was deleted. ` +
+          'Make room there, or move that folder away by hand, and start again.',
+        { cause: err },
+      );
+    }
+    await fs.rm(repoDir, { recursive: true, force: true });
+  }
+
   /**
    * The branch's working copy at the runtime layout
    * (`<workspacesRoot>/<id>/<kbDirName>`), so the workspace service finds it
@@ -515,25 +670,24 @@ export class KbStartupRunner {
    * commit recovery owns that work, not this phase.
    */
   private async ensureClone(branch: string): Promise<string> {
-    const user = this.opts.gitUsername();
     const workspaceDir = path.join(this.opts.workspacesRoot, workspaceIdForBranch(branch));
     const repoDir = path.join(workspaceDir, this.opts.kbDirName);
     const hasGit = await fs.access(path.join(repoDir, '.git')).then(() => true, () => false);
     if (!hasGit) {
       await fs.mkdir(workspaceDir, { recursive: true });
       await fs.rm(repoDir, { recursive: true, force: true });
-      await git(this.opts.gitRunner, workspaceDir, user,['clone', '-b', branch, this.opts.kbRepoUrl(), repoDir]);
-      await git(this.opts.gitRunner, repoDir, user,['config', 'core.longpaths', 'true']);
-      await stampIdentity(this.opts.gitRunner, repoDir, user);
+      await git(this.opts.gitRunner, workspaceDir, ['clone', '-b', branch, this.opts.kbRepoUrl(), repoDir]);
+      await git(this.opts.gitRunner, repoDir, ['config', 'core.longpaths', 'true']);
+      await stampIdentity(this.opts.gitRunner, repoDir);
       return repoDir;
     }
-    await git(this.opts.gitRunner, repoDir, user,['fetch', 'origin', branch]);
-    const local = (await git(this.opts.gitRunner, repoDir, user,['rev-parse', 'HEAD'])).trim();
-    const remote = (await git(this.opts.gitRunner, repoDir, user,['rev-parse', `origin/${branch}`])).trim();
+    await git(this.opts.gitRunner, repoDir, ['fetch', 'origin', branch]);
+    const local = (await git(this.opts.gitRunner, repoDir, ['rev-parse', 'HEAD'])).trim();
+    const remote = (await git(this.opts.gitRunner, repoDir, ['rev-parse', `origin/${branch}`])).trim();
     if (local !== remote) {
-      const mergeBase = (await git(this.opts.gitRunner, repoDir, user,['merge-base', 'HEAD', `origin/${branch}`])).trim();
+      const mergeBase = (await git(this.opts.gitRunner, repoDir, ['merge-base', 'HEAD', `origin/${branch}`])).trim();
       if (mergeBase === local) {
-        await git(this.opts.gitRunner, repoDir, user,['reset', '--hard', `origin/${branch}`]);
+        await git(this.opts.gitRunner, repoDir, ['reset', '--hard', `origin/${branch}`]);
       }
       // Ahead or diverged: committed-but-unpushed work lives here; not ours to discard.
     }
@@ -544,13 +698,12 @@ export class KbStartupRunner {
   private async finalize(h: BranchHandle): Promise<void> {
     if (!h.dirty) return;
     const repoDir = await h.repoDir();
-    const user = this.opts.gitUsername();
-    await stampIdentity(this.opts.gitRunner, repoDir, user);
+    await stampIdentity(this.opts.gitRunner, repoDir);
     // Drop any PRE-EXISTING index state first (a crashed tool may have left
     // edits staged): `git commit` publishes the whole index, and the phase
     // must commit exactly its own staged set. The edits stay in the working
     // tree, unstaged and unpublished — preserved, not adopted.
-    await git(this.opts.gitRunner, repoDir, user,['reset', '-q']);
+    await git(this.opts.gitRunner, repoDir, ['reset', '-q']);
     // Stage ONLY the paths the phase's ops touched — sources and targets both
     // (a move's `from` and a remove's path stage as deletions; `add -A -- <path>`
     // handles a deleted path, `-f` handles one a branch `.gitignore` matches).
@@ -566,7 +719,7 @@ export class KbStartupRunner {
     for (const rel of h.appliedPaths()) {
       const onDisk = await fs.access(path.join(repoDir, rel)).then(() => true, () => false);
       if (!onDisk) {
-        const known = (await git(this.opts.gitRunner, repoDir, user,['ls-files', '--', `:(literal)${rel}`])).trim();
+        const known = (await git(this.opts.gitRunner, repoDir, ['ls-files', '--', `:(literal)${rel}`])).trim();
         if (known === '') continue;
       }
       touched.push(rel);
@@ -574,7 +727,7 @@ export class KbStartupRunner {
     // `:(literal)` — these are file paths, not pathspecs; chunked so a large
     // migration cannot overflow the platform's argv limit.
     for (let i = 0; i < touched.length; i += 100) {
-      await git(this.opts.gitRunner, repoDir, user,[
+      await git(this.opts.gitRunner, repoDir, [
         'add',
         '-A',
         '-f',
@@ -585,7 +738,7 @@ export class KbStartupRunner {
     // Exit 0 = nothing staged: the ops converged to no byte changes. (An
     // errored diff reads as "something staged"; a genuinely broken repo then
     // fails loudly at commit rather than being silently skipped here.)
-    const nothingStaged = await git(this.opts.gitRunner, repoDir, user,['diff', '--cached', '--quiet']).then(
+    const nothingStaged = await git(this.opts.gitRunner, repoDir, ['diff', '--cached', '--quiet']).then(
       () => true,
       () => false,
     );
@@ -594,10 +747,10 @@ export class KbStartupRunner {
     // can undo exactly it — and ONLY it. Resetting to origin/<name> instead
     // would also nuke a pre-existing committed-but-unpushed (AHEAD) commit
     // that ensureClone deliberately preserved.
-    const preCommit = (await git(this.opts.gitRunner, repoDir, user,['rev-parse', 'HEAD'])).trim();
-    await git(this.opts.gitRunner, repoDir, user,['commit', '-m', h.commitMessage()]);
+    const preCommit = (await git(this.opts.gitRunner, repoDir, ['rev-parse', 'HEAD'])).trim();
+    await git(this.opts.gitRunner, repoDir, ['commit', '-m', h.commitMessage()]);
     try {
-      await git(this.opts.gitRunner, repoDir, user,['push', 'origin', `HEAD:refs/heads/${h.name}`]);
+      await git(this.opts.gitRunner, repoDir, ['push', 'origin', `HEAD:refs/heads/${h.name}`]);
       startupLog.info(`${h.name}: ${h.commitSubject()}`);
       // Committed AND pushed: nothing of the phase remains uncommitted here,
       // so a LATER branch's failure under KB_SAFE_BOOT must not rewind this
@@ -621,7 +774,7 @@ export class KbStartupRunner {
       startupLog.warn(`${h.name}: push rejected (concurrent replica?) — rolling back local commit.`, {
         detail: this.redact(msg),
       });
-      await git(this.opts.gitRunner, repoDir, user, ['reset', '--hard', preCommit]).catch(() => {});
+      await git(this.opts.gitRunner, repoDir, ['reset', '--hard', preCommit]).catch(() => {});
     }
   }
 }
@@ -655,7 +808,7 @@ class BranchHandle implements KbBranch {
       // resetUncommitted resets to THIS sha rather than HEAD, so a finalize
       // commit that was created but failed to push rolls back too instead of
       // surviving as a stranded local commit no later boot would ever push.
-      this.prePhaseSha = (await git(this.gitRunner, dir, 'x-access-token',['rev-parse', 'HEAD'])).trim();
+      this.prePhaseSha = (await git(this.gitRunner, dir, ['rev-parse', 'HEAD'])).trim();
       return dir;
     });
   }
@@ -777,12 +930,12 @@ class BranchHandle implements KbBranch {
   async resetUncommitted(): Promise<void> {
     if (!this.dirty) return;
     const repoDir = await this.repoDir();
-    await git(this.gitRunner, repoDir, 'x-access-token',['reset', '--hard', this.prePhaseSha ?? 'HEAD']).catch(() => {});
+    await git(this.gitRunner, repoDir, ['reset', '--hard', this.prePhaseSha ?? 'HEAD']).catch(() => {});
     if (this.applied.size > 0) {
       // `:(literal)` — these are file paths, not pathspecs: a name that
       // happens to contain glob or magic characters must match itself only,
       // never broaden the cleanup.
-      await git(this.gitRunner, repoDir, 'x-access-token',[
+      await git(this.gitRunner, repoDir, [
         'clean',
         '-fdx',
         '--',