mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-07 07:55:13 +02:00
feat(cli): improve agent setup guidance
This commit is contained in:
Luca Martial
parent
05750836b8
commit
1a2bb1015d
6 changed files with 708 additions and 138 deletions
|
|
@ -49,8 +49,10 @@ describe('KTX demo next steps', () => {
|
|||
const rendered = formatNextStepLines().join('\n');
|
||||
|
||||
expect(rendered).toContain('KTX context is ready for agents.');
|
||||
expect(rendered).toContain('KTX project directory');
|
||||
expect(rendered).toContain('ask a data question');
|
||||
expect(rendered).toContain('Verify with:');
|
||||
expect(rendered).not.toContain('this directory');
|
||||
expect(rendered).not.toContain('Preferred route');
|
||||
expect(rendered).not.toContain('Optional MCP:');
|
||||
});
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ function commandLines(commands: ReadonlyArray<{ command: string; description: st
|
|||
|
||||
export function formatNextStepLines(indent = ' '): string[] {
|
||||
return [
|
||||
`${indent}KTX context is ready for agents. Open your coding agent in this directory and ask a data question.`,
|
||||
`${indent}KTX context is ready for agents. Open your coding agent from the KTX project directory and ask a data question.`,
|
||||
`${indent}Verify with:`,
|
||||
...commandLines(KTX_NEXT_STEP_DIRECT_COMMANDS, indent),
|
||||
];
|
||||
|
|
|
|||
|
|
@ -144,7 +144,7 @@ describe('setup agents', () => {
|
|||
},
|
||||
io.io,
|
||||
),
|
||||
).resolves.toEqual({
|
||||
).resolves.toMatchObject({
|
||||
status: 'ready',
|
||||
projectDir: tempDir,
|
||||
installs: [{ target: 'universal', scope: 'project', mode: 'mcp-cli' }],
|
||||
|
|
@ -170,6 +170,63 @@ describe('setup agents', () => {
|
|||
expect(io.stderr()).toBe('');
|
||||
});
|
||||
|
||||
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()).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('Agent integration complete');
|
||||
expect(io.stdout()).not.toContain('Required before using agents');
|
||||
});
|
||||
|
||||
it('installs the analytics skill from the runtime asset', async () => {
|
||||
const io = makeIo();
|
||||
|
||||
|
|
@ -252,7 +309,6 @@ describe('setup agents', () => {
|
|||
expect(await readKtxAgentInstallManifest(tempDir)).toMatchObject({
|
||||
entries: expect.arrayContaining([{ kind: 'json-key', path: join(tempDir, '.mcp.json'), jsonPath: ['mcpServers', 'ktx'] }]),
|
||||
});
|
||||
expect(io.stdout()).toContain('Run `ktx mcp start` to enable the configured KTX MCP server.');
|
||||
});
|
||||
|
||||
it('prompts for MCP-first client agent connection mode in interactive setup', async () => {
|
||||
|
|
@ -283,10 +339,18 @@ describe('setup agents', () => {
|
|||
});
|
||||
|
||||
expect(prompts.select).toHaveBeenCalledWith({
|
||||
message: 'How should client agents connect to this KTX project?',
|
||||
message: 'What should agents be allowed to do with this KTX project?',
|
||||
options: [
|
||||
{ value: 'mcp', label: 'MCP tools + analytics skill' },
|
||||
{ value: 'mcp-cli', label: 'MCP tools + analytics skill + admin CLI skill' },
|
||||
{
|
||||
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(
|
||||
|
|
@ -330,10 +394,18 @@ describe('setup agents', () => {
|
|||
});
|
||||
|
||||
expect(prompts.select).toHaveBeenCalledWith({
|
||||
message: 'Where should KTX install supported agent config?',
|
||||
message: `Where should KTX install supported agent config?\n\nKTX project: ${tempDir}`,
|
||||
options: [
|
||||
{ value: 'project', label: 'Project' },
|
||||
{ value: 'global', label: 'Global' },
|
||||
{
|
||||
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 {
|
||||
|
|
@ -395,14 +467,18 @@ describe('setup agents', () => {
|
|||
expect(await readZipText(pluginPath, 'skills/ktx-analytics/SKILL.md')).toContain('KTX Analytics Workflow');
|
||||
const setupMd = await readZipText(pluginPath, 'SETUP.md');
|
||||
expect(setupMd).not.toContain('ktx mcp start');
|
||||
expect(setupMd).toContain('no manual plugin install step is required');
|
||||
expect(setupMd).toContain('claude_desktop_config.json');
|
||||
expect(setupMd).not.toContain('Install this plugin ZIP from Claude Desktop');
|
||||
await expect(readZipText(pluginPath, 'skills/ktx/SKILL.md')).rejects.toThrow('Missing zip entry');
|
||||
|
||||
expect(io.stdout()).toContain('Claude plugin generated');
|
||||
expect(io.stdout()).toContain('.ktx/agents/claude/ktx-plugin.zip');
|
||||
expect(io.stdout()).toContain('KTX MCP server registered');
|
||||
expect(io.stdout()).toContain('Claude Desktop');
|
||||
expect(io.stdout()).not.toContain('.ktx/agents/claude/ktx-plugin.zip');
|
||||
expect(io.stdout()).toContain('claude_desktop_config.json');
|
||||
expect(io.stdout()).toContain('Restart Claude Desktop');
|
||||
expect(io.stdout()).toContain('Required before using agents');
|
||||
expect(io.stdout()).toContain('1. Restart Claude Desktop');
|
||||
expect(io.stdout()).toContain('Claude Desktop loads KTX after restart.');
|
||||
expect(io.stdout()).not.toContain('install plugin');
|
||||
expect(io.stdout()).not.toContain('Run `ktx mcp start`');
|
||||
} finally {
|
||||
process.env.HOME = previousHome;
|
||||
|
|
@ -568,6 +644,9 @@ describe('setup agents', () => {
|
|||
);
|
||||
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(
|
||||
|
|
@ -585,6 +664,8 @@ describe('setup agents', () => {
|
|||
);
|
||||
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();
|
||||
|
|
@ -603,6 +684,8 @@ describe('setup agents', () => {
|
|||
);
|
||||
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 () => {
|
||||
|
|
@ -648,7 +731,9 @@ describe('setup agents', () => {
|
|||
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 `ktx mcp start` to enable the configured KTX MCP server.');
|
||||
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;
|
||||
|
|
@ -833,31 +918,35 @@ describe('setup agents', () => {
|
|||
|
||||
const output = io.stdout();
|
||||
expect(output).toContain('Agent integration complete');
|
||||
expect(output).toContain(`KTX project\n ${tempDir}`);
|
||||
expect(output).toContain('Installed agents');
|
||||
expect(output).toContain('Claude Code');
|
||||
expect(output).toContain('+ Analytics skill installed — teaches your agent the KTX MCP analytics workflow');
|
||||
expect(output).toContain('.claude/skills/ktx-analytics/SKILL.md');
|
||||
expect(output).toContain('+ Skill installed — teaches admin agents which KTX CLI commands to run');
|
||||
expect(output).toContain('.claude/skills/ktx/SKILL.md');
|
||||
expect(output).toContain('+ Rule installed — tells admin agents when to use KTX CLI');
|
||||
expect(output).toContain('.claude/rules/ktx.md');
|
||||
expect(output).toContain(`Project scope\n ${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('.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 relative paths for project scope', () => {
|
||||
it('formats summary with explicit project-scoped config paths', () => {
|
||||
const summary = formatInstallSummary(
|
||||
[{ 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).toContain('Cursor');
|
||||
expect(summary).toContain('+ Analytics skill installed — teaches your agent the KTX MCP analytics workflow');
|
||||
expect(summary).toContain('.cursor/rules/ktx-analytics.mdc');
|
||||
expect(summary).toContain('+ Rule installed — tells admin agents when to use KTX CLI');
|
||||
expect(summary).toContain('.cursor/rules/ktx.mdc');
|
||||
expect(summary).not.toContain(tempDir);
|
||||
expect(summary).toContain(`Project scope\n ${join(tempDir, '.cursor/mcp.json')}`);
|
||||
expect(summary).toContain('Requires MCP to be started');
|
||||
expect(summary).toContain('Cursor rules installed');
|
||||
expect(summary).not.toContain('.cursor/rules/ktx-analytics.mdc');
|
||||
expect(summary).not.toContain('.cursor/rules/ktx.mdc');
|
||||
});
|
||||
|
||||
it('formats summary with multiple agent targets', () => {
|
||||
|
|
@ -870,6 +959,7 @@ describe('setup agents', () => {
|
|||
{ 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' },
|
||||
|
|
@ -878,11 +968,159 @@ describe('setup agents', () => {
|
|||
);
|
||||
|
||||
expect(summary).toContain('Claude Code');
|
||||
expect(summary).toContain('+ Analytics skill installed — teaches your agent the KTX MCP analytics workflow');
|
||||
expect(summary).toContain('+ Skill installed — teaches admin agents which KTX CLI commands to run');
|
||||
expect(summary).toContain('+ Rule installed — tells admin agents when to use KTX CLI');
|
||||
expect(summary).toContain('Project scope\n ');
|
||||
expect(summary).toContain('Analytics skill installed');
|
||||
expect(summary).toContain('Admin CLI skill installed');
|
||||
expect(summary).toContain('\n\n Codex\n');
|
||||
expect(summary).toContain('MCP config\n Add the snippet shown below to ~/.codex/config.toml.');
|
||||
expect(summary).toContain('Codex');
|
||||
expect(summary).toContain('.agents/skills/ktx-analytics/SKILL.md');
|
||||
expect(summary).toContain('.agents/skills/ktx/SKILL.md');
|
||||
expect(summary).toContain('Codex guidance installed');
|
||||
expect(summary).not.toContain('.agents/skills/ktx-analytics/SKILL.md');
|
||||
expect(summary).not.toContain('.agents/skills/ktx/SKILL.md');
|
||||
});
|
||||
|
||||
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: string }) =>
|
||||
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 after restart.');
|
||||
expect(output).not.toContain('install plugin');
|
||||
expect(output).not.toContain(join(tempDir, '.ktx/agents/claude/ktx-plugin.zip'));
|
||||
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');
|
||||
});
|
||||
});
|
||||
|
|
|
|||
|
|
@ -9,7 +9,6 @@ import {
|
|||
} from '@ktx/context/project';
|
||||
import { strToU8, zipSync } from 'fflate';
|
||||
import type { KtxCliIo } from './cli-runtime.js';
|
||||
import { bold, dim, green } from './io/symbols.js';
|
||||
import { withMultiselectNavigation } from './prompt-navigation.js';
|
||||
import {
|
||||
createKtxSetupPromptAdapter,
|
||||
|
|
@ -31,6 +30,7 @@ export interface KtxSetupAgentsArgs {
|
|||
scope: KtxAgentScope;
|
||||
mode: KtxAgentInstallMode;
|
||||
skipAgents: boolean;
|
||||
showNextActions?: boolean;
|
||||
}
|
||||
|
||||
export type KtxSetupAgentsResult =
|
||||
|
|
@ -38,6 +38,7 @@ export type KtxSetupAgentsResult =
|
|||
status: 'ready';
|
||||
projectDir: string;
|
||||
installs: Array<{ target: KtxAgentTarget; scope: KtxAgentScope; mode: KtxAgentInstallMode }>;
|
||||
nextActions?: string;
|
||||
}
|
||||
| { status: 'skipped'; projectDir: string }
|
||||
| { status: 'back'; projectDir: string }
|
||||
|
|
@ -69,6 +70,8 @@ interface KtxMcpClientInstallResult {
|
|||
notices: string[];
|
||||
}
|
||||
|
||||
const MCP_DAEMON_REQUIRED_NOTICE = 'mcp-daemon-required';
|
||||
|
||||
interface KtxCliLauncher {
|
||||
command: string;
|
||||
args: string[];
|
||||
|
|
@ -257,7 +260,7 @@ async function installMcpClientConfig(input: {
|
|||
|
||||
const endpoint = await resolveMcpEndpoint(input.projectDir);
|
||||
if (!endpoint.running) {
|
||||
notices.push('Run `ktx mcp start` to enable the configured KTX MCP server.');
|
||||
notices.push(MCP_DAEMON_REQUIRED_NOTICE);
|
||||
}
|
||||
|
||||
if (input.target === 'claude-code') {
|
||||
|
|
@ -269,15 +272,15 @@ async function installMcpClientConfig(input: {
|
|||
await writeJsonKey(config.path, config.jsonPath, cursorMcpEntry(endpoint));
|
||||
entries.push({ kind: 'json-key', path: config.path, jsonPath: config.jsonPath });
|
||||
} else if (input.target === 'codex') {
|
||||
snippets.push(`Codex MCP snippet for ~/.codex/config.toml:\n${codexSnippet(endpoint)}`);
|
||||
snippets.push(`Add this Codex MCP snippet to ~/.codex/config.toml:\n${codexSnippet(endpoint)}`);
|
||||
} else if (input.target === 'opencode') {
|
||||
const path =
|
||||
input.scope === 'global'
|
||||
? '~/.config/opencode/opencode.json'
|
||||
: relative(input.projectDir, join(input.projectDir, 'opencode.json'));
|
||||
snippets.push(`opencode MCP snippet for ${path}:\n${opencodeSnippet(endpoint)}`);
|
||||
snippets.push(`Add this OpenCode MCP snippet to ${path}:\n${opencodeSnippet(endpoint)}`);
|
||||
} else if (input.target === 'universal') {
|
||||
snippets.push(universalMcpSnippet(endpoint));
|
||||
snippets.push(`Use this universal MCP endpoint with unsupported MCP clients:\n${universalMcpSnippet(endpoint)}`);
|
||||
}
|
||||
|
||||
return { entries, snippets, notices };
|
||||
|
|
@ -504,7 +507,7 @@ function claudePluginSetupContent(input: { projectDir: string; withAdminCli: boo
|
|||
return [
|
||||
'# KTX Claude Plugin',
|
||||
'',
|
||||
'Install this plugin ZIP from Claude Desktop to load the KTX analytics skill.',
|
||||
'This package is generated by KTX setup. Claude Desktop loads KTX through the registered `claude_desktop_config.json` entry after restart; no manual plugin install step is required.',
|
||||
'',
|
||||
`KTX project: \`${input.projectDir}\``,
|
||||
'',
|
||||
|
|
@ -515,7 +518,7 @@ function claudePluginSetupContent(input: { projectDir: string; withAdminCli: boo
|
|||
'',
|
||||
'The KTX MCP server is registered separately in `claude_desktop_config.json` by `ktx setup` and runs as a local stdio child of Claude Desktop — no daemon to start.',
|
||||
'',
|
||||
'If this checkout or project directory moves, rerun `ktx setup --agents` and reinstall the regenerated plugin.',
|
||||
'If this checkout or project directory moves, rerun `ktx setup --agents` and restart Claude Desktop.',
|
||||
'',
|
||||
].join('\n');
|
||||
}
|
||||
|
|
@ -719,17 +722,8 @@ const targetDisplayNames: Record<KtxAgentTarget, string> = {
|
|||
universal: 'Universal .agents',
|
||||
};
|
||||
|
||||
const fileEntryLabels: Record<KtxAgentTarget, string> = {
|
||||
'claude-code': 'Skill installed',
|
||||
'claude-desktop': 'Skill installed',
|
||||
codex: 'Skill installed',
|
||||
cursor: 'Rule installed',
|
||||
opencode: 'Command installed',
|
||||
universal: 'Skill installed',
|
||||
};
|
||||
|
||||
function mcpEntryLabel(entry: Extract<InstallEntry, { kind: 'json-key' }>): string {
|
||||
return `MCP config installed — connects client agents to KTX MCP tools (${entry.jsonPath.join('.')})`;
|
||||
export function targetDisplayName(target: string): string {
|
||||
return Object.hasOwn(targetDisplayNames, target) ? targetDisplayNames[target as KtxAgentTarget] : target;
|
||||
}
|
||||
|
||||
function targetSupportsGlobalScope(target: KtxAgentTarget): boolean {
|
||||
|
|
@ -740,11 +734,58 @@ function effectiveInstallScope(target: KtxAgentTarget, requestedScope: KtxAgentS
|
|||
return target === 'claude-desktop' ? 'global' : requestedScope;
|
||||
}
|
||||
|
||||
function scopeDisplayName(scope: KtxAgentScope): string {
|
||||
if (scope === 'project') return 'Project scope';
|
||||
if (scope === 'global') return 'Global scope';
|
||||
return 'Local scope';
|
||||
}
|
||||
|
||||
function targetUsesHttpMcpDaemon(target: KtxAgentTarget): boolean {
|
||||
return target !== 'claude-desktop';
|
||||
}
|
||||
|
||||
function manualMcpConfigInstruction(target: KtxAgentTarget, scope: KtxAgentScope): string {
|
||||
if (target === 'codex') {
|
||||
return 'Add the snippet shown below to ~/.codex/config.toml.';
|
||||
}
|
||||
if (target === 'opencode') {
|
||||
return scope === 'global'
|
||||
? 'Add the snippet shown below to ~/.config/opencode/opencode.json.'
|
||||
: 'Add the snippet shown below to opencode.json.';
|
||||
}
|
||||
if (target === 'universal') {
|
||||
return 'Use the printed endpoint with unsupported MCP clients.';
|
||||
}
|
||||
return 'Add the printed snippet manually.';
|
||||
}
|
||||
|
||||
function guidanceInstallLine(target: KtxAgentTarget): string {
|
||||
if (target === 'codex') return 'Codex guidance installed';
|
||||
if (target === 'cursor') return 'Cursor rules installed';
|
||||
if (target === 'opencode') return 'OpenCode commands installed';
|
||||
if (target === 'universal') return '.agents guidance installed';
|
||||
if (target === 'claude-desktop') return 'Claude Desktop skills bundled';
|
||||
return 'Agent guidance installed';
|
||||
}
|
||||
|
||||
function hasEntryRole(entries: InstallEntry[], role: Extract<InstallEntry, { kind: 'file' }>['role']): boolean {
|
||||
return entries.some((entry) => entry.kind === 'file' && entry.role === role);
|
||||
}
|
||||
|
||||
function hasAdminCliEntries(entries: InstallEntry[]): boolean {
|
||||
return entries.some(
|
||||
(entry) =>
|
||||
entry.kind === 'file' &&
|
||||
(entry.role === 'skill' || entry.role === 'rule' || entry.role === undefined),
|
||||
);
|
||||
}
|
||||
|
||||
export function formatInstallSummary(
|
||||
installs: Array<{ target: KtxAgentTarget; scope: KtxAgentScope; mode: KtxAgentInstallMode }>,
|
||||
entries: InstallEntry[],
|
||||
projectDir: string,
|
||||
): string {
|
||||
const resolvedProjectDir = resolve(projectDir);
|
||||
const entriesByTarget = new Map<KtxAgentTarget, InstallEntry[]>();
|
||||
for (const install of installs) {
|
||||
const plannedFilePaths = new Set(
|
||||
|
|
@ -766,51 +807,193 @@ export function formatInstallSummary(
|
|||
);
|
||||
}
|
||||
|
||||
const fileHints: Record<string, string> = {
|
||||
skill: 'teaches admin agents which KTX CLI commands to run',
|
||||
rule: 'tells admin agents when to use KTX CLI',
|
||||
'analytics-skill': 'teaches your agent the KTX MCP analytics workflow',
|
||||
'claude-plugin': 'bundles KTX skills for Claude Desktop (MCP server is registered in claude_desktop_config.json)',
|
||||
launcher: 'runs the local KTX CLI with an available Node.js for Claude Desktop',
|
||||
};
|
||||
|
||||
const lines: string[] = [];
|
||||
const lines: string[] = ['KTX project', ` ${resolvedProjectDir}`, '', 'Installed agents'];
|
||||
for (const install of installs) {
|
||||
const targetEntries = entriesByTarget.get(install.target) ?? [];
|
||||
lines.push(` ${targetDisplayNames[install.target]}`);
|
||||
for (const entry of targetEntries) {
|
||||
if (entry.kind === 'file') {
|
||||
const isRule = entry.role === 'rule' || (!entry.role && fileEntryLabels[install.target] === 'Rule installed');
|
||||
const label =
|
||||
entry.role === 'analytics-skill'
|
||||
? 'Analytics skill installed'
|
||||
: entry.role === 'claude-plugin'
|
||||
? 'Claude plugin generated'
|
||||
: entry.role === 'launcher'
|
||||
? 'Launcher installed'
|
||||
: isRule
|
||||
? 'Rule installed'
|
||||
: fileEntryLabels[install.target];
|
||||
const hint = fileHints[isRule ? 'rule' : (entry.role ?? 'skill')] ?? '';
|
||||
lines.push(` + ${label} — ${hint}`);
|
||||
if (entry.role !== 'claude-plugin') {
|
||||
const displayPath =
|
||||
install.scope === 'global' ? entry.path : relative(projectDir, entry.path);
|
||||
lines.push(` ${displayPath}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
for (const entry of mcpEntriesByTarget
|
||||
const mcpEntry = mcpEntriesByTarget
|
||||
.get(install.target)
|
||||
?.filter((entry): entry is Extract<InstallEntry, { kind: 'json-key' }> => entry.kind === 'json-key') ?? []) {
|
||||
const displayPath = install.scope === 'global' ? entry.path : relative(projectDir, entry.path);
|
||||
lines.push(` + ${mcpEntryLabel(entry)}`);
|
||||
lines.push(` ${displayPath}`);
|
||||
?.find((entry): entry is Extract<InstallEntry, { kind: 'json-key' }> => entry.kind === 'json-key');
|
||||
lines.push('', ` ${targetDisplayName(install.target)}`);
|
||||
if (mcpEntry) {
|
||||
lines.push(` ${scopeDisplayName(install.scope)}`);
|
||||
lines.push(` ${mcpEntry.path}`);
|
||||
} else if (install.target !== 'claude-desktop') {
|
||||
lines.push(' MCP config');
|
||||
lines.push(` ${manualMcpConfigInstruction(install.target, install.scope)}`);
|
||||
}
|
||||
if (targetUsesHttpMcpDaemon(install.target)) {
|
||||
lines.push(' Requires MCP to be started');
|
||||
}
|
||||
const hasAnalytics = hasEntryRole(targetEntries, 'analytics-skill');
|
||||
const hasAdmin = hasAdminCliEntries(targetEntries);
|
||||
const hasPlugin = hasEntryRole(targetEntries, 'claude-plugin');
|
||||
if (install.target === 'claude-code') {
|
||||
if (hasAnalytics) {
|
||||
lines.push(' Analytics skill installed');
|
||||
}
|
||||
if (hasAdmin) {
|
||||
lines.push(' Admin CLI skill installed');
|
||||
}
|
||||
} else if (hasAnalytics || hasAdmin || hasPlugin) {
|
||||
lines.push(` ${guidanceInstallLine(install.target)}`);
|
||||
}
|
||||
if (hasEntryRole(targetEntries, 'launcher')) {
|
||||
lines.push(' Starts KTX over stdio from Claude Desktop');
|
||||
}
|
||||
}
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
function humanList(values: string[]): string {
|
||||
if (values.length <= 2) {
|
||||
return values.join(' and ');
|
||||
}
|
||||
return `${values.slice(0, -1).join(', ')}, and ${values[values.length - 1]}`;
|
||||
}
|
||||
|
||||
function pushBlankLine(lines: string[]): void {
|
||||
if (lines.length > 0 && lines[lines.length - 1] !== '') {
|
||||
lines.push('');
|
||||
}
|
||||
}
|
||||
|
||||
function trimTrailingBlankLines(lines: string[]): void {
|
||||
while (lines[lines.length - 1] === '') {
|
||||
lines.pop();
|
||||
}
|
||||
}
|
||||
|
||||
function manualActionFromSnippet(snippet: string): {
|
||||
title: string;
|
||||
instruction: string;
|
||||
marker: 'PASTE' | 'USE';
|
||||
body: string[];
|
||||
} {
|
||||
const [label = '', ...body] = snippet.split('\n');
|
||||
const codexPrefix = 'Add this Codex MCP snippet to ~/.codex/config.toml:';
|
||||
if (label === codexPrefix) {
|
||||
return {
|
||||
title: 'Configure Codex',
|
||||
instruction: 'Open ~/.codex/config.toml, then paste this block:',
|
||||
marker: 'PASTE',
|
||||
body,
|
||||
};
|
||||
}
|
||||
|
||||
const opencodeMatch = label.match(/^Add this OpenCode MCP snippet to (.+):$/);
|
||||
if (opencodeMatch) {
|
||||
return {
|
||||
title: 'Configure OpenCode',
|
||||
instruction: `Open ${opencodeMatch[1]}, then paste this block:`,
|
||||
marker: 'PASTE',
|
||||
body,
|
||||
};
|
||||
}
|
||||
|
||||
if (label === 'Use this universal MCP endpoint with unsupported MCP clients:') {
|
||||
return {
|
||||
title: 'Configure unsupported MCP clients',
|
||||
instruction: 'Use this endpoint when setting up unsupported MCP clients:',
|
||||
marker: 'USE',
|
||||
body,
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
title: 'Configure MCP client',
|
||||
instruction: label,
|
||||
marker: 'PASTE',
|
||||
body,
|
||||
};
|
||||
}
|
||||
|
||||
function formatAgentNextActions(input: {
|
||||
projectDir: string;
|
||||
installs: Array<{ target: KtxAgentTarget; scope: KtxAgentScope; mode: KtxAgentInstallMode }>;
|
||||
notices: string[];
|
||||
snippets: string[];
|
||||
}): string {
|
||||
const projectDir = resolve(input.projectDir);
|
||||
const lines: string[] = [];
|
||||
let step = 1;
|
||||
|
||||
for (const snippet of input.snippets) {
|
||||
const action = manualActionFromSnippet(snippet);
|
||||
lines.push(`${step}. ${action.title}`);
|
||||
lines.push(` ${action.instruction}`);
|
||||
if (action.body.length > 0) {
|
||||
lines.push('', ` ${action.marker}:`);
|
||||
}
|
||||
for (const line of action.body) {
|
||||
lines.push(` ${line}`);
|
||||
}
|
||||
pushBlankLine(lines);
|
||||
step += 1;
|
||||
}
|
||||
|
||||
const httpTargets = input.installs
|
||||
.filter((install) => targetUsesHttpMcpDaemon(install.target))
|
||||
.map((install) => targetDisplayName(install.target));
|
||||
if (input.notices.length > 0 && httpTargets.length > 0) {
|
||||
lines.push(`${step}. Start MCP`);
|
||||
lines.push(` Run this command before using ${humanList(httpTargets)}:`);
|
||||
lines.push('');
|
||||
lines.push(' RUN:');
|
||||
lines.push(` ktx mcp start --project-dir ${projectDir}`);
|
||||
lines.push('');
|
||||
lines.push(' If you need to stop MCP later:');
|
||||
lines.push(` ktx mcp stop --project-dir ${projectDir}`);
|
||||
pushBlankLine(lines);
|
||||
step += 1;
|
||||
}
|
||||
|
||||
const claudeCodeInstall = input.installs.find((install) => install.target === 'claude-code');
|
||||
if (claudeCodeInstall) {
|
||||
lines.push(`${step}. Open Claude Code`);
|
||||
if (claudeCodeInstall.scope === 'project') {
|
||||
lines.push(' Open Claude Code from the KTX project directory:');
|
||||
lines.push('');
|
||||
lines.push(' RUN:');
|
||||
lines.push(` cd ${shellScriptQuote(projectDir)}`);
|
||||
lines.push(' claude');
|
||||
} else {
|
||||
lines.push(' RUN:');
|
||||
lines.push(' claude');
|
||||
}
|
||||
pushBlankLine(lines);
|
||||
step += 1;
|
||||
}
|
||||
|
||||
const cursorInstall = input.installs.find((install) => install.target === 'cursor');
|
||||
if (cursorInstall) {
|
||||
lines.push(`${step}. Open Cursor`);
|
||||
if (cursorInstall.scope === 'project') {
|
||||
lines.push(' Open Cursor from the KTX project directory:');
|
||||
lines.push('');
|
||||
lines.push(' OPEN:');
|
||||
lines.push(` ${projectDir}`);
|
||||
} else {
|
||||
lines.push(' Open Cursor.');
|
||||
}
|
||||
pushBlankLine(lines);
|
||||
step += 1;
|
||||
}
|
||||
|
||||
if (input.installs.some((install) => install.target === 'claude-desktop')) {
|
||||
lines.push(`${step}. Restart Claude Desktop`);
|
||||
lines.push(' Claude Desktop loads KTX after restart.');
|
||||
pushBlankLine(lines);
|
||||
step += 1;
|
||||
}
|
||||
|
||||
if (lines.length === 0) {
|
||||
lines.push('Open your configured agent and ask a data question.');
|
||||
}
|
||||
|
||||
trimTrailingBlankLines(lines);
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
async function installTarget(input: {
|
||||
projectDir: string;
|
||||
target: KtxAgentTarget;
|
||||
|
|
@ -870,10 +1053,18 @@ export async function runKtxSetupAgentsStep(
|
|||
args.inputMode === 'disabled'
|
||||
? args.mode
|
||||
: ((await prompts.select({
|
||||
message: 'How should client agents connect to this KTX project?',
|
||||
message: 'What should agents be allowed to do with this KTX project?',
|
||||
options: [
|
||||
{ value: 'mcp', label: 'MCP tools + analytics skill' },
|
||||
{ value: 'mcp-cli', label: 'MCP tools + analytics skill + admin CLI skill' },
|
||||
{
|
||||
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.',
|
||||
},
|
||||
],
|
||||
})) as KtxAgentInstallMode | 'back');
|
||||
if (mode === 'back') return { status: 'skipped', projectDir: args.projectDir };
|
||||
|
|
@ -908,10 +1099,18 @@ export async function runKtxSetupAgentsStep(
|
|||
scopeTargets.length > 0 &&
|
||||
scopeTargets.every(targetSupportsGlobalScope)
|
||||
? ((await prompts.select({
|
||||
message: 'Where should KTX install supported agent config?',
|
||||
message: `Where should KTX install supported agent config?\n\nKTX project: ${resolve(args.projectDir)}`,
|
||||
options: [
|
||||
{ value: 'project', label: 'Project' },
|
||||
{ value: 'global', label: 'Global' },
|
||||
{
|
||||
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.',
|
||||
},
|
||||
],
|
||||
})) as KtxAgentScope | 'back')
|
||||
: args.scope;
|
||||
|
|
@ -921,7 +1120,6 @@ export async function runKtxSetupAgentsStep(
|
|||
const entries: InstallEntry[] = [];
|
||||
const snippets: string[] = [];
|
||||
const notices = new Set<string>();
|
||||
let claudeDesktopTutorial: string | undefined;
|
||||
try {
|
||||
for (const install of installs) {
|
||||
const targetEntries = await installTarget({ projectDir: args.projectDir, ...install });
|
||||
|
|
@ -934,25 +1132,6 @@ export async function runKtxSetupAgentsStep(
|
|||
entries.push(...mcpResult.entries);
|
||||
for (const snippet of mcpResult.snippets) snippets.push(snippet);
|
||||
for (const notice of mcpResult.notices) notices.add(notice);
|
||||
if (install.target === 'claude-desktop') {
|
||||
const pluginEntry = targetEntries.find(
|
||||
(entry): entry is Extract<InstallEntry, { kind: 'file' }> =>
|
||||
entry.kind === 'file' && entry.role === 'claude-plugin',
|
||||
);
|
||||
const pluginPath = pluginEntry?.path ?? '';
|
||||
const configPath = claudeDesktopConfigPath().path;
|
||||
claudeDesktopTutorial = [
|
||||
`${green('✓')} ${bold('KTX MCP server registered')}`,
|
||||
` ${dim(configPath)}`,
|
||||
'',
|
||||
bold('1. Restart Claude Desktop'),
|
||||
' Quit and reopen so it picks up the new MCP server.',
|
||||
'',
|
||||
bold('2. Install the KTX plugin'),
|
||||
' Open Claude Desktop → Settings → Plugins and install from file:',
|
||||
` 📦 ${dim(pluginPath)}`,
|
||||
].join('\n');
|
||||
}
|
||||
}
|
||||
await writeManifest(
|
||||
args.projectDir,
|
||||
|
|
@ -965,18 +1144,16 @@ export async function runKtxSetupAgentsStep(
|
|||
'Agent integration complete',
|
||||
io,
|
||||
);
|
||||
if (claudeDesktopTutorial) {
|
||||
setupUi.note(claudeDesktopTutorial, 'Finish Claude Desktop setup', io, {
|
||||
format: (line) => line,
|
||||
});
|
||||
const nextActions = formatAgentNextActions({
|
||||
projectDir: args.projectDir,
|
||||
installs,
|
||||
notices: [...notices],
|
||||
snippets,
|
||||
});
|
||||
if (args.showNextActions !== false) {
|
||||
setupUi.note(nextActions, 'Required before using agents', io, { format: (line) => line });
|
||||
}
|
||||
const nextStepBlocks: string[] = [];
|
||||
for (const notice of notices) nextStepBlocks.push(notice);
|
||||
for (const snippet of snippets) nextStepBlocks.push(snippet);
|
||||
if (nextStepBlocks.length > 0) {
|
||||
setupUi.note(nextStepBlocks.join('\n\n'), 'Next steps', io, { format: bold });
|
||||
}
|
||||
return { status: 'ready', projectDir: args.projectDir, installs };
|
||||
return { status: 'ready', projectDir: args.projectDir, installs, nextActions };
|
||||
} catch (error) {
|
||||
io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
|
||||
return { status: 'failed', projectDir: args.projectDir };
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
|
|||
import { localFakeBundleReport, persistLocalBundleReport } from './ingest.test-utils.js';
|
||||
import { contextBuildCommands, writeKtxSetupContextState } from './setup-context.js';
|
||||
import { runDemoTour } from './setup-demo-tour.js';
|
||||
import { formatKtxSetupStatus, readKtxSetupStatus, runKtxSetup } from './setup.js';
|
||||
import { formatKtxSetupCompletionSummary, formatKtxSetupStatus, readKtxSetupStatus, runKtxSetup } from './setup.js';
|
||||
|
||||
vi.mock('./setup-demo-tour.js', () => ({
|
||||
runDemoTour: vi.fn(async () => 0),
|
||||
|
|
@ -424,6 +424,108 @@ describe('setup status', () => {
|
|||
expect(rendered).not.toContain('No KTX project found.');
|
||||
});
|
||||
|
||||
it('formats a concise ready summary for completed agent setup', () => {
|
||||
const rendered = formatKtxSetupCompletionSummary(
|
||||
{
|
||||
project: { path: tempDir, ready: true },
|
||||
llm: { ready: true, model: 'sonnet' },
|
||||
embeddings: { ready: true, model: 'text-embedding-3-small' },
|
||||
databases: [{ connectionId: 'postgres-warehouse', ready: true }],
|
||||
sources: [{ connectionId: 'dbt-main', type: 'dbt', ready: true }],
|
||||
runtime: { required: true, ready: true, features: ['core'] },
|
||||
context: { ready: true, status: 'completed' },
|
||||
agents: [
|
||||
{ target: 'claude-code', scope: 'project', ready: true },
|
||||
{ target: 'claude-desktop', scope: 'global', ready: true },
|
||||
],
|
||||
},
|
||||
{
|
||||
agentNextActions: [
|
||||
'1. Start MCP',
|
||||
' Run this command before using Claude Code:',
|
||||
'',
|
||||
' RUN:',
|
||||
` ktx mcp start --project-dir ${tempDir}`,
|
||||
'',
|
||||
' If you need to stop MCP later:',
|
||||
` ktx mcp stop --project-dir ${tempDir}`,
|
||||
'',
|
||||
'2. Open Claude Code',
|
||||
' Open Claude Code from the KTX project directory:',
|
||||
'',
|
||||
' RUN:',
|
||||
` cd '${tempDir}'`,
|
||||
' claude',
|
||||
].join('\n'),
|
||||
},
|
||||
);
|
||||
|
||||
expect(rendered).toContain(`Project\n ${tempDir}`);
|
||||
expect(rendered).toContain('Context\n built');
|
||||
expect(rendered).toContain('Agents configured\n Claude Code, Claude Desktop');
|
||||
expect(rendered).toContain('REQUIRED BEFORE USING AGENTS\n\n 1. Start MCP');
|
||||
expect(rendered).toContain(' Run this command before using Claude Code:');
|
||||
expect(rendered).toContain(' RUN:');
|
||||
expect(rendered).toContain(' If you need to stop MCP later:');
|
||||
expect(rendered).toContain(`ktx mcp stop --project-dir ${tempDir}`);
|
||||
expect(rendered).toContain('After that, try\n Ask your agent: "Use KTX to show me the available tables."');
|
||||
expect(rendered).not.toContain('Verify');
|
||||
expect(rendered).not.toContain('Project ready: yes');
|
||||
expect(rendered).not.toContain('What you can do next');
|
||||
});
|
||||
|
||||
it('prints agent next actions inside the final ready summary during full setup', async () => {
|
||||
const testIo = makeIo();
|
||||
|
||||
await expect(
|
||||
runKtxSetup(
|
||||
{
|
||||
command: 'run',
|
||||
projectDir: tempDir,
|
||||
mode: 'new',
|
||||
agents: false,
|
||||
target: 'claude-code',
|
||||
skipAgents: false,
|
||||
inputMode: 'disabled',
|
||||
yes: true,
|
||||
cliVersion: '0.2.0',
|
||||
skipLlm: true,
|
||||
skipEmbeddings: true,
|
||||
skipDatabases: true,
|
||||
skipSources: true,
|
||||
databaseSchemas: [],
|
||||
},
|
||||
testIo.io,
|
||||
{
|
||||
runtime: async () => runtimeReady(tempDir),
|
||||
context: async () => {
|
||||
await writeKtxSetupContextState(tempDir, {
|
||||
runId: 'setup-context-local-test',
|
||||
status: 'completed',
|
||||
primarySourceConnectionIds: [],
|
||||
contextSourceConnectionIds: [],
|
||||
reportIds: [],
|
||||
artifactPaths: [],
|
||||
retryableFailedTargets: [],
|
||||
commands: contextBuildCommands(tempDir, 'setup-context-local-test'),
|
||||
});
|
||||
await writeKtxSetupState(tempDir, { completed_steps: ['project', 'context'] });
|
||||
return { status: 'ready', projectDir: tempDir, runId: 'setup-context-local-test' };
|
||||
},
|
||||
},
|
||||
),
|
||||
).resolves.toBe(0);
|
||||
|
||||
const output = testIo.stdout();
|
||||
expect(output).toContain('Agent integration complete');
|
||||
expect(output).toContain('Finish KTX agent setup');
|
||||
expect(output).not.toContain('KTX project ready');
|
||||
expect(output).toContain('REQUIRED BEFORE USING AGENTS');
|
||||
expect(output).toContain('Run this command before using Claude Code:');
|
||||
expect(output).toContain(`ktx mcp start --project-dir ${tempDir}`);
|
||||
expect(output).not.toContain('Finish agent setup');
|
||||
});
|
||||
|
||||
it('prints the setup shell intro for auto-created run mode', async () => {
|
||||
const testIo = makeIo();
|
||||
|
||||
|
|
|
|||
|
|
@ -19,6 +19,7 @@ import {
|
|||
type KtxSetupAgentsDeps,
|
||||
readKtxAgentInstallManifest,
|
||||
runKtxSetupAgentsStep,
|
||||
targetDisplayName,
|
||||
} from './setup-agents.js';
|
||||
import {
|
||||
type KtxSetupDatabaseDriver,
|
||||
|
|
@ -435,6 +436,35 @@ export function formatKtxSetupStatus(status: KtxSetupStatus): string {
|
|||
return `${lines.join('\n')}\n`;
|
||||
}
|
||||
|
||||
export function formatKtxSetupCompletionSummary(
|
||||
status: KtxSetupStatus,
|
||||
options: { agentNextActions?: string } = {},
|
||||
): string {
|
||||
const readyAgents = status.agents.filter((agent) => agent.ready).map((agent) => targetDisplayName(agent.target));
|
||||
const lines = [
|
||||
'Project',
|
||||
` ${status.project.path}`,
|
||||
'',
|
||||
'Context',
|
||||
` ${status.context.ready ? 'built' : formatContextBuilt(status.context)}`,
|
||||
'',
|
||||
'Agents configured',
|
||||
` ${readyAgents.length > 0 ? readyAgents.join(', ') : 'not installed'}`,
|
||||
];
|
||||
const agentNextActions = options.agentNextActions?.trim();
|
||||
if (agentNextActions) {
|
||||
lines.push(
|
||||
'',
|
||||
'REQUIRED BEFORE USING AGENTS',
|
||||
'',
|
||||
...agentNextActions.split('\n').map((line) => (line ? ` ${line}` : '')),
|
||||
);
|
||||
}
|
||||
lines.push('', agentNextActions ? 'After that, try' : 'Try it');
|
||||
lines.push(' Ask your agent: "Use KTX to show me the available tables."');
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
function setupStatusReady(status: KtxSetupStatus): boolean {
|
||||
if (!status.project.ready) {
|
||||
return false;
|
||||
|
|
@ -459,6 +489,10 @@ function setupContextReady(status: KtxSetupStatus): boolean {
|
|||
return status.context.ready;
|
||||
}
|
||||
|
||||
function shouldPrintConciseReadySummary(status: KtxSetupStatus): boolean {
|
||||
return setupStatusReady(status) && setupContextReady(status) && status.agents.some((agent) => agent.ready);
|
||||
}
|
||||
|
||||
function writeContextNotReadyForAgents(projectDir: string, io: KtxCliIo): void {
|
||||
io.stderr.write('KTX context is not ready for agents.\n\n');
|
||||
io.stderr.write(`Build context first:\n ktx setup --project-dir ${resolve(projectDir)}\n\n`);
|
||||
|
|
@ -493,6 +527,7 @@ async function runKtxSetupInner(args: KtxSetupArgs, io: KtxCliIo, deps: KtxSetup
|
|||
setupUi.intro('KTX setup', io);
|
||||
let entryAction: KtxSetupEntryAction | undefined;
|
||||
let projectResult: Awaited<ReturnType<typeof runKtxSetupProjectStep>>;
|
||||
let agentNextActions: string | undefined;
|
||||
const canShowEntryMenu =
|
||||
args.showEntryMenu === true &&
|
||||
args.inputMode !== 'disabled' &&
|
||||
|
|
@ -724,7 +759,7 @@ async function runKtxSetupInner(args: KtxSetupArgs, io: KtxCliIo, deps: KtxSetup
|
|||
} else {
|
||||
const agentsRunner =
|
||||
deps.agents ?? ((agentArgs, agentIo) => runKtxSetupAgentsStep(agentArgs, agentIo, deps.agentsDeps));
|
||||
stepResult = await agentsRunner(
|
||||
const agentResult = await agentsRunner(
|
||||
{
|
||||
projectDir: projectResult.projectDir,
|
||||
inputMode: args.inputMode,
|
||||
|
|
@ -734,9 +769,14 @@ async function runKtxSetupInner(args: KtxSetupArgs, io: KtxCliIo, deps: KtxSetup
|
|||
scope: args.agentScope ?? 'project',
|
||||
mode: 'mcp',
|
||||
skipAgents: false,
|
||||
showNextActions: agentsRequested,
|
||||
},
|
||||
io,
|
||||
);
|
||||
stepResult = agentResult;
|
||||
if (agentResult.status === 'ready') {
|
||||
agentNextActions = agentResult.nextActions;
|
||||
}
|
||||
}
|
||||
|
||||
if (stepResult.status === 'failed' || stepResult.status === 'missing-input') {
|
||||
|
|
@ -779,19 +819,30 @@ async function runKtxSetupInner(args: KtxSetupArgs, io: KtxCliIo, deps: KtxSetup
|
|||
const status = await readKtxSetupStatus(projectResult.projectDir, { cliVersion: args.cliVersion });
|
||||
const focusedOnAgents = args.agents || entryAction === 'agents';
|
||||
if (!focusedOnAgents) {
|
||||
setupUi.note(formatKtxSetupStatus(status).trimEnd(), 'Project status', io, {
|
||||
format: (line) => line,
|
||||
});
|
||||
setupUi.note(
|
||||
formatSetupNextStepLines({
|
||||
setupReady: setupStatusReady(status),
|
||||
hasContextTargets: setupHasContextTargets(status),
|
||||
contextReady: setupContextReady(status),
|
||||
agentIntegrationReady: status.agents.some((agent) => agent.ready),
|
||||
}).join('\n'),
|
||||
'What you can do next',
|
||||
io,
|
||||
);
|
||||
if (shouldPrintConciseReadySummary(status)) {
|
||||
setupUi.note(
|
||||
formatKtxSetupCompletionSummary(status, { agentNextActions }),
|
||||
agentNextActions ? 'Finish KTX agent setup' : 'KTX project ready',
|
||||
io,
|
||||
{
|
||||
format: (line) => line,
|
||||
},
|
||||
);
|
||||
} else {
|
||||
setupUi.note(formatKtxSetupStatus(status).trimEnd(), 'Project status', io, {
|
||||
format: (line) => line,
|
||||
});
|
||||
setupUi.note(
|
||||
formatSetupNextStepLines({
|
||||
setupReady: setupStatusReady(status),
|
||||
hasContextTargets: setupHasContextTargets(status),
|
||||
contextReady: setupContextReady(status),
|
||||
agentIntegrationReady: status.agents.some((agent) => agent.ready),
|
||||
}).join('\n'),
|
||||
'What you can do next',
|
||||
io,
|
||||
);
|
||||
}
|
||||
}
|
||||
return 0;
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue