@cachly-dev/mcp-server 0.10.26 → 0.10.40

package/dist/__tests__/auth.test.js

@@ -0,0 +1,107 @@
+import { describe, it, expect } from 'vitest';
+import { ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { jwtExpiryMs, checkJwt, handleApiError } from '../auth.js';
+function makeJwt(payload) {
+    const header = Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })).toString('base64url');
+    const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
+    return `${header}.${body}.fakesig`;
+}
+const nowSec = () => Math.floor(Date.now() / 1000);
+describe('jwtExpiryMs', () => {
+    it('returns null for an empty string', () => {
+        expect(jwtExpiryMs('')).toBeNull();
+    });
+    it('returns null for a plain (non-JWT) string', () => {
+        expect(jwtExpiryMs('not-a-token')).toBeNull();
+    });
+    it('returns null when the JWT has only two parts', () => {
+        expect(jwtExpiryMs('header.payload')).toBeNull();
+    });
+    it('returns null when the JWT has four parts', () => {
+        expect(jwtExpiryMs('a.b.c.d')).toBeNull();
+    });
+    it('returns null when the payload base64 is invalid', () => {
+        expect(jwtExpiryMs('header.!!!.sig')).toBeNull();
+    });
+    it('returns null when the payload has no exp field', () => {
+        expect(jwtExpiryMs(makeJwt({ sub: 'user-123', iat: nowSec() }))).toBeNull();
+    });
+    it('returns null when exp is 0', () => {
+        expect(jwtExpiryMs(makeJwt({ exp: 0 }))).toBeNull();
+    });
+    it('converts exp (seconds) to milliseconds', () => {
+        const expSec = nowSec() + 3600;
+        expect(jwtExpiryMs(makeJwt({ exp: expSec }))).toBe(expSec * 1000);
+    });
+    it('returns a past timestamp for an expired token', () => {
+        expect(jwtExpiryMs(makeJwt({ exp: nowSec() - 300 }))).toBeLessThan(Date.now());
+    });
+    it('returns a future timestamp for a valid token', () => {
+        expect(jwtExpiryMs(makeJwt({ exp: nowSec() + 86400 }))).toBeGreaterThan(Date.now());
+    });
+    it('handles a token expiring in less than 60 minutes', () => {
+        const expSec = nowSec() + 30 * 60;
+        const result = jwtExpiryMs(makeJwt({ exp: expSec }));
+        const minsLeft = Math.floor((result - Date.now()) / 60_000);
+        expect(minsLeft).toBeGreaterThanOrEqual(29);
+        expect(minsLeft).toBeLessThanOrEqual(30);
+    });
+    it('ignores extra claims', () => {
+        const expSec = nowSec() + 3600;
+        expect(jwtExpiryMs(makeJwt({ sub: 'u', iat: nowSec(), exp: expSec, plan: 'free' }))).toBe(expSec * 1000);
+    });
+    it('handles padding-free base64url payloads', () => {
+        // base64url (no =) — Buffer.from handles this natively
+        const expSec = nowSec() + 7200;
+        expect(jwtExpiryMs(makeJwt({ exp: expSec, x: 'a' }))).toBe(expSec * 1000);
+    });
+});
+describe('checkJwt', () => {
+    it('throws InvalidRequest when jwt is empty', () => {
+        expect(() => checkJwt('')).toThrowError(expect.objectContaining({ code: ErrorCode.InvalidRequest, message: expect.stringContaining('CACHLY_JWT env var not set') }));
+    });
+    it('throws with setup URL when jwt is missing', () => {
+        expect(() => checkJwt('')).toThrowError(expect.objectContaining({ message: expect.stringContaining('cachly.dev/setup-ai') }));
+    });
+    it('throws InvalidRequest with expiry timestamp for an expired token', () => {
+        const expSec = nowSec() - 60;
+        const token = makeJwt({ exp: expSec });
+        expect(() => checkJwt(token)).toThrowError(expect.objectContaining({
+            code: ErrorCode.InvalidRequest,
+            message: expect.stringContaining('expired at'),
+        }));
+    });
+    it('does not throw for a valid non-expired token', () => {
+        expect(() => checkJwt(makeJwt({ exp: nowSec() + 3600 }))).not.toThrow();
+    });
+    it('does not throw for a token with no exp claim', () => {
+        expect(() => checkJwt(makeJwt({ sub: 'user' }))).not.toThrow();
+    });
+});
+describe('handleApiError', () => {
+    it('throws InvalidRequest for 401 with the detail message', () => {
+        expect(() => handleApiError(401, 'token expired')).toThrowError(expect.objectContaining({
+            code: ErrorCode.InvalidRequest,
+            message: expect.stringContaining('Authentication failed (401): token expired'),
+        }));
+    });
+    it('throws InvalidRequest for 403 with the detail message', () => {
+        expect(() => handleApiError(403, 'plan limit reached')).toThrowError(expect.objectContaining({
+            code: ErrorCode.InvalidRequest,
+            message: expect.stringContaining('Access denied (403): plan limit reached'),
+        }));
+    });
+    it('throws InternalError for other status codes', () => {
+        expect(() => handleApiError(500, 'server crash')).toThrowError(expect.objectContaining({
+            code: ErrorCode.InternalError,
+            message: expect.stringContaining('cachly API error 500: server crash'),
+        }));
+    });
+    it('includes the cachly.dev/setup-ai link for 401 errors', () => {
+        expect(() => handleApiError(401, 'Unauthorized')).toThrowError(expect.objectContaining({ message: expect.stringContaining('cachly.dev/setup-ai') }));
+    });
+    it('includes account access hint for 403 errors', () => {
+        expect(() => handleApiError(403, 'Forbidden')).toThrowError(expect.objectContaining({ message: expect.stringContaining('access to this resource') }));
+    });
+});
+//# sourceMappingURL=auth.test.js.map

package/dist/__tests__/auth.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.test.js","sourceRoot":"","sources":["../../src/__tests__/auth.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/e2e/api-auth.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * E2E: Authenticated API endpoints
+ *
+ * Requires: E2E_JWT, E2E_INSTANCE_ID
+ * Run: npx vitest run src/__tests__/e2e/api-auth.test.ts
+ */
+export {};

package/dist/__tests__/e2e/api-auth.test.js

@@ -0,0 +1,162 @@
+/**
+ * E2E: Authenticated API endpoints
+ *
+ * Requires: E2E_JWT, E2E_INSTANCE_ID
+ * Run: npx vitest run src/__tests__/e2e/api-auth.test.ts
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import { cfg, requireAuth, apiGet, apiPost } from './config.js';
+beforeAll(() => requireAuth());
+describe('Auth guard', () => {
+    it('GET /api/v1/instances without token returns 401', async () => {
+        const { status } = await apiGet('/api/v1/instances', '');
+        expect(status).toBe(401);
+    });
+    it('GET /api/v1/instances with invalid token returns 401', async () => {
+        const { status } = await apiGet('/api/v1/instances', 'not-a-real-token');
+        expect(status).toBe(401);
+    });
+    it('GET /api/v1/instances with valid token returns 200', async () => {
+        const { status } = await apiGet('/api/v1/instances');
+        expect(status).toBe(200);
+    });
+});
+describe('Instances API', () => {
+    // API returns { data: Instance[], count: number }
+    it('returns object with data array', async () => {
+        const { body } = await apiGet('/api/v1/instances');
+        const b = body;
+        expect(Array.isArray(b.data)).toBe(true);
+        expect(typeof b.count).toBe('number');
+    });
+    it('each instance has required fields', async () => {
+        const { body } = await apiGet('/api/v1/instances');
+        const instances = (body.data) ?? [];
+        if (instances.length === 0)
+            return; // fresh account — skip
+        for (const inst of instances) {
+            expect(typeof inst.id).toBe('string');
+            expect(typeof inst.name).toBe('string');
+            expect(typeof inst.status).toBe('string');
+            expect(typeof inst.tier).toBe('string');
+        }
+    });
+    it('test instance is present and running', async () => {
+        const { body } = await apiGet('/api/v1/instances');
+        const instances = (body.data) ?? [];
+        const found = instances.find((i) => i.id === cfg.instanceId);
+        expect(found).toBeDefined();
+        expect(found.status).toBe('running');
+    });
+});
+describe('Single instance GET', () => {
+    it('returns 200 for test instance', async () => {
+        const { status } = await apiGet(`/api/v1/instances/${cfg.instanceId}`);
+        expect(status).toBe(200);
+    });
+    it('returns 404 for non-existent instance', async () => {
+        const { status } = await apiGet('/api/v1/instances/00000000-0000-0000-0000-000000000000');
+        expect([403, 404]).toContain(status);
+    });
+    it('instance body has id, status running, tier, name', async () => {
+        const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}`);
+        const inst = body;
+        expect(inst.id).toBe(cfg.instanceId);
+        expect(inst.status).toBe('running');
+        expect(typeof inst.tier).toBe('string');
+        expect(typeof inst.name).toBe('string');
+    });
+});
+describe('Connection endpoint', () => {
+    it('returns 200 with connection details for running instance', async () => {
+        const { status, body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/connection`);
+        expect(status).toBe(200);
+        const conn = body;
+        expect(typeof conn.host).toBe('string');
+        expect(typeof conn.port).toBe('number');
+        expect(typeof conn.password).toBe('string');
+        expect(conn.host.length).toBeGreaterThan(3);
+    });
+    it('connection host is not localhost (prod/dev has real host)', async () => {
+        const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/connection`);
+        const conn = body;
+        expect(String(conn.host)).not.toBe('localhost');
+        expect(String(conn.host)).not.toBe('127.0.0.1');
+    });
+    it('port is within valid Redis range', async () => {
+        const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/connection`);
+        const conn = body;
+        expect(Number(conn.port)).toBeGreaterThan(1023);
+        expect(Number(conn.port)).toBeLessThan(65536);
+    });
+});
+describe('API keys', () => {
+    // API returns { keys: APIKey[], count: number }
+    it('GET /api/v1/api-keys returns 200 with keys array', async () => {
+        const { status, body } = await apiGet('/api/v1/api-keys');
+        expect(status).toBe(200);
+        const b = body;
+        expect(Array.isArray(b.keys)).toBe(true);
+    });
+    it('api-keys have id and instance_id fields', async () => {
+        const { body } = await apiGet('/api/v1/api-keys');
+        const keys = (body.keys) ?? [];
+        if (keys.length === 0)
+            return;
+        for (const k of keys) {
+            expect(typeof k.id).toBe('string');
+            expect(typeof k.instance_id).toBe('string');
+        }
+    });
+});
+describe('Brain Stats endpoint', () => {
+    it('GET /api/v1/instances/:id/brain-stats returns 200', async () => {
+        const { status } = await apiGet(`/api/v1/instances/${cfg.instanceId}/brain-stats`);
+        expect(status).toBe(200);
+    });
+    it('brain-stats body has brain_level and brain_level_name', async () => {
+        const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/brain-stats`);
+        const stats = body;
+        expect(typeof stats.brain_level).toBe('number');
+        expect(stats.brain_level).toBeGreaterThanOrEqual(1);
+        expect(typeof stats.brain_level_name).toBe('string');
+        expect(['Apprentice', 'Explorer', 'Expert', 'Architect', 'Oracle']).toContain(stats.brain_level_name);
+    });
+    it('brain-stats has hours_saved and brain_recall_count', async () => {
+        const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/brain-stats`);
+        const stats = body;
+        expect(typeof stats.hours_saved).toBe('number');
+        expect(stats.hours_saved).toBeGreaterThanOrEqual(0);
+        expect(typeof stats.brain_recall_count).toBe('number');
+        expect(stats.brain_recall_count).toBeGreaterThanOrEqual(0);
+    });
+    it('brain-stats has standard search telemetry fields', async () => {
+        const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/brain-stats`);
+        const stats = body;
+        expect(typeof stats.total_searches).toBe('number');
+        expect(typeof stats.avg_latency_ms).toBe('number');
+        expect(Array.isArray(stats.top_queries)).toBe(true);
+    });
+});
+describe('Provisioning status messages', () => {
+    it('non-existent instance connection returns 4xx, never 500', async () => {
+        const { status } = await apiGet('/api/v1/instances/00000000-0000-0000-0000-000000000001/connection');
+        expect([400, 403, 404, 422]).toContain(status);
+    });
+});
+describe('Auto-provision endpoint', () => {
+    it('POST /api/v1/instances/auto returns 200 or 201', async () => {
+        const { status } = await apiPost('/api/v1/instances/auto', {});
+        expect([200, 201]).toContain(status);
+    });
+    it('returns existing running instance without creating a new one', async () => {
+        const { body } = await apiPost('/api/v1/instances/auto', {});
+        const b = body;
+        if (b.instance) {
+            // Existing instance returned
+            expect(typeof b.instance.id).toBe('string');
+            expect(b.created).toBe(false);
+        }
+    });
+});
+//# sourceMappingURL=api-auth.test.js.map

package/dist/__tests__/e2e/api-auth.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-auth.test.js","sourceRoot":"","sources":["../../../src/__tests__/e2e/api-auth.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/e2e/api-health.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * E2E: API health & public endpoints
+ *
+ * These tests require NO credentials — they hit publicly accessible endpoints.
+ * Run: E2E_API_URL=https://api.dev.cachly.dev npx vitest run src/__tests__/e2e/api-health.test.ts
+ */
+export {};

package/dist/__tests__/e2e/api-health.test.js

@@ -0,0 +1,95 @@
+/**
+ * E2E: API health & public endpoints
+ *
+ * These tests require NO credentials — they hit publicly accessible endpoints.
+ * Run: E2E_API_URL=https://api.dev.cachly.dev npx vitest run src/__tests__/e2e/api-health.test.ts
+ */
+import { describe, it, expect } from 'vitest';
+import { cfg } from './config.js';
+describe('API health (no auth required)', () => {
+    it('GET /health returns 200', async () => {
+        const res = await fetch(`${cfg.apiUrl}/health`);
+        expect(res.status).toBe(200);
+    });
+    it('GET /health body contains status ok', async () => {
+        const res = await fetch(`${cfg.apiUrl}/health`);
+        const body = await res.json();
+        expect(body.status ?? body.ok ?? body.alive).toBeTruthy();
+    });
+    it('unknown route returns 404, not 500', async () => {
+        const res = await fetch(`${cfg.apiUrl}/api/v1/does-not-exist-xyz`);
+        expect(res.status).toBe(404);
+    });
+});
+describe('Device flow init (no auth required)', () => {
+    it('GET /api/v1/auth/device/code returns device_code and user_code', async () => {
+        const res = await fetch(`${cfg.apiUrl}/api/v1/auth/device/code`);
+        expect(res.status).toBe(200);
+        const body = await res.json();
+        expect(typeof body.device_code).toBe('string');
+        expect(typeof body.user_code).toBe('string');
+        expect(typeof body.verification_uri).toBe('string');
+        expect(body.verification_uri).toContain('cachly.dev');
+    });
+    it('device_code is at least 20 chars (not truncated)', async () => {
+        const res = await fetch(`${cfg.apiUrl}/api/v1/auth/device/code`);
+        const body = await res.json();
+        expect(body.device_code.length).toBeGreaterThanOrEqual(20);
+    });
+    it('expires_in is a positive number', async () => {
+        const res = await fetch(`${cfg.apiUrl}/api/v1/auth/device/code`);
+        const body = await res.json();
+        expect(Number(body.expires_in)).toBeGreaterThan(0);
+    });
+});
+describe('Badge endpoint (public, no auth)', () => {
+    it('returns 400 or 404 for an invalid instance id', async () => {
+        const res = await fetch(`${cfg.apiUrl}/api/v1/badge/not-a-real-uuid`);
+        expect([400, 404]).toContain(res.status);
+    });
+    it('returns badge JSON for a valid instance id', async () => {
+        if (!cfg.instanceId)
+            return; // skip if not configured
+        const res = await fetch(`${cfg.apiUrl}/api/v1/badge/${cfg.instanceId}`);
+        expect(res.status).toBe(200);
+        const body = await res.json();
+        expect(typeof body.schemaVersion).toBe('number');
+        expect(typeof body.label).toBe('string');
+        expect(typeof body.message).toBe('string');
+    });
+    it('badge message contains lesson count (numeric string)', async () => {
+        if (!cfg.instanceId)
+            return;
+        const res = await fetch(`${cfg.apiUrl}/api/v1/badge/${cfg.instanceId}`);
+        const body = await res.json();
+        expect(body.message).toMatch(/\d+/);
+    });
+});
+describe('Telemetry endpoint (public)', () => {
+    it('POST /api/v1/telemetry/mcp accepts anonymous event', async () => {
+        const res = await fetch(`${cfg.apiUrl}/api/v1/telemetry/mcp`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ event: 'e2e_test_ping', version: '0.0.0', editor: 'test', source: 'e2e' }),
+        });
+        expect([200, 202, 204]).toContain(res.status);
+    });
+    it('POST /api/v1/telemetry/mcp accepts jwt-attributed event', async () => {
+        if (!cfg.jwt)
+            return;
+        const res = await fetch(`${cfg.apiUrl}/api/v1/telemetry/mcp`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                event: 'e2e_test_ping_authed',
+                version: '0.0.0',
+                editor: 'test',
+                source: 'e2e',
+                jwt: cfg.jwt,
+                instance_id: cfg.instanceId,
+            }),
+        });
+        expect([200, 202, 204]).toContain(res.status);
+    });
+});
+//# sourceMappingURL=api-health.test.js.map

package/dist/__tests__/e2e/api-health.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-health.test.js","sourceRoot":"","sources":["../../../src/__tests__/e2e/api-health.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/e2e/cli.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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
+ */
+export {};

package/dist/__tests__/e2e/cli.test.js

@@ -0,0 +1,204 @@
+/**
+ * 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, env = {}, timeoutMs = TIMEOUT_MS) {
+    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');
+    });
+});
+//# sourceMappingURL=cli.test.js.map