@cachly-dev/mcp-server 0.10.26 → 0.10.40

package/src/__tests__/e2e/cli.test.ts

@@ -0,0 +1,228 @@
+/**
+ * E2E: CLI command smoke tests
+ *
+ * Spawns the actual CLI binary and verifies output + exit codes.
+ * Uses the built dist/ — run `npm run build` first.
+ *
+ * Requires: E2E_JWT, E2E_INSTANCE_ID (for health/badge/share)
+ * Run: npm run build && npx vitest run src/__tests__/e2e/cli.test.ts
+ */
+
+import { describe, it, expect } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { cfg } from './config.js';
+
+const BIN = join(import.meta.dirname, '../../../../dist/index.js');
+const TIMEOUT_MS = 30_000;
+
+function run(
+  args: string[],
+  env: Record<string, string> = {},
+  timeoutMs = TIMEOUT_MS,
+): { stdout: string; stderr: string; code: number | null } {
+  const result = spawnSync(process.execPath, [BIN, ...args], {
+    env: {
+      ...process.env,
+      CACHLY_JWT: cfg.jwt,
+      CACHLY_BRAIN_INSTANCE_ID: cfg.instanceId,
+      CACHLY_API_URL: cfg.apiUrl,
+      ...env,
+    },
+    timeout: timeoutMs,
+    encoding: 'utf8',
+  });
+  return {
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+    code:   result.status,
+  };
+}
+
+describe('cachly (no args) — help output', () => {
+  it('exits 0', () => {
+    const { code } = run([]);
+    expect(code).toBe(0);
+  });
+
+  it('prints cachly branding', () => {
+    const { stdout } = run([]);
+    expect(stdout).toMatch(/cachly/i);
+  });
+
+  it('lists setup command', () => {
+    const { stdout } = run([]);
+    expect(stdout).toContain('setup');
+  });
+
+  it('lists demo command', () => {
+    const { stdout } = run([]);
+    expect(stdout).toContain('demo');
+  });
+
+  it('mentions 1–5 minutes (no false "30 seconds" promise)', () => {
+    const { stdout } = run([]);
+    // Must NOT contain "30 seconds" — we corrected this in v0.10.19+
+    expect(stdout).not.toContain('30 seconds');
+    expect(stdout).not.toMatch(/\b30s\b/);
+  });
+
+  it('mentions free forever', () => {
+    const { stdout } = run([]);
+    expect(stdout.toLowerCase()).toMatch(/free|kostenlos/);
+  });
+});
+
+describe('cachly upgrade', () => {
+  it('exits 0', () => {
+    const { code } = run(['upgrade']);
+    expect(code).toBe(0);
+  });
+
+  it('prints current version', () => {
+    const { stdout } = run(['upgrade']);
+    expect(stdout).toMatch(/\d+\.\d+\.\d+/);
+  });
+
+  it('version string is valid semver', () => {
+    const { stdout } = run(['upgrade']);
+    const match = stdout.match(/(\d+\.\d+\.\d+)/);
+    expect(match).not.toBeNull();
+    const parts = match![1].split('.').map(Number);
+    expect(parts).toHaveLength(3);
+    parts.forEach((p) => expect(Number.isInteger(p)).toBe(true));
+  });
+
+  it('does not crash on npm registry timeout (graceful error)', () => {
+    const { code } = run(['upgrade'], { CACHLY_API_URL: 'http://127.0.0.1:1' });
+    // Should exit 0 or 1 — never crash with unhandled exception
+    expect([0, 1]).toContain(code);
+  });
+});
+
+describe('cachly demo', () => {
+  it('exits 0 even without credentials', () => {
+    const { code } = run(['demo'], { CACHLY_JWT: '', CACHLY_BRAIN_INSTANCE_ID: '' }, 15_000);
+    expect(code).toBe(0);
+  });
+
+  it('prints Brain Preview header', () => {
+    const { stdout } = run(['demo'], { CACHLY_JWT: '', CACHLY_BRAIN_INSTANCE_ID: '' }, 15_000);
+    expect(stdout).toMatch(/brain|preview|cachly/i);
+  });
+
+  it('prints setup command at the end', () => {
+    const { stdout } = run(['demo'], { CACHLY_JWT: '', CACHLY_BRAIN_INSTANCE_ID: '' }, 15_000);
+    expect(stdout).toContain('setup');
+  });
+
+  it('does not crash with invalid git repo (fallback gracefully)', () => {
+    const { code } = run(['demo'], {
+      CACHLY_JWT: '',
+      CACHLY_BRAIN_INSTANCE_ID: '',
+    }, 15_000);
+    expect([0, 1]).toContain(code); // never 2+ (unhandled crash)
+  });
+
+  it('shows Brain Level (valid level name)', () => {
+    const { stdout } = run(['demo'], { CACHLY_JWT: '', CACHLY_BRAIN_INSTANCE_ID: '' }, 15_000);
+    // Demo must show a valid brain level — Apprentice for new projects is expected
+    expect(stdout).toMatch(/Apprentice|Explorer|Expert|Architect|Oracle/);
+  });
+
+  it('shows 1–5 minutes in the CTA (no "30 seconds")', () => {
+    const { stdout } = run(['demo'], { CACHLY_JWT: '', CACHLY_BRAIN_INSTANCE_ID: '' }, 15_000);
+    expect(stdout).toContain('1–5 minutes');
+    expect(stdout).not.toContain('30 seconds');
+  });
+
+  it('shows "never repeat" instead of "remember" for bug fixes', () => {
+    const { stdout } = run(['demo'], { CACHLY_JWT: '', CACHLY_BRAIN_INSTANCE_ID: '' }, 15_000);
+    // Copy should say "never repeat" not "remember" — old wording was weaker
+    if (stdout.includes('Bug fixes')) {
+      expect(stdout).toMatch(/never repeat/i);
+    }
+  });
+});
+
+describe('cachly health', () => {
+  it('exits 0 with valid credentials', () => {
+    if (!cfg.jwt || !cfg.instanceId) return;
+    const { code } = run(['health']);
+    expect(code).toBe(0);
+  });
+
+  it('prints API status', () => {
+    if (!cfg.jwt || !cfg.instanceId) return;
+    const { stdout } = run(['health']);
+    expect(stdout.toLowerCase()).toMatch(/api|status|ok|connected/);
+  });
+
+  it('prints editor detection results', () => {
+    if (!cfg.jwt || !cfg.instanceId) return;
+    const { stdout } = run(['health']);
+    expect(stdout.toLowerCase()).toMatch(/editor|claude|cursor|copilot|windsurf/);
+  });
+
+  it('exits non-zero without JWT', () => {
+    const { code, stdout } = run(['health'], { CACHLY_JWT: '' });
+    // Either exits non-zero, or prints an error message
+    const hasError = code !== 0 || stdout.toLowerCase().includes('not set') || stdout.toLowerCase().includes('sign in');
+    expect(hasError).toBe(true);
+  });
+});
+
+describe('cachly badge', () => {
+  it('exits 0 with valid instance', () => {
+    if (!cfg.jwt || !cfg.instanceId) return;
+    const { code } = run(['badge']);
+    expect(code).toBe(0);
+  });
+
+  it('outputs a markdown badge snippet', () => {
+    if (!cfg.jwt || !cfg.instanceId) return;
+    const { stdout } = run(['badge']);
+    expect(stdout).toMatch(/\[!\[.*cachly.*\]\(.*\)\]\(.*\)/i);
+  });
+
+  it('badge URL points to api.cachly.dev', () => {
+    if (!cfg.jwt || !cfg.instanceId) return;
+    const { stdout } = run(['badge']);
+    expect(stdout).toContain('api.cachly.dev');
+  });
+});
+
+describe('cachly share', () => {
+  it('exits 0 with valid credentials', () => {
+    if (!cfg.jwt || !cfg.instanceId) return;
+    const { code } = run(['share']);
+    expect(code).toBe(0);
+  });
+
+  it('output contains UTM share URL', () => {
+    if (!cfg.jwt || !cfg.instanceId) return;
+    const { stdout } = run(['share']);
+    expect(stdout).toContain('utm_source=x');
+  });
+
+  it('output contains tweet text', () => {
+    if (!cfg.jwt || !cfg.instanceId) return;
+    const { stdout } = run(['share']);
+    expect(stdout.toLowerCase()).toMatch(/tweet|x\.com|twitter/i);
+  });
+});
+
+describe('cachly invite', () => {
+  it('exits 0 and prints invite link', () => {
+    if (!cfg.jwt || !cfg.instanceId) return;
+    const { code, stdout } = run(['invite']);
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/invite|join|cachly\.dev/i);
+  });
+
+  it('does NOT mention 30 seconds (1-5 minutes only)', () => {
+    if (!cfg.jwt || !cfg.instanceId) return;
+    const { stdout } = run(['invite']);
+    expect(stdout).not.toContain('30 seconds');
+  });
+});

package/src/__tests__/e2e/config.ts

@@ -0,0 +1,53 @@
+/**
+ * E2E test configuration — read from environment variables.
+ *
+ * Required for full e2e run:
+ *   E2E_API_URL       Base URL of the API server  (default: https://api.cachly.dev)
+ *   E2E_JWT           Valid Keycloak JWT for a test user
+ *   E2E_INSTANCE_ID   ID of a pre-provisioned (active) Brain instance
+ *   E2E_API_KEY       Redis password for the test instance
+ *   E2E_REDIS_HOST    Redis host for the test instance
+ *   E2E_REDIS_PORT    Redis port                  (default: 6380)
+ *   E2E_REDIS_TLS     "true" if TLS is required   (default: true)
+ *
+ * Optional:
+ *   E2E_SKIP_SLOW     "true" to skip provisioning + device-flow tests
+ */
+
+export const cfg = {
+  apiUrl:     process.env.E2E_API_URL     ?? 'https://api.cachly.dev',
+  jwt:        process.env.E2E_JWT         ?? '',
+  instanceId: process.env.E2E_INSTANCE_ID ?? '',
+  apiKey:     process.env.E2E_API_KEY     ?? '',
+  redisHost:  process.env.E2E_REDIS_HOST  ?? '',
+  redisPort:  Number(process.env.E2E_REDIS_PORT ?? '6380'),
+  redisTls:   (process.env.E2E_REDIS_TLS ?? 'true') !== 'false',
+  skipSlow:   process.env.E2E_SKIP_SLOW   === 'true',
+};
+
+export function requireAuth() {
+  if (!cfg.jwt)        throw new Error('E2E_JWT is required — run: export E2E_JWT=<your-token>');
+  if (!cfg.instanceId) throw new Error('E2E_INSTANCE_ID is required');
+}
+
+export function requireRedis() {
+  requireAuth();
+  if (!cfg.apiKey)    throw new Error('E2E_API_KEY is required');
+  if (!cfg.redisHost) throw new Error('E2E_REDIS_HOST is required');
+}
+
+export async function apiGet(path: string, jwt = cfg.jwt) {
+  const res = await fetch(`${cfg.apiUrl}${path}`, {
+    headers: { Authorization: `Bearer ${jwt}`, 'Content-Type': 'application/json' },
+  });
+  return { status: res.status, body: await res.json().catch(() => null) };
+}
+
+export async function apiPost(path: string, body: unknown, jwt = cfg.jwt) {
+  const res = await fetch(`${cfg.apiUrl}${path}`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${jwt}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  return { status: res.status, body: await res.json().catch(() => null) };
+}

package/src/__tests__/e2e/funnel.test.ts

@@ -0,0 +1,99 @@
+/**
+ * E2E: Activation funnel telemetry
+ *
+ * Verifies that every funnel event:
+ *   setup_started → device_flow_started → device_flow_completed →
+ *   first_call_success → onboarding_completed
+ *
+ * is accepted by the API and (after Docker redeploy) persisted to mcp_events.
+ *
+ * Requires: E2E_JWT, E2E_INSTANCE_ID
+ * Run: npx vitest run src/__tests__/e2e/funnel.test.ts
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { cfg, requireAuth, apiGet } from './config.js';
+
+beforeAll(() => requireAuth());
+
+const FUNNEL_EVENTS = [
+  'setup_started',
+  'device_flow_started',
+  'device_flow_completed',
+  'auto_provision_started',
+  'first_call_success',
+  'onboarding_completed',
+] as const;
+
+async function postTelemetry(event: string, extra: Record<string, unknown> = {}) {
+  return fetch(`${cfg.apiUrl}/api/v1/telemetry/mcp`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      event,
+      version: '0.10.24',
+      editor: 'claude',
+      source: 'e2e',
+      jwt: cfg.jwt,
+      instance_id: cfg.instanceId,
+      ...extra,
+    }),
+  });
+}
+
+describe('Funnel event acceptance', () => {
+  for (const event of FUNNEL_EVENTS) {
+    it(`POST ${event} returns 2xx`, async () => {
+      const res = await postTelemetry(event);
+      expect(res.status).toBeGreaterThanOrEqual(200);
+      expect(res.status).toBeLessThan(300);
+    });
+  }
+
+  it('unknown event is accepted (API is permissive)', async () => {
+    const res = await postTelemetry('e2e_unknown_event_xyz');
+    expect(res.status).toBeGreaterThanOrEqual(200);
+    expect(res.status).toBeLessThan(300);
+  });
+
+  it('event with no jwt is still accepted', async () => {
+    const res = await fetch(`${cfg.apiUrl}/api/v1/telemetry/mcp`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ event: 'setup_started', version: '0.10.24', editor: 'cursor', source: 'mcp' }),
+    });
+    expect(res.status).toBeGreaterThanOrEqual(200);
+    expect(res.status).toBeLessThan(300);
+  });
+});
+
+describe('first_call_success attribution', () => {
+  it('fires with tool and instance_id fields', async () => {
+    const res = await postTelemetry('first_call_success', {
+      tool: 'brain_recall',
+      instance_id: cfg.instanceId,
+    });
+    expect(res.status).toBeGreaterThanOrEqual(200);
+    expect(res.status).toBeLessThan(300);
+  });
+
+  it('fires for different tools', async () => {
+    for (const tool of ['brain_store', 'session_start', 'causal_trace']) {
+      const res = await postTelemetry('first_call_success', { tool, instance_id: cfg.instanceId });
+      expect(res.status).toBeGreaterThanOrEqual(200);
+      expect(res.status).toBeLessThan(300);
+    }
+  });
+});
+
+describe('Funnel stats endpoint (post-deploy only)', () => {
+  it('daily summary telemetry query is reachable', async () => {
+    // This verifies the mcp_events table exists after Docker redeploy.
+    // Hits /api/v1/admin/funnel if it exists, otherwise checks telemetry endpoint.
+    const { status } = await apiGet('/api/v1/admin/funnel');
+    // 200 = table exists and endpoint works
+    // 404 = endpoint not exposed (acceptable — internal only via watchdog)
+    // 401/403 = auth required (also acceptable)
+    expect([200, 401, 403, 404]).toContain(status);
+  });
+});

package/src/__tests__/e2e/mcp-tools.test.ts

@@ -0,0 +1,191 @@
+/**
+ * E2E: MCP tool calls via live Redis connection
+ *
+ * Requires: E2E_JWT, E2E_INSTANCE_ID, E2E_API_KEY, E2E_REDIS_HOST
+ * Run: npx vitest run src/__tests__/e2e/mcp-tools.test.ts
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { Redis } from 'ioredis';
+import { cfg, requireRedis } from './config.js';
+
+import { handleBrainTool } from '../../handlers/brain.js';
+import { handleContextTool } from '../../handlers/context.js';
+
+let redis: Redis;
+
+function getConn(_id: string): Promise<Redis> {
+  return Promise.resolve(redis);
+}
+
+// ApiFetch matches the generic signature the handlers expect
+async function apiFetch<T>(path: string, opts?: RequestInit): Promise<T> {
+  const res = await fetch(`${cfg.apiUrl}${path}`, {
+    ...opts,
+    headers: {
+      Authorization: `Bearer ${cfg.jwt}`,
+      'Content-Type': 'application/json',
+      ...(opts?.headers as Record<string, string> ?? {}),
+    },
+  });
+  return res.json() as Promise<T>;
+}
+
+beforeAll(async () => {
+  requireRedis();
+  redis = new Redis({
+    host: cfg.redisHost,
+    port: cfg.redisPort,
+    password: cfg.apiKey,
+    tls: cfg.redisTls ? {} : undefined,
+    lazyConnect: true,
+    connectTimeout: 8000,
+  });
+  await redis.connect();
+  expect(await redis.ping()).toBe('PONG');
+});
+
+afterAll(async () => {
+  await redis.quit();
+});
+
+describe('Redis connectivity', () => {
+  it('PING returns PONG', async () => {
+    expect(await redis.ping()).toBe('PONG');
+  });
+
+  it('SET / GET round-trip works', async () => {
+    const key = `e2e:probe:${Date.now()}`;
+    await redis.set(key, 'ok', 'EX', 60);
+    expect(await redis.get(key)).toBe('ok');
+    await redis.del(key);
+  });
+});
+
+describe('session_start', () => {
+  it('returns a non-empty briefing string', async () => {
+    // session_start is handled by handleBrainTool, not handleContextTool
+    const result = await handleBrainTool(
+      'session_start',
+      { instance_id: cfg.instanceId, focus: 'e2e-test' },
+      getConn,
+      apiFetch,
+    );
+    expect(typeof result === 'string' || result === null).toBe(true);
+    if (result !== null) expect(result.length).toBeGreaterThan(0);
+  });
+});
+
+describe('brain_store + brain_recall', () => {
+  const marker = `E2E-lesson-${Date.now()}`;
+
+  it('brain_store returns without error', async () => {
+    const result = await handleBrainTool(
+      'brain_store',
+      {
+        instance_id: cfg.instanceId,
+        lesson: `${marker}: Redis race condition fixed with WAIT command`,
+        tags: ['e2e', 'redis', 'race-condition'],
+        severity: 'info',
+      },
+      getConn,
+      apiFetch,
+    );
+    // Returns a string (confirmation message) or null — never throws
+    expect(result === null || typeof result === 'string').toBe(true);
+  });
+
+  it('brain_recall finds the stored lesson', async () => {
+    await new Promise((r) => setTimeout(r, 400));
+    const result = await handleBrainTool(
+      'brain_recall',
+      {
+        instance_id: cfg.instanceId,
+        query: marker,
+        limit: 5,
+      },
+      getConn,
+      apiFetch,
+    );
+    // Result is a formatted string with lessons, or null if empty
+    if (result !== null) {
+      expect(result).toContain(marker.split(':')[0]);
+    }
+  });
+
+  it('brain_recall handles unknown query gracefully (no throw)', async () => {
+    const result = await handleBrainTool(
+      'brain_recall',
+      { instance_id: cfg.instanceId, query: 'xyzzy-no-match-e2e-99887766', limit: 3 },
+      getConn,
+      apiFetch,
+    );
+    expect(result === null || typeof result === 'string').toBe(true);
+  });
+});
+
+describe('brain_from_git (smoke)', () => {
+  it('responds without throwing', async () => {
+    const result = await handleBrainTool(
+      'brain_from_git',
+      { instance_id: cfg.instanceId, max_commits: 5 },
+      getConn,
+      apiFetch,
+    );
+    expect(result === null || typeof result === 'string').toBe(true);
+  });
+});
+
+describe('causal_trace', () => {
+  it('returns a trace string without throwing', async () => {
+    const result = await handleBrainTool(
+      'causal_trace',
+      { instance_id: cfg.instanceId, problem: 'auth breaks after restart', depth: 2 },
+      getConn,
+      apiFetch,
+    );
+    expect(result === null || typeof result === 'string').toBe(true);
+  });
+});
+
+describe('brain_predict', () => {
+  it('returns a prediction string without throwing', async () => {
+    const result = await handleBrainTool(
+      'brain_predict',
+      { instance_id: cfg.instanceId, target: 'deploy' },
+      getConn,
+      apiFetch,
+    );
+    expect(result === null || typeof result === 'string').toBe(true);
+  });
+});
+
+describe('session_end', () => {
+  it('persists session summary without throwing', async () => {
+    const result = await handleContextTool(
+      'session_end',
+      {
+        instance_id: cfg.instanceId,
+        summary: 'E2E test session completed.',
+        lessons: ['brain_recall round-trip verified', 'causal_trace responded correctly'],
+      },
+      getConn,
+      apiFetch,
+    );
+    expect(result === null || typeof result === 'string').toBe(true);
+  });
+});
+
+describe('brain_health', () => {
+  it('returns a health string containing a positive indicator', async () => {
+    const result = await handleBrainTool(
+      'brain_health',
+      { instance_id: cfg.instanceId },
+      getConn,
+      apiFetch,
+    );
+    if (result !== null) {
+      expect(result.toLowerCase()).toMatch(/ok|healthy|active|ping|pong|connected/);
+    }
+  });
+});

package/src/__tests__/e2e/provisioning.test.ts

@@ -0,0 +1,128 @@
+/**
+ * E2E: Provisioning flow
+ *
+ * Tests the full instance lifecycle:
+ *   create → poll until active (or timeout) → connect → delete
+ *
+ * ⚠️  This test creates a real instance and WILL be billed if not deleted.
+ *     It always cleans up in afterAll, even on failure.
+ *
+ * Skipped if E2E_SKIP_SLOW=true.
+ *
+ * Requires: E2E_JWT
+ * Run: npx vitest run src/__tests__/e2e/provisioning.test.ts --reporter=verbose
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { cfg, requireAuth, apiGet, apiPost } from './config.js';
+
+beforeAll(() => {
+  requireAuth();
+  if (cfg.skipSlow) {
+    console.log('Skipping provisioning tests (E2E_SKIP_SLOW=true)');
+  }
+});
+
+let createdInstanceId: string | null = null;
+
+afterAll(async () => {
+  if (!createdInstanceId) return;
+  try {
+    const res = await fetch(`${cfg.apiUrl}/api/v1/instances/${createdInstanceId}`, {
+      method: 'DELETE',
+      headers: { Authorization: `Bearer ${cfg.jwt}` },
+    });
+    console.log(`Cleanup: deleted instance ${createdInstanceId} → ${res.status}`);
+  } catch (e) {
+    console.warn(`Cleanup failed for ${createdInstanceId}:`, e);
+  }
+});
+
+describe('Instance provisioning lifecycle', () => {
+  it.skipIf(cfg.skipSlow)('POST /api/v1/instances creates a new free instance', async () => {
+    const { status, body } = await apiPost('/api/v1/instances', {
+      name: `e2e-test-${Date.now()}`,
+      tier: 'free',
+    });
+    expect([200, 201]).toContain(status);
+    const inst = body as Record<string, unknown>;
+    expect(typeof inst.id).toBe('string');
+    expect(inst.status).toMatch(/^(provisioning|active)$/);
+    createdInstanceId = inst.id as string;
+  });
+
+  it.skipIf(cfg.skipSlow)('instance status transitions from provisioning → active within 5 min', async () => {
+    if (!createdInstanceId) return;
+
+    const maxWaitMs = 5 * 60 * 1000; // 5 minutes
+    const pollMs    = 10_000;         // poll every 10 seconds
+    const start     = Date.now();
+    let status      = 'provisioning';
+
+    while (Date.now() - start < maxWaitMs) {
+      await new Promise((r) => setTimeout(r, pollMs));
+      const { body } = await apiGet(`/api/v1/instances/${createdInstanceId}`);
+      status = (body as Record<string, unknown>).status as string;
+      console.log(`  [${Math.round((Date.now() - start) / 1000)}s] status: ${status}`);
+      if (status === 'active') break;
+      if (status === 'failed')  break;
+    }
+
+    expect(status).toBe('active');
+  }, 6 * 60 * 1000); // vitest timeout: 6 min
+
+  it.skipIf(cfg.skipSlow)('active instance returns valid connection details', async () => {
+    if (!createdInstanceId) return;
+    const { status, body } = await apiGet(`/api/v1/instances/${createdInstanceId}/connection`);
+    expect(status).toBe(200);
+    const conn = body as Record<string, unknown>;
+    expect(typeof conn.host).toBe('string');
+    expect(Number(conn.port)).toBeGreaterThan(0);
+    expect(typeof conn.password).toBe('string');
+  });
+
+  it.skipIf(cfg.skipSlow)('can PING the provisioned Redis', async () => {
+    if (!createdInstanceId) return;
+    const { body } = await apiGet(`/api/v1/instances/${createdInstanceId}/connection`);
+    const conn = body as Record<string, unknown>;
+
+    const { Redis: RedisClass } = await import('ioredis');
+    const r = new RedisClass({
+      host: conn.host as string,
+      port: Number(conn.port),
+      password: conn.password as string,
+      tls: cfg.redisTls ? {} : undefined,
+      connectTimeout: 8000,
+      lazyConnect: true,
+    });
+    try {
+      await r.connect();
+      expect(await r.ping()).toBe('PONG');
+    } finally {
+      await r.quit();
+    }
+  });
+});
+
+describe('Provisioning status — failed instance handling', () => {
+  it('failed status returns meaningful error (not 500) from connection endpoint', async () => {
+    // We use a known-bad UUID to simulate a missing/failed instance
+    const { status } = await apiGet('/api/v1/instances/00000000-0000-0000-0000-000000000000/connection');
+    // Should be a client error (4xx), never a server error (5xx)
+    expect(status).toBeGreaterThanOrEqual(400);
+    expect(status).toBeLessThan(500);
+  });
+});
+
+describe('Auto-provision via /instances/auto', () => {
+  it.skipIf(cfg.skipSlow)('POST /api/v1/instances/auto returns instance id', async () => {
+    const { status, body } = await apiPost('/api/v1/instances/auto', {});
+    // 200 = existing instance returned
+    // 201 = new instance created
+    // 409 = already has an instance (also fine)
+    expect([200, 201, 409]).toContain(status);
+    if (status !== 409) {
+      expect(typeof (body as Record<string, unknown>).id).toBe('string');
+    }
+  });
+});