@bevel-software/platform-core-backend 0.29.0 → 0.31.0

package/src/modules/workspace/pattern-matcher.contract.ts

@@ -0,0 +1,69 @@
+import { ToolError } from '../tool-helpers/tool.contract.js';
+
+/**
+ * The contract for running a CALLER'S regular expression: what `grep` (REST,
+ * MCP and `call_tool_chain` alike, one handler) depends on, so it never holds
+ * a concrete engine. The one implementation is `WorkerPatternMatcher`
+ * (`bounded-matcher.ts`), owned by the composition root and closed with the
+ * graph.
+ *
+ * JavaScript's engine backtracks, so a pattern like `^(a+)+$` over a line of
+ * forty `a`s and a `!` never finishes. An implementation must therefore never
+ * run the pattern on the request thread, must stop a search whose matching
+ * outlives its budget with {@link PatternTooExpensiveError}, and must refuse
+ * work it cannot take on with {@link SearchBusyError} rather than queue it
+ * without bound. Within budget, a pattern matches exactly the lines
+ * `RegExp#test` does.
+ */
+export interface IPatternMatcher {
+  /**
+   * One search's matcher for `source`/`flags`: its budget is spent across
+   * every call it makes. Throws the 400 `Invalid regex` the caller's syntax
+   * earns, or the 400 `pattern_too_long` an over-long pattern earns.
+   */
+  search(source: string, flags: string): IPatternSearch;
+  /** Ends the workers; a search after this is refused. */
+  close(): Promise<void>;
+}
+
+/** One search, under one budget. */
+export interface IPatternSearch {
+  /**
+   * The indices of the lines the pattern matches, in order, at most `limit` of
+   * them (the first `limit`, exactly as a loop that stops at the cap finds).
+   * Throws {@link PatternTooExpensiveError} once the search's budget is spent.
+   */
+  matchingLines(lines: string[], limit: number): Promise<number[]>;
+}
+
+/** A pattern stopped for taking too long — a 400, worded for the caller. */
+export class PatternTooExpensiveError extends ToolError {
+  constructor(pattern: string, budgetMs: number) {
+    super(
+      `Pattern too expensive: /${pattern.length > 80 ? `${pattern.slice(0, 80)}…` : pattern}/ did not finish matching within this search's ${budgetMs / 1000} s budget, ` +
+        'so it was stopped and nothing was returned. Patterns with nested or overlapping repetition such as ' +
+        '`(a+)+` or `(a|aa)*` can take exponential time on some lines. Use a simpler pattern — a literal, ' +
+        'an anchor, a character class, a single repetition — or narrow `path`.',
+      400,
+      { code: 'pattern_too_expensive' },
+    );
+    this.name = 'PatternTooExpensiveError';
+  }
+}
+
+/** Every worker busy and the queue for one full — a 503, so the caller retries rather than reads a partial answer. */
+export class SearchBusyError extends ToolError {
+  constructor() {
+    super('Too many searches are running at once; try again in a few seconds.', 503, { code: 'search_busy' });
+    this.name = 'SearchBusyError';
+  }
+}
+
+/**
+ * Whether `err` ends a whole search rather than one file's part of it: a
+ * directory walk that skipped a file for either would answer an incomplete
+ * result as if it were the whole one.
+ */
+export function endsTheSearch(err: unknown): boolean {
+  return err instanceof PatternTooExpensiveError || err instanceof SearchBusyError;
+}

package/src/modules/workspace/routine-write-policy.ts

@@ -33,12 +33,6 @@ export interface IRoutineWritePolicy {
    * always passes — so this is a no-op for every non-restricted caller.
    */
   assertPathWritable(sessionId: string | undefined, wsPath: string): void;
-  /**
-   * Throw a 403 `ToolError` when the session is restricted at all — for write
-   * tools with no single target path to check (arbitrary shell), which a
-   * restricted run must not be able to use as a write bypass.
-   */
-  assertUnrestricted(sessionId: string | undefined): void;
 }
 
 export class RoutineWritePolicyService implements IRoutineWritePolicy {
@@ -66,13 +60,4 @@ export class RoutineWritePolicyService implements IRoutineWritePolicy {
       403,
     );
   }
-
-  assertUnrestricted(sessionId: string | undefined): void {
-    if (sessionId && this.restrictions.has(sessionId)) {
-      throw new ToolError(
-        'This run is restricted to writing dashboard views only, so shell commands (which could write any file) are disabled.',
-        403,
-      );
-    }
-  }
 }

package/src/modules/workspace/set-aside-clone.ts

@@ -1,5 +1,40 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
+import { logger } from '../../shared/logging.js';
+import { isAbsence } from '../../shared/fs.contract.js';
+import { readGitfile } from '../kb-fs/index.js';
+import type { IKbRepository } from './kb-repository.contract.js';
+
+const log = logger('set-aside');
+
+/**
+ * `p` as the file system names it, for comparing two paths that may be
+ * spelled differently: git writes a worktree's link with forward slashes and
+ * the long folder names (`C:/Users/runneradmin/…`) where node may hold the
+ * same folder by its 8.3 short name (`C:\Users\RUNNER~1\…`). The nearest
+ * part that exists is resolved by the OS, the rest appended; on Windows the
+ * result is case-folded, as its file system is. Only an absent part is
+ * stepped over: a part that cannot be read (a permission or I/O error) throws,
+ * since "could not tell" is no reason to move someone's worktree.
+ */
+async function comparablePath(p: string): Promise<string> {
+  let existing = path.resolve(p);
+  const rest: string[] = [];
+  for (;;) {
+    try {
+      existing = await fs.realpath(existing);
+      break;
+    } catch (err) {
+      if (!isAbsence(err)) throw err;
+      const parent = path.dirname(existing);
+      if (parent === existing) break;
+      rest.unshift(path.basename(existing));
+      existing = parent;
+    }
+  }
+  const joined = path.join(existing, ...rest);
+  return process.platform === 'win32' ? joined.toLowerCase() : joined;
+}
 
 /**
  * Moving a working copy of a repository that is no longer the configured one
@@ -94,3 +129,108 @@ export async function setAsideClone(repoDir: string, dest: string): Promise<void
   }
   await fs.rm(repoDir, { recursive: true, force: true });
 }
+
+/**
+ * Set aside the knowledge base's repository AND EVERY WORKTREE OF IT, together,
+ * into `dest`: each worktree's folder as `dest/<workspace id>` (where a clone
+ * lands), the repository beside them under its own name.
+ *
+ * Together, because neither is any use without the other: a worktree's
+ * commits live in the repository, and a repository of another address is
+ * exactly as unusable as a clone of one. Nothing is deleted. The moved
+ * worktrees are re-linked to the moved repository, so `git log` in
+ * `dest/<workspace id>` shows the work that was never pushed.
+ *
+ * All or nothing: when a move fails part-way (the repository will not move
+ * after its worktrees did), the worktrees already moved are put back where
+ * they were, so a retry finds them with their repository and moves them
+ * together. A repository whose presence cannot be read (a permission or I/O
+ * error, not an absence) stops the call before anything moves.
+ *
+ * A worktree is found by its `.git` FILE naming a folder inside the
+ * repository — whether or not that folder is still there — so a worktree
+ * git had already lost track of goes with the rest. As the repository's one
+ * administrator (`exclusive`): no creation of a fresh repository and no
+ * config write runs while the folders move. Git operations in the worktrees
+ * are the caller's to hold off: the startup phase runs before anything is
+ * served, and the workspace service wraps the move in what surrounds a
+ * set-aside. Answers the workspace ids moved.
+ *
+ * `stillApplies`, when given, is asked again as the administrator, before
+ * anything moves: a caller decided to set the repository aside on what it
+ * read before taking the reservation, and another caller may have set it
+ * aside and made a fresh one of the configured address meanwhile. When the
+ * answer is no, nothing moves and the call answers no ids.
+ *
+ * A workspaces root, or a working copy's `.git`, that cannot be read (a
+ * permission or I/O error, not an absence) stops the call before anything
+ * moves, as an unreadable repository does: moving the repository without
+ * worktrees it could not see would leave every one of them pointing at
+ * nothing.
+ */
+export async function setAsideRepository(
+  repository: IKbRepository,
+  workspacesRoot: string,
+  kbDirName: string,
+  dest: string,
+  stillApplies?: () => Promise<boolean>,
+): Promise<string[]> {
+  return repository.exclusive(async () => {
+    if (stillApplies && !(await stillApplies())) return [];
+    const repositoryPath = await comparablePath(repository.dir);
+    const inside = async (p: string): Promise<boolean> => {
+      const at = await comparablePath(p);
+      return at === repositoryPath || at.startsWith(repositoryPath + path.sep);
+    };
+    const worktrees: Array<{ id: string; dir: string }> = [];
+    let entries: import('node:fs').Dirent[] = [];
+    try {
+      entries = await fs.readdir(workspacesRoot, { withFileTypes: true });
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      // No workspaces root: only the repository to move.
+      if (code !== 'ENOENT' && code !== 'ENOTDIR') throw err;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const dir = path.join(workspacesRoot, entry.name, kbDirName);
+      // Only absence shows a folder is no worktree: a `.git` that could not be
+      // read (EACCES, EIO) stops the call, as an unreadable root does.
+      const gitdir = await readGitfile(path.join(dir, '.git'));
+      if (gitdir !== null && (await inside(gitdir))) worktrees.push({ id: entry.name, dir });
+    }
+    const repositoryThere = await fs.access(repository.dir).then(
+      () => true,
+      (err: NodeJS.ErrnoException) => {
+        if (err.code === 'ENOENT' || err.code === 'ENOTDIR') return false;
+        throw err;
+      },
+    );
+    if (!repositoryThere && worktrees.length === 0) return [];
+    const moved: Array<{ dir: string; to: string }> = [];
+    const movedRepository = path.join(dest, path.basename(repository.dir));
+    try {
+      for (const { id, dir } of worktrees) {
+        const to = path.join(dest, id);
+        await setAsideClone(dir, to);
+        moved.push({ dir, to });
+      }
+      if (repositoryThere) await setAsideClone(repository.dir, movedRepository);
+    } catch (err) {
+      // Back where they were, beside the repository that did not move.
+      for (const { dir, to } of moved.reverse()) {
+        await setAsideClone(to, dir).catch((backErr: unknown) => {
+          log.error(`the set-aside worktree ${to} could not be put back at ${dir}; it is kept there:`, {
+            detail: backErr instanceof Error ? backErr.message : String(backErr),
+          });
+        });
+      }
+      throw err;
+    }
+    if (repositoryThere) {
+      await repository.relinkMovedCopy(movedRepository, moved.map(({ to }) => to));
+    }
+    repository.forget();
+    return worktrees.map(({ id }) => id);
+  });
+}

package/src/modules/workspace/startup/__tests__/kb-startup-runner.degraded.test.ts

@@ -4,10 +4,11 @@ import { promisify } from 'node:util';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { KbRemoteUnreachableError, KbStartupRunner } from '../kb-startup-runner.js';
+import { KbRemoteUnreachableError } from '../kb-startup-runner.js';
 import { NodeGitRunner } from '../../../workflow/git/node-git-runner.js';
 import { GitRunError, NO_GIT_CREDENTIALS, type IGitRunner } from '../../../../shared/git.contract.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
+import { newKbStartupRunner } from '../../../../__tests__/workspace-service.js';
 
 /**
  * What the runner does when the remote is not there — the one failure a boot
@@ -66,7 +67,7 @@ async function waitFor(condition: () => boolean, timeoutMs = 20_000): Promise<vo
 }
 
 function makeRunner(steps: OnServerStart[], url: () => string, gitRunner: IGitRunner = new NodeGitRunner()) {
-  return new KbStartupRunner({
+  return newKbStartupRunner({
     gitRunner,
     kbRepoUrl: url,
     workspacesRoot,

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

@@ -6,12 +6,11 @@ import { promisify } from 'node:util';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { KbStartupRunner } from '../kb-startup-runner.js';
-import { WorkspaceService } from '../../workspace.service.js';
 import { NodeGitRunner } from '../../../workflow/git/node-git-runner.js';
 import { ClassifiedFailure, classifyGitFailure, failureOf } from '../../../../shared/git-failure.js';
 import { GitRunError, gitCredentials } from '../../../../shared/git.contract.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
+import { newKbStartupRunner, newWorkspaceService } from '../../../../__tests__/workspace-service.js';
 
 /**
  * The token in effect for the runners these suites build, changed by the
@@ -71,7 +70,7 @@ async function populatedUpstream(): Promise<void> {
 }
 
 function makeRunner(steps: OnServerStart[], overrides: Partial<Parameters<typeof runnerOpts>[1]> = {}) {
-  return new KbStartupRunner(runnerOpts(steps, overrides));
+  return newKbStartupRunner(runnerOpts(steps, overrides));
 }
 
 function runnerOpts(steps: OnServerStart[], overrides: Record<string, unknown> = {}) {
@@ -996,8 +995,11 @@ describe('KbStartupRunner — a working copy whose clone was never finished', ()
     // The clone is sound and has a commit, but git cannot read the branch it
     // is to follow: the ref the fetch updates is damaged. Not a state this
     // phase repairs, so the start stops, and says which working copy.
-    const refs = path.join(local(), '.git', 'refs', 'remotes', 'origin');
-    await fs.rm(path.join(local(), '.git', 'packed-refs'), { force: true });
+    // The refs are where git says they are: a worktree's live in the
+    // repository it shares with every other branch.
+    const gitDir = (await git(local(), ['rev-parse', '--path-format=absolute', '--git-common-dir'])).trim();
+    const refs = path.join(gitDir, 'refs', 'remotes', 'origin');
+    await fs.rm(path.join(gitDir, 'packed-refs'), { force: true });
     await fs.mkdir(refs, { recursive: true });
     await fs.writeFile(path.join(refs, DEFAULT_BRANCH), 'not a commit id\n', 'utf8');
 
@@ -1129,7 +1131,7 @@ describe('KbStartupRunner credentials', () => {
     await git(repo, ['config', '--add', 'credential.helper',
       '!f() { echo "username=stale-user"; echo "password=$GITHUB_TOKEN"; }; f']);
 
-    const ws = new WorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs(), new NodeGitRunner(undefined, credentials));
+    const ws = newWorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs(), new NodeGitRunner(undefined, credentials));
     await ws.getOrCreateForBranch(DEFAULT_BRANCH);
 
     const all = (await git(repo, ['config', '--local', '--get-all', 'credential.helper'])).trim();
@@ -1147,14 +1149,14 @@ describe('KbStartupRunner credentials', () => {
     const repo = await materializeDefaultBranchClone();
     await git(repo, ['config', '--add', 'credential.helper', 'cache --timeout=300']);
 
-    const ws = new WorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs(), new NodeGitRunner(undefined, credentials));
+    const ws = newWorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs(), new NodeGitRunner(undefined, credentials));
     await ws.getOrCreateForBranch(DEFAULT_BRANCH); // stamp with token
     let all = (await git(repo, ['config', '--local', '--get-all', 'credential.helper'])).trim();
     expect(all).toContain('cache --timeout=300');
     expect(all).toContain('password=$GITHUB_TOKEN');
 
     token = null;
-    const ws2 =new WorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs(), new NodeGitRunner(undefined, credentials));
+    const ws2 =newWorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs(), new NodeGitRunner(undefined, credentials));
     await ws2.getOrCreateForBranch(DEFAULT_BRANCH); // unset OUR helper only
     all = (await git(repo, ['config', '--local', '--get-all', 'credential.helper'])).trim();
     expect(all).toContain('cache --timeout=300');
@@ -1170,7 +1172,7 @@ describe('KbStartupRunner credentials', () => {
     const repo = await materializeDefaultBranchClone(); // stamped
     token = null;
 
-    const ws = new WorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs(), new NodeGitRunner(undefined, credentials));
+    const ws = newWorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs(), new NodeGitRunner(undefined, credentials));
     await ws.getOrCreateForBranch(DEFAULT_BRANCH);
 
     await expect(git(repo, ['config', '--local', '--get', 'credential.helper']))
@@ -1185,7 +1187,7 @@ describe('KbStartupRunner credentials', () => {
     await populatedUpstream();
     const repo = await materializeDefaultBranchClone(); // no helper
 
-    const ws = new WorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs(), new NodeGitRunner(undefined, credentials));
+    const ws = newWorkspaceService(workspacesRoot, upstream, testKbContext(), new NodeFs(), new NodeGitRunner(undefined, credentials));
     await ws.getOrCreateForBranch(DEFAULT_BRANCH); // adopt, tokenless
     token = 'ghp_late';
     await ws.getOrCreateForBranch(DEFAULT_BRANCH); // cached fast path