@bevel-software/platform-core-backend 0.1.0

package/src/modules/workflow/file-lock.service.ts

@@ -0,0 +1,269 @@
+/**
+ * Per-(workspace, branch, path) edit lock store. The spec calls for
+ * file-scoped locks acquired on first edit and released either explicitly
+ * (with an autosave commit) or implicitly by TTL expiry — preventing a
+ * disconnected client from holding a file hostage.
+ *
+ * Lock state lives in Postgres because workspaces share state across
+ * backend instances eventually. The hot read path (does someone hold this
+ * lock?) is one indexed lookup; the hot write path (heartbeat) is a single
+ * row update. We don't bother caching in process memory — the lock table
+ * is the source of truth and any cache would lose its purpose the moment
+ * a different replica takes over.
+ *
+ * Stale-lock semantics: `get`, `acquire`, and `heartbeat` all treat a row
+ * with `expires_at <= now()` as if the lock didn't exist. We purge it
+ * lazily on next access rather than running a sweeper — the row count is
+ * bounded by concurrent editors, not history, so lazy GC is fine.
+ */
+
+import { and, eq, gt, lte } from 'drizzle-orm';
+import type { Database } from '../database/connection.js';
+import { fileLocks } from '../database/schema.js';
+import type { AcquireLockResult, AuthUser, FileLock } from '@bevel-software/platform-shared';
+import { WorkflowValidationError } from './workflow.errors.js';
+
+/**
+ * Lock lifetime without a heartbeat. The client is expected to heartbeat
+ * every ~half this interval so a single missed ping doesn't release the
+ * lock out from under them. Bumping the TTL trades off "how long does a
+ * crashed client hold a file" against "how forgiving are we of network
+ * blips" — 60s is a balance.
+ */
+const LOCK_TTL_MS = 60_000;
+
+function rowToFileLock(row: typeof fileLocks.$inferSelect): FileLock {
+  return {
+    branch: row.branch,
+    path: row.path,
+    holderUserId: row.holderUserId,
+    holderName: row.holderName,
+    acquiredAt: row.acquiredAt.toISOString(),
+    lastHeartbeatAt: row.lastHeartbeatAt.toISOString(),
+    expiresAt: row.expiresAt.toISOString(),
+  };
+}
+
+export class FileLockService {
+  constructor(private readonly db: Database) {}
+
+  /**
+   * Acquire a lock for `(workspaceId, branch, path)` on behalf of `user`.
+   *
+   * Three outcomes folded into the same return shape:
+   *   - No existing row: insert + return `{ acquired: true, lock }`.
+   *   - Existing row, expired: take it over (update) + `{ acquired: true }`.
+   *   - Existing row, live, different user: return `{ acquired: false }`
+   *     with the current holder's lock state so the UI can render
+   *     "Locked by X" without a follow-up call.
+   *   - Existing row, live, same user: refresh TTL + `{ acquired: true }`
+   *     so re-acquiring your own lock is idempotent.
+   */
+  async acquire(
+    workspaceId: string,
+    branch: string,
+    targetPath: string,
+    user: AuthUser,
+  ): Promise<AcquireLockResult> {
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + LOCK_TTL_MS);
+
+    // Atomic acquire-or-takeover, in a single statement. Two callers
+    // racing on the same `(workspace, branch, path)` would otherwise
+    // both SELECT no row → both INSERT (one PK-fails) or both SELECT a
+    // stale row → both UPDATE (one silently overwrites the other's
+    // takeover). PostgreSQL's INSERT ... ON CONFLICT DO UPDATE WHERE
+    // collapses both paths into one atomic statement:
+    //
+    //   - No existing row → INSERT succeeds, RETURNING our new row.
+    //   - Existing row, WHERE matches (stale OR same user) → UPDATE
+    //     fires, RETURNING the updated row.
+    //   - Existing row, WHERE doesn't match (live + different user) →
+    //     the conflict is silently absorbed (PG's documented behavior),
+    //     RETURNING is empty. We then read the live holder for the
+    //     "Locked by X" payload.
+    //
+    // **Only expired rows can be taken over.** The same-user clause used
+    // to be here as an "idempotent refresh" shortcut, but it had a nasty
+    // side effect: the AGENT and the HUMAN EDITOR share the same `user.id`
+    // (agent edits attribute to the human), so the agent's
+    // `LockingFilesystem.withLock` would silently steal a lock the human
+    // had taken via the Edit button — overwriting their in-flight edits
+    // and dropping their lock on agent-release. Removing same-user from
+    // setWhere makes acquire strict: a non-expired lock is contended even
+    // by yourself, so the agent's retry/skip path kicks in and the human
+    // keeps editing. Real refresh-while-holding goes through
+    // `heartbeat()` (which has its own same-user UPDATE), and the
+    // editor's save flow detects "I already hold it" via `getLock` in
+    // `workspace.routes.withLock` rather than re-acquiring.
+    const upsertResult = await this.db
+      .insert(fileLocks)
+      .values({
+        workspaceId,
+        branch,
+        path: targetPath,
+        holderUserId: user.id,
+        holderName: user.name,
+        acquiredAt: now,
+        lastHeartbeatAt: now,
+        expiresAt,
+      })
+      .onConflictDoUpdate({
+        target: [fileLocks.workspaceId, fileLocks.branch, fileLocks.path],
+        set: {
+          holderUserId: user.id,
+          holderName: user.name,
+          acquiredAt: now,
+          lastHeartbeatAt: now,
+          expiresAt,
+        },
+        setWhere: lte(fileLocks.expiresAt, now),
+      })
+      .returning();
+
+    if (upsertResult.length > 0) {
+      return { acquired: true, lock: rowToFileLock(upsertResult[0]) };
+    }
+
+    // Live lock held by another user. Fetch it for the "Locked by X" UI
+    // payload. We don't filter on `expiresAt > now` here because the
+    // upsert above already proved an unreclaimable row exists; the only
+    // way this read returns null is a tight race where the holder
+    // released between the upsert and this select — rare enough to
+    // surface as a retryable error rather than complicate the happy path.
+    const [holder] = await this.db
+      .select()
+      .from(fileLocks)
+      .where(
+        and(
+          eq(fileLocks.workspaceId, workspaceId),
+          eq(fileLocks.branch, branch),
+          eq(fileLocks.path, targetPath),
+        ),
+      )
+      .limit(1);
+    if (!holder) {
+      throw new WorkflowValidationError(
+        `Lock contention race on "${targetPath}" — please retry.`,
+        { kind: 'lock-contention-race', branch, path: targetPath },
+      );
+    }
+    return { acquired: false, lock: rowToFileLock(holder) };
+  }
+
+  /**
+   * Extend the lock's TTL. Refuses if the lock is held by someone else or
+   * doesn't exist — the client is then expected to re-call `acquire`,
+   * which will either succeed (taking over a stale lock) or surface the
+   * current holder.
+   */
+  async heartbeat(
+    workspaceId: string,
+    branch: string,
+    targetPath: string,
+    user: AuthUser,
+  ): Promise<FileLock> {
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + LOCK_TTL_MS);
+    // The expiry guard (`expiresAt > now`) matters because an expired
+    // lock is conceptually released, even if its row hasn't been swept
+    // and no other user has taken it yet. Without it, a client whose
+    // tab was suspended past the TTL would silently extend a lock that
+    // the rest of the system considers "free for the next acquire" —
+    // any subsequent `acquire()` by another user could already have
+    // taken it (the upsert's `lte(expiresAt, now)` predicate matches),
+    // and the heartbeat would race with that takeover. Failing here
+    // forces the client to re-acquire (which goes through the proper
+    // takeover path) and surfaces the "your session went stale" state
+    // honestly.
+    const [updated] = await this.db
+      .update(fileLocks)
+      .set({ lastHeartbeatAt: now, expiresAt })
+      .where(
+        and(
+          eq(fileLocks.workspaceId, workspaceId),
+          eq(fileLocks.branch, branch),
+          eq(fileLocks.path, targetPath),
+          eq(fileLocks.holderUserId, user.id),
+          gt(fileLocks.expiresAt, now),
+        ),
+      )
+      .returning();
+    if (!updated) {
+      throw new WorkflowValidationError(
+        `Cannot heartbeat lock on "${targetPath}": not held by you (or no longer exists).`,
+        { kind: 'lock-not-held', branch, path: targetPath },
+      );
+    }
+    return rowToFileLock(updated);
+  }
+
+  /**
+   * Idempotent release. Deletes the lock row when the caller holds it;
+   * silently no-ops otherwise (the lock may have expired and been taken
+   * over by someone else — that's not an error from the caller's POV).
+   */
+  async release(
+    workspaceId: string,
+    branch: string,
+    targetPath: string,
+    user: AuthUser,
+  ): Promise<void> {
+    await this.db
+      .delete(fileLocks)
+      .where(
+        and(
+          eq(fileLocks.workspaceId, workspaceId),
+          eq(fileLocks.branch, branch),
+          eq(fileLocks.path, targetPath),
+          eq(fileLocks.holderUserId, user.id),
+        ),
+      );
+  }
+
+  /**
+   * Read the current lock for `(workspace, branch, path)`. Returns null when
+   * no one holds it, OR when the existing row is expired — expired locks
+   * are purged here lazily.
+   */
+  async get(
+    workspaceId: string,
+    branch: string,
+    targetPath: string,
+  ): Promise<FileLock | null> {
+    const rows = await this.db
+      .select()
+      .from(fileLocks)
+      .where(
+        and(
+          eq(fileLocks.workspaceId, workspaceId),
+          eq(fileLocks.branch, branch),
+          eq(fileLocks.path, targetPath),
+        ),
+      )
+      .limit(1);
+    if (rows.length === 0) return null;
+    const row = rows[0];
+    if (row.expiresAt.getTime() <= Date.now()) {
+      // Lazy GC — drop the stale row so the next `acquire` doesn't have
+      // to bypass it. Bind the delete to this exact row's `expiresAt` so
+      // a concurrent acquire that wrote a fresh row in the gap between
+      // our SELECT and DELETE doesn't get clobbered. Primary key
+      // `(workspaceId, branch, path)` alone isn't enough — a new acquire
+      // for the same triple updates that row in place with a future
+      // expiry, and a path-only delete here would silently nuke it.
+      await this.db
+        .delete(fileLocks)
+        .where(
+          and(
+            eq(fileLocks.workspaceId, workspaceId),
+            eq(fileLocks.branch, branch),
+            eq(fileLocks.path, targetPath),
+            eq(fileLocks.expiresAt, row.expiresAt),
+          ),
+        );
+      return null;
+    }
+    return rowToFileLock(row);
+  }
+}

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

@@ -0,0 +1,86 @@
+import { describe, it, expect } from 'vitest';
+import {
+  assertValidBranchName,
+  assertValidRelativePath,
+  isProtectedBranch,
+} from '../branch-name.js';
+import { BranchNameError, WorkflowValidationError } from '../../workflow.errors.js';
+
+describe('assertValidBranchName', () => {
+  it.each([
+    'ali-raza/add-owner',
+    'feature/x',
+    'fix_123',
+    'v1.2.3',
+    'main',
+    'release-2026.04',
+  ])('accepts %s', (name) => {
+    expect(() => assertValidBranchName(name)).not.toThrow();
+  });
+
+  it.each([
+    ['empty', ''],
+    ['leading dash', '-dangerous'],
+    ['semicolon', 'foo;rm -rf /'],
+    ['backtick', 'foo`whoami`'],
+    ['space', 'foo bar'],
+    ['double dot', 'foo..bar'],
+    ['trailing slash', 'foo/'],
+    ['trailing dot', 'foo.'],
+    ['trailing .lock', 'foo.lock'],
+    ['double slash', 'foo//bar'],
+    ['ref expansion', 'HEAD@{0}'],
+    ['null byte', 'foo\x00bar'],
+    ['newline', 'foo\nbar'],
+    ['path traversal', '../../etc/passwd'],
+  ])('rejects %s (%s)', (_label, name) => {
+    expect(() => assertValidBranchName(name)).toThrow(BranchNameError);
+  });
+});
+
+describe('assertValidRelativePath', () => {
+  it.each([
+    'Knowledge/Foo.md',
+    'NodeTypes/Process.md',
+    'scripts/generate-mermaid.js',
+    'a/b/c/d.md',
+    'file-with-dash.md',
+    // Pathspec glob characters used to be rejected here, but `GitService.git()`
+    // now sets `GIT_LITERAL_PATHSPECS=1` on every git subprocess, so KB files
+    // arriving with bracketed prefixes (`[Approved]`, `[New]`, `[Updated …]`)
+    // or other glob metacharacters round-trip through commit cleanly.
+    '[Approved] Purchasing_Order archive.docx',
+    'Purchasing/[New] Purchasing_E-Invoicing DE.docx',
+    'Purchasing/[Updated 03.09.2025] Purchasing_How to search_Product detail page.docx',
+    'docs/wildcard*name.md',
+    'docs/question?name.md',
+    'docs/bang!name.md',
+  ])('accepts %s', (p) => {
+    expect(() => assertValidRelativePath(p)).not.toThrow();
+  });
+
+  it.each([
+    ['empty', ''],
+    ['absolute unix', '/etc/passwd'],
+    ['windows drive', 'C:/Users/a'],
+    ['parent segment', '../etc/passwd'],
+    ['nested parent', 'a/../b'],
+    ['current segment', 'a/./b'],
+    ['null byte', 'a\x00b'],
+    ['leading dash', '-afile'],
+  ])('rejects %s (%s)', (_label, p) => {
+    expect(() => assertValidRelativePath(p)).toThrow(WorkflowValidationError);
+  });
+});
+
+describe('isProtectedBranch', () => {
+  it('protects current-company-state and target-company-state', () => {
+    expect(isProtectedBranch('current-company-state')).toBe(true);
+    expect(isProtectedBranch('target-company-state')).toBe(true);
+  });
+  it('does not protect user branches', () => {
+    expect(isProtectedBranch('ali-raza/add-owner')).toBe(false);
+    expect(isProtectedBranch('main')).toBe(false);
+    expect(isProtectedBranch('develop')).toBe(false);
+  });
+});

package/src/modules/workflow/git/__tests__/branchAuthor.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest';
+import {
+  branchAuthorLocalpart,
+  isBranchAuthoredBy,
+} from '@bevel-software/platform-shared';
+
+describe('branchAuthorLocalpart', () => {
+  it('extracts and lowercases the localpart', () => {
+    expect(branchAuthorLocalpart('Alice@example.com')).toBe('alice');
+  });
+
+  it('sanitizes dotted localparts to match slugifyDraftName', () => {
+    // The frontend slugifies "john.doe" → "john-doe" when creating drafts,
+    // so authorship has to recognise the same shape on lookup.
+    expect(branchAuthorLocalpart('john.doe@example.com')).toBe('john-doe');
+  });
+
+  it('sanitizes plus-addressed localparts the same way', () => {
+    expect(branchAuthorLocalpart('alice+test@example.com')).toBe('alice-test');
+  });
+
+  it('returns null for empty / missing email', () => {
+    expect(branchAuthorLocalpart('')).toBeNull();
+    expect(branchAuthorLocalpart(null)).toBeNull();
+    expect(branchAuthorLocalpart(undefined)).toBeNull();
+  });
+
+  it('returns null when the localpart sanitizes to nothing (no auth identity)', () => {
+    // Email with only non-alphanumeric chars before @ — refuse to derive an
+    // identity rather than silently mapping to a default like "user", which
+    // would let any malformed-email user delete any "user/..." branch.
+    expect(branchAuthorLocalpart('___@example.com')).toBeNull();
+  });
+
+  it('handles emails with no @ by treating the whole string as localpart', () => {
+    // Internal identity systems occasionally use bare usernames; sanitizing
+    // them through the same pipeline keeps the comparison consistent.
+    expect(branchAuthorLocalpart('alice')).toBe('alice');
+  });
+});
+
+describe('isBranchAuthoredBy', () => {
+  it('matches when the branch name starts with <localpart>/', () => {
+    expect(isBranchAuthoredBy('alice/my-draft', 'alice@example.com')).toBe(true);
+  });
+
+  it('rejects when prefix is a different user', () => {
+    expect(isBranchAuthoredBy('bob/my-draft', 'alice@example.com')).toBe(false);
+  });
+
+  it('rejects when the branch has no slash (no recognisable prefix)', () => {
+    expect(isBranchAuthoredBy('alice', 'alice@example.com')).toBe(false);
+  });
+
+  it('rejects conventional non-author prefixes (fix/, polish/)', () => {
+    // `fix/...` is a common CLI-created prefix in this repo. It has no author
+    // claim, so the authored-by check must NOT grant ownership to anyone.
+    expect(isBranchAuthoredBy('fix/some-bug', 'alice@example.com')).toBe(false);
+    expect(isBranchAuthoredBy('polish/foo', 'alice@example.com')).toBe(false);
+  });
+
+  it('returns false when email is null / undefined / empty', () => {
+    expect(isBranchAuthoredBy('alice/my-draft', null)).toBe(false);
+    expect(isBranchAuthoredBy('alice/my-draft', undefined)).toBe(false);
+    expect(isBranchAuthoredBy('alice/my-draft', '')).toBe(false);
+  });
+
+  it('matches case-insensitively on the email side (branch is already lowercase by convention)', () => {
+    // slugifyDraftName lowercases the email at create time, so a user with
+    // capitals in their email still ends up owning a lowercase prefix.
+    expect(isBranchAuthoredBy('alice/draft', 'ALICE@example.com')).toBe(true);
+  });
+
+  it('requires the slash boundary — does not treat substring as prefix', () => {
+    // "alice-extra/foo" must not look authored by "alice" — otherwise users
+    // could delete other people's branches whose prefix happens to start
+    // with their own localpart.
+    expect(isBranchAuthoredBy('alice-extra/foo', 'alice@example.com')).toBe(false);
+  });
+});

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

@@ -0,0 +1,15 @@
+import { describe, it, expect } from 'vitest';
+import { cloneTrackingConfigArgs, ORIGIN_FETCH_REFSPEC } from '../clone-config.js';
+
+describe('cloneTrackingConfigArgs', () => {
+  // A slashed draft name is the everyday case (`<email-localpart>/<slug>`), and
+  // the branch lands verbatim inside the config KEY — pin the exact tuples so a
+  // future quoting/encoding change can't silently re-point tracking.
+  it('emits the three --replace-all tuples for a slashed branch', () => {
+    expect(cloneTrackingConfigArgs('feature/x')).toEqual([
+      ['config', '--replace-all', 'remote.origin.fetch', ORIGIN_FETCH_REFSPEC],
+      ['config', '--replace-all', 'branch.feature/x.remote', 'origin'],
+      ['config', '--replace-all', 'branch.feature/x.merge', 'refs/heads/feature/x'],
+    ]);
+  });
+});

package/src/modules/workflow/git/__tests__/git-test-helpers.ts

@@ -0,0 +1,47 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import { WorkflowHooks } from '../../workflow-hooks.js';
+
+/**
+ * Helpers shared by the GitService integration suites that drive a real git
+ * against temp repos (`git.service.pull.test.ts`,
+ * `git.service.postMergePull.test.ts`). Not a test file itself — vitest only
+ * picks up `*.test.ts`.
+ */
+
+const execFileAsync = promisify(execFile);
+
+/** Run git with a pinned test committer identity, discarding output. */
+export async function runGit(cwd: string, args: string[]): Promise<void> {
+  await execFileAsync('git', args, {
+    cwd,
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 'Test', GIT_AUTHOR_EMAIL: 't@x.com',
+      GIT_COMMITTER_NAME: 'Test', GIT_COMMITTER_EMAIL: 't@x.com',
+    },
+  });
+}
+
+/** Run git and return its trimmed stdout. */
+export async function gitOut(cwd: string, args: string[]): Promise<string> {
+  const { stdout } = await execFileAsync('git', args, { cwd });
+  return stdout.toString().trim();
+}
+
+/** An empty hooks registry — no commit-time validation, so pulls/merges never block. */
+export function stubWorkflowHooks(): WorkflowHooks {
+  return new WorkflowHooks();
+}
+
+/** Resolves each workspace id to its directory, like the real service does. */
+export function stubWorkspaceService(dirs: Record<string, string>): WorkspaceService {
+  return {
+    getWorkspacePath: async (id: string) => {
+      const dir = dirs[id];
+      if (!dir) throw new Error(`unexpected workspace ${id}`);
+      return dir;
+    },
+  } as unknown as WorkspaceService;
+}

package/src/modules/workflow/git/__tests__/git-version.failure.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect, vi } from 'vitest';
+import { assertGitVersion } from '../git-version.js';
+
+// Lives in its own file (not git-version.test.ts) because `git-version.ts`
+// binds `promisify(execFile)` at module load: the spawn failure must be mocked
+// module-wide before that import, which would also break the sibling test that
+// runs against the real git binary.
+vi.mock('node:child_process', () => ({
+  execFile: (
+    _cmd: string,
+    _args: readonly string[],
+    cb: (err: Error) => void,
+  ) => {
+    cb(Object.assign(new Error('spawn git ENOENT'), { code: 'ENOENT' }));
+  },
+}));
+
+describe('assertGitVersion — git binary missing', () => {
+  it('wraps the spawn failure in the "git is required" boot error', async () => {
+    await expect(assertGitVersion()).rejects.toThrow(
+      /git is required but could not be run: .*ENOENT/,
+    );
+  });
+});

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

@@ -0,0 +1,49 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import {
+  MIN_GIT_VERSION,
+  parseGitVersion,
+  assertSupportedGitVersion,
+  assertGitVersion,
+} from '../git-version.js';
+
+describe('the git version floor', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('reads the major/minor out of the shapes git actually prints', () => {
+    expect(parseGitVersion('git version 2.39.5\n')).toEqual([2, 39]);
+    expect(parseGitVersion('git version 2.39.5 (Apple Git-154)\n')).toEqual([2, 39]);
+    expect(parseGitVersion('git version 2.45.1.windows.1\n')).toEqual([2, 45]);
+    expect(parseGitVersion('git version 3.0\n')).toEqual([3, 0]);
+    expect(parseGitVersion('not git at all')).toBeNull();
+  });
+
+  it('rejects a git too old for --no-write-fetch-head', () => {
+    const [major, minor] = MIN_GIT_VERSION;
+    expect(() => assertSupportedGitVersion(`git version ${major}.${minor - 1}.0`))
+      .toThrow(/git 2\.29 or newer is required, found 2\.28/);
+    expect(() => assertSupportedGitVersion('git version 1.9.5')).toThrow(/required/);
+  });
+
+  it('accepts the floor itself and anything newer', () => {
+    const [major, minor] = MIN_GIT_VERSION;
+    expect(() => assertSupportedGitVersion(`git version ${major}.${minor}.0`)).not.toThrow();
+    expect(() => assertSupportedGitVersion('git version 2.39.5')).not.toThrow();
+    expect(() => assertSupportedGitVersion('git version 3.0.0')).not.toThrow();
+  });
+
+  // A git build with an unusual version banner is far more likely than one
+  // older than 2.29, so an unreadable string must not take down the boot.
+  it('warns but does not block boot on an unreadable version string', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    expect(() => assertSupportedGitVersion('some vendored git\n')).not.toThrow();
+    expect(warn).toHaveBeenCalled();
+  });
+
+  // The real binary on any machine that can run this suite is well past the
+  // floor; this pins the wiring (spawn + parse) rather than the version.
+  it('passes against the git installed on this machine', async () => {
+    await expect(assertGitVersion()).resolves.toBeUndefined();
+  });
+});