@bevel-software/platform-core-backend 0.1.0

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

@@ -0,0 +1,225 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { PullRequestSummary } from '@bevel-software/platform-shared';
+import { PullRequestService } from '../pull-request.service.js';
+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';
+
+function pr(overrides: Partial<PullRequestSummary>): PullRequestSummary {
+  return {
+    number: 1,
+    title: 'PR',
+    author: { login: 'bot' },
+    branch: 'feature/x',
+    base: 'current-company-state',
+    state: 'open',
+    createdAt: '2026-04-01T00:00:00Z',
+    touchedNodePaths: [],
+    review: { approvals: 0, changesRequested: 0, pendingLogins: [] },
+    url: 'https://github.com/acme/repo/pull/1',
+    ...overrides,
+  };
+}
+
+/**
+ * (ref, path) → set of emails that have write access at that point in the
+ * access tree. Drives the `canWriteBatchAtRef` stub.
+ */
+type WritersByRefAndPath = Record<string, Record<string, string[]>>;
+
+function makeAccessControl(byRef: WritersByRefAndPath): IAccessControl {
+  return {
+    canWrite: async () => false,
+    canWriteBatch: async () => new Map(),
+    canRead: async () => true,
+    canReadBatch: async () => new Map(),
+    eligibleReaders: async () => ({ restricted: false, roles: [], users: [] }),
+    canReadAtRef: async () => null,
+    canDownload: async () => false,
+    canOwner: async () => false,
+    eligibleOwners: async () => ({ roles: [], users: [] }),
+    eligibleDownloaders: async () => ({ roles: [], users: [] }),
+    eligibleWriters: async () => ({ roles: [], users: [] }),
+    eligibleWriterEmails: async () => new Map(),
+    eligibleOwnerEmails: async () => new Map(),
+    grantSources: async () => ({}),
+    invalidate: () => {},
+    canWriteAtRef: async () => null,
+    canWriteBatchAtRef: async (_ws, ref, userEmail, paths) => {
+      const result = new Map<string, boolean>();
+      const refMap = byRef[ref];
+      if (!refMap) {
+        for (const p of paths) result.set(p, false);
+        return result;
+      }
+      const normalized = userEmail.trim().toLowerCase();
+      for (const p of paths) {
+        const writers = refMap[p] ?? [];
+        result.set(p, writers.map((e) => e.toLowerCase()).includes(normalized));
+      }
+      return result;
+    },
+    eligibleWritersAtRef: async () => null,
+    eligibleWritersForPathsAtRef: async () => null,
+    findEmailByHash: async () => null,
+    kbPrincipals: async () => ({ groups: [], people: [] }),
+    validateRolesYaml: () => ({ ok: true }),
+    referencesToRole: async () => [],
+  };
+}
+
+function makeService(
+  prs: PullRequestSummary[],
+  writers: WritersByRefAndPath,
+): { svc: PullRequestService; fetchSpy: ReturnType<typeof vi.fn> } {
+  const fetchSpy = vi.fn(async () => undefined);
+  const workspace = {
+    ensureRemotesFetched: fetchSpy,
+    findAnyWorkspaceId: async () => 'ws',
+  } as unknown as WorkspaceService;
+  // listOpenPrs is mocked below, so the DB + git deps are never exercised
+  // through that path. `listPrsForOwnerEmail` (the unit under test) reads
+  // pre-built summaries straight from the mock.
+  const svc = new PullRequestService(
+    {} as unknown as Database,
+    workspace,
+    makeAccessControl(writers),
+    {} as unknown as GitService,
+  );
+  vi.spyOn(svc, 'listOpenPrs').mockResolvedValue(prs);
+  return { svc, fetchSpy };
+}
+
+describe('PullRequestService.listPrsForOwnerEmail', () => {
+  const USER = 'juan@bevel.software';
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns empty for a blank email without touching git', async () => {
+    const { svc, fetchSpy } = makeService([pr({ number: 1 })], {});
+    expect(await svc.listPrsForOwnerEmail('ws', '   ')).toEqual([]);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it('includes PRs the user authored even when they have no write access on the touched files', async () => {
+    const { svc } = makeService(
+      [
+        pr({
+          number: 1,
+          authorId: hash(USER),
+          branch: 'feature/mine',
+          touchedNodePaths: ['Knowledge/Foo.md'],
+        }),
+      ],
+      {},
+    );
+
+    const out = await svc.listPrsForOwnerEmail('ws', USER);
+    expect(out.map((p) => p.number)).toEqual([1]);
+  });
+
+  it('matches when the PR head broadens access to include the user (base does not)', async () => {
+    const { svc } = makeService(
+      [
+        pr({
+          number: 23,
+          branch: 'razvan/sme-basket-filter',
+          base: 'current-company-state',
+          touchedNodePaths: ['Knowledge/Processes/Basket.md'],
+        }),
+      ],
+      {
+        'razvan/sme-basket-filter': {
+          'Knowledge/Processes/Basket.md': [USER],
+        },
+        // Base grants no one — empty map.
+      },
+    );
+
+    const out = await svc.listPrsForOwnerEmail('ws', USER);
+    expect(out.map((p) => p.number)).toEqual([23]);
+  });
+
+  it('matches when the base branch grants the user write (the PR head removes it)', async () => {
+    const { svc } = makeService(
+      [
+        pr({
+          number: 42,
+          branch: 'feature/remove-access',
+          touchedNodePaths: ['Knowledge/Foo.md'],
+        }),
+      ],
+      {
+        'current-company-state': {
+          'Knowledge/Foo.md': [USER],
+        },
+        // Head removed them — no entry.
+      },
+    );
+
+    const out = await svc.listPrsForOwnerEmail('ws', USER);
+    expect(out.map((p) => p.number)).toEqual([42]);
+  });
+
+  it('excludes PRs where neither head nor base grants the user write', async () => {
+    const { svc } = makeService(
+      [
+        pr({
+          number: 99,
+          branch: 'feature/other',
+          touchedNodePaths: ['Knowledge/Foo.md'],
+        }),
+      ],
+      {
+        'feature/other': { 'Knowledge/Foo.md': ['ali@bevel.software'] },
+        'current-company-state': { 'Knowledge/Foo.md': ['ali@bevel.software'] },
+      },
+    );
+
+    const out = await svc.listPrsForOwnerEmail('ws', USER);
+    expect(out).toEqual([]);
+  });
+
+  it('is case- and whitespace-insensitive on the user email', async () => {
+    const { svc } = makeService(
+      [
+        pr({
+          number: 1,
+          touchedNodePaths: ['Knowledge/Foo.md'],
+        }),
+      ],
+      {
+        'current-company-state': {
+          'Knowledge/Foo.md': ['JUAN@Bevel.Software'],
+        },
+      },
+    );
+
+    const out = await svc.listPrsForOwnerEmail('ws', '  juan@bevel.software  ');
+    expect(out.map((p) => p.number)).toEqual([1]);
+  });
+
+  it('fetches remote refs once before resolving access, even across many PRs', async () => {
+    const { svc, fetchSpy } = makeService(
+      [
+        pr({ number: 1, branch: 'a', touchedNodePaths: ['Knowledge/Foo.md'] }),
+        pr({ number: 2, branch: 'b', touchedNodePaths: ['Knowledge/Bar.md'] }),
+      ],
+      {},
+    );
+
+    await svc.listPrsForOwnerEmail('ws', USER);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('skips access resolution when no PRs are returned', async () => {
+    const { svc, fetchSpy } = makeService([], {});
+    const out = await svc.listPrsForOwnerEmail('ws', USER);
+    expect(out).toEqual([]);
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest';
+import { computeViewerCanCancel } from '../pull-request.service.js';
+import { hashEmail } from '../../../../shared/hash-email.js';
+
+const EMAIL = 'juan@bevel.software';
+const AUTHOR_HASH = hashEmail(EMAIL);
+const OTHER_AUTHOR_HASH = hashEmail('someone-else@bevel.software');
+
+describe('computeViewerCanCancel', () => {
+  it('returns false when viewerEmail is missing (anonymous detail fetch)', () => {
+    expect(
+      computeViewerCanCancel({
+        state: 'open',
+        authorId: AUTHOR_HASH,
+        viewerEmail: undefined,
+        viewerCanBypassMerge: false,
+      }),
+    ).toBe(false);
+  });
+
+  it('returns true when state is open and the viewer is the author', () => {
+    expect(
+      computeViewerCanCancel({
+        state: 'open',
+        authorId: AUTHOR_HASH,
+        viewerEmail: EMAIL,
+        viewerCanBypassMerge: false,
+      }),
+    ).toBe(true);
+  });
+
+  it('returns true when state is open and the viewer is an admin (bypass=true)', () => {
+    expect(
+      computeViewerCanCancel({
+        state: 'open',
+        authorId: OTHER_AUTHOR_HASH,
+        viewerEmail: EMAIL,
+        viewerCanBypassMerge: true,
+      }),
+    ).toBe(true);
+  });
+
+  it('returns true when viewer is both author AND admin', () => {
+    expect(
+      computeViewerCanCancel({
+        state: 'open',
+        authorId: AUTHOR_HASH,
+        viewerEmail: EMAIL,
+        viewerCanBypassMerge: true,
+      }),
+    ).toBe(true);
+  });
+
+  it('returns false when state is closed even for the author', () => {
+    expect(
+      computeViewerCanCancel({
+        state: 'closed',
+        authorId: AUTHOR_HASH,
+        viewerEmail: EMAIL,
+        viewerCanBypassMerge: false,
+      }),
+    ).toBe(false);
+  });
+
+  it('returns false when state is merged even for an admin', () => {
+    expect(
+      computeViewerCanCancel({
+        state: 'merged',
+        authorId: OTHER_AUTHOR_HASH,
+        viewerEmail: EMAIL,
+        viewerCanBypassMerge: true,
+      }),
+    ).toBe(false);
+  });
+
+  it('returns false when authorId is absent and the viewer is not an admin (PRs opened outside bevel)', () => {
+    expect(
+      computeViewerCanCancel({
+        state: 'open',
+        authorId: undefined,
+        viewerEmail: EMAIL,
+        viewerCanBypassMerge: false,
+      }),
+    ).toBe(false);
+  });
+
+  it('normalizes the viewer email exactly the same way hashEmail does (trim + lowercase)', () => {
+    // hashEmail trims + lowercases internally; the predicate must hash the
+    // raw viewerEmail it gets and rely on hashEmail's normalization. A
+    // regression where the predicate pre-normalizes or skips normalization
+    // would break attribution for any caller that doesn't already normalize.
+    expect(
+      computeViewerCanCancel({
+        state: 'open',
+        authorId: AUTHOR_HASH,
+        viewerEmail: '  Juan@Bevel.Software  ',
+        viewerCanBypassMerge: false,
+      }),
+    ).toBe(true);
+  });
+});

package/src/modules/workflow/git/branch-name.ts

@@ -0,0 +1,70 @@
+import { BranchNameError, WorkflowValidationError } from '../workflow.errors.js';
+
+// Single source of truth for the protected-branch list lives in `@bevel-software/platform-shared` so
+// the backend guard and the frontend banner/disabling logic can't drift apart.
+export { PROTECTED_BRANCHES, isProtectedBranch } from '@bevel-software/platform-shared';
+// Authorship inference lives in `@bevel-software/platform-shared` for the same reason — the
+// picker's `canDelete` rule and the backend authorisation check on
+// `deleteBranch` must agree on every edge case (uppercase email, dotted
+// localpart, etc.).
+export { branchAuthorLocalpart, isBranchAuthoredBy } from '@bevel-software/platform-shared';
+
+const VALID_BRANCH_REGEX = /^[A-Za-z0-9][A-Za-z0-9/_\-.]*$/;
+
+/** Throw if `name` cannot safely be passed to `git` as a branch name. */
+export function assertValidBranchName(name: string): void {
+  if (!name) throw new BranchNameError('empty name', name);
+  if (name.length > 255) throw new BranchNameError('too long', name);
+  if (!VALID_BRANCH_REGEX.test(name)) {
+    throw new BranchNameError('contains invalid characters', name);
+  }
+  if (name.includes('..')) throw new BranchNameError('contains ".."', name);
+  if (name.includes('//')) throw new BranchNameError('contains "//"', name);
+  if (name.endsWith('/') || name.endsWith('.')) {
+    throw new BranchNameError('ends with "/" or "."', name);
+  }
+  if (name.startsWith('-')) throw new BranchNameError('starts with "-"', name);
+  if (name.includes('@{')) throw new BranchNameError('contains "@{"', name);
+  // Per-segment rules: git forbids any `/`-separated segment from beginning
+  // with "." or ending with ".lock" (e.g. `foo/.tmp`, `foo.lock/bar`).
+  // The whole-name checks above can't catch nested violations.
+  for (const segment of name.split('/')) {
+    if (segment.startsWith('.')) {
+      throw new BranchNameError('segment starts with "."', name);
+    }
+    if (segment.endsWith('.lock')) {
+      throw new BranchNameError('segment ends with ".lock"', name);
+    }
+  }
+}
+
+/**
+ * Guard against path traversal and shell-unsafe characters on any workspace-relative
+ * path we pass to `git` as a pathspec. Must stay within the repo; forward slashes only.
+ */
+export function assertValidRelativePath(relativePath: string): void {
+  if (!relativePath) throw new WorkflowValidationError('path is required');
+  if (relativePath.length > 1024) throw new WorkflowValidationError('path too long');
+  if (relativePath.includes('\0')) throw new WorkflowValidationError('path contains NUL');
+  if (relativePath.includes('\\')) {
+    throw new WorkflowValidationError('path must use forward slashes only');
+  }
+  if (relativePath.startsWith('/') || /^[A-Za-z]:/.test(relativePath)) {
+    throw new WorkflowValidationError('path must be relative');
+  }
+  const parts = relativePath.split('/');
+  if (parts.some((p) => p === '..' || p === '.')) {
+    throw new WorkflowValidationError('path must not contain "." or ".."');
+  }
+  if (relativePath.startsWith('-')) {
+    throw new WorkflowValidationError('path must not start with "-"');
+  }
+  // Pathspec glob characters (`*`, `?`, `[`, `]`, `!`) and pathspec magic (`:(…)`)
+  // would otherwise be interpreted by `git add -- <path>` / `git log -- <path>`
+  // and match the wrong files. `GitService.git()` sets `GIT_LITERAL_PATHSPECS=1`
+  // on every git subprocess, which forces literal interpretation across the
+  // board — so KB filenames containing `[Approved]`, `[New]`, etc. round-trip
+  // through commit cleanly. The shared `validateFilename` already rejects `:`
+  // along with the rest of Windows-forbidden characters before paths reach this
+  // layer, so a redundant check here would only confuse the error message.
+}

package/src/modules/workflow/git/clone-config.ts

@@ -0,0 +1,71 @@
+/**
+ * The git configuration a per-branch workspace clone must have for its branch
+ * to track exactly ONE upstream ref.
+ *
+ * Why this exists: a clone's config is append-only from git's point of view,
+ * and several things write to it:
+ *
+ *   - `git config --add branch.<name>.merge …` / `git branch --set-upstream-to`
+ *     run out of band (an agent shell session in the workspace, a manual fix)
+ *     leaves a SECOND `branch.<name>.merge` value;
+ *   - `git remote set-branches --add origin …`, a re-run `git remote add`, or a
+ *     hand-edited `.git/config` leaves a SECOND `remote.origin.fetch` refspec,
+ *     so one fetch maps the same remote branch in twice.
+ *
+ * A multi-valued `branch.<name>.merge` is what makes a BARE `git fetch origin`
+ * write more than one *for-merge* entry into the clone's shared
+ * `.git/FETCH_HEAD` — git adds one per configured merge ref. That is the
+ * ammunition behind the reported failure: `git pull` reads its rebase target
+ * out of that same shared file, so when one of the app's unmutexed bare
+ * fetches lands inside the pull's fetch→read window, the pull sees two merge
+ * heads and dies with `fatal: Cannot rebase onto multiple branches.`
+ *
+ * The drift alone is NOT sufficient — an explicit `git pull --rebase origin
+ * <branch>` survives every drift shape on its own (verified across the shapes
+ * above on git 2.39.5); it takes the concurrent fetch too. `GitService.pull`
+ * closes the other half by never reading or writing FETCH_HEAD; normalising
+ * the config here removes the ammunition.
+ *
+ * These are the three keys that pin the clone back to "this branch tracks
+ * `origin/<branch>`, nothing else"; applied with `--replace-all` they collapse
+ * any accumulated duplicates into one value.
+ *
+ * Lives here — next to `assertValidBranchName` — as a leaf-level primitive
+ * shared by the git layer (self-heal before every pull) and `WorkspaceService`
+ * (stamped on new clones, and re-stamped on existing ones the first time this
+ * process opens them, which is the migration for clones already on disk).
+ */
+
+/** The single fetch refspec a workspace clone of the KB is created with. */
+export const ORIGIN_FETCH_REFSPEC = '+refs/heads/*:refs/remotes/origin/*';
+
+/**
+ * The one safe shape for an implicit background fetch of a workspace clone —
+ * shared by `GitService.fetchOriginIfStale` and
+ * `WorkspaceService.ensureRemotesFetched`, both of which run OUTSIDE the
+ * workspace mutex. `--no-write-fetch-head` is what makes that safe: without it
+ * a bare fetch rewrites the clone's shared `.git/FETCH_HEAD` underneath
+ * whatever else is running in it, which is how the post-merge `git pull` read
+ * two merge heads and died with "Cannot rebase onto multiple branches" (see
+ * the header comment above and `GitService.pull`). These paths only want the
+ * remote-tracking refs refreshed; `--prune` keeps deleted remote branches from
+ * lingering. Callers prepend their own runner context (`-C <dir>` /
+ * `-c http.*` options) but must not vary these arguments.
+ */
+export const SAFE_IMPLICIT_FETCH_ARGS: readonly string[] = [
+  'fetch', '--prune', '--no-write-fetch-head', 'origin',
+];
+
+/**
+ * `git` argument lists that normalise a clone's tracking config for `branch`.
+ * Returns the arguments rather than running them so each caller can use its own
+ * git runner (the git service's mutex-aware wrapper, `git -C` from the
+ * workspace service) — no process is spawned here.
+ */
+export function cloneTrackingConfigArgs(branch: string): string[][] {
+  return [
+    ['config', '--replace-all', 'remote.origin.fetch', ORIGIN_FETCH_REFSPEC],
+    ['config', '--replace-all', `branch.${branch}.remote`, 'origin'],
+    ['config', '--replace-all', `branch.${branch}.merge`, `refs/heads/${branch}`],
+  ];
+}

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

@@ -0,0 +1,70 @@
+/**
+ * The `git` floor this app depends on.
+ *
+ * Every fetch the workspace layer runs passes `--no-write-fetch-head` — the
+ * option that keeps one clone's fetches from steering a concurrent refresh
+ * through the shared `.git/FETCH_HEAD` (see `GitService.pull`) — and git only
+ * learned it in 2.29. On an older binary every one of those fetches dies with
+ * `unknown option`, which takes out `pull`, `resetToRemote` and
+ * `mergeChangeRequest` at once.
+ *
+ * The production image installs git from Debian via `node:22-slim`, which is
+ * well past the floor, so this guard is about a re-based or swapped runtime
+ * image rather than a live problem. Its value is *when* it fires: at boot,
+ * naming the installed version, instead of at the first change-request merge
+ * with an opaque git error.
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+/** Oldest git that understands `--no-write-fetch-head`. */
+export const MIN_GIT_VERSION: readonly [number, number] = [2, 29];
+
+/** `git version 2.39.5 (Apple Git-154)` → `[2, 39]`; null if unrecognisable. */
+export function parseGitVersion(stdout: string): [number, number] | null {
+  const m = /^git version (\d+)\.(\d+)/.exec(stdout.trim());
+  return m ? [Number(m[1]), Number(m[2])] : null;
+}
+
+/**
+ * Throw when `git --version` output names a version below the floor.
+ *
+ * An output we can't parse is NOT fatal: a git build with an unusual version
+ * string is far more likely than one older than 2.29, and refusing to boot over
+ * an unrecognised string would be a worse failure than the one being guarded.
+ */
+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()}" — ` +
+        `skipping the git ${minMajor}.${minMinor}+ check`,
+    );
+    return;
+  }
+  const [major, minor] = found;
+  if (major > minMajor || (major === minMajor && minor >= minMinor)) return;
+  throw new Error(
+    `git ${minMajor}.${minMinor} or newer is required, found ${major}.${minor}. ` +
+      'Every workspace fetch passes --no-write-fetch-head, which older git rejects, ' +
+      'so branch refresh and change-request merges cannot work on this runtime.',
+  );
+}
+
+/**
+ * Run `git --version` and apply the floor. Call once during startup, before
+ * anything clones or fetches.
+ */
+export async function assertGitVersion(): Promise<void> {
+  let stdout: string;
+  try {
+    ({ stdout } = await execFileAsync('git', ['--version']));
+  } catch (err) {
+    throw new Error(`git is required but could not be run: ${String(err)}`);
+  }
+  assertSupportedGitVersion(stdout);
+}