@bevel-software/platform-core-backend 0.15.1 → 0.19.0

package/src/modules/workflow/git/__tests__/node-git-runner.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { NodeGitRunner } from '../node-git-runner.js';
+import { GitRunError, isGitTimeout } from '../../../../shared/git.contract.js';
+
+/**
+ * These run REAL git, like the rest of this module's suites: the behaviours
+ * under test — what a deadline does to a live child, what an exit code means,
+ * what git puts in a message — are properties of the process, and a stubbed
+ * spawn would only re-assert the stub.
+ */
+describe('NodeGitRunner', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await fs.mkdtemp(path.join(os.tmpdir(), 'git-runner-'));
+    const runner = new NodeGitRunner();
+    await runner.run(dir, ['init', '--initial-branch=main']);
+  });
+
+  afterEach(async () => {
+    await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
+  });
+
+  it('returns what git wrote', async () => {
+    const runner = new NodeGitRunner();
+    // `symbolic-ref` rather than `rev-parse HEAD`: the repository has no commit
+    // yet, and an unborn HEAD is not a revision `rev-parse` can resolve.
+    const { stdout } = await runner.run(dir, ['symbolic-ref', '--short', 'HEAD']);
+    expect(stdout.trim()).toBe('main');
+  });
+
+  it('feeds stdin to commands that read it', async () => {
+    const runner = new NodeGitRunner();
+    const { stdout } = await runner.run(dir, ['hash-object', '--stdin'], { input: 'hello' });
+    // git's hash for the blob "hello" — stable across every git version.
+    expect(stdout.trim()).toBe('b6fc4c620b67d95f953a5c1c1230aaab5db5a1b0');
+  });
+
+  it('carries the exit code so callers can read an expected non-zero exit', async () => {
+    const runner = new NodeGitRunner();
+    // `merge-base --is-ancestor` exits 1 for "no", which several callers read
+    // as an answer rather than a failure.
+    const err = await runner
+      .run(dir, ['merge-base', '--is-ancestor', 'HEAD', 'HEAD'])
+      .catch((e: unknown) => e);
+    // An unborn HEAD makes this fail outright; either way the point is that a
+    // failure arrives as GitRunError with git's own exit code attached.
+    expect(err).toBeInstanceOf(GitRunError);
+    expect(typeof (err as GitRunError).exitCode).toBe('number');
+    expect(isGitTimeout(err)).toBe(false);
+  });
+
+  it('names the failing subcommand past any leading -c pairs', async () => {
+    const runner = new NodeGitRunner();
+    const err = await runner
+      .run(dir, ['-c', 'user.name=x', '-c', 'user.email=y', 'checkout', 'no-such-branch'])
+      .catch((e: unknown) => e);
+    expect((err as Error).message).toMatch(/^git checkout failed:/);
+  });
+
+  it('kills a command that outlives its deadline, and says that is what happened', async () => {
+    const runner = new NodeGitRunner();
+    // `git ls-remote` against a routable-but-dead address hangs in connect:
+    // 203.0.113.0/24 is TEST-NET-3, reserved for documentation and guaranteed
+    // not to be routed to anything that answers.
+    const started = Date.now();
+    const err = await runner
+      .run(dir, ['ls-remote', 'http://203.0.113.1/repo.git'], { timeoutMs: 1_000 })
+      .catch((e: unknown) => e);
+
+    expect(isGitTimeout(err)).toBe(true);
+    expect((err as Error).message).toMatch(/timed out after 1000ms/);
+    // The deadline has to bound the WAIT, not just fire a timer. Signalling
+    // git alone does not: the transport helper it spawned keeps the stdio
+    // pipes open, and node resolves an execFile when the pipes close, so the
+    // call returned after the helper's own connect timeout (measured at 21s
+    // against this address) rather than after ours. The tree kill is what
+    // makes this assertion hold.
+    expect(Date.now() - started).toBeLessThan(10_000);
+  });
+
+  it('does not hold the event loop open after a call that beat its deadline', async () => {
+    const runner = new NodeGitRunner();
+    // A generous deadline on a command that finishes immediately. The
+    // escalation timer is armed only on the timeout path, but the deadline
+    // timer is armed on every call and would keep the process alive for its
+    // full duration if it were not cleared.
+    await runner.run(dir, ['rev-parse', '--git-dir'], { timeoutMs: 600_000 });
+    // Vitest fails the run on a leaked handle; reaching here with no open
+    // timer is the assertion.
+    expect(true).toBe(true);
+  });
+
+  it('keeps the configured git token out of failures', async () => {
+    const runner = new NodeGitRunner();
+    const previous = process.env.GITHUB_TOKEN;
+    process.env.GITHUB_TOKEN = 'ghp_secret_value_here';
+    try {
+      const err = await runner
+        .run(dir, ['ls-remote', 'https://x-access-token:ghp_secret_value_here@127.0.0.1:1/r.git'], {
+          timeoutMs: 15_000,
+        })
+        .catch((e: unknown) => e);
+      const text = `${(err as Error).message} ${(err as GitRunError).stderr ?? ''}`;
+      expect(text).not.toContain('ghp_secret_value_here');
+    } finally {
+      if (previous === undefined) delete process.env.GITHUB_TOKEN;
+      else process.env.GITHUB_TOKEN = previous;
+    }
+  });
+});

package/src/modules/workflow/git/__tests__/pull-request.service.getPrDetail.test.ts

@@ -34,6 +34,7 @@ function makeDb(): Database {
 
 const BASE = 'b'.repeat(40);
 const HEAD = 'a'.repeat(40);
+const FORK = 'c'.repeat(40);
 
 /**
  * A detail read is the hot path behind every change-request poll, every
@@ -47,7 +48,8 @@ describe('PullRequestService.getPrDetail — git work per read', () => {
   function harness() {
     const resolvePrShas = vi.fn(async () => ({ baseSha: BASE, headSha: HEAD }));
     const changedFilesForPr = vi.fn(async () => []);
-    const git = { resolvePrShas, changedFilesForPr } as unknown as GitService;
+    const forkPointForPr = vi.fn(async () => ({ mergeBaseSha: FORK, behind: true }));
+    const git = { resolvePrShas, changedFilesForPr, forkPointForPr } as unknown as GitService;
     const workspace = {
       findAnyWorkspaceId: async () => 'ws-main',
       ensureRemotesFetched: async () => undefined,
@@ -61,7 +63,7 @@ describe('PullRequestService.getPrDetail — git work per read', () => {
       getApprovalStates,
       evaluateMergeGate: () => ({ mergeable: false, reasons: [], warnings: [] }),
     });
-    return { svc, resolvePrShas, changedFilesForPr, getApprovalStates };
+    return { svc, resolvePrShas, changedFilesForPr, forkPointForPr, getApprovalStates };
   }
 
   it('pins the file list to the SHAs it just resolved, and keeps patches for a client read', async () => {
@@ -111,4 +113,69 @@ describe('PullRequestService.getPrDetail — git work per read', () => {
       { at: { baseSha: BASE, headSha: HEAD } },
     );
   });
+
+  it('carries the fork point and "needs updating", pinned to the same SHAs as the file list', async () => {
+    const { svc, forkPointForPr } = harness();
+    const detail = await svc.getPrDetail(7, { fresh: true });
+    expect(forkPointForPr).toHaveBeenCalledWith('ws-main', { baseSha: BASE, headSha: HEAD });
+    expect(detail?.mergeBaseSha).toBe(FORK);
+    expect(detail?.behind).toBe(true);
+    // Anonymous read: no viewer, no Update.
+    expect(detail?.viewerCanUpdate).toBe(false);
+  });
+
+  it('the target moving on invalidates a cached detail, even with the head unchanged', async () => {
+    const { svc, resolvePrShas, getApprovalStates } = harness();
+    await svc.getPrDetail(7, { fresh: true });
+    resolvePrShas.mockResolvedValueOnce({ baseSha: 'd'.repeat(40), headSha: HEAD });
+    await svc.getPrDetail(7);
+    expect(getApprovalStates).toHaveBeenCalledTimes(2);
+  });
+});
+
+/**
+ * The link on a change request is what an agent hands a person, so it is built
+ * from the configured public frontend address — never from the source branch.
+ */
+describe('PullRequestService — change request link', () => {
+  function detailWith(publicFrontendUrl?: string | null) {
+    const git = {
+      resolvePrShas: async () => ({ baseSha: BASE, headSha: HEAD }),
+      changedFilesForPr: async () => [],
+      forkPointForPr: async () => ({ mergeBaseSha: FORK, behind: false }),
+    } as unknown as GitService;
+    const workspace = {
+      findAnyWorkspaceId: async () => 'ws-main',
+      ensureRemotesFetched: async () => undefined,
+    } as unknown as WorkspaceService;
+    const access = { canWriteAtRef: async () => false } as unknown as IAccessControl;
+    const svc = new PullRequestService(makeDb(), workspace, access, git, publicFrontendUrl);
+    svc.setDetailEnricher({
+      listComments: async () => [],
+      getApprovalStates: async () => [],
+      evaluateMergeGate: () => ({ mergeable: false, reasons: [], warnings: [] }),
+    });
+    return svc.getPrDetail(7, { fresh: true });
+  }
+
+  it('is absolute under a configured address, with no note', async () => {
+    const detail = await detailWith('https://bevel.example.com');
+    expect(detail?.number).toBe(7);
+    expect(detail?.url).toBe('https://bevel.example.com/change-requests/7');
+    expect(detail).not.toHaveProperty('urlNote');
+    expect(detail?.url).not.toContain('alice');
+    expect(detail?.url).not.toContain('feature');
+  });
+
+  it('includes a proxied deployment\'s path prefix', async () => {
+    const detail = await detailWith('https://example.com/hexis/');
+    expect(detail?.url).toBe('https://example.com/hexis/change-requests/7');
+  });
+
+  it('stays relative with a note when no address is configured', async () => {
+    const detail = await detailWith(null);
+    expect(detail?.number).toBe(7);
+    expect(detail?.url).toBe('/change-requests/7');
+    expect(detail?.urlNote).toBe('Set PUBLIC_FRONTEND_URL to get absolute links.');
+  });
 });

package/src/modules/workflow/git/__tests__/pull-request.service.list-fetch.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect, vi } from 'vitest';
+
+import { PullRequestService } from '../pull-request.service.js';
+import type { Database } from '../../../database/connection.js';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import type { GitService } from '../git.service.js';
+import type { IAccessControl } from '../../../access/access-control.interface.js';
+
+/**
+ * What a change-request LIST is allowed to cost.
+ *
+ * REPRODUCED against a running instance (ticket log, 2026-09-18): a cold
+ * `GET /api/workflow/change-requests/for-me?fresh=1` took 1.31s at two open
+ * requests and 3.48s at five — about 0.55s more per additional request. The
+ * cause is per-request: every summary needs the request's touched paths, and
+ * `changedPathsForPr` fetches the two refs it is about before diffing them,
+ * so the list paid one NETWORK ROUND TRIP per open request. It is re-read
+ * after every proposal and polled every 60s, and the tree asks two list
+ * endpoints at once, so the cost landed twice over.
+ *
+ * The refs still have to be fresh. They are refreshed once for the whole
+ * clone instead — `ensureRemotesFetched` is one `git fetch --prune origin`,
+ * TTL-cached, sharing an in-flight fetch between callers.
+ */
+
+const row = (number: number, sourceBranch: string) => ({
+  id: `cr-${number}`,
+  number,
+  sourceBranch,
+  targetBranch: 'main',
+  title: `Changes ${number}`,
+  body: '',
+  authorEmail: 'biz2@bevel.software',
+  authorName: 'Biz Two',
+  state: 'open',
+  mergedSha: null,
+  createdAt: new Date('2026-09-18T00:00:00Z'),
+  updatedAt: null,
+  closedAt: null,
+});
+
+function harness(rows = [row(1, 'suggestions/a/knowledge'), row(2, 'suggestions/b/knowledge')]) {
+  const db = {
+    select: () => ({
+      from: () => ({
+        where: () => ({ orderBy: async () => rows, limit: async () => rows }),
+      }),
+    }),
+  } as unknown as Database;
+  const changedPathsForPr = vi.fn(async () => ['Shared/one.pdf']);
+  const git = { changedPathsForPr } as unknown as GitService;
+  const ensureRemotesFetched = vi.fn(async () => undefined);
+  const workspace = {
+    findAnyWorkspaceId: async () => 'ws-main',
+    ensureRemotesFetched,
+  } as unknown as WorkspaceService;
+  const access = {
+    canWriteBatchAtRef: async (_w: string, _r: string, _e: string, asked: string[]) =>
+      new Map(asked.map((p) => [p, true])),
+  } as unknown as IAccessControl;
+  return {
+    svc: new PullRequestService(db, workspace, access, git),
+    changedPathsForPr,
+    ensureRemotesFetched,
+  };
+}
+
+describe('the change-request list refreshes the clone once, not once per request', () => {
+  it('fetches the clone once and asks for no per-request fetch', async () => {
+    const { svc, changedPathsForPr, ensureRemotesFetched } = harness();
+
+    const list = await svc.listOpenPrs({ fresh: true });
+
+    expect(list).toHaveLength(2);
+    expect(ensureRemotesFetched).toHaveBeenCalledTimes(1);
+    // FORCED on a fresh read, for the reason the read is fresh at all: the
+    // caller knows the remote just moved, and a fetch skipped by its own 30s
+    // TTL would answer about a request whose branch this clone has not seen.
+    expect(ensureRemotesFetched).toHaveBeenCalledWith('ws-main', { force: true });
+    // Two requests, two diffs — and neither of them a network round trip.
+    expect(changedPathsForPr).toHaveBeenCalledTimes(2);
+    for (const call of changedPathsForPr.mock.calls) {
+      expect(call[3]).toEqual({ fetch: false });
+    }
+  });
+
+  it('does not grow its fetch count with the number of open requests', async () => {
+    const five = [1, 2, 3, 4, 5].map((n) => row(n, `suggestions/${n}/knowledge`));
+    const { svc, ensureRemotesFetched } = harness(five);
+    expect(await svc.listOpenPrs({ fresh: true })).toHaveLength(5);
+    expect(ensureRemotesFetched).toHaveBeenCalledTimes(1);
+  });
+
+  it('touches the network not at all when there is nothing to summarise', async () => {
+    const { svc, ensureRemotesFetched, changedPathsForPr } = harness([]);
+    expect(await svc.listOpenPrs({ fresh: true })).toEqual([]);
+    expect(ensureRemotesFetched).not.toHaveBeenCalled();
+    expect(changedPathsForPr).not.toHaveBeenCalled();
+  });
+
+  it('leaves the fetch TTL alone for a background poll', async () => {
+    const { svc, ensureRemotesFetched } = harness();
+    // No `fresh`: nobody said the remote moved, so the clone is refreshed at
+    // whatever rate `ensureRemotesFetched` sees fit. (A branch the clone has
+    // never heard of is still fetched — `changedPathsForPr` does that for
+    // itself, so a poll can be a poll without hiding a request.)
+    await svc.listOpenPrs();
+    expect(ensureRemotesFetched).toHaveBeenCalledWith('ws-main', { force: false });
+  });
+
+  it('still answers when the refresh itself fails — the refs are then as old as the last one', async () => {
+    const { svc, changedPathsForPr, ensureRemotesFetched } = harness();
+    ensureRemotesFetched.mockRejectedValue(new Error('origin unreachable'));
+    // Degrades exactly as the per-request fetch did (it was `.catch(() => undefined)`
+    // too): the local refs are used, and a request whose diff cannot be
+    // computed reports no touched paths.
+    const list = await svc.listOpenPrs({ fresh: true });
+    expect(list).toHaveLength(2);
+    expect(changedPathsForPr).toHaveBeenCalledTimes(2);
+  });
+});

package/src/modules/workflow/git/__tests__/pull-request.service.placeholder.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, vi } from 'vitest';
+
+import { PullRequestService } from '../pull-request.service.js';
+import type { Database } from '../../../database/connection.js';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import type { GitService } from '../git.service.js';
+import type { IAccessControl } from '../../../access/access-control.interface.js';
+
+const ROW = {
+  id: 'cr-9',
+  number: 9,
+  sourceBranch: 'alice/new-folders',
+  targetBranch: 'current-company-state',
+  title: 'Folders',
+  body: '',
+  authorEmail: 'alice@bevel.software',
+  authorName: 'Alice',
+  state: 'open',
+  mergedSha: null,
+  createdAt: new Date('2026-09-01T00:00:00Z'),
+  updatedAt: null,
+  closedAt: null,
+};
+
+/**
+ * The empty-folder placeholder is never content, so the change-request LIST
+ * (the summaries every "for me" view counts and routes by) leaves it out, just
+ * as the detail's file list does. The raw `changedPathsForPr` keeps it — that
+ * is the authoritative empty-request check, and is not what a list shows.
+ */
+describe('PullRequestService summaries — folder placeholder', () => {
+  function harness(paths: string[] = ['Reports/.gitkeep', 'Reports/Empty/.gitkeep', 'Reports/q3.md']) {
+    const db = {
+      select: () => ({
+        from: () => ({
+          where: () => ({
+            orderBy: async () => [ROW],
+            limit: async () => [ROW],
+          }),
+        }),
+      }),
+    } as unknown as Database;
+    const changedPathsForPr = vi.fn(async () => paths);
+    const git = { changedPathsForPr } as unknown as GitService;
+    const workspace = {
+      findAnyWorkspaceId: async () => 'ws-main',
+      ensureRemotesFetched: async () => undefined,
+    } as unknown as WorkspaceService;
+    // Bob may write under `Reports/` and nowhere else.
+    const canWriteBatchAtRef = vi.fn(async (_ws: string, _ref: string, _email: string, asked: string[]) =>
+      new Map(asked.map((p) => [p, p.startsWith('Reports/')])),
+    );
+    const access = { canWriteBatchAtRef } as unknown as IAccessControl;
+    const svc = new PullRequestService(db, workspace, access, git);
+    return { svc, changedPathsForPr, canWriteBatchAtRef };
+  }
+
+  it('listOpenPrs reports only real files as touched paths', async () => {
+    const { svc, changedPathsForPr } = harness();
+    const [summary] = await svc.listOpenPrs({ fresh: true });
+    expect(changedPathsForPr).toHaveBeenCalledTimes(1);
+    expect(summary.touchedNodePaths).toEqual(['Reports/q3.md']);
+  });
+
+  it('a request that only creates a folder still routes to the folder\'s owners', async () => {
+    const { svc, canWriteBatchAtRef } = harness(['Reports/Empty/.gitkeep']);
+    const [routed] = await svc.listPrsForOwnerEmail('ws-main', 'bob@bevel.software', { fresh: true });
+    expect(routed?.number).toBe(9);
+    // Routed by the placeholder, but never showing it.
+    expect(routed.touchedNodePaths).toEqual([]);
+    // Access was asked about the placeholder, however the lookup is batched.
+    expect(canWriteBatchAtRef.mock.calls.some((c) => c[3].includes('Reports/Empty/.gitkeep'))).toBe(true);
+  });
+
+  it('a folder-only request outside the viewer\'s scope does not route to them', async () => {
+    const { svc } = harness(['Elsewhere/.gitkeep']);
+    expect(await svc.listPrsForOwnerEmail('ws-main', 'bob@bevel.software', { fresh: true })).toEqual([]);
+  });
+});

package/src/modules/workflow/git/__tests__/pull-request.service.test.ts

@@ -5,7 +5,7 @@ import type { GitService } from '../git.service.js';
 import type { Database } from '../../../database/connection.js';
 import type { WorkspaceService } from '../../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../../access/access-control.interface.js';
-import { hashEmail as hash } from '../../../../shared/hash-email.js';
+import { hashEmail as hash } from '../../../../shared/email-identity.js';
 
 function pr(overrides: Partial<PullRequestSummary>): PullRequestSummary {
   return {

package/src/modules/workflow/git/__tests__/pull-request.service.viewer-can-cancel.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { computeViewerCanCancel } from '../pull-request.service.js';
-import { hashEmail } from '../../../../shared/hash-email.js';
+import { hashEmail } from '../../../../shared/email-identity.js';
 
 const EMAIL = 'juan@bevel.software';
 const AUTHOR_HASH = hashEmail(EMAIL);

package/src/modules/workflow/git/__tests__/pull-request.service.viewer-can-update.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest';
+import type { FileApprovalState } from '@bevel-software/platform-shared';
+import { computeViewerCanUpdate } from '../pull-request.service.js';
+import { hashEmail } from '../../../../shared/email-identity.js';
+
+/**
+ * Bringing a request up to date (merging its target into its branch) belongs
+ * to the request's author and to anyone who may apply it — these three are
+ * the viewers whose OPEN of the dialog runs the update by itself. Everyone
+ * else is told in plain words who can do it, and the route refuses them the
+ * same way.
+ */
+
+const EMAIL = 'juan@bevel.software';
+const AUTHOR = hashEmail(EMAIL);
+const SOMEONE_ELSE = hashEmail('someone-else@bevel.software');
+
+const file = (
+  isApproved: boolean,
+  viewerCanApprove: boolean,
+  path = 'Sales/Deal.md',
+  owned = true,
+  eligibilityResolved = true,
+) =>
+  ({
+    path,
+    isApproved,
+    viewerCanApprove,
+    eligibilityResolved,
+    eligibleApprovers: { roles: owned ? ['Sales'] : [], users: [] },
+    approvedBy: [],
+    // The server's own stamp: an owned Markdown or access-config file binds
+    // the gate, nothing else does — and an unresolved tree owns nothing.
+    inMergeGate:
+      owned && eligibilityResolved && (/\.md$/i.test(path) || path === 'roles.yaml'),
+  }) as FileApprovalState;
+
+const base = {
+  state: 'open' as const,
+  authorId: SOMEONE_ELSE,
+  viewerEmail: EMAIL,
+  viewerCanBypassMerge: false,
+  approvals: [file(false, false)],
+};
+
+describe('computeViewerCanUpdate', () => {
+  it('the author may update', () => {
+    expect(computeViewerCanUpdate({ ...base, authorId: AUTHOR })).toBe(true);
+  });
+
+  it('a viewer who may apply (every file approved or approvable by them) may update', () => {
+    expect(
+      computeViewerCanUpdate({ ...base, approvals: [file(true, false), file(false, true)] }),
+    ).toBe(true);
+  });
+
+  it('files outside the approval gate withhold nothing — they need no approval to apply', () => {
+    // A non-Markdown file and an ownerless note: the merge gate lets anyone
+    // apply these, so anyone may update them too.
+    expect(
+      computeViewerCanUpdate({
+        ...base,
+        approvals: [file(false, false, 'Sales/deal.yaml'), file(false, false, 'Notes/Loose.md', false)],
+      }),
+    ).toBe(true);
+    // One gate-bound file the viewer cannot approve still refuses.
+    expect(
+      computeViewerCanUpdate({ ...base, approvals: [file(false, false, 'Sales/deal.yaml'), file(false, false)] }),
+    ).toBe(false);
+    // roles.yaml is bound by the gate even though it is not Markdown.
+    expect(computeViewerCanUpdate({ ...base, approvals: [file(false, false, 'roles.yaml')] })).toBe(false);
+  });
+
+  it('an unresolved access tree fails closed — empty approvers are unknown, not outside the gate', () => {
+    // No workspace or a failed lookup: every file comes back with no eligible
+    // approvers, which must not read as "nobody needs to approve".
+    expect(
+      computeViewerCanUpdate({
+        ...base,
+        approvals: [file(false, false, 'Sales/deal.yaml', false, false), file(false, false, 'Notes/Loose.md', false, false)],
+      }),
+    ).toBe(false);
+    // A detail built without the flag at all is treated the same way.
+    const legacy = { ...file(false, false, 'Notes/Loose.md', false) } as Partial<FileApprovalState>;
+    delete legacy.eligibilityResolved;
+    expect(computeViewerCanUpdate({ ...base, approvals: [legacy as FileApprovalState] })).toBe(false);
+    // The author and an admin are unaffected.
+    expect(
+      computeViewerCanUpdate({ ...base, authorId: AUTHOR, approvals: [file(false, false, 'Notes/Loose.md', false, false)] }),
+    ).toBe(true);
+  });
+
+  it('an admin, who may apply over missing approvals, may update', () => {
+    expect(computeViewerCanUpdate({ ...base, viewerCanBypassMerge: true })).toBe(true);
+  });
+
+  it('anyone else may not — one file they cannot approve is enough to refuse', () => {
+    expect(computeViewerCanUpdate(base)).toBe(false);
+    expect(
+      computeViewerCanUpdate({ ...base, approvals: [file(false, true), file(false, false)] }),
+    ).toBe(false);
+    // No files to judge by is not a grant.
+    expect(computeViewerCanUpdate({ ...base, approvals: [] })).toBe(false);
+  });
+
+  it('fails closed with no viewer, and for a request that is not open', () => {
+    expect(computeViewerCanUpdate({ ...base, authorId: AUTHOR, viewerEmail: undefined })).toBe(false);
+    expect(computeViewerCanUpdate({ ...base, authorId: AUTHOR, state: 'merged' })).toBe(false);
+    expect(computeViewerCanUpdate({ ...base, authorId: AUTHOR, state: 'closed' })).toBe(false);
+  });
+});

package/src/modules/workflow/git/change-request-link.ts

@@ -0,0 +1,35 @@
+/** Shown beside a relative change-request `url` so a caller knows how to get an absolute one. */
+export const CHANGE_REQUEST_URL_NOTE = 'Set PUBLIC_FRONTEND_URL to get absolute links.';
+
+/**
+ * The base a change-request link is built on: the configured public frontend
+ * address reduced to origin + path prefix. Credentials, query and fragment are
+ * dropped so nothing but the public location can reach the link. Null when no
+ * address is configured or it does not parse as http(s).
+ */
+export function changeRequestLinkBase(configured: string | null | undefined): string | null {
+  const raw = configured?.trim();
+  if (!raw) return null;
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') return null;
+  return `${parsed.origin}${parsed.pathname.replace(/\/+$/, '')}`;
+}
+
+/**
+ * The link a person can open for change request `number`: absolute under
+ * `base` (a proxied deployment's path prefix included), else the in-app
+ * relative path plus a note on how to make it absolute. Only the number goes
+ * into the path — never a branch name.
+ */
+export function changeRequestLink(
+  number: number,
+  base: string | null,
+): { url: string; urlNote?: string } {
+  const path = `/change-requests/${number}`;
+  return base ? { url: `${base}${path}` } : { url: path, urlNote: CHANGE_REQUEST_URL_NOTE };
+}

package/src/modules/workflow/git/git-version.ts

@@ -16,6 +16,9 @@
  */
 
 import { execFile } from 'node:child_process';
+import { logger } from '../../../shared/logging.js';
+
+const log = logger('git');
 import { promisify } from 'node:util';
 
 const execFileAsync = promisify(execFile);
@@ -40,8 +43,8 @@ export function assertSupportedGitVersion(stdout: string): void {
   const found = parseGitVersion(stdout);
   const [minMajor, minMinor] = MIN_GIT_VERSION;
   if (!found) {
-    console.warn(
-      `[git] could not read a version from "${stdout.trim()}" — ` +
+    log.warn(
+      `could not read a version from "${stdout.trim()}" — ` +
         `skipping the git ${minMajor}.${minMinor}+ check`,
     );
     return;