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

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

@@ -16,8 +16,11 @@ import {
   failureOf,
   gitFailure,
   type GitFailure,
+  type GitFailureKind,
 } from '../../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../../shared/redact-secret.js';
+import { normalizeRepositoryAddress, sameRepository } from '../../kb-fs/remote-url.js';
+import { setAsideClone, setAsideRootFor, setAsideStamp } from '../set-aside-clone.js';
 
 /**
  * The KB startup phase: run every registered {@link OnServerStart} step, in
@@ -28,7 +31,9 @@ import { redactSecret, urlQuerySecrets } from '../../../shared/redact-secret.js'
  *
  * Fully fail-closed: any failure this phase cannot DECLARE (an unhandled
  * step throw, an unreachable remote, a clone that will not come down, a
- * refused write) throws out of `runAll` and stops the boot. The container's
+ * refused write) throws out of `runAll`. The boot stops on it unless the
+ * host ANSWERED about the repository or the credentials, in which case it
+ * comes up gated instead — see `bootMaySurvive`. The container's
  * restart policy is the retry — each attempt at boot time on quiet trees —
  * so an environmental failure converges without a human the moment the
  * environment returns. The one carve-out: a push rejected because a
@@ -51,6 +56,15 @@ export interface KbStartupRunnerOptions {
   gitRunner: IGitRunner;
   kbRepoUrl: () => string;
   workspacesRoot: string;
+  /**
+   * 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`. THE SAME VALUE THE WORKSPACE
+   * SERVICE IS GIVEN.
+   *
+   * Why, in one place: `setAsideRootFor` in `set-aside-clone.ts`.
+   */
+  setAsideRoot?: string;
   kbDirName: string;
   templateDir: string;
   defaultBranch: () => string;
@@ -67,6 +81,47 @@ export interface KbStartupRunnerOptions {
       template `.gitignore` rule can never silently drop a required seed file
       from the commit. */
   buildSeedTree: (dir: string) => Promise<string[]>;
+  /**
+   * Called with the workspace id of each working copy the phase is ABOUT TO
+   * set aside for being a clone of another repository, and awaited first.
+   * Whatever is still queued to be committed into that copy was written
+   * against the repository that was left, so it must be held back before a
+   * fresh clone of another repository appears at the same path.
+   *
+   * A PRECONDITION, so a failure here STOPS THE PHASE with the copy still
+   * where it was. Carrying on would clone the replacement with the queue
+   * untouched, and the worker would then commit those bytes into a
+   * repository they were never meant for. Stopped before anything moved, the
+   * next run finds the same copy and asks again. Optional: a minimal graph
+   * has no queue.
+   */
+  beforeCloneSetAside?: (workspaceId: string) => Promise<void>;
+  /**
+   * Called with the workspace id of each working copy the phase SET ASIDE for
+   * being a clone of another repository. The workspace service keeps a
+   * branch→directory cache and adopts whatever is on disk, so on a RUNNING
+   * server (the save that moves the deployment to another repository) the
+   * copy would otherwise stay in that cache as a path to nothing. Optional:
+   * at boot nothing has been cached yet.
+   *
+   * Never throws into the phase: a listener that fails must not stop a boot.
+   */
+  onCloneDiscarded?: (workspaceId: string) => void | Promise<void>;
+  /**
+   * Called with the workspace id of each working copy the phase CLONED fresh.
+   * A clone has just downloaded every ref, which is a successful fetch by any
+   * measure — but the git layer keeps its own per-workspace record of the last
+   * fetch and whether it worked, and the one that drove the replacement is a
+   * FAILED fetch of the repository that is gone. Left standing, a strict
+   * branch listing inside that record's TTL refuses the new clone's refs as
+   * unproven, having never touched it.
+   *
+   * The ordinary path already says this (`WorkspaceService`'s cloned
+   * listener); the phase clones with git directly, so it has to say it itself.
+   *
+   * Never throws into the phase, for the same reason as above.
+   */
+  onCloneCreated?: (workspaceId: string) => void;
 }
 
 /**
@@ -97,6 +152,42 @@ export class KbRemoteUnreachableError extends ClassifiedFailure {
   }
 }
 
+/**
+ * The failure kinds a boot may survive GATED rather than stop on: the remote
+ * ANSWERED (or could not be reached at all), and what it said is about the
+ * repository or the credentials — not about what this deployment would write.
+ *
+ * All four are fixed by an operator somewhere other than this process: the
+ * host comes back, the repository is created or the token is granted access
+ * to it, a rotated token is entered on the setup screen. Refusing to boot
+ * over any of them takes away the very screen the fix is entered on — which
+ * is what happened on 2026-09-28, when a replaced repository answered
+ * `not found` inside a step and the container crash-looped.
+ *
+ * Every OTHER failure still stops the boot: it means a step or the template
+ * would write something wrong, and booting over that is worse than not
+ * booting at all.
+ */
+const GATED_BOOT_KINDS: ReadonlySet<GitFailureKind> = new Set([
+  'unreachable',
+  'not-found',
+  'credentials-rejected',
+  'write-refused',
+]);
+
+/**
+ * Whether the boot may come up GATED on this failure instead of stopping.
+ *
+ * {@link KbRemoteUnreachableError} says so by its type — it is raised where
+ * the remote is first contacted, before any step. A failure raised INSIDE the
+ * phase says so by its classification: the same fetch that stops a boot when
+ * it is the first contact must not stop one when a step happened to make it.
+ */
+export function bootMaySurvive(err: unknown): boolean {
+  if (err instanceof KbRemoteUnreachableError) return true;
+  return err instanceof ClassifiedFailure && GATED_BOOT_KINDS.has(err.failure.kind);
+}
+
 export interface RetryOptions {
   /** First wait before trying again. Default 30s. */
   initialDelayMs?: number;
@@ -241,7 +332,7 @@ export class KbStartupRunner {
           // Stopped by either: a failure that is no longer the remote at all
           // (the knowledge base itself is wrong — asking again will not change
           // it), or a remote answer that a retry cannot change (see above).
-          if (!(err instanceof KbRemoteUnreachableError) || !worthRetrying()) return stopOnStanding();
+          if (!bootMaySurvive(err) || !worthRetrying()) return stopOnStanding();
           delay = Math.min(delay * 2, max);
           log(`remote still unreachable; trying again in ${Math.round(delay / 1000)}s`);
         }
@@ -301,6 +392,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) {
@@ -501,6 +596,141 @@ 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 = setAsideStamp();
+    const setAsideRoot = setAsideRootFor(this.opts.workspacesRoot, this.opts.setAsideRoot);
+    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);
+      // First, and allowed to stop the phase: see `beforeCloneSetAside`. The
+      // directory name IS the workspace id (`workspaceIdForBranch`).
+      await this.opts.beforeCloneSetAside?.(entry.name);
+      await setAsideClone(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.',
+      );
+      // Setting it aside already removed it from the workspaces root, so the
+      // cached handle the workspace service holds for it now points at
+      // nothing.
+      try {
+        await this.opts.onCloneDiscarded?.(entry.name);
+      } catch (err) {
+        startupLog.warn(`could not finish setting the working copy "${entry.name}" aside:`, {
+          detail: this.redact(err instanceof Error ? err.message : String(err)),
+        });
+      }
+    }
+  }
+
+  /**
+   * 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.
+   */
+
   /**
    * The branch's working copy at the runtime layout
    * (`<workspacesRoot>/<id>/<kbDirName>`), so the workspace service finds it
@@ -518,6 +748,16 @@ export class KbStartupRunner {
       await fs.mkdir(workspaceDir, { recursive: true });
       await fs.rm(repoDir, { recursive: true, force: true });
       await git(this.opts.gitRunner, workspaceDir, ['clone', '-b', branch, this.opts.kbRepoUrl(), repoDir]);
+      // Said as soon as the clone is there, before its configuration: if a
+      // command below fails, the clone stays on disk, and the retry finds it
+      // and never comes back through here.
+      try {
+        this.opts.onCloneCreated?.(workspaceIdForBranch(branch));
+      } catch (err) {
+        startupLog.warn(`could not announce the fresh working copy for "${branch}":`, {
+          detail: this.redact(err instanceof Error ? err.message : String(err)),
+        });
+      }
       await git(this.opts.gitRunner, repoDir, ['config', 'core.longpaths', 'true']);
       await stampIdentity(this.opts.gitRunner, repoDir);
       return repoDir;

package/src/modules/workspace/workspace.routes.ts

@@ -739,7 +739,7 @@ export function createWorkspaceRoutes(
   }
 
   /**
-   * GET /workspace/:id/file/raw?path=<file>[&download=1][&v=<n>]
+   * GET /workspace/:id/file/raw?path=<file>[&download=1][&v=<n>][&ref=<sha>[&side=before]]
    *
    * The bytes of one workspace file: for the document renderers' fetches, the
    * file tree's Download, and the `<img>` tags the markdown pipeline emits for
@@ -750,7 +750,8 @@ export function createWorkspaceRoutes(
    *   request ──▶ auth: Bearer, else the cookie
    *           ──▶ read gate on the path             403 if the caller may not read it
    *           ──▶ download gate, if ?download=1     403 without the download: verb
-   *           ──▶ readFileBinary                    404 missing, 403 traversal
+   *           ──▶ readFileBinary, or the bytes at   404 missing, 403 traversal
+   *               ?ref when one is named
    *           ──▶ Content-Type from the extension, nosniff, a CSP sandbox for
    *               inline svg, attachment disposition for a download, and
    *               Cache-Control: private, no-cache
@@ -760,6 +761,30 @@ export function createWorkspaceRoutes(
    *
    * `?v=` is not read here. The frontend bumps it when it learns an image
    * changed, so the browser asks for a URL it has not cached.
+   *
+   * `?ref=<sha>` serves the file AS IT WAS at that save instead of the working
+   * tree, so Version history can mount the very viewers this route already
+   * feeds. `&side=before` reads `<sha>^` — the version just before a save,
+   * which is the only thing the save that DELETED a file can show. Everything
+   * around the read is deliberately unchanged: the same read gate, the same
+   * download verb, the same content type, the same svg sandbox. What the ref
+   * changes is WHICH bytes, never WHO may have them:
+   *
+   *   - both gates resolve against TODAY's tree, not the rules as they were at
+   *     that save (hx-history-file-preview, decision 3): anyone who may read
+   *     the file now may read any of its past saves, and anyone who may not is
+   *     refused with the same sentence they get for the file itself;
+   *   - the save must be in the history of the branch this workspace has
+   *     checked out — `fileBytesAtChange` refuses anything else with a 404
+   *     carrying `VERSION_NOT_ON_BRANCH_MESSAGE`;
+   *   - a ref that is present but malformed is a 400, never a silent fall back
+   *     to `readFileBinary`. Serving today's bytes for a request that asked for
+   *     a past version would be the worst possible answer — it looks like a
+   *     success — so the ref branch and the working-tree branch are exclusive;
+   *   - and a read that fails for OUR reasons (a blob over the git runner's
+   *     output ceiling, a timed-out `cat-file`) is a logged 500, not the
+   *     blanket 404 the working-tree read answers with: "not found" about a
+   *     save the reader can see listed is a lie about their own history.
    */
   router.get('/workspace/:id/file/raw', async (req, res) => {
     const id = authenticated(req, res);
@@ -771,6 +796,27 @@ export function createWorkspaceRoutes(
     }
     const filePath = inRepo(res, requested);
     if (filePath === null) return;
+    // A past save, asked for by sha. Validated BEFORE the gates so a
+    // mistyped ref is a 400 rather than a 200 carrying today's bytes.
+    const rawRef = req.query.ref;
+    if (rawRef !== undefined && (typeof rawRef !== 'string' || !/^[a-f0-9]{7,40}$/i.test(rawRef))) {
+      res.status(400).json({ error: 'ref must be a commit sha' });
+      return;
+    }
+    const ref = typeof rawRef === 'string' ? rawRef : null;
+    // Only the two sides exist; `side` without `ref` names nothing, and an
+    // unrecognised value is a spelling mistake in a security-relevant
+    // parameter, not a default to guess at.
+    const rawSide = req.query.side;
+    if (rawSide !== undefined && rawSide !== 'before' && rawSide !== 'after') {
+      res.status(400).json({ error: "side must be 'before' or 'after'" });
+      return;
+    }
+    if (rawSide !== undefined && ref === null) {
+      res.status(400).json({ error: 'side requires ref' });
+      return;
+    }
+    const side = rawSide === 'before' ? 'before' : 'after';
     // `?download=1` flips this from inline-serve (used by PdfRenderer and
     // the image renderers) to "save to disk" — and the save path is gated
     // on per-path `download:` rules in access.md. The inline path stays
@@ -785,7 +831,28 @@ export function createWorkspaceRoutes(
       if (!(await requireDownloadPermission(req, res, id, filePath))) return;
     }
     try {
-      const buffer = await workspaceService.readFileBinary(id, filePath);
+      let buffer: Buffer;
+      if (ref === null) {
+        buffer = await workspaceService.readFileBinary(id, filePath);
+      } else {
+        const at = await workflowService.fileBytesAtChange(id, filePath, ref, side);
+        // Nothing at that path on that side of the save — for `before`, also
+        // how a root commit answers, since it has no parent to read.
+        if (at === null) {
+          res.status(404).json({ error: 'File not found' });
+          return;
+        }
+        // `IWorkflowService` is isomorphic, so the bytes arrive typed as a
+        // `Uint8Array`. `res.send` recognises a Buffer and JSON-encodes
+        // anything else, so a zero-copy view over the same memory is what it
+        // has to be handed — never a copy of a file that may be tens of MB.
+        buffer = Buffer.from(at.bytes.buffer, at.bytes.byteOffset, at.bytes.byteLength);
+        // The blob's object id IS the content hash, and a past version can
+        // never change, so this is the strongest ETag available and costs no
+        // second pass over the bytes. Set BEFORE `res.send`, which then skips
+        // its own weak ETag and answers a matching If-None-Match with a 304.
+        res.setHeader('ETag', `"${at.blobId}"`);
+      }
       const ext = filePath.slice(filePath.lastIndexOf('.')).toLowerCase();
       const mimeTypes: Record<string, string> = {
         '.png': 'image/png',
@@ -844,6 +911,31 @@ export function createWorkspaceRoutes(
         sendError(res, error);
         return;
       }
+      // A refusal the ref branch raised has to reach the caller AS ITSELF: a
+      // save from another branch is answered with
+      // `VERSION_NOT_ON_BRANCH_MESSAGE`, and flattening it into the generic
+      // "File not found" would tell a reader their file had vanished. Only
+      // the ref branch can raise one, so the working-tree read keeps the
+      // blanket 404 it has always answered with.
+      if (ref !== null && error instanceof WorkflowDomainError) {
+        sendError(res, error);
+        return;
+      }
+      // Anything else out of the ref branch is OUR failure, not a missing
+      // version: the read goes through the git runner, where a blob over
+      // `MAX_OUTPUT_BYTES` and a timed-out `cat-file` both arrive here as
+      // plain errors. A 404 would tell a reader the save they can see listed
+      // had vanished, and would do it silently — so it is a logged 500, and
+      // "Try again" in the pane is then a truthful offer.
+      if (ref !== null) {
+        log.error(
+          `could not read ${printable(filePath)} at ${printable(ref)}: ${printable(
+            error instanceof Error ? error.message : String(error),
+          )}`,
+        );
+        res.status(500).json({ error: 'Could not read this version of the file' });
+        return;
+      }
       res.status(404).json({ error: 'File not found' });
     }
   });