@bevel-software/platform-core-backend 0.32.0 → 0.34.0

package/migrations/meta/_journal.json

@@ -141,6 +141,34 @@
       "when": 1792404850653,
       "tag": "0019_oauth_token_rotated_at",
       "breakpoints": true
+    },
+    {
+      "idx": 20,
+      "version": "7",
+      "when": 1792491287956,
+      "tag": "0020_change_request_body_is_the_description",
+      "breakpoints": true
+    },
+    {
+      "idx": 21,
+      "version": "7",
+      "when": 1792491290917,
+      "tag": "0021_data_migrations_ledger",
+      "breakpoints": true
+    },
+    {
+      "idx": 22,
+      "version": "7",
+      "when": 1792657514328,
+      "tag": "0022_session_version",
+      "breakpoints": true
+    },
+    {
+      "idx": 23,
+      "version": "7",
+      "when": 1793089896833,
+      "tag": "0023_agent_path",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,8 +55,8 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.32.0",
-    "@bevel-software/platform-shared": "0.32.0"
+    "@bevel-software/platform-mcp-core": "0.34.0",
+    "@bevel-software/platform-shared": "0.34.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/__tests__/pg-scratch.test.ts

@@ -0,0 +1,69 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+/**
+ * `openMigratedScratchDb` owns the pool it opens until it hands the handle
+ * over: when the migrations fail, the caller never receives `close`, so the
+ * helper must close the pool itself and let the error through. No Postgres
+ * here — the connection, the migrations and the `pg` admin client are stubs,
+ * since the subject is the helper's ownership of what it opened, not the
+ * database.
+ */
+
+const stubs = vi.hoisted(() => ({
+  db: { kind: 'fake-db' },
+  createDb: vi.fn(),
+  closeDb: vi.fn(async () => {}),
+  runCoreMigrations: vi.fn(async () => {}),
+  adminQuery: vi.fn(async () => ({ rows: [] })),
+}));
+
+vi.mock('../modules/database/connection.js', () => ({
+  createDb: stubs.createDb,
+  closeDb: stubs.closeDb,
+}));
+vi.mock('../modules/database/migrate.js', () => ({
+  runCoreMigrations: stubs.runCoreMigrations,
+}));
+vi.mock('../assets.js', () => ({ coreMigrationsDir: () => '/migrations' }));
+vi.mock('pg', () => ({
+  default: {
+    Client: class {
+      connect = async () => {};
+      query = stubs.adminQuery;
+      end = async () => {};
+    },
+  },
+}));
+
+// Read once, at import: a URL the stubbed admin client will never dial.
+process.env.TEST_DATABASE_URL = 'postgres://scratch:scratch@127.0.0.1:1/admin';
+const { openMigratedScratchDb } = await import('./pg-scratch.js');
+
+describe('openMigratedScratchDb', () => {
+  beforeEach(() => {
+    stubs.createDb.mockReturnValue(stubs.db);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+    stubs.runCoreMigrations.mockResolvedValue(undefined);
+  });
+
+  it('hands the migrated database over with a close the caller owns', async () => {
+    const opened = await openMigratedScratchDb('hexis_owned');
+    expect(opened.db).toBe(stubs.db);
+    expect(stubs.runCoreMigrations).toHaveBeenCalledWith(stubs.db, '/migrations');
+    // The pool stays open until the caller closes it.
+    expect(stubs.closeDb).not.toHaveBeenCalled();
+    await opened.close();
+    expect(stubs.closeDb).toHaveBeenCalledWith(stubs.db);
+  });
+
+  it('closes the pool it opened when the migrations fail, and lets the failure through', async () => {
+    stubs.runCoreMigrations.mockRejectedValueOnce(new Error('migration 0022 failed'));
+    await expect(openMigratedScratchDb('hexis_failed')).rejects.toThrow('migration 0022 failed');
+    // Closed by the helper: the caller never received a handle to close.
+    expect(stubs.closeDb).toHaveBeenCalledTimes(1);
+    expect(stubs.closeDb).toHaveBeenCalledWith(stubs.db);
+  });
+});

package/src/__tests__/pg-scratch.ts

@@ -1,5 +1,8 @@
 import { randomBytes } from 'node:crypto';
 import pg from 'pg';
+import { closeDb, createDb, type Database } from '../modules/database/connection.js';
+import { runCoreMigrations } from '../modules/database/migrate.js';
+import { coreMigrationsDir } from '../assets.js';
 
 /**
  * The one fixture for tests that cross a real Postgres. They run where
@@ -9,6 +12,11 @@ import pg from 'pg';
  * of its own, made by {@link scratchDatabaseUrl} and dropped by
  * {@link dropScratchDatabases}; the database the URL names is only connected
  * to, never written.
+ *
+ * A test that wants the schema as a deployment has it opens the database
+ * through {@link openMigratedScratchDb}: this fixture is the one place
+ * outside the database module that knows how a core database is connected
+ * to and migrated, so a module's test need not import those files itself.
  */
 export const PG_ADMIN_URL = process.env.TEST_DATABASE_URL;
 
@@ -38,6 +46,29 @@ export async function scratchDatabaseUrl(prefix: string): Promise<string> {
   return url.toString();
 }
 
+/**
+ * A scratch database at the current core schema — created, connected to with
+ * the PII key given (a fresh random one when none is), and every core
+ * migration run — as a module's test wants it. `close` ends the connection;
+ * {@link dropScratchDatabases} drops the database afterwards as for any other.
+ */
+export async function openMigratedScratchDb(
+  prefix: string,
+  opts: { piiKey?: string } = {},
+): Promise<{ db: Database; close: () => Promise<void> }> {
+  const piiKey = opts.piiKey ?? randomBytes(32).toString('base64');
+  const db = createDb(await scratchDatabaseUrl(prefix), { piiKey });
+  try {
+    await runCoreMigrations(db, coreMigrationsDir());
+  } catch (err) {
+    // The caller never receives the handle on this path, so the pool is
+    // closed here; the database itself is dropped with the others.
+    await closeDb(db);
+    throw err;
+  }
+  return { db, close: () => closeDb(db) };
+}
+
 /** Drop every scratch database this file made; for `afterAll`, with {@link PG_TEST_TIMEOUT}. */
 export async function dropScratchDatabases(): Promise<void> {
   const names = created.splice(0);

package/src/__tests__/slow-ripgrep.ts

@@ -0,0 +1,65 @@
+import { execFile } from 'node:child_process';
+import { chmod, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { promisify } from 'node:util';
+
+/**
+ * A ripgrep that never finishes a TREE search, for the suites about the
+ * search budget and about stopping: an `rg` put first on this process's PATH,
+ * where the server finds its ripgrep. A run reading stdin (the pattern check,
+ * a document's text) is handed to the real `rg`, so a pattern is judged as it
+ * always is; a walk records its process id and sleeps for a minute, which no
+ * budget waits out — or, given `walkMs`, sleeps that long and then finishes
+ * having found nothing, which is how a suite spends a budget in parts.
+ *
+ * `alive()` answers which of the walks it started are still running, so a
+ * suite can assert that a stopped search left no process behind. `remove()`
+ * puts the PATH back.
+ */
+export interface SlowRipgrep {
+  alive(): Promise<number[]>;
+  remove(): Promise<void>;
+}
+
+export async function slowRipgrep(opts: { walkMs?: number } = {}): Promise<SlowRipgrep> {
+  const seconds = opts.walkMs === undefined ? '60' : (opts.walkMs / 1000).toFixed(3);
+  const real = (await promisify(execFile)('sh', ['-c', 'command -v rg'])).stdout.trim();
+  const dir = await mkdtemp(join(tmpdir(), 'slow-rg-'));
+  const pids = join(dir, 'pids');
+  const binary = join(dir, 'rg');
+  await writeFile(
+    binary,
+    [
+      '#!/bin/sh',
+      'for a in "$@"; do last="$a"; done',
+      `if [ "$last" = "-" ]; then exec '${real}' "$@"; fi`,
+      `echo $$ >> '${pids}'`,
+      `exec sleep ${seconds}`,
+      '',
+    ].join('\n'),
+  );
+  await chmod(binary, 0o755);
+  const path = process.env.PATH;
+  process.env.PATH = `${dir}${delimiter}${path ?? ''}`;
+  return {
+    async alive() {
+      const started = (await readFile(pids, 'utf8').catch(() => ''))
+        .split('\n')
+        .filter(Boolean)
+        .map(Number);
+      return started.filter((pid) => {
+        try {
+          process.kill(pid, 0);
+          return true;
+        } catch {
+          return false;
+        }
+      });
+    },
+    async remove() {
+      process.env.PATH = path;
+      await rm(dir, { recursive: true, force: true });
+    },
+  };
+}

package/src/core/__tests__/boot-without-ripgrep.test.ts

@@ -0,0 +1,34 @@
+import { execFile } from 'node:child_process';
+import { mkdtemp, rm, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { afterEach, describe, expect, it } from 'vitest';
+import { createCoreServices } from '../../index.js';
+import type { TenantConfig } from '../../core-config.js';
+
+/**
+ * The server's boot, through the package's own entry, on a PATH that carries
+ * git and no ripgrep: it refuses to build any service, naming the binary.
+ */
+describe('booting without ripgrep', () => {
+  const path = process.env.PATH;
+  let bin = '';
+  afterEach(async () => {
+    process.env.PATH = path;
+    if (bin) await rm(bin, { recursive: true, force: true });
+    bin = '';
+  });
+
+  it('refuses to start, naming rg and the Dockerfile that installs it', async () => {
+    const git = (await promisify(execFile)('sh', ['-c', 'command -v git'])).stdout.trim();
+    bin = await mkdtemp(join(tmpdir(), 'no-rg-'));
+    await symlink(git, join(bin, 'git'));
+    process.env.PATH = bin;
+    // The binaries are checked before the configuration is read, so none is needed.
+    const err = (await createCoreServices({} as TenantConfig).catch((e: unknown) => e)) as Error;
+    expect(err).toBeInstanceOf(Error);
+    expect(err.message).toMatch(/^ripgrep \(`rg`\) is required on the server's PATH but could not be run: .*ENOENT/);
+    expect(err.message).toContain('The Hexis Dockerfile installs it');
+  });
+});

package/src/core/__tests__/catalog-revision.test.ts

@@ -4,6 +4,7 @@ import type { Server } from 'node:http';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import type { SkillSummary } from '../../modules/skills/skills.contract.js';
 import { catalogRevision, createCatalogRevisionRoutes } from '../catalog-revision.js';
+import { agentFile, agentScopeOver, inMemoryKb, type InMemoryKb } from '../../modules/agent-scope/__tests__/in-memory-kb.js';
 
 /**
  * The fingerprint a long-lived client polls to learn that the released catalog
@@ -228,3 +229,91 @@ describe('GET /agent/catalog-revision', () => {
     expect(await res.json()).toEqual({ revision: catalogRevision([], []), tools: 0, skills: 0 });
   });
 });
+
+describe('GET /agent/catalog-revision, for a connection made as an .agent file', () => {
+  let http: Server | null = null;
+
+  afterEach(async () => {
+    if (http) await new Promise<void>((resolve) => http!.close(() => resolve()));
+    http = null;
+  });
+
+  const lines = [
+    ['ops', 'ops', 'Plugins/Ops/ops.tool', 'http', 'remote', '', 's'].join('\u0000'),
+    ['crm', 'crm', 'Plugins/Sales/crm.tool', 'http', 'remote', '', 's'].join('\u0000'),
+  ];
+  const paths = ['Plugins/Ops/ops.tool', 'Plugins/Sales/crm.tool'];
+  const skills = [skill({ name: 'notes', path: 'Skills/Release/notes' }), skill({ name: 'pitch', path: 'Skills/Sales/pitch' })];
+
+  async function mount(kb: InMemoryKb, agentPath: string | undefined) {
+    // The two services narrow by the predicate they are handed, AFTER their
+    // own read gate — stood in for here by the lists above, all readable.
+    const catalogFingerprints = vi.fn(async (_email: string, within?: (p: string) => boolean) =>
+      lines.filter((_, i) => !within || within(paths[i]!)),
+    );
+    const listSkills = vi.fn(async (_email: string, opts?: { within?: (p: string) => boolean }) =>
+      skills.filter((s) => !opts?.within || opts.within(s.path)),
+    );
+    const agentScope = agentScopeOver(kb);
+    const resolve = vi.spyOn(agentScope, 'resolve');
+    const app = express();
+    app.use(
+      createCatalogRevisionRoutes({
+        toolManuals: { catalogFingerprints } as never,
+        skills: { listSkills } as never,
+        manualAuth: (req, _res, next) => {
+          req.toolAuth = { userId: 'u1', ...(agentPath ? { agentPath } : {}) } as never;
+          next();
+        },
+        resolveUserEmail: async () => 'ada@example.com',
+        agentScope,
+      }),
+    );
+    http = app.listen(0);
+    await new Promise<void>((r) => http!.once('listening', r));
+    const url = `http://127.0.0.1:${(http.address() as AddressInfo).port}/agent/catalog-revision`;
+    const read = async () =>
+      (await (await fetch(url)).json()) as { revision: string; tools: number; skills: number; connection?: unknown };
+    return { read, catalogFingerprints, listSkills, resolve };
+  }
+
+  it('Everything is the revision it always was: nothing resolved, nothing narrowed, no `connection`', async () => {
+    const { read, catalogFingerprints, listSkills, resolve } = await mount(inMemoryKb({}), undefined);
+    expect(await read()).toEqual({ revision: catalogRevision(lines, skills), tools: 2, skills: 2 });
+    expect(catalogFingerprints).toHaveBeenCalledWith('ada@example.com');
+    expect(listSkills).toHaveBeenCalledWith('ada@example.com');
+    expect(resolve).not.toHaveBeenCalled();
+  });
+
+  it("is the fingerprint of what the agent loads, and names the agent", async () => {
+    const kb = inMemoryKb({ 'Agents/ops.agent': agentFile('name: ops\nconnectors: [Plugins/Ops]\nskills: [Skills/Release]') });
+    const { read } = await mount(kb, 'Agents/ops.agent');
+    const body = await read();
+    expect(body.tools).toBe(1);
+    expect(body.skills).toBe(1);
+    expect(body.connection).toEqual({ agent: { path: 'Agents/ops.agent', name: 'ops' } });
+    expect(body.revision).not.toBe(catalogRevision(lines, skills));
+  });
+
+  it('moves at the next read after the .agent file is edited — no reconnect', async () => {
+    const kb = inMemoryKb({ 'Agents/ops.agent': agentFile('connectors: [Plugins/Ops]') });
+    const { read } = await mount(kb, 'Agents/ops.agent');
+    const before = await read();
+    expect(await read()).toEqual(before);
+    kb.files.set('Agents/ops.agent', agentFile('connectors: [Plugins/Ops]\nskills: [Skills/Sales]'));
+    const after = await read();
+    expect(after.revision).not.toBe(before.revision);
+    expect(after.skills).toBe(1);
+    // Even an edit that changes nothing listed moves it: the file is the configuration.
+    kb.files.set('Agents/ops.agent', agentFile('connectors: [Plugins/Ops]\nskills: [Skills/Sales]\ndescription: now described'));
+    expect((await read()).revision).not.toBe(after.revision);
+  });
+
+  it('a deleted file is an empty catalog with the reason, never Everything', async () => {
+    const { read } = await mount(inMemoryKb({}), 'Agents/gone.agent');
+    const body = await read();
+    expect(body.tools).toBe(0);
+    expect(body.skills).toBe(0);
+    expect((body.connection as { unavailable?: string }).unavailable).toMatch(/no longer exists or which you can no longer read/);
+  });
+});