@antasphere/chassis-server 1.0.0

package/test/unit/tool-definition-guards.test.ts

@@ -0,0 +1,166 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { ToolIdentity } from '@antasphere/chassis-contract';
+import { createPlatform, type ToolCopy, type ToolDefinition } from '@antasphere/chassis-server';
+import { assertToolCopy, assertToolIdentity } from '../../src/tool-definition.js';
+import { THINGS_COPY, THINGS_IDENTITY } from '../host/identity.js';
+import { minimalTool } from '../host/minimal-tool.js';
+
+/**
+ * The boot-time half of "identity is required" (PRDCT-2531, verifier F-1).
+ *
+ * The types refuse a tool that omits `identity` or `copy`; these guards exist
+ * for the definition the types cannot see (plain JS, a cast). Every case below
+ * is therefore built through a cast, and every expectation is the whole
+ * message, because the message naming the field is the point of the guard.
+ *
+ * The last block proves the BOOT calls them: a guard nobody calls passes every
+ * test above it. Both guards run before the env is parsed and before any
+ * database is touched, so the boot rejects without Postgres and this stays a
+ * unit test.
+ */
+
+/** A deep, mutable copy of the host's identity, one field replaced (dotted path). */
+function identityWith(path: string, value: unknown): ToolIdentity {
+  const copy = JSON.parse(JSON.stringify(THINGS_IDENTITY)) as Record<string, unknown>;
+  const segments = path.split('.');
+  const last = segments.pop()!;
+  let at = copy;
+  for (const segment of segments) at = at[segment] as Record<string, unknown>;
+  if (value === undefined) delete at[last];
+  else at[last] = value;
+  return copy as unknown as ToolIdentity;
+}
+
+const IDENTITY_FIELDS = [
+  'slug',
+  'displayName',
+  'apiKeyPrefix',
+  'scopes.read',
+  'scopes.write',
+  'scopes.dataExport',
+  'cliKeyScopesLabel',
+  'cli.bin',
+  'cli.envPrefix',
+  'cli.legacyConfigDir',
+  'mcp.serverName',
+  'mcp.toolPrefix',
+  'otelServiceName',
+  'imageName'
+] as const;
+
+const COPY_SENTENCES = ['guestForbidden', 'guestTarget', 'fileInUse'] as const;
+
+describe('assertToolIdentity', () => {
+  it('passes a complete identity', () => {
+    expect(() => assertToolIdentity(THINGS_IDENTITY)).not.toThrow();
+  });
+
+  it('refuses a definition whose slot is missing', () => {
+    expect(() => assertToolIdentity(undefined)).toThrow(
+      new Error('tool definition: the `identity` slot is required')
+    );
+  });
+
+  it.each(IDENTITY_FIELDS)('refuses an EMPTY %s, naming the field', (field) => {
+    expect(() => assertToolIdentity(identityWith(field, ''))).toThrow(
+      new Error(`tool definition: identity.${field} is required (a non-empty string)`)
+    );
+  });
+
+  it.each(IDENTITY_FIELDS)('refuses a MISSING %s, naming the field', (field) => {
+    expect(() => assertToolIdentity(identityWith(field, undefined))).toThrow(
+      new Error(`tool definition: identity.${field} is required (a non-empty string)`)
+    );
+  });
+
+  it('refuses a whole group left out (no `mcp`), naming its first field', () => {
+    expect(() => assertToolIdentity(identityWith('mcp', undefined))).toThrow(
+      new Error('tool definition: identity.mcp.serverName is required (a non-empty string)')
+    );
+  });
+
+  it('refuses a value that is not a string', () => {
+    expect(() => assertToolIdentity(identityWith('apiKeyPrefix', 42))).toThrow(
+      new Error('tool definition: identity.apiKeyPrefix is required (a non-empty string)')
+    );
+  });
+});
+
+describe('assertToolCopy', () => {
+  it('passes a complete copy', () => {
+    expect(() => assertToolCopy(THINGS_COPY)).not.toThrow();
+  });
+
+  it('refuses a definition whose slot is missing', () => {
+    expect(() => assertToolCopy(undefined)).toThrow(
+      new Error('tool definition: the `copy` slot is required')
+    );
+  });
+
+  it.each(COPY_SENTENCES)('refuses an EMPTY %s, naming the sentence', (name) => {
+    expect(() => assertToolCopy({ ...THINGS_COPY, [name]: '' })).toThrow(
+      new Error(`tool definition: copy.${name} is required (a non-empty sentence)`)
+    );
+  });
+
+  it.each(COPY_SENTENCES)('refuses a MISSING %s, naming the sentence', (name) => {
+    const copy: Partial<ToolCopy> = { ...THINGS_COPY };
+    delete copy[name];
+    expect(() => assertToolCopy(copy as ToolCopy)).toThrow(
+      new Error(`tool definition: copy.${name} is required (a non-empty sentence)`)
+    );
+  });
+});
+
+describe('the boot calls both guards, before it reads anything', () => {
+  // An env the parser refuses (no DATABASE_URL): the guards speak first, so the
+  // rejection is theirs and no database is needed to see it. The parser's own
+  // refusal is a printed table and `process.exit(1)`; both are stubbed, so a boot
+  // that got past the guards ends here as a plain rejection, quietly.
+  const NO_ENV = {};
+  beforeEach(() => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.spyOn(process, 'exit').mockImplementation((code) => {
+      throw new Error(`env parser: process.exit(${String(code)})`);
+    });
+  });
+  afterEach(() => vi.restoreAllMocks());
+  type AnyTool = ToolDefinition<Record<string, never>, Record<string, never>>;
+  const without = (slot: 'identity' | 'copy'): AnyTool => {
+    const tool: Partial<typeof minimalTool> = { ...minimalTool };
+    delete tool[slot];
+    return tool as unknown as AnyTool;
+  };
+
+  it('a complete tool gets past the guards (the rejection is the env parser’s)', async () => {
+    await expect(createPlatform(minimalTool).boot(NO_ENV)).rejects.toThrow(
+      new Error('env parser: process.exit(1)')
+    );
+  });
+
+  it('a tool cast past the types without `identity` does not boot', async () => {
+    await expect(createPlatform(without('identity')).boot(NO_ENV)).rejects.toThrow(
+      new Error('tool definition: the `identity` slot is required')
+    );
+  });
+
+  it('a tool cast past the types without `copy` does not boot', async () => {
+    await expect(createPlatform(without('copy')).boot(NO_ENV)).rejects.toThrow(
+      new Error('tool definition: the `copy` slot is required')
+    );
+  });
+
+  it('a tool with one empty identity field does not boot, and the boot names the field', async () => {
+    const tool = { ...minimalTool, identity: identityWith('mcp.toolPrefix', '') } as unknown as AnyTool;
+    await expect(createPlatform(tool).boot(NO_ENV)).rejects.toThrow(
+      new Error('tool definition: identity.mcp.toolPrefix is required (a non-empty string)')
+    );
+  });
+
+  it('a tool with one empty copy sentence does not boot, and the boot names the sentence', async () => {
+    const tool = { ...minimalTool, copy: { ...THINGS_COPY, fileInUse: '' } } as unknown as AnyTool;
+    await expect(createPlatform(tool).boot(NO_ENV)).rejects.toThrow(
+      new Error('tool definition: copy.fileInUse is required (a non-empty sentence)')
+    );
+  });
+});

package/test/unit/tool-entitlements-guard.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from 'vitest';
+import { declareRouteEntitlements } from '@antasphere/chassis-contract';
+import {
+  assertToolEntitlements,
+  EMPTY_TOOL_ENTITLEMENTS,
+  type ToolEntitlementDeclaration
+} from '../../src/entitlements/index.js';
+
+/**
+ * The boot-time guard of the `entitlements` slot (slot 22) and the
+ * contract's registry builder: a route that meters an action the price book
+ * does not know, meters it in another unit, checks a limit no tier values
+ * or needs a feature nobody declared stops the boot naming the route; a
+ * route declared twice, or declaring nothing, fails at module load.
+ */
+
+const base = () => ({
+  actions: [{ key: 'things.make', creditsPerUnit: 1, unit: 'call', label: 'Make' }],
+  limits: { 'things.max': { oss: null, free: 2, pro: null } },
+  features: { premium: { free: false, pro: true } }
+});
+
+describe('declareRouteEntitlements', () => {
+  it('refuses a route declared twice, and a declaration that declares nothing', () => {
+    expect(() =>
+      declareRouteEntitlements([
+        { route: { method: 'post', path: '/things' }, meter: { key: 'a', unit: 'call' } },
+        { route: { method: 'POST', path: '/things' }, meter: { key: 'b', unit: 'call' } }
+      ])
+    ).toThrow(/declared twice: POST \/things/);
+    expect(() => declareRouteEntitlements([{ route: { method: 'get', path: '/things' } }])).toThrow(
+      /declares nothing/
+    );
+  });
+});
+
+describe('assertToolEntitlements', () => {
+  it('accepts the empty slot and a coherent one', () => {
+    expect(() => assertToolEntitlements(EMPTY_TOOL_ENTITLEMENTS)).not.toThrow();
+    expect(() =>
+      assertToolEntitlements({
+        ...base(),
+        routes: declareRouteEntitlements([
+          {
+            route: { method: 'post', path: '/things' },
+            meter: { key: 'things.make', unit: 'call' },
+            limit: { key: 'things.max', value: () => 1 },
+            feature: 'premium'
+          }
+        ])
+      })
+    ).not.toThrow();
+  });
+
+  it('refuses a metered action the price book does not declare, and a unit that differs', () => {
+    expect(() =>
+      assertToolEntitlements({
+        ...base(),
+        routes: declareRouteEntitlements([
+          { route: { method: 'post', path: '/x' }, meter: { key: 'nope', unit: 'call' } }
+        ])
+      })
+    ).toThrow(/POST \/x meters "nope"/);
+    expect(() =>
+      assertToolEntitlements({
+        ...base(),
+        routes: declareRouteEntitlements([
+          { route: { method: 'post', path: '/x' }, meter: { key: 'things.make', unit: 'bytes' } }
+        ])
+      })
+    ).toThrow(/in bytes, the action is priced per call/);
+  });
+
+  it('refuses a limit or a feature no tier declares, and an action declared twice', () => {
+    expect(() =>
+      assertToolEntitlements({
+        ...base(),
+        routes: declareRouteEntitlements([
+          { route: { method: 'post', path: '/x' }, limit: { key: 'ghost', value: () => 1 } }
+        ])
+      })
+    ).toThrow(/checks the limit "ghost"/);
+    expect(() =>
+      assertToolEntitlements({
+        ...base(),
+        routes: declareRouteEntitlements([{ route: { method: 'post', path: '/x' }, feature: 'ghost' }])
+      })
+    ).toThrow(/needs the feature "ghost"/);
+    expect(() =>
+      assertToolEntitlements({
+        ...base(),
+        actions: [...base().actions, ...base().actions],
+        routes: declareRouteEntitlements([])
+      })
+    ).toThrow(/declares things.make twice/);
+  });
+});
+
+describe('assertToolEntitlements: the shape of the lists and the instance ceiling (PRDCT-2653)', () => {
+  const MB = 1024 * 1024;
+  const withLimits = (limits: unknown): ToolEntitlementDeclaration => ({
+    ...base(),
+    limits: limits as ToolEntitlementDeclaration['limits'],
+    routes: declareRouteEntitlements([])
+  });
+
+  it('refuses a limit key with a missing tier, naming its path', () => {
+    expect(() => assertToolEntitlements(withLimits({ 'things.max': { oss: 10, free: 10 } }))).toThrow(
+      /entitlements declaration is malformed: limits\.things\.max\.pro: /
+    );
+  });
+
+  it('refuses a feature with a missing tier, naming its path', () => {
+    expect(() =>
+      assertToolEntitlements({
+        ...base(),
+        features: { premium: { free: false } } as unknown as ToolEntitlementDeclaration['features'],
+        routes: declareRouteEntitlements([])
+      })
+    ).toThrow(/entitlements declaration is malformed: features\.premium\.pro: /);
+  });
+
+  it('refuses a tier above a numeric oss, with the ceiling message', () => {
+    expect(() =>
+      assertToolEntitlements(withLimits({ 'files.maxBytes': { oss: 100, free: 20, pro: 500 } }))
+    ).toThrow(
+      'tool definition: entitlements.limits.files.maxBytes.pro (500) is above the instance ceiling (oss 100): a plan value the instance cannot serve must not be advertised'
+    );
+  });
+
+  it('refuses an unlimited (null) tier under a numeric oss', () => {
+    expect(() =>
+      assertToolEntitlements(withLimits({ 'files.maxBytes': { oss: 100, free: null, pro: 100 } }))
+    ).toThrow(
+      'tool definition: entitlements.limits.files.maxBytes.free (null) is above the instance ceiling (oss 100): a plan value the instance cannot serve must not be advertised'
+    );
+  });
+
+  it('accepts any tier value under a null oss (no ceiling)', () => {
+    expect(() =>
+      assertToolEntitlements(withLimits({ 'workspace.members': { oss: null, free: 3, pro: null } }))
+    ).not.toThrow();
+    expect(() =>
+      assertToolEntitlements(withLimits({ 'links.perDeck': { oss: null, free: 10, pro: 1e9 } }))
+    ).not.toThrow();
+  });
+
+  for (const cap of [100 * MB, 500 * MB]) {
+    it(`accepts the two real declarations' shapes at cap = ${cap / MB} MB`, () => {
+      // packages/chassis-server/test/host/minimal-tool.ts
+      expect(() =>
+        assertToolEntitlements(
+          withLimits({ 'files.maxBytes': { oss: cap, free: Math.floor(cap / 5), pro: cap } })
+        )
+      ).not.toThrow();
+      // apps/server/src/tool.ts
+      expect(() =>
+        assertToolEntitlements(
+          withLimits({
+            'files.maxBytes': { oss: cap, free: Math.min(100 * MB, cap), pro: cap },
+            'workspace.members': { oss: null, free: 3, pro: null },
+            'links.perDeck': { oss: null, free: 10, pro: null }
+          })
+        )
+      ).not.toThrow();
+    });
+  }
+});