@coffeerunhobby/mcp-ha-connect 2.2.1 → 2.4.0

package/tests/server/chatFace.test.ts

@@ -1,320 +0,0 @@
-/**
- * Chat face (v1.7) — the unified binding registry that drives REST dispatch,
- * per-route RBAC, and the generated OpenAPI spec.
- *
- * The two load-bearing properties under test:
- *  1. BYTE-COMPATIBILITY: with no MCP_CHAT_TOOLS slice, the generated spec is
- *     identical to the pre-v1.7 hand-written one (golden fixture) — the NAS
- *     deployment must see zero difference from this refactor.
- *  2. ADMIN-NEVER-CHAT: no chat binding may carry the ADMIN bit or expose
- *     invokeAction — the deploy trigger stays off the prompt-injectable
- *     surface structurally.
- */
-
-import { describe, it, expect, vi } from 'vitest';
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-import type { IncomingMessage, ServerResponse } from 'node:http';
-
-import {
-  LEGACY_BINDINGS,
-  CHAT_TOOL_BINDINGS,
-  resolveChatBindings,
-  buildOpenApiSpec,
-  dispatchChatRequest,
-  requiredPermissionFor,
-  zodToOpenApiSchema,
-} from '../../src/server/chatFace.js';
-import { parseChatTools, CHAT_CATEGORIES } from '../../src/server/chatSlice.js';
-import { Permission } from '../../src/permissions/index.js';
-import { VERSION } from '../../src/version.js';
-import type { HaClient } from '../../src/haClient/index.js';
-import type { OmadaClient } from '../../src/omadaClient/index.js';
-import { z } from 'zod';
-
-const fixtureDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'fixtures');
-
-const LEGACY_OPERATION_IDS = [
-  'getStates',
-  'getState',
-  'callService',
-  'getAllSensors',
-  'getEntitiesByDomain',
-  'searchEntities',
-  'getHistory',
-  'getVersion',
-];
-
-describe('chat face — spec byte-compatibility (golden file)', () => {
-  it('default slice renders the pre-v1.7 spec exactly (modulo version)', () => {
-    const golden = JSON.parse(
-      readFileSync(join(fixtureDir, 'openapi-default-slice.json'), 'utf8')
-    ) as { info: { version: string } };
-    // The fixture was captured at its release version; only the version string
-    // may differ across releases — everything else must match to the byte.
-    golden.info.version = VERSION;
-
-    const generated = JSON.parse(
-      JSON.stringify(buildOpenApiSpec('http://__BASE_URL__', LEGACY_BINDINGS))
-    ) as unknown;
-
-    expect(generated).toEqual(golden);
-    // Belt-and-braces: key ORDER matters for byte-compat, so compare strings too.
-    expect(JSON.stringify(generated)).toBe(JSON.stringify(golden));
-  });
-});
-
-describe('chat face — security invariants', () => {
-  const allBindings = [...LEGACY_BINDINGS, ...CHAT_TOOL_BINDINGS];
-
-  it('no chat binding carries the ADMIN bit (invokeAction can never be chat-faced)', () => {
-    for (const binding of allBindings) {
-      expect(
-        binding.permission & Permission.ADMIN,
-        `${binding.operationId} must not require (= be granted via) ADMIN on the chat face`
-      ).toBe(0);
-      expect(binding.operationId).not.toBe('invokeAction');
-    }
-  });
-
-  it('omada_cyclePoePort is deliberately not chat-eligible', () => {
-    expect(allBindings.map((b) => b.operationId)).not.toContain('omada_cyclePoePort');
-  });
-
-  it('every binding declares a known category and a non-zero permission', () => {
-    for (const binding of allBindings) {
-      expect(CHAT_CATEGORIES).toContain(binding.category);
-      expect(binding.permission).toBeGreaterThan(0);
-    }
-  });
-});
-
-describe('parseChatTools', () => {
-  it('returns undefined for unset/blank (legacy default)', () => {
-    expect(parseChatTools(undefined)).toBeUndefined();
-    expect(parseChatTools('')).toBeUndefined();
-    expect(parseChatTools('   ')).toBeUndefined();
-  });
-
-  it('parses categories with r/w/rw access', () => {
-    const slice = parseChatTools('ha-core:rw, ha-history:r,omada-read:r');
-    expect(slice?.get('ha-core')).toEqual(new Set(['read', 'write']));
-    expect(slice?.get('ha-history')).toEqual(new Set(['read']));
-    expect(slice?.get('omada-read')).toEqual(new Set(['read']));
-    expect(slice?.has('omada-write')).toBe(false);
-  });
-
-  it('fails loudly on unknown categories and malformed access', () => {
-    expect(() => parseChatTools('infra:rw')).toThrow(/Invalid MCP_CHAT_TOOLS category/);
-    expect(() => parseChatTools('ha-core')).toThrow(/Invalid MCP_CHAT_TOOLS access/);
-    expect(() => parseChatTools('ha-core:x')).toThrow(/Invalid MCP_CHAT_TOOLS access/);
-  });
-});
-
-describe('resolveChatBindings', () => {
-  const haClient = {} as HaClient;
-  const omadaClient = {} as OmadaClient;
-
-  it('unset slice -> exactly the legacy 8 (zero-surprise upgrade)', () => {
-    const bindings = resolveChatBindings(undefined, { haClient, omadaClient });
-    expect(bindings.map((b) => b.operationId)).toEqual(LEGACY_OPERATION_IDS);
-  });
-
-  it('slice governs both legacy and tool bindings by category:access', () => {
-    const bindings = resolveChatBindings(parseChatTools('ha-core:r'), { haClient, omadaClient });
-    const ids = bindings.map((b) => b.operationId);
-    // ha-core reads, but NOT callService (write), NOT getHistory (ha-history)
-    expect(ids).toContain('getStates');
-    expect(ids).toContain('getDomainSummary'); // tool binding, ha-core:read
-    expect(ids).not.toContain('callService');
-    expect(ids).not.toContain('getHistory');
-    expect(ids).not.toContain('omada_browse');
-  });
-
-  it('omada categories activate the graph + SSID tools', () => {
-    const bindings = resolveChatBindings(parseChatTools('omada-read:r,omada-write:w'), {
-      haClient,
-      omadaClient,
-    });
-    const ids = bindings.map((b) => b.operationId);
-    expect(ids).toEqual(['omada_browse', 'omada_read', 'omada_setSsidEnabled']);
-  });
-
-  it('omada bindings are dropped from the face when no Omada client is configured', () => {
-    const bindings = resolveChatBindings(parseChatTools('omada-read:r'), { haClient });
-    expect(bindings).toEqual([]);
-  });
-
-  it('active omada tools appear in the generated spec as /api/tools/* paths', () => {
-    const bindings = resolveChatBindings(parseChatTools('ha-core:rw,ha-history:r,omada-read:r'), {
-      haClient,
-      omadaClient,
-    });
-    const spec = buildOpenApiSpec('http://x', bindings) as { paths: Record<string, unknown> };
-    expect(Object.keys(spec.paths)).toContain('/api/tools/omada_browse');
-    expect(Object.keys(spec.paths)).toContain('/api/tools/omada_read');
-    expect(Object.keys(spec.paths)).toContain('/api/states');
-    expect(Object.keys(spec.paths)).not.toContain('/api/tools/omada_setSsidEnabled');
-  });
-});
-
-describe('requiredPermissionFor', () => {
-  it('mirrors the MCP twin permissions on legacy routes', () => {
-    expect(requiredPermissionFor(LEGACY_BINDINGS, 'GET', '/api/states')).toBe(Permission.QUERY);
-    expect(requiredPermissionFor(LEGACY_BINDINGS, 'GET', '/api/states/light.x')).toBe(Permission.QUERY);
-    expect(requiredPermissionFor(LEGACY_BINDINGS, 'POST', '/api/services/light/turn_on')).toBe(
-      Permission.CONTROL
-    );
-    expect(requiredPermissionFor(LEGACY_BINDINGS, 'GET', '/api/nope')).toBeNull();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Dispatch behavior
-// ---------------------------------------------------------------------------
-
-function mockReq(method: string, permissions: number | undefined): IncomingMessage {
-  return {
-    method,
-    headers: { host: 'test' },
-    ...(permissions !== undefined ? { auth: { extra: { permissions } } } : {}),
-  } as unknown as IncomingMessage;
-}
-
-function makeDispatch(overrides: {
-  bindings: Parameters<typeof dispatchChatRequest>[3]['bindings'];
-  deps?: Parameters<typeof dispatchChatRequest>[3]['deps'];
-  body?: unknown;
-}) {
-  const sent: { status?: number; body?: unknown } = {};
-  const sendJson = vi.fn((_res: ServerResponse, status: number, body: unknown) => {
-    sent.status = status;
-    sent.body = body;
-  });
-  const run = (req: IncomingMessage, url: string) =>
-    dispatchChatRequest(req, {} as ServerResponse, url, {
-      bindings: overrides.bindings,
-      deps: overrides.deps ?? {},
-      parseBody: () => Promise.resolve(overrides.body),
-      sendJson,
-    });
-  return { run, sent };
-}
-
-describe('dispatchChatRequest', () => {
-  it('404s unknown routes without touching a client', async () => {
-    const { run, sent } = makeDispatch({ bindings: LEGACY_BINDINGS });
-    await run(mockReq('GET', 0xff), '/api/definitely-not-a-route');
-    expect(sent.status).toBe(404);
-  });
-
-  it('fails closed: missing permission mask -> 403', async () => {
-    const { run, sent } = makeDispatch({
-      bindings: LEGACY_BINDINGS,
-      deps: { haClient: {} as HaClient },
-    });
-    await run(mockReq('GET', undefined), '/api/states');
-    expect(sent.status).toBe(403);
-    expect((sent.body as { error: string }).error).toBe('Forbidden');
-  });
-
-  it('503s when a required client is not configured', async () => {
-    const { run, sent } = makeDispatch({ bindings: LEGACY_BINDINGS, deps: {} });
-    await run(mockReq('GET', 0xff), '/api/states');
-    expect(sent.status).toBe(503);
-  });
-
-  it('runs a legacy handler with decoded path params', async () => {
-    const haClient = {
-      getState: vi.fn().mockResolvedValue({ entity_id: 'light.living room', state: 'on' }),
-    } as unknown as HaClient;
-    const { run, sent } = makeDispatch({ bindings: LEGACY_BINDINGS, deps: { haClient } });
-    await run(mockReq('GET', Permission.QUERY), '/api/states/light.living%20room');
-    expect(sent.status).toBe(200);
-    expect((haClient as unknown as { getState: ReturnType<typeof vi.fn> }).getState).toHaveBeenCalledWith(
-      'light.living room'
-    );
-  });
-
-  it('dispatches a chat tool THROUGH the shared MCP handler (single source of truth)', async () => {
-    const omadaClient = {
-      setSsidEnabled: vi.fn().mockResolvedValue({ ssid: 'guest', enabled: false, applied: true }),
-    } as unknown as OmadaClient;
-    const bindings = resolveChatBindings(parseChatTools('omada-write:w'), { omadaClient });
-
-    const { run, sent } = makeDispatch({
-      bindings,
-      deps: { omadaClient },
-      body: { ssid: 'guest', enabled: false },
-    });
-    await run(mockReq('POST', Permission.CONTROL), '/api/tools/omada_setSsidEnabled');
-
-    expect(sent.status).toBe(200);
-    expect(sent.body).toMatchObject({ ssid: 'guest', enabled: false, applied: true });
-  });
-
-  it('rejects invalid tool arguments with 400 (zod validation, same as MCP face)', async () => {
-    const omadaClient = { setSsidEnabled: vi.fn() } as unknown as OmadaClient;
-    const bindings = resolveChatBindings(parseChatTools('omada-write:w'), { omadaClient });
-
-    const { run, sent } = makeDispatch({
-      bindings,
-      deps: { omadaClient },
-      body: { enabled: 'yes' }, // missing ssid; enabled wrong type
-    });
-    await run(mockReq('POST', Permission.CONTROL), '/api/tools/omada_setSsidEnabled');
-
-    expect(sent.status).toBe(400);
-    expect((sent.body as { error: string }).error).toBe('Invalid arguments');
-    expect(
-      (omadaClient as unknown as { setSsidEnabled: ReturnType<typeof vi.fn> }).setSsidEnabled
-    ).not.toHaveBeenCalled();
-  });
-
-  it("maps the shared handler's own permission denial to 403 (defense in depth)", async () => {
-    const omadaClient = { setSsidEnabled: vi.fn() } as unknown as OmadaClient;
-    // Force the binding past route-level RBAC by dispatching with CONTROL,
-    // then strip the bit the inner wrapToolHandler checks — impossible via the
-    // real dispatcher (same bit), so simulate a QUERY-only caller on a route
-    // whose binding requires QUERY but whose inner handler needs CONTROL:
-    // omada_read's per-path permissions provide exactly this split, but the
-    // simplest deterministic probe is a caller with route bit only.
-    const bindings = resolveChatBindings(parseChatTools('omada-read:r'), { omadaClient });
-    const { run, sent } = makeDispatch({
-      bindings,
-      deps: { omadaClient },
-      body: { path: '/sites' }, // resource path requiring more than QUERY (per manifest)
-    });
-    await run(mockReq('POST', Permission.QUERY), '/api/tools/omada_read');
-    // Either the manifest grants /sites to QUERY (200) or denies (403) — the
-    // invariant under test is that a denial surfaces as 403, never 200.
-    expect([200, 403, 500]).toContain(sent.status);
-    if (sent.status === 403) {
-      expect(JSON.stringify(sent.body)).toContain('Permission denied');
-    }
-  });
-});
-
-describe('zodToOpenApiSchema', () => {
-  it('converts the schema subset used by chat tools', () => {
-    const schema = z.object({
-      name: z.string().describe('The name'),
-      enabled: z.boolean(),
-      mode: z.enum(['a', 'b']).optional(),
-      count: z.number().int().min(1).optional(),
-      path: z.string().default('/'),
-    });
-    const out = zodToOpenApiSchema(schema) as {
-      type: string;
-      properties: Record<string, { type?: string; enum?: string[]; default?: unknown }>;
-      required?: string[];
-    };
-    expect(out.type).toBe('object');
-    expect(out.properties.name).toEqual({ type: 'string', description: 'The name' });
-    expect(out.properties.enabled.type).toBe('boolean');
-    expect(out.properties.mode.enum).toEqual(['a', 'b']);
-    expect(out.properties.path.default).toBe('/');
-    expect(out.required).toEqual(['name', 'enabled']);
-  });
-});

package/tests/server/common.test.ts

@@ -1,84 +0,0 @@
-/**
- * Server common functionality tests
- */
-
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createServer } from '../../src/server/common.js';
-
-// Mock HaClient
-const mockHaClient = {
-  getStates: vi.fn(),
-  getState: vi.fn(),
-  searchEntities: vi.fn(),
-  getEntitiesByDomain: vi.fn(),
-};
-
-// Mock the tools index
-vi.mock('../../src/tools/index.js', () => ({
-  registerAllTools: vi.fn(),
-}));
-
-// Mock the resources index
-vi.mock('../../src/resources/index.js', () => ({
-  registerAllResources: vi.fn(),
-}));
-
-describe('createServer', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it('should create MCP server with correct name and version', () => {
-    const server = createServer({ haClient: mockHaClient as any });
-
-    expect(server).toBeDefined();
-    // Server should have the correct configuration
-    // Note: We can't easily test internal properties, but we can verify it was created
-  });
-
-  it('should register all tools on server creation', async () => {
-    const { registerAllTools } = await import('../../src/tools/index.js');
-    const server = createServer({ haClient: mockHaClient as any });
-
-    expect(registerAllTools).toHaveBeenCalledWith({
-      server,
-      haClient: mockHaClient,
-      omadaClient: undefined,
-      aiClient: undefined,
-    });
-  });
-
-  it('should create server with tools capability', () => {
-    const server = createServer({ haClient: mockHaClient as any });
-
-    // The server should be created successfully
-    expect(server).toBeDefined();
-    expect(typeof server.connect).toBe('function');
-  });
-
-  it('should work without haClient (Omada-only mode)', () => {
-    const server = createServer({});
-
-    expect(server).toBeDefined();
-    expect(typeof server.connect).toBe('function');
-  });
-
-  it('should accept omadaClient and aiClient', async () => {
-    const { registerAllTools } = await import('../../src/tools/index.js');
-    const mockOmadaClient = { listSites: vi.fn() };
-    const mockAiClient = { analyze: vi.fn() };
-
-    const server = createServer({
-      haClient: mockHaClient as any,
-      omadaClient: mockOmadaClient as any,
-      aiClient: mockAiClient as any,
-    });
-
-    expect(registerAllTools).toHaveBeenCalledWith({
-      server,
-      haClient: mockHaClient,
-      omadaClient: mockOmadaClient,
-      aiClient: mockAiClient,
-    });
-  });
-});