@bevel-software/platform-core-backend 0.7.5 → 0.9.0

package/src/modules/auth/__tests__/rate-limit.test.ts

@@ -1,36 +1,36 @@
-import { describe, expect, it } from 'vitest';
-import { FixedWindowRateLimiter } from '../rate-limit.js';
-
-describe('FixedWindowRateLimiter', () => {
-  it('allows up to max attempts per window, then refuses', () => {
-    let now = 0;
-    const limiter = new FixedWindowRateLimiter(3, 1000, () => now);
-    expect(limiter.consume('k')).toBe(true);
-    expect(limiter.consume('k')).toBe(true);
-    expect(limiter.consume('k')).toBe(true);
-    expect(limiter.consume('k')).toBe(false);
-    // A different key has its own budget.
-    expect(limiter.consume('other')).toBe(true);
-    // Window rollover restores the budget.
-    now = 1001;
-    expect(limiter.consume('k')).toBe(true);
-  });
-
-  it('reset() clears a key immediately', () => {
-    const limiter = new FixedWindowRateLimiter(1, 60_000, () => 0);
-    expect(limiter.consume('k')).toBe(true);
-    expect(limiter.consume('k')).toBe(false);
-    limiter.reset('k');
-    expect(limiter.consume('k')).toBe(true);
-  });
-
-  it('prunes expired windows so the map stays bounded', () => {
-    let now = 0;
-    const limiter = new FixedWindowRateLimiter(1, 1000, () => now);
-    for (let i = 0; i < 100; i++) limiter.consume(`k${i}`);
-    now = 2000;
-    limiter.consume('fresh');
-    // Internal map pruned to just the fresh key.
-    expect((limiter as unknown as { hits: Map<string, unknown> }).hits.size).toBe(1);
-  });
-});
+import { describe, expect, it } from 'vitest';
+import { FixedWindowRateLimiter } from '../rate-limit.js';
+
+describe('FixedWindowRateLimiter', () => {
+  it('allows up to max attempts per window, then refuses', () => {
+    let now = 0;
+    const limiter = new FixedWindowRateLimiter(3, 1000, () => now);
+    expect(limiter.consume('k')).toBe(true);
+    expect(limiter.consume('k')).toBe(true);
+    expect(limiter.consume('k')).toBe(true);
+    expect(limiter.consume('k')).toBe(false);
+    // A different key has its own budget.
+    expect(limiter.consume('other')).toBe(true);
+    // Window rollover restores the budget.
+    now = 1001;
+    expect(limiter.consume('k')).toBe(true);
+  });
+
+  it('reset() clears a key immediately', () => {
+    const limiter = new FixedWindowRateLimiter(1, 60_000, () => 0);
+    expect(limiter.consume('k')).toBe(true);
+    expect(limiter.consume('k')).toBe(false);
+    limiter.reset('k');
+    expect(limiter.consume('k')).toBe(true);
+  });
+
+  it('prunes expired windows so the map stays bounded', () => {
+    let now = 0;
+    const limiter = new FixedWindowRateLimiter(1, 1000, () => now);
+    for (let i = 0; i < 100; i++) limiter.consume(`k${i}`);
+    now = 2000;
+    limiter.consume('fresh');
+    // Internal map pruned to just the fresh key.
+    expect((limiter as unknown as { hits: Map<string, unknown> }).hits.size).toBe(1);
+  });
+});

package/src/modules/auth/rate-limit.ts

@@ -1,45 +1,45 @@
-/**
- * Tiny fixed-window in-memory rate limiter for the password endpoints —
- * brute-force / scrypt-DoS protection, not traffic shaping. In-memory is the
- * right scope for the single-instance deployment model (same assumption as
- * the MCP session store); a multi-replica future moves this behind a shared
- * store.
- *
- * Expired windows are pruned opportunistically on each hit so the map stays
- * bounded by the number of DISTINCT active keys per window.
- */
-export class FixedWindowRateLimiter {
-  private readonly hits = new Map<string, { count: number; resetAt: number }>();
-
-  constructor(
-    /** Attempts allowed per window per key. */
-    private readonly max: number,
-    private readonly windowMs: number,
-    /** Injectable clock for tests. */
-    private readonly now: () => number = Date.now,
-  ) {}
-
-  /**
-   * Record one attempt for `key`; returns true when the attempt is ALLOWED
-   * (i.e. the key is within its budget for the current window).
-   */
-  consume(key: string): boolean {
-    const now = this.now();
-    for (const [k, entry] of this.hits) {
-      if (entry.resetAt <= now) this.hits.delete(k);
-    }
-    const entry = this.hits.get(key);
-    if (!entry || entry.resetAt <= now) {
-      this.hits.set(key, { count: 1, resetAt: now + this.windowMs });
-      return true;
-    }
-    entry.count += 1;
-    return entry.count <= this.max;
-  }
-
-  /** Clear a key's window — called after a SUCCESSFUL login so legitimate
-   * users who fumbled a few attempts aren't locked out of their next visit. */
-  reset(key: string): void {
-    this.hits.delete(key);
-  }
-}
+/**
+ * Tiny fixed-window in-memory rate limiter for the password endpoints —
+ * brute-force / scrypt-DoS protection, not traffic shaping. In-memory is the
+ * right scope for the single-instance deployment model (same assumption as
+ * the MCP session store); a multi-replica future moves this behind a shared
+ * store.
+ *
+ * Expired windows are pruned opportunistically on each hit so the map stays
+ * bounded by the number of DISTINCT active keys per window.
+ */
+export class FixedWindowRateLimiter {
+  private readonly hits = new Map<string, { count: number; resetAt: number }>();
+
+  constructor(
+    /** Attempts allowed per window per key. */
+    private readonly max: number,
+    private readonly windowMs: number,
+    /** Injectable clock for tests. */
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  /**
+   * Record one attempt for `key`; returns true when the attempt is ALLOWED
+   * (i.e. the key is within its budget for the current window).
+   */
+  consume(key: string): boolean {
+    const now = this.now();
+    for (const [k, entry] of this.hits) {
+      if (entry.resetAt <= now) this.hits.delete(k);
+    }
+    const entry = this.hits.get(key);
+    if (!entry || entry.resetAt <= now) {
+      this.hits.set(key, { count: 1, resetAt: now + this.windowMs });
+      return true;
+    }
+    entry.count += 1;
+    return entry.count <= this.max;
+  }
+
+  /** Clear a key's window — called after a SUCCESSFUL login so legitimate
+   * users who fumbled a few attempts aren't locked out of their next visit. */
+  reset(key: string): void {
+    this.hits.delete(key);
+  }
+}

package/src/modules/code-mode/__tests__/code-mode.tool.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { CodeModeUtcpClient } from '@utcp/code-mode';
+
+/**
+ * `tools_info` containment of a THROWING name lookup. `findToolByName`
+ * (mcp-core) throws on an ambiguous sanitized name — sanitization is lossy
+ * (`a-b` and `a+b` both become `a_b`) — and one ambiguous entry in a batch
+ * must cost that entry an error message, never the whole response. The
+ * lookup is mocked at the module seam so the test pins THIS module's
+ * per-name containment, not mcp-core's collision detection.
+ */
+
+vi.mock('../code-mode-names.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../code-mode-names.js')>();
+  return {
+    ...actual,
+    findToolByName: vi.fn(async (_client: unknown, name: string) => {
+      if (name === 'a_b.fetch') {
+        // The REAL sentinel class — the containment branches on instanceof,
+        // and a lookalike Error would test the wrong contract.
+        throw new actual.AmbiguousToolNameError(
+          'Tool name "a_b.fetch" is ambiguous: "a-b.fetch", "a+b.fetch" all sanitize to it. ' +
+            'Call the tool by its exact UTCP name instead.',
+        );
+      }
+      if (name === 'down.run') throw new Error('repository unavailable: ECONNREFUSED');
+      if (name === 'solo.run') return { tool: { name: 'solo.run' }, utcpName: 'solo.run' };
+      return null;
+    }),
+  };
+});
+
+const { createToolsInfoTool } = await import('../code-mode.tool.js');
+
+const client = {
+  toolToTypeScriptInterface: (tool: { name: string }) => `interface ${tool.name}`,
+} as unknown as CodeModeUtcpClient;
+
+type ToolsInfoResult = { interfaces: string; not_found: string[]; errors?: string[] };
+
+async function run(toolNames: string[]): Promise<ToolsInfoResult> {
+  const tool = createToolsInfoTool(client) as unknown as {
+    execute: (input: { tool_names: string[] }) => Promise<ToolsInfoResult>;
+  };
+  return tool.execute({ tool_names: toolNames });
+}
+
+describe('tools_info', () => {
+  it('answers every resolvable name even when one in the batch throws as ambiguous', async () => {
+    const result = await run(['a_b.fetch', 'solo.run', 'nope']);
+    expect(result.interfaces).toContain('interface solo.run');
+    expect(result.not_found).toEqual(['nope']);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors?.[0]).toMatch(/^a_b\.fetch: .*ambiguous/);
+  });
+
+  it('omits the errors field entirely when every name resolves or misses cleanly', async () => {
+    const result = await run(['solo.run', 'nope']);
+    expect(result.interfaces).toBe('interface solo.run');
+    expect(result.not_found).toEqual(['nope']);
+    expect(result.errors).toBeUndefined();
+  });
+
+  it('contains ONLY ambiguity — an outage rethrows instead of posing as partial success', async () => {
+    await expect(run(['solo.run', 'down.run'])).rejects.toThrow(/repository unavailable/);
+  });
+});

package/src/modules/code-mode/code-mode-names.ts

@@ -1,38 +1,12 @@
-import type { Tool } from '@utcp/sdk';
-import type { CodeModeUtcpClient } from '@utcp/code-mode';
-
 /**
- * Pure helpers for mapping UTCP tool names to their code-mode (TypeScript)
- * accessible form. Kept Mastra-free so both the agent's Mastra tools
- * (`code-mode.tool.ts`) and the MCP proxy can share them.
+ * Re-export of the code-mode name helpers, which now live in
+ * `@bevel-software/platform-mcp-core` so the local MCP server can share them
+ * without depending on this package. Kept as a module here because the agent's
+ * Mastra tools and the MCP proxy both import it by this path.
  */
-
-export function sanitizeIdentifier(name: string): string {
-  return name.replace(/[^a-zA-Z0-9_]/g, '_').replace(/^[0-9]/, '_$&');
-}
-
-/** `MANUAL.tool` → the `manual.tool` form the code-mode runtime exposes. */
-export function utcpNameToTsInterfaceName(utcpName: string): string {
-  if (utcpName.includes('.')) {
-    const [manualName, ...toolParts] = utcpName.split('.');
-    return `${sanitizeIdentifier(manualName!)}.${toolParts.map(sanitizeIdentifier).join('_')}`;
-  }
-  return sanitizeIdentifier(utcpName);
-}
-
-/** Resolve a tool by its raw UTCP name or its sanitized TS-accessible name. */
-export async function findToolByName(
-  client: CodeModeUtcpClient,
-  name: string,
-): Promise<{ tool: Tool; utcpName: string } | null> {
-  const direct = await client.config.tool_repository.getTool(name);
-  if (direct) return { tool: direct, utcpName: name };
-
-  const all = await client.config.tool_repository.getTools();
-  for (const tool of all) {
-    if (utcpNameToTsInterfaceName(tool.name) === name) {
-      return { tool, utcpName: tool.name };
-    }
-  }
-  return null;
-}
+export {
+  sanitizeIdentifier,
+  utcpNameToTsInterfaceName,
+  findToolByName,
+  AmbiguousToolNameError,
+} from '@bevel-software/platform-mcp-core';

package/src/modules/code-mode/code-mode.tool.ts

@@ -3,7 +3,7 @@ import { createTool } from '@mastra/core/tools';
 import { z } from 'zod';
 import { CodeModeUtcpClient } from '@utcp/code-mode';
 import type { SpillStore } from '../workspace/spill-store.js';
-import { utcpNameToTsInterfaceName, findToolByName } from './code-mode-names.js';
+import { utcpNameToTsInterfaceName, findToolByName, AmbiguousToolNameError } from './code-mode-names.js';
 
 export function createCallToolChainTool(
   client: CodeModeUtcpClient,
@@ -103,15 +103,35 @@ export function createToolsInfoTool(client: CodeModeUtcpClient) {
     execute: async (input) => {
       const interfaces: string[] = [];
       const notFound: string[] = [];
+      const errors: string[] = [];
       for (const name of input.tool_names) {
-        const found = await findToolByName(client, name);
-        if (found) {
-          interfaces.push(client.toolToTypeScriptInterface(found.tool));
-        } else {
-          notFound.push(name);
+        // Per-name, not per-call: `findToolByName` THROWS on an ambiguous
+        // sanitized name (two UTCP tools collapsing to one TS name), and one
+        // ambiguous entry aborting the whole batch would cost the agent every
+        // other answer in it. The error text says how to disambiguate, so it
+        // is the per-name answer, not a failure of the tool.
+        try {
+          const found = await findToolByName(client, name);
+          if (found) {
+            interfaces.push(client.toolToTypeScriptInterface(found.tool));
+          } else {
+            notFound.push(name);
+          }
+        } catch (err) {
+          // Only AMBIGUITY is a per-name answer (the message says how to
+          // disambiguate). Anything else — a repository outage, a catalog
+          // failure — must fail the call: containing it would dress an
+          // outage up as a successful lookup with partial data. Typed, not
+          // message-matched: the wording belongs to another package.
+          if (!(err instanceof AmbiguousToolNameError)) throw err;
+          errors.push(`${name}: ${err.message}`);
         }
       }
-      return { interfaces: interfaces.join('\n\n'), not_found: notFound };
+      return {
+        interfaces: interfaces.join('\n\n'),
+        not_found: notFound,
+        ...(errors.length > 0 ? { errors } : {}),
+      };
     },
   });
 }

package/src/modules/database/connection.ts

@@ -1,15 +1,15 @@
-import { drizzle } from 'drizzle-orm/node-postgres';
-import pg from 'pg';
-import * as schema from './schema.js';
-
-let db: ReturnType<typeof drizzle<typeof schema>> | null = null;
-
-export function getDb(databaseUrl: string) {
-  if (!db) {
-    const pool = new pg.Pool({ connectionString: databaseUrl });
-    db = drizzle(pool, { schema });
-  }
-  return db;
-}
-
-export type Database = ReturnType<typeof getDb>;
+import { drizzle } from 'drizzle-orm/node-postgres';
+import pg from 'pg';
+import * as schema from './schema.js';
+
+let db: ReturnType<typeof drizzle<typeof schema>> | null = null;
+
+export function getDb(databaseUrl: string) {
+  if (!db) {
+    const pool = new pg.Pool({ connectionString: databaseUrl });
+    db = drizzle(pool, { schema });
+  }
+  return db;
+}
+
+export type Database = ReturnType<typeof getDb>;

package/src/modules/database/schema.ts

@@ -1,11 +1,11 @@
-/**
- * The database schema of the CORE platform.
- *
- * In this package `schema.ts` is a re-export of `core-schema.ts` ONLY — the
- * enterprise tables live with the enterprise product, whose own schema file
- * imports the FK targets (`users`, `apiTokens`) from
- * `@bevel-software/platform-core-backend/schema`. Kept as a separate module (rather
- * than folding the tables in here) so module code keeps importing
- * `./schema.js` unchanged.
- */
-export * from './core-schema.js';
+/**
+ * The database schema of the CORE platform.
+ *
+ * In this package `schema.ts` is a re-export of `core-schema.ts` ONLY — the
+ * enterprise tables live with the enterprise product, whose own schema file
+ * imports the FK targets (`users`, `apiTokens`) from
+ * `@bevel-software/platform-core-backend/schema`. Kept as a separate module (rather
+ * than folding the tables in here) so module code keeps importing
+ * `./schema.js` unchanged.
+ */
+export * from './core-schema.js';