Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

10.3 KB
Raw Blame
import { describe, expect, it } from 'vitest';
import {
  AGENT_REGISTRY,
  type DetectionSnapshot,
  EMPTY_DETECTION_SNAPSHOT,
  EMPTY_PROBE_SNAPSHOT,
  type InstallChoice,
  type InstallChoices,
  KNOWN_SURFACE_STATES,
  listInstallChoices,
  type ProbeSnapshot,
  STATE_POLICY,
  type SurfaceState,
} from './index.ts';

function snapshotOf(states: Record<string, SurfaceState>): ProbeSnapshot {
  return {
    env: 'desktop',
    satisfiers: Object.fromEntries(Object.entries(states).map(([id, state]) => [id, { state }])),
  };
}

function probedDetection(detected: DetectionSnapshot['detected']): DetectionSnapshot {
  return { detected, probed: true };
}

function choiceFor(result: InstallChoices, satisfierId: string): InstallChoice {
  const choice = result.choices.find((candidate) => candidate.satisfierId === satisfierId);
  if (choice === undefined) throw new Error(`no choice for ${satisfierId}`);
  return choice;
}

const CLAUDE_PROJECT_MCP = 'claude/mcp/project/config-entry';
const CURSOR_PROJECT_MCP = 'cursor/mcp/project/config-entry';
const CLAUDE_USER_MCP = 'claude/mcp/user/config-entry';
const COPILOT_PROJECT_SKILL = 'copilot/skill/project/skill-bundle-copy';
const GEMINI_SESSION_MCP = 'gemini/mcp/session/session-injection';
const HERMES_USER_MCP = 'hermes/mcp/user/config-entry';
const LM_STUDIO_USER_MCP = 'lm-studio/mcp/user/config-entry';

describe('what a choice carries', () => {
  it('names the audience an artifact serves once it exists', () => {
    const result = listInstallChoices('claude', 'mcp');

    expect(choiceFor(result, CLAUDE_USER_MCP).audience).toBe('this-user');
    expect(choiceFor(result, CLAUDE_PROJECT_MCP).audience).toBe('this-project');
  });

  it('carries the installability of every option', () => {
    const claude = listInstallChoices('claude', 'mcp');
    for (const choice of claude.choices) {
      expect(choice.installability).toBe('installable');
    }
    expect(
      choiceFor(listInstallChoices('lm-studio', 'mcp'), LM_STUDIO_USER_MCP).installability,
    ).toBe('not-installable');
  });

  it('carries the caveat guidance for what the user still owes and what to try', () => {
    const cursor = choiceFor(listInstallChoices('cursor', 'mcp'), CURSOR_PROJECT_MCP);

    expect(cursor.consentClass).toBe('enable-manually');
    expect(cursor.caveats.map((ref) => ref.id)).toEqual([
      'followup.enable-manually',
      'troubleshooting.cursor.project-entry-not-loaded',
    ]);
  });

  it('leaves the follow-up caveat off an entry whose agent prompts on its own', () => {
    const claude = choiceFor(listInstallChoices('claude', 'mcp'), CLAUDE_PROJECT_MCP);

    expect(claude.consentClass).toBe('approve-once');
    expect(claude.caveats.map((ref) => ref.id)).toEqual([
      'troubleshooting.claude.project-entry-not-approved',
    ]);
  });

  it('leaves caveats an empty array rather than omitting it', () => {
    const user = choiceFor(listInstallChoices('claude', 'mcp'), CLAUDE_USER_MCP);

    expect(user.caveats).toEqual([]);
  });

  it('says which other agents would read the same artifact', () => {
    const project = choiceFor(listInstallChoices('claude', 'mcp'), CLAUDE_PROJECT_MCP);

    expect(project.sharedWith).toEqual(['copilot']);
  });
});

describe('the claude chooser', () => {
  it('offers exactly two options and highlights neither', () => {
    const result = listInstallChoices('claude', 'mcp');

    expect(result.status).toBe('offer');
    expect(result.choices.map((choice) => choice.satisfierId)).toEqual([
      CLAUDE_USER_MCP,
      CLAUDE_PROJECT_MCP,
    ]);
    expect(result.choices.some((choice) => choice.preferred)).toBe(false);
  });

  it('does not offer the session injection as a third option', () => {
    const result = listInstallChoices('claude', 'mcp');

    expect(result.choices.map((choice) => choice.kind)).toEqual(['config-entry', 'config-entry']);
  });
});

describe('an agent whose piece is handed over by the session', () => {
  it('returns gemini one non-installable injection option', () => {
    const result = listInstallChoices('gemini', 'mcp');

    expect(result.status).toBe('handled');
    expect(result.choices).toHaveLength(1);
    const injection = choiceFor(result, GEMINI_SESSION_MCP);
    expect(injection.kind).toBe('session-injection');
    expect(injection.installability).toBe('not-installable');
    expect(injection.notInstallableReason).toBe('session-scoped');
    expect(injection.installable).toBe(false);
  });
});

describe('an agent OK cannot install for', () => {
  it("records lm-studio's reason as the missing non-interactive verb", () => {
    const choice = choiceFor(listInstallChoices('lm-studio', 'mcp'), LM_STUDIO_USER_MCP);

    expect(choice.installability).toBe('not-installable');
    expect(choice.notInstallableReason).toBe('no-non-interactive-verb');
  });

  it('does not blame a missing CLI or a missing URL scheme', () => {
    const choice = choiceFor(listInstallChoices('lm-studio', 'mcp'), LM_STUDIO_USER_MCP);

    expect(choice.notInstallableReason).not.toBe('no-surface');
    expect(choice.notInstallableReason).not.toBe('session-scoped');
  });

  it('still offers the option so the chooser can explain it', () => {
    const result = listInstallChoices('lm-studio', 'mcp');

    expect(result.status).toBe('offer');
    expect(result.choices).toHaveLength(1);
  });
});

describe('present but not installable', () => {
  it('is present and blocked when the agent is not on this machine', () => {
    const result = listInstallChoices('hermes', 'mcp', {
      probes: snapshotOf({ [HERMES_USER_MCP]: 'satisfied' }),
      detection: probedDetection(['claude']),
    });

    const choice = choiceFor(result, HERMES_USER_MCP);
    expect(choice.present).toBe(true);
    expect(choice.installable).toBe(false);
    expect(choice.blockedReason).toBe('agent-undetected');
  });

  it('stays installable while reporting what it still needs', () => {
    const result = listInstallChoices('copilot', 'skill', {
      probes: snapshotOf({ [COPILOT_PROJECT_SKILL]: 'satisfied' }),
    });

    const choice = choiceFor(result, COPILOT_PROJECT_SKILL);
    expect(choice.present).toBe(true);
    expect(choice.installable).toBe(true);
    expect(choice.blockedReason).toBe(null);
    expect(choice.unmetPrerequisites).toEqual([
      'copilot/mcp/project/config-entry',
      'copilot/mcp/user/config-entry',
    ]);
  });

  it('is installable once nothing stands in the way', () => {
    const result = listInstallChoices('claude', 'mcp', {
      probes: snapshotOf({ [CLAUDE_USER_MCP]: 'absent' }),
      detection: probedDetection(['claude']),
    });

    const choice = choiceFor(result, CLAUDE_USER_MCP);
    expect(choice.present).toBe(false);
    expect(choice.installable).toBe(true);
    expect(choice.blockedReason).toBeNull();
  });

  it('offers an entry somebody else owns as a writable overwrite', () => {
    const result = listInstallChoices('claude', 'mcp', {
      probes: snapshotOf({ [CLAUDE_USER_MCP]: 'foreign-replaceable' }),
    });

    const choice = choiceFor(result, CLAUDE_USER_MCP);
    expect(choice.blockedReason).toBeNull();
    expect(choice.present).toBe(false);
  });

  it('never claims OK can overwrite one a merging writer owns', () => {
    const result = listInstallChoices('claude', 'mcp', {
      probes: snapshotOf({ [CLAUDE_USER_MCP]: 'foreign' }),
    });

    expect(choiceFor(result, CLAUDE_USER_MCP).blockedReason).toBe('foreign');
  });

  it('agrees with the settings authority about what is already in place', () => {
    for (const state of KNOWN_SURFACE_STATES) {
      const result = listInstallChoices('claude', 'mcp', {
        probes: snapshotOf({ [CLAUDE_USER_MCP]: state }),
      });
      expect(choiceFor(result, CLAUDE_USER_MCP).present).toBe(STATE_POLICY[state].counts);
    }
  });
});

describe('when there is nothing to choose between', () => {
  it('reports an unregistered agent with a reason rather than a bare empty list', () => {
    const result = listInstallChoices('some-long-tail-agent', 'mcp');

    expect(result.status).toBe('not-registered');
    expect(result.choices).toEqual([]);
    expect(result.agentId).toBe('some-long-tail-agent');
    expect(result.piece).toBe('mcp');
  });

  it('reports no surface at all when the agent has none of that kind', () => {
    const result = listInstallChoices('gemini', 'skill');

    expect(result.status).toBe('no-surface');
    expect(result.choices).toEqual([]);
  });

  it('reports the surfaces as absent on this machine, still listing them', () => {
    const result = listInstallChoices('claude', 'mcp', {
      probes: snapshotOf({
        [CLAUDE_USER_MCP]: 'structural-na',
        [CLAUDE_PROJECT_MCP]: 'structural-na',
      }),
    });

    expect(result.status).toBe('structurally-absent');
    expect(result.choices).toHaveLength(2);
    for (const choice of result.choices) {
      expect(choice.blockedReason).toBe('structural-na');
    }
  });

  it('still offers when only one of the surfaces is absent', () => {
    const result = listInstallChoices('claude', 'mcp', {
      probes: snapshotOf({ [CLAUDE_USER_MCP]: 'structural-na' }),
    });

    expect(result.status).toBe('offer');
  });
});

describe('degrading rather than throwing', () => {
  it('survives every registered agent and piece with no context at all', () => {
    for (const agentId of Object.keys(AGENT_REGISTRY)) {
      for (const piece of ['mcp', 'skill'] as const) {
        expect(() => listInstallChoices(agentId, piece)).not.toThrow();
      }
    }
  });

  it('survives garbage where a snapshot should be', () => {
    const junk = { env: 'desktop', satisfiers: { [CLAUDE_USER_MCP]: 'nope' } } as unknown;

    const result = listInstallChoices('claude', 'mcp', {
      probes: junk as ProbeSnapshot,
      detection: junk as DetectionSnapshot,
    });

    expect(result.status).toBe('offer');
    expect(choiceFor(result, CLAUDE_USER_MCP).state).toBe('unprobed');
  });

  it('treats a piece it has no vocabulary for as no surface', () => {
    const result = listInstallChoices('claude', 'hologram' as 'mcp');

    expect(result.status).toBe('no-surface');
    expect(result.choices).toEqual([]);
  });

  it('claims nothing about detection when nobody looked', () => {
    const result = listInstallChoices('hermes', 'mcp', {
      probes: EMPTY_PROBE_SNAPSHOT,
      detection: EMPTY_DETECTION_SNAPSHOT,
    });

    expect(choiceFor(result, HERMES_USER_MCP).blockedReason).toBeNull();
  });
});