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

package/src/modules/workspace/__tests__/workspace.service.unknown-branch.test.ts

@@ -0,0 +1,197 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import { WorkspaceService } from '../workspace.service.js';
+import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+
+const execFileAsync = promisify(execFile);
+
+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',
+    },
+  });
+}
+
+/**
+ * Origin answering "I have no such ref" is ONE git failure with two stories,
+ * and which one the platform tells depends on whether it has ever heard of
+ * the name. A branch it cloned or listed is a branch that was DELETED (410).
+ * A name nothing has ever shown it is not a branch at all (404) — telling
+ * that caller their typo "no longer exists on the remote" states, falsely,
+ * that it once did.
+ */
+describe('WorkspaceService — a branch origin does not have', () => {
+  let root: string;
+  let workspacesRoot: string;
+  let upstream: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-unknown-branch-'));
+    workspacesRoot = path.join(root, 'workspaces');
+    await fs.mkdir(workspacesRoot, { recursive: true });
+
+    upstream = path.join(root, 'upstream.git');
+    await runGit(root, ['init', '--bare', '-b', 'target-company-state', upstream]);
+
+    const seed = path.join(root, '.seed');
+    await fs.mkdir(seed);
+    await runGit(seed, ['init', '-b', 'target-company-state']);
+    await runGit(seed, ['remote', 'add', 'origin', upstream]);
+    await fs.writeFile(path.join(seed, 'marker.txt'), 'on-target', 'utf-8');
+    await runGit(seed, ['add', '.']);
+    await runGit(seed, ['commit', '-m', 'init target']);
+    await runGit(seed, ['checkout', '-b', 'alice/draft']);
+    await fs.writeFile(path.join(seed, 'marker.txt'), 'on-draft', 'utf-8');
+    await runGit(seed, ['commit', '-am', 'draft change']);
+    await runGit(seed, ['push', 'origin', 'target-company-state', 'alice/draft']);
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  /** Delete a branch on the git host, as a teammate or a merge would. */
+  const deleteOnHost = (branch: string): Promise<void> => runGit(upstream, ['branch', '-D', branch]);
+
+  const service = (repoUrl = upstream): WorkspaceService =>
+    new WorkspaceService(workspacesRoot, repoUrl, 'knowledge-base', new NodeFs());
+
+  it('a name nothing has ever cloned or listed is a 404 that names only the branch', async () => {
+    const svc = service();
+
+    await expect(svc.getOrCreateForBranch('nobody/never-made-this')).rejects.toMatchObject({
+      name: 'BranchNotFoundError',
+      status: 404,
+      message: 'There is no branch named nobody/never-made-this.',
+      payload: { kind: 'branch-not-found', branch: 'nobody/never-made-this' },
+    });
+  });
+
+  it('a name a listing showed us, and origin no longer has, stays a 410', async () => {
+    const svc = service();
+    // What the branch selector saw while the draft still existed.
+    svc.noteBranchesListed(['target-company-state', 'alice/draft']);
+    await deleteOnHost('alice/draft');
+
+    await expect(svc.getOrCreateForBranch('alice/draft')).rejects.toMatchObject({
+      name: 'RemoteBranchGoneError',
+      status: 410,
+      payload: { kind: 'remote-branch-gone', branch: 'alice/draft' },
+    });
+  });
+
+  it('a branch it had cloned, deleted on the host and swept off disk, is still a 410', async () => {
+    const svc = service();
+    // The whole life of a deleted draft: listed, opened (cloned), deleted on
+    // the host, its stale clone retired by the sync — and then someone opens
+    // an old link to it.
+    svc.noteBranchesListed(['target-company-state', 'alice/draft']);
+    await svc.getOrCreateForBranch('alice/draft');
+    await deleteOnHost('alice/draft');
+    await svc.deleteWorkspace(workspaceIdForBranch('alice/draft'));
+
+    await expect(svc.getOrCreateForBranch('alice/draft')).rejects.toMatchObject({
+      name: 'RemoteBranchGoneError',
+      status: 410,
+    });
+  });
+
+  it('a branch opened by link and never listed is still a 410 once its clone is swept', async () => {
+    const svc = service();
+    // No listing ever happened: someone followed a direct link, the branch
+    // cloned, the host deleted it, and the sweep retired the stale clone.
+    // The clone was the platform hearing of the name, and losing the clone
+    // must not lose that.
+    await svc.getOrCreateForBranch('alice/draft');
+    await deleteOnHost('alice/draft');
+    await svc.deleteWorkspace(workspaceIdForBranch('alice/draft'));
+
+    await expect(svc.getOrCreateForBranch('alice/draft')).rejects.toMatchObject({
+      name: 'RemoteBranchGoneError',
+      status: 410,
+    });
+  });
+
+  it('after a restart, a deleted branch with no clone left on disk reads as never known', async () => {
+    const svc = service();
+    svc.noteBranchesListed(['target-company-state', 'alice/draft']);
+    await svc.getOrCreateForBranch('alice/draft');
+    await deleteOnHost('alice/draft');
+    await svc.deleteWorkspace(workspaceIdForBranch('alice/draft'));
+
+    // The other half of the restart story: the clone is gone from disk and
+    // the listing memory died with the process, so nothing anywhere has ever
+    // shown this instance the name. 404 is then the honest answer — the
+    // platform is not claiming the branch never existed, only that it knows
+    // of no such branch.
+    await expect(service().getOrCreateForBranch('alice/draft')).rejects.toMatchObject({
+      name: 'BranchNotFoundError',
+      status: 404,
+      message: 'There is no branch named alice/draft.',
+    });
+  });
+
+  it('a clone probe that cannot be read is our failure, not a branch that never existed', async () => {
+    const svc = service();
+    await deleteOnHost('alice/draft');
+
+    // The probe for a clone on disk hits a permission fault rather than an
+    // empty directory. "I could not look" is not "there is no such branch":
+    // answering 404 here would blame the user's link for our broken storage.
+    const realAccess = fs.access.bind(fs);
+    const probePath = path.join(workspacesRoot, workspaceIdForBranch('alice/draft'), 'knowledge-base', '.git');
+    vi.spyOn(fs, 'access').mockImplementation(async (p: Parameters<typeof fs.access>[0], mode?: number) => {
+      if (String(p) === probePath) throw Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' });
+      return realAccess(p, mode);
+    });
+
+    try {
+      const err = await svc.getOrCreateForBranch('alice/draft').catch((e: unknown) => e);
+      expect((err as { name?: string }).name).not.toBe('BranchNotFoundError');
+      expect((err as { status?: number }).status).toBeUndefined();
+      expect((err as Error).message).toContain('Failed to clone process map');
+    } finally {
+      vi.restoreAllMocks();
+    }
+  });
+
+  it('a clone on disk answers for its branch with no listing in memory at all', async () => {
+    const svc = service();
+    await svc.getOrCreateForBranch('alice/draft');
+    await deleteOnHost('alice/draft');
+
+    // A fresh instance stands in for a restarted process: nothing listed,
+    // nothing registered, only the clone left on disk. That clone is the
+    // record — the branch opens, and no 404 is anywhere near this path.
+    await expect(service().getOrCreateForBranch('alice/draft')).resolves.toMatchObject({
+      id: workspaceIdForBranch('alice/draft'),
+    });
+  });
+
+  it('a branch that exists still bootstraps — neither error is on the happy path', async () => {
+    const svc = service();
+    const info = await svc.getOrCreateForBranch('alice/draft');
+    const repo = path.join(info.absolutePath, 'knowledge-base');
+    expect(await fs.readFile(path.join(repo, 'marker.txt'), 'utf-8')).toBe('on-draft');
+  });
+
+  it('an unreachable remote is neither 404 nor 410 — it is our failure, not the branch’s', async () => {
+    const svc = service(path.join(root, 'no-such-repo.git'));
+
+    const err = await svc.getOrCreateForBranch('alice/draft').catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(Error);
+    // No domain status at all: the routes answer 500 and the operator reads
+    // the log, rather than the user being told their branch does not exist.
+    expect((err as { status?: number }).status).toBeUndefined();
+    expect((err as Error).message).toContain('Failed to clone process map');
+  });
+});

package/src/modules/workspace/__tests__/workspace.tools.agents-file.test.ts

@@ -0,0 +1,128 @@
+import express from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { DEFAULT_KB_LAYOUT, configureKbLayout } from '@bevel-software/platform-shared';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
+import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import { DocExtractService } from '../file-readers/doc-extract.service.js';
+import { RoutineWritePolicyService } from '../routine-write-policy.js';
+import { SpillStore } from '../spill-store.js';
+import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { registerWorkspaceTools } from '../workspace.tools.js';
+
+/**
+ * What the platform TELLS AN AGENT about the conventions file, under the
+ * default name and under a deployment's own.
+ *
+ * Descriptions only: the behaviour behind them is covered in
+ * `workspace.tools.test.ts`, and what matters here is the text a remote agent
+ * reads, which is the only place it learns that the organisation's own
+ * `AGENTS.md` exists at all — it has no checkout, so no harness reads that file
+ * for it.
+ */
+const KB_DIR = 'knowledge-base';
+
+/** Every workspace tool's description, keyed by name, under the layout in effect. */
+async function descriptions(registry: ToolRegistry = new ToolRegistry()): Promise<Map<string, string>> {
+  const router = express.Router();
+  const auth = ((_req: unknown, _res: unknown, next: () => void) => next()) as unknown as ToolAuth;
+  registerWorkspaceTools(
+    registry,
+    router,
+    auth,
+    createToolHandlerFactory(() => ({ userEmail: 'a@x.io' })) as never,
+    new SpillStore(join(tmpdir(), 'bevel-test-spills')),
+    new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')),
+    {} as unknown as IAccessControl,
+    KB_DIR,
+    {
+      service: {} as never,
+      enabled: false,
+      kbDirName: KB_DIR,
+      recoveryBotEmail: 'recovery-bot@bevel.local',
+      hooks: new WorkflowHooks(),
+    },
+    new RoutineWritePolicyService(),
+    {} as never,
+  );
+  return listed(registry);
+}
+
+/** What the catalog says NOW, with nothing registered again. */
+async function listed(registry: ToolRegistry): Promise<Map<string, string>> {
+  const tools = await registry.listExternal();
+  return new Map(tools.map((t) => [t.name, t.description ?? '']));
+}
+
+afterEach(() => configureKbLayout({ ...DEFAULT_KB_LAYOUT }));
+
+describe('the conventions note every workspace tool carries', () => {
+  it('names AGENTS.md, and CLAUDE.md beside it, under the default name', async () => {
+    const byName = await descriptions();
+    // On EVERY entrypoint, reads included: any of them can be a session's first.
+    for (const name of ['grep', 'list_files', 'file_stat', 'write_file', 'move_file']) {
+      expect(byName.get(name), name).toContain(
+        'read `AGENTS.md` at the KB root — or `CLAUDE.md` on a knowledge base seeded before it was renamed',
+      );
+    }
+  });
+
+  it('names the configured file first and the organisation\'s own AGENTS.md second', async () => {
+    configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
+    const byName = await descriptions();
+    const note = byName.get('grep') ?? '';
+    expect(note).toContain('read `HEXIS.md` at the KB root, then `AGENTS.md` if it also exists');
+    expect(note).toContain("the organisation's own conventions");
+    // Ours first: an agent that reads only one must read the platform's.
+    expect(note.indexOf('`HEXIS.md`')).toBeLessThan(note.indexOf('`AGENTS.md`'));
+    // The legacy name is still offered, for a KB seeded before the rename.
+    expect(note).toContain('`CLAUDE.md`');
+  });
+
+  it('describes the platform files under the configured name, and no longer under AGENTS.md', async () => {
+    configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
+    const byName = await descriptions();
+    const stat = byName.get('file_stat') ?? '';
+    expect(stat).toContain('`access.md`, `roles.yaml`, `.bevelignore`, `HEXIS.md`');
+
+    for (const name of ['delete_file', 'move_file']) {
+      const text = byName.get(name) ?? '';
+      expect(text, name).toContain('`roles.yaml` or `HEXIS.md` at the repository root');
+      // The customer's file is content on such a deployment, so the rule that
+      // refuses a move must not claim it.
+      expect(text.replace(/`AGENTS\.md` if it also exists/g, ''), name).not.toContain(
+        'or `AGENTS.md` at the repository root',
+      );
+    }
+  });
+
+  it('keeps naming AGENTS.md as a platform file under the default name', async () => {
+    const byName = await descriptions();
+    expect(byName.get('file_stat')).toContain('`access.md`, `roles.yaml`, `.bevelignore`, `AGENTS.md`');
+    expect(byName.get('delete_file')).toContain('`roles.yaml` or `AGENTS.md` at the repository root');
+  });
+
+  /**
+   * First-run setup on a fresh deployment: the tools are mounted at boot, under
+   * the defaults, and the save that COMPLETES setup applies the admin's names
+   * in that same request — without a restart, deliberately, so the KB phase it
+   * runs next scaffolds the names they chose. A catalog built once at boot
+   * would go on naming `AGENTS.md` to every agent that connected afterwards.
+   */
+  it('follows a layout applied after the tools were mounted', async () => {
+    const registry = new ToolRegistry();
+    const atMount = await descriptions(registry);
+    expect(atMount.get('grep')).toContain('read `AGENTS.md` at the KB root');
+
+    configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
+
+    const now = await listed(registry);
+    expect(now.get('grep')).toContain('read `HEXIS.md` at the KB root, then `AGENTS.md` if it also exists');
+    expect(now.get('file_stat')).toContain('`access.md`, `roles.yaml`, `.bevelignore`, `HEXIS.md`');
+    expect(now.get('delete_file')).toContain('`roles.yaml` or `HEXIS.md` at the repository root');
+    expect(now.get('move_file')).toContain('`roles.yaml` or `HEXIS.md` at the repository root');
+  });
+});

package/src/modules/workspace/__tests__/workspace.tools.branch-errors.test.ts

@@ -0,0 +1,212 @@
+import type { Server as HttpServer } from 'node:http';
+import { execFile } from 'node:child_process';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import express from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import { ToolRegistry } from '../../tool-registry/tool-registry.js';
+import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
+import { createToolContextResolver } from '../../tool-helpers/tool-context.js';
+import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
+import type { AuthService } from '../../auth/auth.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { ICreatorAccess } from '../../access-model/creator.js';
+import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { RoutineWritePolicyService } from '../routine-write-policy.js';
+import { SpillStore } from '../spill-store.js';
+import { DocExtractService } from '../file-readers/doc-extract.service.js';
+import { registerWorkspaceTools } from '../workspace.tools.js';
+import { WorkspaceService } from '../workspace.service.js';
+
+const execFileAsync = promisify(execFile);
+const KB_DIR = 'knowledge-base';
+
+const allowAll = {
+  canRead: async () => true,
+  canReadBatch: async (_w: string, _u: string, paths: string[]) =>
+    new Map(paths.map((p) => [p, true])),
+} as unknown as IAccessControl;
+
+const stubCreatorAccess: ICreatorAccess = {
+  planForCreate: async () => null,
+  grantInExtractedFile: async () => null,
+  noteAccessFileWritten: () => {},
+};
+
+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',
+    },
+  });
+}
+
+/**
+ * The agent surface reaches a branch the same way the browser does — a tool
+ * names it, `getFilesystem` resolves the per-branch clone — so the same two
+ * refusals must come back out of a tool call, with the discriminator a model
+ * (or the MCP proxy) can branch on rather than prose it has to read. This is
+ * the surface the bug was reported from: a tester named a branch nobody ever
+ * created and was told it "no longer exists on the remote".
+ */
+describe('workspace tools — a branch that cannot be opened', () => {
+  let httpServer: HttpServer | undefined;
+  let root = '';
+  let workspaces: WorkspaceService | null = null;
+  let spillRoot = '';
+  let docCacheDir = '';
+
+  afterEach(async () => {
+    if (httpServer) {
+      // Drop the pooled keep-alive sockets first, or close() waits out the
+      // 5s keepAliveTimeout on every test in this file.
+      httpServer.closeAllConnections();
+      await new Promise<void>((r) => httpServer!.close(() => r()));
+    }
+    httpServer = undefined;
+    workspaces = null;
+    for (const dir of [root, spillRoot, docCacheDir]) {
+      if (dir) await rm(dir, { recursive: true, force: true });
+    }
+    root = '';
+    spillRoot = '';
+    docCacheDir = '';
+  });
+
+  /**
+   * A real per-branch WorkspaceService over a real local origin, behind the
+   * real tool-context resolver — so a tool call clones (or fails to clone)
+   * exactly as it does in production.
+   */
+  async function start(opts: { repoUrl?: 'origin' | 'unreachable' } = {}): Promise<string> {
+    root = await mkdtemp(join(tmpdir(), 'ws-tools-branch-'));
+    spillRoot = await mkdtemp(join(tmpdir(), 'ws-tools-spill-'));
+    docCacheDir = await mkdtemp(join(tmpdir(), 'ws-tools-doc-'));
+    const workspacesRoot = join(root, 'workspaces');
+    await mkdir(workspacesRoot, { recursive: true });
+
+    const upstream = join(root, 'upstream.git');
+    await runGit(root, ['init', '--bare', '-b', 'target-company-state', upstream]);
+    const seed = join(root, '.seed');
+    await mkdir(seed);
+    await runGit(seed, ['init', '-b', 'target-company-state']);
+    await runGit(seed, ['remote', 'add', 'origin', upstream]);
+    await mkdir(join(seed, KB_DIR));
+    await writeFile(join(seed, KB_DIR, 'a.md'), 'hello\n', 'utf-8');
+    await runGit(seed, ['add', '.']);
+    await runGit(seed, ['commit', '-m', 'init']);
+    await runGit(seed, ['checkout', '-b', 'alice/draft']);
+    await runGit(seed, ['commit', '--allow-empty', '-m', 'draft']);
+    await runGit(seed, ['push', 'origin', 'target-company-state', 'alice/draft']);
+
+    workspaces = new WorkspaceService(
+      workspacesRoot,
+      opts.repoUrl === 'unreachable' ? join(root, 'no-such-repo.git') : upstream,
+      KB_DIR,
+      new NodeFs(),
+    );
+
+    const resolve = createToolContextResolver({
+      authService: {
+        getUserById: async () => ({ id: 'u', email: 'alice@example.com', name: 'Alice' }),
+      } as unknown as AuthService,
+      workspaceService: workspaces,
+      workflowService: {} as never,
+      events: { emit: () => {} } as unknown as WorkflowEventBus,
+      kbDirName: KB_DIR,
+      creatorAccess: stubCreatorAccess,
+    });
+
+    const app = express();
+    app.use(express.json());
+    const router = express.Router();
+    registerWorkspaceTools(
+      new ToolRegistry(),
+      router,
+      (req: express.Request, _res: express.Response, next: express.NextFunction) => {
+        req.toolAuth = { source: 'external', userId: 'u', scope: 'read' } as ToolAuth;
+        next();
+      },
+      createToolHandlerFactory(resolve),
+      new SpillStore(spillRoot),
+      new DocExtractService(docCacheDir),
+      allowAll,
+      KB_DIR,
+      {
+        service: {} as never,
+        enabled: false,
+        kbDirName: KB_DIR,
+        recoveryBotEmail: 'recovery-bot@bevel.local',
+        hooks: new WorkflowHooks(),
+      },
+      new RoutineWritePolicyService(),
+      {} as never,
+    );
+    app.use('/api', router);
+    httpServer = await new Promise<HttpServer>((r) => {
+      const s = app.listen(0, () => r(s));
+    });
+    return `http://127.0.0.1:${(httpServer.address() as { port: number }).port}`;
+  }
+
+  const listFiles = async (base: string, branch: string): Promise<{ status: number; body: Record<string, unknown> }> => {
+    const res = await fetch(`${base}/api/agent/tools/list_files`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: 'Bearer x' },
+      body: JSON.stringify({ branch, path: '' }),
+    });
+    return { status: res.status, body: (await res.json()) as Record<string, unknown> };
+  };
+
+  const deleteOnHost = (branch: string): Promise<void> =>
+    runGit(join(root, 'upstream.git'), ['branch', '-D', branch]);
+
+  it('404s a branch nothing has ever cloned or listed, and says only that', async () => {
+    const base = await start();
+
+    const { status, body } = await listFiles(base, 'nobody/never-made-this');
+
+    expect(status).toBe(404);
+    expect(body).toEqual({
+      kind: 'branch-not-found',
+      branch: 'nobody/never-made-this',
+      error: 'There is no branch named nobody/never-made-this.',
+    });
+  });
+
+  it('410s a branch a listing showed us and origin no longer has', async () => {
+    const base = await start();
+    workspaces!.noteBranchesListed(['target-company-state', 'alice/draft']);
+    await deleteOnHost('alice/draft');
+
+    const { status, body } = await listFiles(base, 'alice/draft');
+
+    expect(status).toBe(410);
+    expect(body).toMatchObject({ kind: 'remote-branch-gone', branch: 'alice/draft' });
+  });
+
+  it('serves a branch that exists', async () => {
+    const base = await start();
+
+    const { status, body } = await listFiles(base, 'alice/draft');
+
+    expect(status).toBe(200);
+    expect((body.entries as { name: string }[]).map((e) => e.name)).toContain(KB_DIR);
+  });
+
+  it('500s an unreachable remote rather than blaming the branch', async () => {
+    const base = await start({ repoUrl: 'unreachable' });
+
+    const { status, body } = await listFiles(base, 'alice/draft');
+
+    expect(status).toBe(500);
+    expect(body.kind).toBeUndefined();
+  });
+});