@kaelio/ktx 0.5.0 → 0.7.0

package/dist/setup-agents.test.js

@@ -1,1028 +0,0 @@
-import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { readKtxSetupState } from './context/project/setup-config.js';
-import { strFromU8, unzipSync } from 'fflate';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { createAgentNextActionsLineFormatter, formatInstallSummaryLines, plannedKtxAgentFiles, readKtxAgentInstallManifest, removeKtxAgentInstall, runKtxSetupAgentsStep, } from './setup-agents.js';
-function makeIo() {
-    let stdout = '';
-    let stderr = '';
-    return {
-        io: {
-            stdout: { write: (chunk) => (stdout += chunk) },
-            stderr: { write: (chunk) => (stderr += chunk) },
-        },
-        stdout: () => stdout,
-        stderr: () => stderr,
-    };
-}
-async function readZipText(path, entry) {
-    const archive = unzipSync(new Uint8Array(await readFile(path)));
-    const content = archive[entry];
-    if (!content)
-        throw new Error(`Missing zip entry: ${entry}`);
-    return strFromU8(content);
-}
-function captureEnvKeys(env, keys) {
-    const snapshot = {};
-    for (const key of keys)
-        snapshot[key] = env[key];
-    return snapshot;
-}
-function clearEnvKeys(env, keys) {
-    for (const key of keys)
-        delete env[key];
-}
-function captureKtxEnv(env) {
-    const snapshot = {};
-    for (const key of Object.keys(env)) {
-        if (key.startsWith('KTX_'))
-            snapshot[key] = env[key];
-    }
-    return snapshot;
-}
-function clearKtxEnv(env) {
-    for (const key of Object.keys(env)) {
-        if (key.startsWith('KTX_'))
-            delete env[key];
-    }
-}
-function restoreEnvKeys(env, snapshot) {
-    for (const [key, value] of Object.entries(snapshot)) {
-        if (value === undefined)
-            delete env[key];
-        else
-            env[key] = value;
-    }
-}
-describe('setup agents', () => {
-    let tempDir;
-    beforeEach(async () => {
-        tempDir = await mkdtemp(join(tmpdir(), 'ktx-setup-agents-'));
-        await mkdir(join(tempDir, '.ktx', 'agents'), { recursive: true });
-        await writeFile(join(tempDir, 'ktx.yaml'), 'connections: {}\n', 'utf-8');
-    });
-    afterEach(async () => {
-        await rm(tempDir, { recursive: true, force: true });
-    });
-    it('plans project-scoped MCP analytics files for every target', () => {
-        expect(plannedKtxAgentFiles({ projectDir: tempDir, target: 'claude-code', scope: 'project', mode: 'mcp' })).toEqual([
-            { kind: 'file', path: join(tempDir, '.claude/skills/ktx-analytics/SKILL.md'), role: 'analytics-skill' },
-        ]);
-        expect(plannedKtxAgentFiles({ projectDir: tempDir, target: 'claude-desktop', scope: 'global', mode: 'mcp' })).toEqual([
-            { kind: 'file', path: join(tempDir, '.ktx/agents/claude/ktx-plugin-runner.sh'), role: 'launcher' },
-            {
-                kind: 'file',
-                path: join(tempDir, '.ktx/agents/claude/ktx-analytics.zip'),
-                role: 'claude-desktop-skill-bundle',
-            },
-        ]);
-        expect(plannedKtxAgentFiles({ projectDir: tempDir, target: 'codex', scope: 'project', mode: 'mcp' })).toEqual([
-            { kind: 'file', path: join(tempDir, '.agents/skills/ktx-analytics/SKILL.md'), role: 'analytics-skill' },
-        ]);
-        expect(plannedKtxAgentFiles({ projectDir: tempDir, target: 'cursor', scope: 'project', mode: 'mcp' })).toEqual([
-            { kind: 'file', path: join(tempDir, '.cursor/rules/ktx-analytics.mdc'), role: 'analytics-skill' },
-        ]);
-        expect(plannedKtxAgentFiles({ projectDir: tempDir, target: 'opencode', scope: 'project', mode: 'mcp' })).toEqual([
-            { kind: 'file', path: join(tempDir, '.opencode/commands/ktx-analytics.md'), role: 'analytics-skill' },
-        ]);
-        expect(plannedKtxAgentFiles({ projectDir: tempDir, target: 'universal', scope: 'project', mode: 'mcp' })).toEqual([
-            { kind: 'file', path: join(tempDir, '.agents/skills/ktx-analytics/SKILL.md'), role: 'analytics-skill' },
-        ]);
-    });
-    it('plans project-scoped admin CLI files for every target when requested', () => {
-        expect(plannedKtxAgentFiles({ projectDir: tempDir, target: 'claude-code', scope: 'project', mode: 'mcp-cli' })).toEqual([
-            { kind: 'file', path: join(tempDir, '.claude/skills/ktx-analytics/SKILL.md'), role: 'analytics-skill' },
-            { kind: 'file', path: join(tempDir, '.claude/skills/ktx/SKILL.md'), role: 'skill' },
-            { kind: 'file', path: join(tempDir, '.claude/rules/ktx.md'), role: 'rule' },
-        ]);
-        expect(plannedKtxAgentFiles({ projectDir: tempDir, target: 'codex', scope: 'project', mode: 'mcp-cli' })).toEqual([
-            { kind: 'file', path: join(tempDir, '.agents/skills/ktx-analytics/SKILL.md'), role: 'analytics-skill' },
-            { kind: 'file', path: join(tempDir, '.agents/skills/ktx/SKILL.md'), role: 'skill' },
-            { kind: 'file', path: join(tempDir, '.codex/instructions/ktx.md'), role: 'rule' },
-        ]);
-        expect(plannedKtxAgentFiles({ projectDir: tempDir, target: 'cursor', scope: 'project', mode: 'mcp-cli' })).toEqual([
-            { kind: 'file', path: join(tempDir, '.cursor/rules/ktx-analytics.mdc'), role: 'analytics-skill' },
-            { kind: 'file', path: join(tempDir, '.cursor/rules/ktx.mdc') },
-        ]);
-        expect(plannedKtxAgentFiles({ projectDir: tempDir, target: 'opencode', scope: 'project', mode: 'mcp-cli' })).toEqual([
-            { kind: 'file', path: join(tempDir, '.opencode/commands/ktx-analytics.md'), role: 'analytics-skill' },
-            { kind: 'file', path: join(tempDir, '.opencode/commands/ktx.md') },
-        ]);
-        expect(plannedKtxAgentFiles({ projectDir: tempDir, target: 'universal', scope: 'project', mode: 'mcp-cli' })).toEqual([
-            { kind: 'file', path: join(tempDir, '.agents/skills/ktx-analytics/SKILL.md'), role: 'analytics-skill' },
-            { kind: 'file', path: join(tempDir, '.agents/skills/ktx/SKILL.md') },
-        ]);
-        expect(plannedKtxAgentFiles({ projectDir: tempDir, target: 'claude-desktop', scope: 'global', mode: 'mcp-cli' })).toEqual([
-            { kind: 'file', path: join(tempDir, '.ktx/agents/claude/ktx-plugin-runner.sh'), role: 'launcher' },
-            {
-                kind: 'file',
-                path: join(tempDir, '.ktx/agents/claude/ktx-analytics.zip'),
-                role: 'claude-desktop-skill-bundle',
-            },
-            {
-                kind: 'file',
-                path: join(tempDir, '.ktx/agents/claude/ktx.zip'),
-                role: 'claude-desktop-skill-bundle',
-            },
-        ]);
-    });
-    it('installs target files, writes a manifest, and marks agents complete', async () => {
-        const io = makeIo();
-        await expect(runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'disabled',
-            yes: true,
-            agents: true,
-            target: 'universal',
-            scope: 'project',
-            mode: 'mcp-cli',
-            skipAgents: false,
-        }, io.io)).resolves.toMatchObject({
-            status: 'ready',
-            projectDir: tempDir,
-            installs: [{ target: 'universal', scope: 'project', mode: 'mcp-cli' }],
-        });
-        await expect(stat(join(tempDir, '.agents/skills/ktx/SKILL.md'))).resolves.toBeDefined();
-        const skill = await readFile(join(tempDir, '.agents/skills/ktx/SKILL.md'), 'utf-8');
-        expect(skill).toContain(`--project-dir ${tempDir}`);
-        expect(skill).toContain('must not print secrets');
-        expect(skill).toContain('status --json');
-        expect(skill).toContain('sl --json');
-        expect(skill).toContain('sl query');
-        expect(skill).toContain('--format json');
-        expect(skill).not.toContain('sl query --json');
-        expect(skill).not.toContain('agent ');
-        expect(skill).not.toContain('sql execute');
-        expect(await readKtxAgentInstallManifest(tempDir)).toMatchObject({
-            version: 1,
-            projectDir: tempDir,
-            installs: [{ target: 'universal', scope: 'project', mode: 'mcp-cli' }],
-        });
-        expect(await readKtxSetupState(tempDir)).toEqual({ completed_steps: ['agents'] });
-        expect(io.stderr()).toBe('');
-    });
-    it('installs a specified target in non-interactive mode without --yes', async () => {
-        const io = makeIo();
-        await expect(runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'disabled',
-            yes: false,
-            agents: true,
-            target: 'claude-code',
-            scope: 'project',
-            mode: 'mcp',
-            skipAgents: false,
-        }, io.io)).resolves.toMatchObject({
-            status: 'ready',
-            projectDir: tempDir,
-            installs: [{ target: 'claude-code', scope: 'project', mode: 'mcp' }],
-        });
-        await expect(stat(join(tempDir, '.claude/skills/ktx-analytics/SKILL.md'))).resolves.toBeDefined();
-        const mcpConfig = JSON.parse(await readFile(join(tempDir, '.mcp.json'), 'utf-8'));
-        expect(mcpConfig.mcpServers).toHaveProperty('ktx');
-        expect(io.stderr()).toBe('');
-    });
-    it('prints concrete target guidance when non-interactive agent setup has no target', async () => {
-        const io = makeIo();
-        await expect(runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'disabled',
-            yes: false,
-            agents: true,
-            scope: 'project',
-            mode: 'mcp',
-            skipAgents: false,
-        }, io.io)).resolves.toEqual({ status: 'missing-input', projectDir: tempDir });
-        expect(io.stderr()).toBe('Run in a TTY, or pass --target <target>.\n');
-    });
-    it('prints standalone agent next actions after successful installation', async () => {
-        const io = makeIo();
-        const result = await runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'disabled',
-            yes: true,
-            agents: true,
-            target: 'claude-code',
-            scope: 'project',
-            mode: 'mcp-cli',
-            skipAgents: false,
-        }, io.io);
-        expect(result).toMatchObject({
-            status: 'ready',
-            nextActions: expect.stringContaining('Run this command before using Claude Code:'),
-        });
-        expect(io.stdout()).toContain('Required before using agents');
-        expect(io.stdout()).toContain('Run this command before using Claude Code:');
-        expect(io.stdout()).toContain('RUN:');
-        expect(io.stdout()).toContain(`ktx mcp start --project-dir ${tempDir}`);
-        expect(io.stdout()).toContain('If you need to stop MCP later:');
-        expect(io.stdout()).toContain(`ktx mcp stop --project-dir ${tempDir}`);
-        expect(io.stdout()).toContain('All set.');
-        expect(io.stdout()).not.toContain('Finish agent setup');
-        expect(io.stdout()).not.toContain('Next actions');
-    });
-    it('can return agent next actions without printing them', async () => {
-        const io = makeIo();
-        const result = await runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'disabled',
-            yes: true,
-            agents: true,
-            target: 'claude-code',
-            scope: 'project',
-            mode: 'mcp-cli',
-            skipAgents: false,
-            showNextActions: false,
-        }, io.io);
-        expect(result).toMatchObject({
-            status: 'ready',
-            nextActions: expect.stringContaining(`ktx mcp start --project-dir ${tempDir}`),
-        });
-        expect(io.stdout()).toContain('Claude Code · Project scope');
-        expect(io.stdout()).not.toContain('Agent integration complete');
-        expect(io.stdout()).not.toContain('Required before using agents');
-        expect(io.stdout()).not.toContain('All set.');
-    });
-    it('installs the analytics skill from the runtime asset', async () => {
-        const io = makeIo();
-        await expect(runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'disabled',
-            yes: true,
-            agents: true,
-            target: 'universal',
-            scope: 'project',
-            mode: 'mcp-cli',
-            skipAgents: false,
-        }, io.io)).resolves.toMatchObject({ status: 'ready' });
-        const analyticsSkill = await readFile(join(tempDir, '.agents/skills/ktx-analytics/SKILL.md'), 'utf-8');
-        expect(analyticsSkill).toContain('name: ktx-analytics');
-        expect(analyticsSkill).toContain('Always run `discover_data` before writing SQL.');
-        expect(analyticsSkill).toContain('Treat a `dictionary_search` miss as non-authoritative.');
-        expect(analyticsSkill).toContain('memory_ingest');
-        expect(analyticsSkill).toContain('ARR is reported in cents');
-        expect(analyticsSkill).not.toContain(`memory_${'capture'}`);
-    });
-    it('writes PATH-independent launcher commands for skills', async () => {
-        const io = makeIo();
-        await expect(runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'disabled',
-            yes: true,
-            agents: true,
-            target: 'universal',
-            scope: 'project',
-            mode: 'mcp-cli',
-            skipAgents: false,
-        }, io.io)).resolves.toMatchObject({ status: 'ready' });
-        const skill = await readFile(join(tempDir, '.agents/skills/ktx/SKILL.md'), 'utf-8');
-        expect(skill).not.toContain('`ktx agent');
-        expect(skill).toContain('status --json');
-        expect(skill).toContain('sl query');
-        expect(skill).toContain('--format json');
-        expect(skill).not.toContain('sl query --json');
-        expect(skill).not.toContain('sql execute');
-    });
-    it('writes Claude Code project MCP config and tracks the json key', async () => {
-        const io = makeIo();
-        await expect(runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'disabled',
-            yes: true,
-            agents: true,
-            target: 'claude-code',
-            scope: 'project',
-            mode: 'mcp-cli',
-            skipAgents: false,
-        }, io.io)).resolves.toMatchObject({ status: 'ready' });
-        const mcpJson = JSON.parse(await readFile(join(tempDir, '.mcp.json'), 'utf-8'));
-        expect(mcpJson.mcpServers.ktx).toEqual({ type: 'http', url: 'http://localhost:7878/mcp' });
-        expect(await readKtxAgentInstallManifest(tempDir)).toMatchObject({
-            entries: expect.arrayContaining([{ kind: 'json-key', path: join(tempDir, '.mcp.json'), jsonPath: ['mcpServers', 'ktx'] }]),
-        });
-    });
-    it('prompts for MCP-first agent client connection mode in interactive setup', async () => {
-        const io = makeIo();
-        const prompts = {
-            select: vi.fn(async ({ message }) => (message.startsWith('Where') ? 'project' : 'mcp')),
-            multiselect: vi.fn(async () => ['claude-code']),
-            cancel: vi.fn(),
-        };
-        await expect(runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'auto',
-            yes: false,
-            agents: true,
-            scope: 'project',
-            mode: 'mcp',
-            skipAgents: false,
-        }, io.io, { prompts })).resolves.toMatchObject({
-            status: 'ready',
-            installs: [{ target: 'claude-code', scope: 'project', mode: 'mcp' }],
-        });
-        expect(prompts.select).toHaveBeenCalledWith({
-            message: 'What should agents be allowed to do with this KTX project?',
-            options: [
-                {
-                    value: 'mcp',
-                    label: 'Ask data questions with KTX MCP',
-                    hint: 'Installs the MCP connection and analytics workflow skill. Best for normal use.',
-                },
-                {
-                    value: 'mcp-cli',
-                    label: 'Ask data questions + manage KTX with CLI commands',
-                    hint: 'Adds an admin CLI skill so agents can run ktx status, sl, wiki, and setup commands.',
-                },
-            ],
-        });
-        expect(prompts.multiselect).toHaveBeenCalledWith(expect.objectContaining({
-            options: expect.arrayContaining([{ value: 'claude-desktop', label: 'Claude Desktop' }]),
-        }));
-    });
-    it('prompts for global scope when every selected target supports it', async () => {
-        const home = await mkdtemp(join(tmpdir(), 'ktx-setup-agents-home-'));
-        const previousHome = process.env.HOME;
-        process.env.HOME = home;
-        try {
-            const io = makeIo();
-            const prompts = {
-                select: vi.fn(async ({ message }) => message.startsWith('Where should') ? 'global' : 'mcp'),
-                multiselect: vi.fn(async () => ['claude-code']),
-                cancel: vi.fn(),
-            };
-            await expect(runKtxSetupAgentsStep({
-                projectDir: tempDir,
-                inputMode: 'auto',
-                yes: false,
-                agents: true,
-                scope: 'project',
-                mode: 'mcp',
-                skipAgents: false,
-            }, io.io, { prompts })).resolves.toMatchObject({
-                status: 'ready',
-                installs: [{ target: 'claude-code', scope: 'global', mode: 'mcp' }],
-            });
-            expect(prompts.select).toHaveBeenCalledWith({
-                message: `Where should KTX install supported agent config?\n\nKTX project: ${tempDir}`,
-                options: [
-                    {
-                        value: 'project',
-                        label: 'Project scope (KTX project directory)',
-                        hint: 'Only agents opened from this KTX project path load the project-scoped config.',
-                    },
-                    {
-                        value: 'global',
-                        label: 'Global scope (user config)',
-                        hint: 'Agents can load this KTX project from any working directory.',
-                    },
-                ],
-            });
-        }
-        finally {
-            process.env.HOME = previousHome;
-            await rm(home, { recursive: true, force: true });
-        }
-    });
-    it('registers Claude Desktop MCP and ships an uploadable analytics skill zip', async () => {
-        const home = await mkdtemp(join(tmpdir(), 'ktx-setup-agents-home-'));
-        const previousHome = process.env.HOME;
-        const envSnapshot = captureEnvKeys(process.env, ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY']);
-        const ktxEnvSnapshot = captureKtxEnv(process.env);
-        process.env.HOME = home;
-        clearEnvKeys(process.env, ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY']);
-        clearKtxEnv(process.env);
-        try {
-            const io = makeIo();
-            await expect(runKtxSetupAgentsStep({
-                projectDir: tempDir,
-                inputMode: 'disabled',
-                yes: true,
-                agents: true,
-                target: 'claude-desktop',
-                scope: 'project',
-                mode: 'mcp',
-                skipAgents: false,
-            }, io.io)).resolves.toMatchObject({
-                status: 'ready',
-                installs: [{ target: 'claude-desktop', scope: 'global', mode: 'mcp' }],
-            });
-            const analyticsSkillPath = join(tempDir, '.ktx/agents/claude/ktx-analytics.zip');
-            const adminSkillPath = join(tempDir, '.ktx/agents/claude/ktx.zip');
-            const launcherPath = join(tempDir, '.ktx/agents/claude/ktx-plugin-runner.sh');
-            await expect(stat(analyticsSkillPath)).resolves.toBeDefined();
-            await expect(stat(adminSkillPath)).rejects.toThrow();
-            const launcherStat = await stat(launcherPath);
-            expect(launcherStat.mode & 0o111).not.toBe(0);
-            const launcher = await readFile(launcherPath, 'utf-8');
-            expect(launcher).toContain('KTX_CLI_BIN=');
-            expect(launcher).toContain('.nvm/versions/node');
-            const configPath = join(home, 'Library/Application Support/Claude/claude_desktop_config.json');
-            const config = JSON.parse(await readFile(configPath, 'utf-8'));
-            expect(config.mcpServers.ktx).toEqual({
-                command: launcherPath,
-                args: ['--project-dir', tempDir, 'mcp', 'stdio'],
-            });
-            expect(await readZipText(analyticsSkillPath, 'ktx-analytics/SKILL.md')).toContain('KTX Analytics Workflow');
-            await expect(readZipText(analyticsSkillPath, 'ktx/SKILL.md')).rejects.toThrow('Missing zip entry');
-            await expect(readZipText(analyticsSkillPath, '.claude-plugin/plugin.json')).rejects.toThrow('Missing zip entry');
-            await expect(readZipText(analyticsSkillPath, 'skills/ktx-analytics/SKILL.md')).rejects.toThrow('Missing zip entry');
-            expect(io.stdout()).toContain('Claude Desktop');
-            expect(io.stdout()).toContain(analyticsSkillPath);
-            expect(io.stdout()).not.toContain(adminSkillPath);
-            expect(io.stdout()).toContain('claude_desktop_config.json');
-            expect(io.stdout()).toContain('Required before using agents');
-            expect(io.stdout()).toContain('1. Restart Claude Desktop');
-            expect(io.stdout()).toContain('Claude Desktop loads KTX MCP after restart.');
-            expect(io.stdout()).toContain('2. Upload Claude Desktop skills');
-            expect(io.stdout()).toContain('Customize > Skills > + > Create skill > Upload a skill');
-            expect(io.stdout()).toContain('Upload this file:');
-            expect(io.stdout()).toContain('Toggle the uploaded KTX skills on.');
-            expect(io.stdout()).not.toContain('Run `ktx mcp start`');
-        }
-        finally {
-            process.env.HOME = previousHome;
-            restoreEnvKeys(process.env, envSnapshot);
-            restoreEnvKeys(process.env, ktxEnvSnapshot);
-            await rm(home, { recursive: true, force: true });
-        }
-    });
-    it('captures KTX_*, OPENAI_API_KEY, and ANTHROPIC_API_KEY into the Claude Desktop MCP env block', async () => {
-        const home = await mkdtemp(join(tmpdir(), 'ktx-setup-agents-home-'));
-        const previousHome = process.env.HOME;
-        const envSnapshot = captureEnvKeys(process.env, [
-            'OPENAI_API_KEY',
-            'ANTHROPIC_API_KEY',
-            'KTX_LOG_LEVEL',
-        ]);
-        const ktxEnvSnapshot = captureKtxEnv(process.env);
-        process.env.HOME = home;
-        clearKtxEnv(process.env);
-        process.env.OPENAI_API_KEY = 'sk-test-openai'; // pragma: allowlist secret
-        process.env.ANTHROPIC_API_KEY = 'sk-ant-test'; // pragma: allowlist secret
-        process.env.KTX_LOG_LEVEL = 'debug';
-        try {
-            const io = makeIo();
-            await runKtxSetupAgentsStep({
-                projectDir: tempDir,
-                inputMode: 'disabled',
-                yes: true,
-                agents: true,
-                target: 'claude-desktop',
-                scope: 'project',
-                mode: 'mcp',
-                skipAgents: false,
-            }, io.io);
-            const configPath = join(home, 'Library/Application Support/Claude/claude_desktop_config.json');
-            const config = JSON.parse(await readFile(configPath, 'utf-8'));
-            expect(config.mcpServers.ktx.env).toEqual({
-                OPENAI_API_KEY: 'sk-test-openai', // pragma: allowlist secret
-                ANTHROPIC_API_KEY: 'sk-ant-test', // pragma: allowlist secret
-                KTX_LOG_LEVEL: 'debug',
-            });
-        }
-        finally {
-            process.env.HOME = previousHome;
-            restoreEnvKeys(process.env, envSnapshot);
-            restoreEnvKeys(process.env, ktxEnvSnapshot);
-            await rm(home, { recursive: true, force: true });
-        }
-    });
-    it('includes an uploadable admin CLI skill zip for Claude Desktop when requested', async () => {
-        const home = await mkdtemp(join(tmpdir(), 'ktx-setup-agents-home-'));
-        const previousHome = process.env.HOME;
-        process.env.HOME = home;
-        try {
-            const io = makeIo();
-            await expect(runKtxSetupAgentsStep({
-                projectDir: tempDir,
-                inputMode: 'disabled',
-                yes: true,
-                agents: true,
-                target: 'claude-desktop',
-                scope: 'project',
-                mode: 'mcp-cli',
-                skipAgents: false,
-            }, io.io)).resolves.toMatchObject({
-                status: 'ready',
-                installs: [{ target: 'claude-desktop', scope: 'global', mode: 'mcp-cli' }],
-            });
-            const analyticsSkillPath = join(tempDir, '.ktx/agents/claude/ktx-analytics.zip');
-            const adminSkillPath = join(tempDir, '.ktx/agents/claude/ktx.zip');
-            expect(await readZipText(analyticsSkillPath, 'ktx-analytics/SKILL.md')).toContain('KTX Analytics Workflow');
-            await expect(readZipText(analyticsSkillPath, 'ktx/SKILL.md')).rejects.toThrow('Missing zip entry');
-            const adminSkill = await readZipText(adminSkillPath, 'ktx/SKILL.md');
-            expect(adminSkill).toContain(`--project-dir ${tempDir}`);
-            expect(adminSkill).toContain('status --json');
-            await expect(readZipText(adminSkillPath, '.mcp.json')).rejects.toThrow('Missing zip entry');
-            await expect(readZipText(adminSkillPath, 'ktx-analytics/SKILL.md')).rejects.toThrow('Missing zip entry');
-            expect(io.stdout()).toContain(analyticsSkillPath);
-            expect(io.stdout()).toContain(adminSkillPath);
-            expect(io.stdout()).toContain('Upload each file separately:');
-        }
-        finally {
-            process.env.HOME = previousHome;
-            await rm(home, { recursive: true, force: true });
-        }
-    });
-    it('installs MCP client config and analytics skill without admin CLI files', async () => {
-        const io = makeIo();
-        await expect(runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'disabled',
-            yes: true,
-            agents: true,
-            target: 'claude-code',
-            scope: 'project',
-            mode: 'mcp',
-            skipAgents: false,
-        }, io.io)).resolves.toMatchObject({
-            status: 'ready',
-            installs: [{ target: 'claude-code', scope: 'project', mode: 'mcp' }],
-        });
-        const mcpJson = JSON.parse(await readFile(join(tempDir, '.mcp.json'), 'utf-8'));
-        expect(mcpJson.mcpServers.ktx).toEqual({ type: 'http', url: 'http://localhost:7878/mcp' });
-        await expect(stat(join(tempDir, '.claude/skills/ktx-analytics/SKILL.md'))).resolves.toBeDefined();
-        await expect(stat(join(tempDir, '.claude/skills/ktx/SKILL.md'))).rejects.toThrow();
-        await expect(stat(join(tempDir, '.claude/rules/ktx.md'))).rejects.toThrow();
-    });
-    it('writes Cursor project MCP config', async () => {
-        const io = makeIo();
-        await runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'disabled',
-            yes: true,
-            agents: true,
-            target: 'cursor',
-            scope: 'project',
-            mode: 'mcp-cli',
-            skipAgents: false,
-        }, io.io);
-        const cursorJson = JSON.parse(await readFile(join(tempDir, '.cursor/mcp.json'), 'utf-8'));
-        expect(cursorJson.mcpServers.ktx).toEqual({ url: 'http://localhost:7878/mcp' });
-    });
-    it('prints Codex, opencode, and universal snippets without mutating printed-only config files', async () => {
-        const codexIo = makeIo();
-        await runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'disabled',
-            yes: true,
-            agents: true,
-            target: 'codex',
-            scope: 'project',
-            mode: 'mcp-cli',
-            skipAgents: false,
-        }, codexIo.io);
-        expect(codexIo.stdout()).toContain('[mcp_servers.ktx]');
-        expect(codexIo.stdout()).toContain('url = "http://localhost:7878/mcp"');
-        expect(codexIo.stdout()).toContain('1. Configure Codex');
-        expect(codexIo.stdout()).toContain('Open ~/.codex/config.toml, then paste this block:');
-        expect(codexIo.stdout()).toContain('PASTE:');
-        const opencodeIo = makeIo();
-        await runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'disabled',
-            yes: true,
-            agents: true,
-            target: 'opencode',
-            scope: 'project',
-            mode: 'mcp-cli',
-            skipAgents: false,
-        }, opencodeIo.io);
-        expect(opencodeIo.stdout()).toContain('"mcp"');
-        expect(opencodeIo.stdout()).toContain('"type": "remote"');
-        expect(opencodeIo.stdout()).toContain('1. Configure OpenCode');
-        expect(opencodeIo.stdout()).toContain('Open opencode.json, then paste this block:');
-        await expect(readFile(join(tempDir, 'opencode.json'), 'utf-8')).rejects.toThrow();
-        const universalIo = makeIo();
-        await runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'disabled',
-            yes: true,
-            agents: true,
-            target: 'universal',
-            scope: 'project',
-            mode: 'mcp',
-            skipAgents: false,
-        }, universalIo.io);
-        expect(universalIo.stdout()).toContain('Universal MCP endpoint:');
-        expect(universalIo.stdout()).toContain('http://localhost:7878/mcp');
-        expect(universalIo.stdout()).toContain('1. Configure unsupported MCP clients');
-        expect(universalIo.stdout()).toContain('Use this endpoint when setting up unsupported MCP clients:');
-    });
-    it('uses MCP daemon state for port and token metadata without rendering literal tokens', async () => {
-        await mkdir(join(tempDir, '.ktx'), { recursive: true });
-        await writeFile(join(tempDir, '.ktx/mcp.json'), `${JSON.stringify({
-            schemaVersion: 1,
-            pid: 999999,
-            host: '127.0.0.1',
-            port: 8787,
-            tokenAuth: true,
-            projectDir: tempDir,
-            startedAt: '2026-05-14T00:00:00.000Z',
-            logPath: join(tempDir, '.ktx/logs/mcp.log'),
-        }, null, 2)}\n`, 'utf-8');
-        const io = makeIo();
-        const previousToken = process.env.KTX_MCP_TOKEN;
-        process.env.KTX_MCP_TOKEN = 'secret-token';
-        try {
-            await runKtxSetupAgentsStep({
-                projectDir: tempDir,
-                inputMode: 'disabled',
-                yes: true,
-                agents: true,
-                target: 'claude-code',
-                scope: 'project',
-                mode: 'mcp-cli',
-                skipAgents: false,
-            }, io.io);
-            const rendered = JSON.stringify(JSON.parse(await readFile(join(tempDir, '.mcp.json'), 'utf-8')));
-            expect(rendered).toContain('http://127.0.0.1:8787/mcp');
-            expect(rendered).toContain('Bearer ${KTX_MCP_TOKEN}');
-            expect(rendered).not.toContain('secret-token');
-            expect(io.stdout()).toContain('Run this command before using Claude Code:');
-            expect(io.stdout()).toContain('RUN:');
-            expect(io.stdout()).toContain(`ktx mcp start --project-dir ${tempDir}`);
-        }
-        finally {
-            if (previousToken === undefined) {
-                delete process.env.KTX_MCP_TOKEN;
-            }
-            else {
-                process.env.KTX_MCP_TOKEN = previousToken;
-            }
-        }
-    });
-    it('writes Claude Code local MCP config under the project key in ~/.claude.json', async () => {
-        const home = await mkdtemp(join(tmpdir(), 'ktx-setup-agents-home-'));
-        const previousHome = process.env.HOME;
-        process.env.HOME = home;
-        try {
-            const io = makeIo();
-            await runKtxSetupAgentsStep({
-                projectDir: tempDir,
-                inputMode: 'disabled',
-                yes: true,
-                agents: true,
-                target: 'claude-code',
-                scope: 'local',
-                mode: 'mcp-cli',
-                skipAgents: false,
-            }, io.io);
-            const config = JSON.parse(await readFile(join(home, '.claude.json'), 'utf-8'));
-            expect(config.projects[tempDir].mcpServers.ktx).toEqual({ type: 'http', url: 'http://localhost:7878/mcp' });
-        }
-        finally {
-            process.env.HOME = previousHome;
-            await rm(home, { recursive: true, force: true });
-        }
-    });
-    it('removes only manifest-listed files', async () => {
-        const io = makeIo();
-        await runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'disabled',
-            yes: true,
-            agents: true,
-            target: 'claude-code',
-            scope: 'project',
-            mode: 'mcp-cli',
-            skipAgents: false,
-        }, io.io);
-        await writeFile(join(tempDir, '.claude/skills/ktx/keep.txt'), 'user file', 'utf-8');
-        await expect(removeKtxAgentInstall(tempDir, io.io)).resolves.toBe(0);
-        await expect(stat(join(tempDir, '.claude/skills/ktx/SKILL.md'))).rejects.toThrow();
-        await expect(stat(join(tempDir, '.claude/rules/ktx.md'))).rejects.toThrow();
-        await expect(stat(join(tempDir, '.claude/skills/ktx/keep.txt'))).resolves.toBeDefined();
-        await expect(readKtxAgentInstallManifest(tempDir)).resolves.toEqual(null);
-    });
-    it('removes generated Claude Desktop skill zips from the manifest', async () => {
-        const home = await mkdtemp(join(tmpdir(), 'ktx-setup-agents-home-'));
-        const previousHome = process.env.HOME;
-        process.env.HOME = home;
-        try {
-            const io = makeIo();
-            await runKtxSetupAgentsStep({
-                projectDir: tempDir,
-                inputMode: 'disabled',
-                yes: true,
-                agents: true,
-                target: 'claude-desktop',
-                scope: 'project',
-                mode: 'mcp-cli',
-                skipAgents: false,
-            }, io.io);
-            const analyticsSkillPath = join(tempDir, '.ktx/agents/claude/ktx-analytics.zip');
-            const adminSkillPath = join(tempDir, '.ktx/agents/claude/ktx.zip');
-            const launcherPath = join(tempDir, '.ktx/agents/claude/ktx-plugin-runner.sh');
-            const configPath = join(home, 'Library/Application Support/Claude/claude_desktop_config.json');
-            await expect(stat(analyticsSkillPath)).resolves.toBeDefined();
-            await expect(stat(adminSkillPath)).resolves.toBeDefined();
-            await expect(stat(launcherPath)).resolves.toBeDefined();
-            const beforeConfig = JSON.parse(await readFile(configPath, 'utf-8'));
-            expect(beforeConfig.mcpServers.ktx).toBeDefined();
-            await expect(removeKtxAgentInstall(tempDir, io.io)).resolves.toBe(0);
-            await expect(stat(analyticsSkillPath)).rejects.toThrow();
-            await expect(stat(adminSkillPath)).rejects.toThrow();
-            await expect(stat(launcherPath)).rejects.toThrow();
-            const afterConfig = JSON.parse(await readFile(configPath, 'utf-8'));
-            expect(afterConfig.mcpServers.ktx).toBeUndefined();
-            await expect(readKtxAgentInstallManifest(tempDir)).resolves.toEqual(null);
-        }
-        finally {
-            process.env.HOME = previousHome;
-            await rm(home, { recursive: true, force: true });
-        }
-    });
-    it('treats cancel as skip in interactive mode', async () => {
-        const io = makeIo();
-        const prompts = {
-            select: vi.fn(async () => 'back'),
-            multiselect: vi.fn(async () => ['codex']),
-            cancel: vi.fn(),
-        };
-        await expect(runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'auto',
-            yes: false,
-            agents: true,
-            scope: 'project',
-            mode: 'mcp-cli',
-            skipAgents: false,
-        }, io.io, { prompts })).resolves.toEqual({ status: 'skipped', projectDir: tempDir });
-    });
-    it('prints one navigation hint before interactive agent target prompts', async () => {
-        const io = makeIo();
-        const prompts = {
-            select: vi.fn(async () => 'mcp-cli'),
-            multiselect: vi.fn(async () => ['back']),
-            cancel: vi.fn(),
-        };
-        await expect(runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'auto',
-            yes: false,
-            agents: true,
-            scope: 'project',
-            mode: 'mcp-cli',
-            skipAgents: false,
-        }, io.io, { prompts })).resolves.toEqual({ status: 'back', projectDir: tempDir });
-        expect(io.stdout()).toContain('Space to select, Enter to confirm, Esc to go back.');
-        expect(io.stdout().match(/Space to select/g)).toHaveLength(1);
-        expect(prompts.multiselect).toHaveBeenCalledWith(expect.objectContaining({
-            message: 'Which agent targets should KTX install?',
-        }));
-    });
-    it('prints per-agent install summary after successful installation', async () => {
-        const io = makeIo();
-        await runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'disabled',
-            yes: true,
-            agents: true,
-            target: 'claude-code',
-            scope: 'project',
-            mode: 'mcp-cli',
-            skipAgents: false,
-        }, io.io);
-        const output = io.stdout();
-        expect(output).toContain('Claude Code · Project scope');
-        expect(output).toContain(join(tempDir, '.mcp.json'));
-        expect(output).toContain('Requires MCP to be started.');
-        expect(output).toContain('Analytics skill installed.');
-        expect(output).toContain('Admin CLI skill installed.');
-        expect(output).not.toContain('Agent integration complete');
-        expect(output).not.toContain(`KTX project\n  ${tempDir}`);
-        expect(output).not.toContain('Installed agents');
-        expect(output).not.toContain('.claude/skills/ktx-analytics/SKILL.md');
-        expect(output).not.toContain('.claude/skills/ktx/SKILL.md');
-        expect(output).not.toContain('.claude/rules/ktx.md');
-    });
-    it('formats summary with explicit project-scoped config paths', () => {
-        const summary = formatInstallSummaryLines([{ target: 'cursor', scope: 'project', mode: 'mcp-cli' }], [
-            { kind: 'file', path: join(tempDir, '.cursor/rules/ktx-analytics.mdc'), role: 'analytics-skill' },
-            { kind: 'file', path: join(tempDir, '.cursor/rules/ktx.mdc') },
-            { kind: 'json-key', path: join(tempDir, '.cursor/mcp.json'), jsonPath: ['mcpServers', 'ktx'] },
-        ], tempDir);
-        expect(summary).toEqual([
-            {
-                title: 'Cursor · Project scope',
-                lines: [
-                    join(tempDir, '.cursor/mcp.json'),
-                    'Requires MCP to be started.',
-                    'Cursor rules installed.',
-                ],
-            },
-        ]);
-    });
-    it('formats summary with multiple agent targets', () => {
-        const summary = formatInstallSummaryLines([
-            { target: 'claude-code', scope: 'project', mode: 'mcp-cli' },
-            { target: 'codex', scope: 'project', mode: 'mcp-cli' },
-        ], [
-            { kind: 'file', path: join(tempDir, '.claude/skills/ktx-analytics/SKILL.md'), role: 'analytics-skill' },
-            { kind: 'file', path: join(tempDir, '.claude/skills/ktx/SKILL.md'), role: 'skill' },
-            { kind: 'file', path: join(tempDir, '.claude/rules/ktx.md'), role: 'rule' },
-            { kind: 'json-key', path: join(tempDir, '.mcp.json'), jsonPath: ['mcpServers', 'ktx'] },
-            { kind: 'file', path: join(tempDir, '.agents/skills/ktx-analytics/SKILL.md'), role: 'analytics-skill' },
-            { kind: 'file', path: join(tempDir, '.agents/skills/ktx/SKILL.md'), role: 'skill' },
-            { kind: 'file', path: join(tempDir, '.codex/instructions/ktx.md'), role: 'rule' },
-        ], tempDir);
-        expect(summary).toEqual([
-            {
-                title: 'Claude Code · Project scope',
-                lines: [
-                    join(tempDir, '.mcp.json'),
-                    'Requires MCP to be started.',
-                    'Analytics skill installed.',
-                    'Admin CLI skill installed.',
-                ],
-            },
-            {
-                title: 'Codex · Project scope',
-                lines: [
-                    'Add the snippet shown below to ~/.codex/config.toml.',
-                    'Requires MCP to be started.',
-                    'Codex guidance installed.',
-                ],
-            },
-        ]);
-    });
-    it('prints one target-aware next actions block for mixed agent targets', async () => {
-        const home = await mkdtemp(join(tmpdir(), 'ktx-setup-agents-home-'));
-        const previousHome = process.env.HOME;
-        process.env.HOME = home;
-        try {
-            const io = makeIo();
-            const prompts = {
-                select: vi.fn(async ({ message }) => message.startsWith('Where should') ? 'project' : 'mcp'),
-                multiselect: vi.fn(async () => ['claude-code', 'claude-desktop']),
-                cancel: vi.fn(),
-            };
-            await expect(runKtxSetupAgentsStep({
-                projectDir: tempDir,
-                inputMode: 'auto',
-                yes: false,
-                agents: true,
-                scope: 'project',
-                mode: 'mcp',
-                skipAgents: false,
-            }, io.io, { prompts })).resolves.toMatchObject({
-                status: 'ready',
-                installs: [
-                    { target: 'claude-code', scope: 'project', mode: 'mcp' },
-                    { target: 'claude-desktop', scope: 'global', mode: 'mcp' },
-                ],
-            });
-            const output = io.stdout();
-            expect(output).toContain('Required before using agents');
-            expect(output).not.toContain('Next actions');
-            expect(output).toContain('1. Start MCP');
-            expect(output).toContain('Run this command before using Claude Code:');
-            expect(output).toContain(`ktx mcp start --project-dir ${tempDir}`);
-            expect(output).toContain(`ktx mcp stop --project-dir ${tempDir}\n\n2. Open Claude Code`);
-            expect(output).toContain('Open Claude Code from the KTX project directory');
-            expect(output).toContain('RUN:');
-            expect(output).toContain(`cd '${tempDir}'`);
-            expect(output).toContain('3. Restart Claude Desktop');
-            expect(output).toContain('Claude Desktop loads KTX MCP after restart.');
-            expect(output).toContain('4. Upload Claude Desktop skills');
-            expect(output).toContain('Customize > Skills > + > Create skill > Upload a skill');
-            expect(output).toContain(join(tempDir, '.ktx/agents/claude/ktx-analytics.zip'));
-            expect(output).not.toContain(join(tempDir, '.ktx/agents/claude/ktx.zip'));
-            expect(output).toContain('Upload this file:');
-            expect(output).toContain('All set.');
-            expect(output).not.toContain('Finish Claude Desktop setup');
-            expect(output).not.toContain('Run `ktx mcp start` to enable the configured KTX MCP server.');
-        }
-        finally {
-            process.env.HOME = previousHome;
-            await rm(home, { recursive: true, force: true });
-        }
-    });
-    it('does not tell global Claude Code installs to open from the project directory', async () => {
-        const home = await mkdtemp(join(tmpdir(), 'ktx-setup-agents-home-'));
-        const previousHome = process.env.HOME;
-        process.env.HOME = home;
-        try {
-            const io = makeIo();
-            await expect(runKtxSetupAgentsStep({
-                projectDir: tempDir,
-                inputMode: 'disabled',
-                yes: true,
-                agents: true,
-                target: 'claude-code',
-                scope: 'global',
-                mode: 'mcp',
-                skipAgents: false,
-            }, io.io)).resolves.toMatchObject({
-                status: 'ready',
-                installs: [{ target: 'claude-code', scope: 'global', mode: 'mcp' }],
-            });
-            const output = io.stdout();
-            expect(output).toContain('2. Open Claude Code');
-            expect(output).toContain('RUN:');
-            expect(output).toContain('claude');
-            expect(output).not.toContain('Open Claude Code from the KTX project directory');
-            expect(output).not.toContain(`cd '${tempDir}'`);
-        }
-        finally {
-            process.env.HOME = previousHome;
-            await rm(home, { recursive: true, force: true });
-        }
-    });
-    it('explains next actions for Codex, Cursor, OpenCode, and universal MCP targets', async () => {
-        const io = makeIo();
-        const prompts = {
-            select: vi.fn(async () => 'mcp-cli'),
-            multiselect: vi.fn(async () => ['codex', 'cursor', 'opencode', 'universal']),
-            cancel: vi.fn(),
-        };
-        await expect(runKtxSetupAgentsStep({
-            projectDir: tempDir,
-            inputMode: 'auto',
-            yes: false,
-            agents: true,
-            scope: 'project',
-            mode: 'mcp-cli',
-            skipAgents: false,
-        }, io.io, { prompts })).resolves.toMatchObject({
-            status: 'ready',
-            installs: [
-                { target: 'codex', scope: 'project', mode: 'mcp-cli' },
-                { target: 'cursor', scope: 'project', mode: 'mcp-cli' },
-                { target: 'opencode', scope: 'project', mode: 'mcp-cli' },
-                { target: 'universal', scope: 'project', mode: 'mcp-cli' },
-            ],
-        });
-        const output = io.stdout();
-        expect(output).toContain('Required before using agents');
-        expect(output).toContain('1. Configure Codex');
-        expect(output).toContain('2. Configure OpenCode');
-        expect(output).toContain('3. Configure unsupported MCP clients');
-        expect(output).toContain('4. Start MCP');
-        expect(output).toContain('Run this command before using Codex, Cursor, OpenCode, and Universal .agents:');
-        expect(output).toContain('Open Cursor from the KTX project directory');
-        expect(output).toContain('Open ~/.codex/config.toml, then paste this block:\n\n  PASTE:\n  [mcp_servers.ktx]');
-        expect(output).toContain('Open opencode.json, then paste this block:');
-        expect(output).toContain('Use this endpoint when setting up unsupported MCP clients:');
-        expect(output).toContain('Codex guidance installed');
-        expect(output).toContain('Cursor rules installed');
-        expect(output).toContain('OpenCode commands installed');
-        expect(output).toContain('.agents guidance installed');
-    });
-    describe('createAgentNextActionsLineFormatter', () => {
-        function makeColorStdout() {
-            return { write: () => true, hasColors: () => true };
-        }
-        function makePlainStdout() {
-            return { write: () => true, hasColors: () => false };
-        }
-        const ESC = String.fromCharCode(27);
-        it('returns the line untouched when the stream cannot render colors', () => {
-            const format = createAgentNextActionsLineFormatter(makePlainStdout());
-            expect(format('2. Upload Claude Desktop skills')).toBe('2. Upload Claude Desktop skills');
-            expect(format('  /tmp/ktx/.ktx/agents/claude/ktx.zip')).toBe('  /tmp/ktx/.ktx/agents/claude/ktx.zip');
-        });
-        it('styles step headings and aligns sub-prose under the title', () => {
-            const format = createAgentNextActionsLineFormatter(makeColorStdout());
-            const heading = format('2. Upload Claude Desktop skills');
-            expect(heading).toContain(ESC);
-            expect(heading).toContain('2');
-            expect(heading).toContain('Upload Claude Desktop skills');
-            expect(heading).not.toMatch(/^2\. /);
-            const sub = format('  Toggle the uploaded KTX skills on.');
-            expect(sub).toMatch(/^ {3}/);
-            expect(sub).toContain('Toggle the uploaded KTX skills on.');
-        });
-        it('renders skill bundle .zip paths as bullets and shortens HOME to ~', () => {
-            const previousHome = process.env.HOME;
-            process.env.HOME = '/tmp/test-home';
-            try {
-                const format = createAgentNextActionsLineFormatter(makeColorStdout());
-                const line = format('  /tmp/test-home/.ktx/agents/claude/ktx-analytics.zip');
-                expect(line).toContain('•');
-                expect(line).toContain('~/.ktx/agents/claude/ktx-analytics.zip');
-                expect(line).not.toContain('/tmp/test-home/');
-            }
-            finally {
-                if (previousHome === undefined)
-                    delete process.env.HOME;
-                else
-                    process.env.HOME = previousHome;
-            }
-        });
-        it('replaces breadcrumb separators with a typographic chevron', () => {
-            const format = createAgentNextActionsLineFormatter(makeColorStdout());
-            const line = format('  Open Claude Desktop: Customize > Skills > + > Create skill > Upload a skill.');
-            expect(line).toContain('›');
-            expect(line).not.toContain(' > ');
-        });
-        it('leaves already-styled lines untouched to avoid double-wrapping', () => {
-            const format = createAgentNextActionsLineFormatter(makeColorStdout());
-            const preStyled = `${ESC}[1m2. Already styled${ESC}[22m`;
-            expect(format(preStyled)).toBe(preStyled);
-        });
-    });
-});