apunkt/ktx
1
0
Fork 0
mirror of https://github.com/Kaelio/ktx.git synced 2026-06-22 08:38:08 +02:00
Code Issues Projects Releases Packages Wiki Activity

Merge origin/main into rename-knowledge-to-wiki

Browse source
This commit is contained in:
Andrey Avtomonov 2026-05-13 15:47:19 +02:00
commit b494af3574
14 changed files with 308 additions and 301 deletions
Download patch file Download diff file Expand all files Collapse all files

78
packages/cli/src/commands/sl-commands.ts
View file

@ -41,7 +41,7 @@ async function runSlArgs(context: KtxCliCommandContext, args: KtxSlArgs): Promis
export function registerSlCommands(program: Command, context: KtxCliCommandContext, commandName = 'sl'): void {
const sl = program
.command(commandName)
.description('List, read, validate, query, or write local semantic-layer sources')
.description('List, search, validate, or query local semantic-layer sources')
.showHelpAfterError()
.addHelpText(
'after',
@ -51,7 +51,31 @@ export function registerSlCommands(program: Command, context: KtxCliCommandConte
sl.command('list')
.description('List semantic-layer sources')
.option('--connection-id <id>', 'KTX connection id')
.option('--query <text>', 'Search source names and descriptions')
.addOption(
new Option('--output <mode>', 'Output mode: pretty (default in TTY), plain (TSV), or json').choices([
'pretty',
'plain',
'json',
]),
)
.option('--json', 'Shortcut for --output=json (overrides --output)', false)
.action(
async (options: { connectionId?: string; output?: 'pretty' | 'plain' | 'json'; json?: boolean }, command) => {
await runSlArgs(context, {
command: 'list',
projectDir: resolveCommandProjectDir(command),
connectionId: options.connectionId,
output: options.output,
json: options.json,
});
},
);
sl.command('search')
.description('Search semantic-layer sources')
.argument('<query>', 'Search query')
.option('--connection-id <id>', 'KTX connection id')
.option('--limit <number>', 'Maximum search results', parsePositiveIntegerOption)
.addOption(
new Option('--output <mode>', 'Output mode: pretty (default in TTY), plain (TSV), or json').choices([
'pretty',
@ -62,35 +86,22 @@ export function registerSlCommands(program: Command, context: KtxCliCommandConte
.option('--json', 'Shortcut for --output=json (overrides --output)', false)
.action(
async (
options: { connectionId?: string; query?: string; output?: 'pretty' | 'plain' | 'json'; json?: boolean },
query: string,
options: { connectionId?: string; limit?: number; output?: 'pretty' | 'plain' | 'json'; json?: boolean },
command,
) => {
await runSlArgs(context, {
command: 'list',
projectDir: resolveCommandProjectDir(command),
connectionId: options.connectionId,
query: options.query,
output: options.output,
json: options.json,
});
await runSlArgs(context, {
command: 'search',
projectDir: resolveCommandProjectDir(command),
connectionId: options.connectionId,
query,
...(options.limit !== undefined ? { limit: options.limit } : {}),
output: options.output,
json: options.json,
});
},
);
sl.command('read')
.description('Read a semantic-layer source')
.argument('<sourceName>', 'Semantic-layer source name')
.requiredOption('--connection-id <id>', 'KTX connection id')
.option('--json', 'Print JSON output', false)
.action(async (sourceName: string, options: { connectionId: string; json?: boolean }, command) => {
await runSlArgs(context, {
command: 'read',
projectDir: resolveCommandProjectDir(command),
connectionId: options.connectionId,
sourceName,
json: options.json,
});
});
sl.command('validate')
.description('Validate a semantic-layer source')
.argument('<sourceName>', 'Semantic-layer source name')
@ -104,21 +115,6 @@ export function registerSlCommands(program: Command, context: KtxCliCommandConte
});
});
sl.command('write')
.description('Write a semantic-layer source')
.argument('<sourceName>', 'Semantic-layer source name')
.requiredOption('--connection-id <id>', 'KTX connection id')
.requiredOption('--yaml <yaml>', 'Semantic-layer source YAML')
.action(async (sourceName: string, options: { connectionId: string; yaml: string }, command) => {
await runSlArgs(context, {
command: 'write',
projectDir: resolveCommandProjectDir(command),
connectionId: options.connectionId,
sourceName,
yaml: options.yaml,
});
});
sl.command('query')
.description('Compile or execute a semantic-layer query')
.option('--connection-id <id>', 'KTX connection id')

16
packages/cli/src/example-smoke.test.ts
View file

@ -79,12 +79,6 @@ describe('standalone local warehouse example', () => {
parseJsonOutput<{ data: { items: Array<{ key: string; summary: string }> } }>(knowledgeList.stdout).data.items,
).toContainEqual(expect.objectContaining({ key: 'revenue', summary: 'Paid order value after refunds' }));
const knowledgeRead = await runBuiltCli(['wiki', 'read', 'revenue', '--json', '--project-dir', projectDir]);
expect(knowledgeRead).toMatchObject({ code: 0, stderr: '' });
expect(parseJsonOutput<{ data: { content: string } }>(knowledgeRead.stdout).data.content).toContain(
'Revenue is paid order amount after refund adjustments.',
);
const slList = await runBuiltCli(['sl', 'list', '--json', '--project-dir', projectDir, '--connection-id', 'warehouse']);
expect(slList).toMatchObject({ code: 0, stderr: '' });
expect(
@ -93,9 +87,9 @@ describe('standalone local warehouse example', () => {
).data.items,
).toContainEqual(expect.objectContaining({ connectionId: 'warehouse', name: 'orders', columnCount: 3 }));
const slRead = await runBuiltCli([
const slSearch = await runBuiltCli([
'sl',
'read',
'search',
'orders',
'--json',
'--connection-id',
@ -103,8 +97,10 @@ describe('standalone local warehouse example', () => {
'--project-dir',
projectDir,
]);
expect(slRead).toMatchObject({ code: 0, stderr: '' });
expect(parseJsonOutput<{ data: { yaml: string } }>(slRead.stdout).data.yaml).toContain('name: orders');
expect(slSearch).toMatchObject({ code: 0, stderr: '' });
expect(
parseJsonOutput<{ data: { items: Array<{ connectionId: string; name: string }> } }>(slSearch.stdout).data.items,
).toContainEqual(expect.objectContaining({ connectionId: 'warehouse', name: 'orders' }));
const ingest = await runBuiltCli([
'ingest',

106
packages/cli/src/index.test.ts
View file

@ -139,6 +139,112 @@ describe('runKtxCli', () => {
expect(testIo.stderr()).toBe('');
});
it('routes public wiki read and write commands', async () => {
const knowledge = vi.fn(async () => 0);
const readIo = makeIo();
await expect(runKtxCli(['--project-dir', tempDir, 'wiki', 'read', 'revenue', '--json'], readIo.io, { knowledge }))
.resolves.toBe(0);
expect(knowledge).toHaveBeenCalledWith(
{
command: 'read',
projectDir: tempDir,
key: 'revenue',
userId: 'local',
json: true,
},
readIo.io,
);
const writeIo = makeIo();
await expect(
runKtxCli(
[
'--project-dir',
tempDir,
'wiki',
'write',
'revenue',
'--scope',
'user',
'--summary',
'Revenue',
'--content',
'Revenue.',
'--tag',
'finance',
'--ref',
'https://example.com/revenue',
'--sl-ref',
'orders',
],
writeIo.io,
{ knowledge },
),
).resolves.toBe(0);
expect(knowledge).toHaveBeenLastCalledWith(
{
command: 'write',
projectDir: tempDir,
key: 'revenue',
scope: 'USER',
userId: 'local',
summary: 'Revenue',
content: 'Revenue.',
tags: ['finance'],
refs: ['https://example.com/revenue'],
slRefs: ['orders'],
},
writeIo.io,
);
});
it('rejects removed public sl read/write commands', async () => {
const sl = vi.fn(async () => 0);
for (const argv of [
['--project-dir', tempDir, 'sl', 'read', 'orders', '--connection-id', 'warehouse'],
['--project-dir', tempDir, 'sl', 'write', 'orders', '--connection-id', 'warehouse', '--yaml', 'name: orders'],
]) {
const io = makeIo();
await expect(runKtxCli(argv, io.io, { sl })).resolves.toBe(1);
expect(io.stderr()).toMatch(/unknown command|error:/);
}
expect(sl).not.toHaveBeenCalled();
});
it('routes sl search and rejects the old sl list --query flag', async () => {
const sl = vi.fn(async () => 0);
const searchIo = makeIo();
await expect(
runKtxCli(
['--project-dir', tempDir, 'sl', 'search', 'revenue', '--connection-id', 'warehouse', '--limit', '5', '--json'],
searchIo.io,
{ sl },
),
).resolves.toBe(0);
expect(sl).toHaveBeenCalledWith(
{
command: 'search',
projectDir: tempDir,
connectionId: 'warehouse',
query: 'revenue',
limit: 5,
json: true,
output: undefined,
},
searchIo.io,
);
const listIo = makeIo();
await expect(
runKtxCli(['--project-dir', tempDir, 'sl', 'list', '--query', 'revenue'], listIo.io, { sl }),
).resolves.toBe(1);
expect(listIo.stderr()).toContain("unknown option '--query'");
});
it('routes runtime management commands with the CLI package version', async () => {
const runtime = vi.fn(async () => 0);
const installIo = makeIo();

4
packages/cli/src/setup-agents.ts
View file

@ -138,8 +138,7 @@ function cliInstructionContent(input: { projectDir: string; launcher: KtxCliLaun
'',
`- \`${ktxCommandLine(input.launcher, ['status', ...projectDirArgs])}\``,
`- \`${ktxCommandLine(input.launcher, ['sl', 'list', ...projectDirArgs])}\``,
`- \`${ktxCommandLine(input.launcher, ['sl', 'list', ...projectDirArgs, '--query', '<text>'])}\``,
`- \`${ktxCommandLine(input.launcher, ['sl', 'read', '<sourceName>', ...projectDirArgs, '--connection-id', '<id>'])}\``,
`- \`${ktxCommandLine(input.launcher, ['sl', 'search', '<text>', ...projectDirArgs, '--connection-id', '<id>'])}\``,
`- \`${ktxCommandLine(input.launcher, [
'sl',
'query',
@ -153,7 +152,6 @@ function cliInstructionContent(input: { projectDir: string; launcher: KtxCliLaun
'100',
])}\``,
`- \`${ktxCommandLine(input.launcher, ['wiki', 'search', '<query>', ...projectDirArgs, '--limit', '10'])}\``,
`- \`${ktxCommandLine(input.launcher, ['wiki', 'read', '<pageId>', ...projectDirArgs])}\``,
'',
'Use semantic-layer queries before direct database access. Do not print secrets or credential references.',
'',

130
packages/cli/src/sl.test.ts
View file

@ -38,6 +38,22 @@ function makeIo() {
};
}
async function seedSlSource(input: {
projectDir: string;
connectionId?: string;
sourceName?: string;
yaml?: string;
}): Promise<void> {
const project = await initKtxProject({ projectDir: input.projectDir, projectName: 'warehouse' });
await project.fileStore.writeFile(
`semantic-layer/${input.connectionId ?? 'warehouse'}/${input.sourceName ?? 'orders'}.yaml`,
input.yaml ?? ORDERS_YAML,
'ktx',
'ktx@example.com',
'Add semantic-layer source',
);
}
describe('runKtxSl', () => {
let tempDir: string;
@ -49,24 +65,9 @@ describe('runKtxSl', () => {
await rm(tempDir, { recursive: true, force: true });
});
it('writes, validates, reads, and lists semantic-layer sources', async () => {
it('validates, lists, and searches semantic-layer sources', async () => {
const projectDir = join(tempDir, 'project');
await initKtxProject({ projectDir, projectName: 'warehouse' });
const writeIo = makeIo();
await expect(
runKtxSl(
{
command: 'write',
projectDir,
connectionId: 'warehouse',
sourceName: 'orders',
yaml: ORDERS_YAML,
},
writeIo.io,
),
).resolves.toBe(0);
expect(writeIo.stdout()).toContain('Wrote semantic-layer/warehouse/orders.yaml');
await seedSlSource({ projectDir });
const validateIo = makeIo();
await expect(
@ -74,62 +75,49 @@ describe('runKtxSl', () => {
).resolves.toBe(0);
expect(validateIo.stdout()).toContain('Valid semantic-layer source: warehouse/orders');
const readIo = makeIo();
await expect(runKtxSl({ command: 'read', projectDir, connectionId: 'warehouse', sourceName: 'orders' }, readIo.io))
.resolves.toBe(0);
expect(readIo.stdout()).toContain('name: orders');
const listIo = makeIo();
await expect(runKtxSl({ command: 'list', projectDir, connectionId: 'warehouse' }, listIo.io)).resolves.toBe(0);
expect(listIo.stdout()).toContain('warehouse\torders\tcolumns=1\tmeasures=0\tjoins=0');
const searchIo = makeIo();
await expect(
runKtxSl({ command: 'search', projectDir, connectionId: 'warehouse', query: 'order', json: true }, searchIo.io),
).resolves.toBe(0);
expect(JSON.parse(searchIo.stdout())).toMatchObject({
kind: 'list',
data: {
items: [
expect.objectContaining({
connectionId: 'warehouse',
name: 'orders',
score: expect.any(Number),
}),
],
},
meta: { command: 'sl search' },
});
});
it('prints semantic-layer reads and searched lists as public JSON envelopes', async () => {
it('prints semantic-layer list and search as public JSON envelopes', async () => {
const projectDir = join(tempDir, 'project');
await initKtxProject({ projectDir, projectName: 'warehouse' });
await expect(
runKtxSl(
{
command: 'write',
projectDir,
connectionId: 'warehouse',
sourceName: 'orders',
yaml: [
'name: orders',
'table: public.orders',
'description: Paid order facts',
'grain: [order_id]',
'columns:',
' - name: order_id',
' type: string',
'',
].join('\n'),
},
makeIo().io,
),
).resolves.toBe(0);
const readIo = makeIo();
await expect(
runKtxSl(
{ command: 'read', projectDir, connectionId: 'warehouse', sourceName: 'orders', json: true },
readIo.io,
),
).resolves.toBe(0);
expect(JSON.parse(readIo.stdout())).toMatchObject({
kind: 'sl.source',
data: {
connectionId: 'warehouse',
name: 'orders',
yaml: expect.stringContaining('name: orders'),
},
await seedSlSource({
projectDir,
yaml: [
'name: orders',
'table: public.orders',
'description: Paid order facts',
'grain: [order_id]',
'columns:',
' - name: order_id',
' type: string',
'',
].join('\n'),
});
const listIo = makeIo();
await expect(
runKtxSl(
{ command: 'list', projectDir, connectionId: 'warehouse', query: 'paid', json: true },
{ command: 'search', projectDir, connectionId: 'warehouse', query: 'paid', json: true },
listIo.io,
),
).resolves.toBe(0);
@ -145,7 +133,7 @@ describe('runKtxSl', () => {
}),
],
},
meta: { command: 'sl list' },
meta: { command: 'sl search' },
});
});
@ -566,13 +554,7 @@ joins: []
it('emits sl list as a JSON envelope when output=json', async () => {
const projectDir = join(tempDir, 'project');
await initKtxProject({ projectDir, projectName: 'warehouse' });
const writeIo = makeIo();
await runKtxSl(
{ command: 'write', projectDir, connectionId: 'warehouse', sourceName: 'orders', yaml: ORDERS_YAML },
writeIo.io,
);
await seedSlSource({ projectDir });
const listIo = makeIo();
const code = await runKtxSl(
@ -604,13 +586,7 @@ joins: []
it('emits sl list with grouping and Clack-style framing when output=pretty', async () => {
const projectDir = join(tempDir, 'project');
await initKtxProject({ projectDir, projectName: 'warehouse' });
const writeIo = makeIo();
await runKtxSl(
{ command: 'write', projectDir, connectionId: 'warehouse', sourceName: 'orders', yaml: ORDERS_YAML },
writeIo.io,
);
await seedSlSource({ projectDir });
const listIo = makeIo();
const code = await runKtxSl(

109
packages/cli/src/sl.ts
View file

@ -13,10 +13,10 @@ import {
readLocalSlSource,
searchLocalSlSources,
validateLocalSlSource,
writeLocalSlSource,
type LocalSlSourceSearchResult,
type LocalSlSourceSummary,
type SemanticLayerQueryInput,
} from '@ktx/context/sl';
import { writeJsonResult } from './io/print-list.js';
import {
createManagedPythonSemanticLayerComputePort,
type KtxManagedPythonInstallPolicy,
@ -28,10 +28,17 @@ profileMark('module:sl');
type SlQueryFormat = 'json' | 'sql';
export type KtxSlArgs =
| { command: 'list'; projectDir: string; connectionId?: string; query?: string; output?: string; json?: boolean }
| { command: 'read'; projectDir: string; connectionId: string; sourceName: string; json?: boolean }
| { command: 'list'; projectDir: string; connectionId?: string; output?: string; json?: boolean }
| {
command: 'search';
projectDir: string;
connectionId?: string;
query: string;
limit?: number;
output?: string;
json?: boolean;
}
| { command: 'validate'; projectDir: string; connectionId: string; sourceName: string }
| { command: 'write'; projectDir: string; connectionId: string; sourceName: string; yaml: string }
| {
command: 'query';
projectDir: string;
@ -73,6 +80,35 @@ function slSearchEmbeddingService(project: KtxLocalProject, deps: KtxSlDeps): Kt
return provider ? new KtxIngestEmbeddingPortAdapter(provider) : null;
}
async function printSlSources(input: {
rows: ReadonlyArray<LocalSlSourceSummary | LocalSlSourceSearchResult>;
command: 'sl list' | 'sl search';
output?: string;
json?: boolean;
io: KtxSlIo;
emptyMessage: string;
}): Promise<void> {
const { resolveOutputMode } = await import('./io/mode.js');
const { printList } = await import('./io/print-list.js');
const mode = resolveOutputMode({ explicit: input.output, json: input.json, io: input.io });
printList({
rows: input.rows,
columns: [
{ key: 'connectionId', label: 'CONNECTION', plain: '' },
{ key: 'name', label: 'NAME', plain: '' },
{ key: 'columnCount', label: 'COLS', plain: 'columns=', dim: true },
{ key: 'measureCount', label: 'MEASURES', plain: 'measures=', dim: true },
{ key: 'joinCount', label: 'JOINS', plain: 'joins=', dim: true },
{ key: 'description', label: 'DESCRIPTION', plain: false, optional: true, dim: true },
],
groupBy: 'connectionId',
emptyMessage: input.emptyMessage,
command: input.command,
mode,
io: input.io,
});
}
async function readSlQueryFile(path: string): Promise<SemanticLayerQueryInput> {
const parsed = JSON.parse(await readFile(path, 'utf-8')) as unknown;
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
@ -85,51 +121,32 @@ export async function runKtxSl(args: KtxSlArgs, io: KtxSlIo = process, deps: Ktx
try {
const project = await (deps.loadProject ?? loadKtxProject)({ projectDir: args.projectDir });
if (args.command === 'list') {
const sources = args.query
? await searchLocalSlSources(project, {
connectionId: args.connectionId,
query: args.query,
embeddingService: slSearchEmbeddingService(project, deps),
})
: await listLocalSlSources(project, { connectionId: args.connectionId });
const { resolveOutputMode } = await import('./io/mode.js');
const { printList } = await import('./io/print-list.js');
const mode = resolveOutputMode({ explicit: args.output, json: args.json, io });
printList({
const sources = await listLocalSlSources(project, { connectionId: args.connectionId });
await printSlSources({
rows: sources,
columns: [
{ key: 'connectionId', label: 'CONNECTION', plain: '' },
{ key: 'name', label: 'NAME', plain: '' },
{ key: 'columnCount', label: 'COLS', plain: 'columns=', dim: true },
{ key: 'measureCount', label: 'MEASURES', plain: 'measures=', dim: true },
{ key: 'joinCount', label: 'JOINS', plain: 'joins=', dim: true },
{ key: 'description', label: 'DESCRIPTION', plain: false, optional: true, dim: true },
],
groupBy: 'connectionId',
emptyMessage: `No semantic-layer sources found in ${project.projectDir}`,
command: 'sl list',
mode,
output: args.output,
json: args.json,
io,
});
return 0;
}
if (args.command === 'read') {
const source = await readLocalSlSource(project, {
if (args.command === 'search') {
const sources = await searchLocalSlSources(project, {
connectionId: args.connectionId,
sourceName: args.sourceName,
query: args.query,
embeddingService: slSearchEmbeddingService(project, deps),
limit: args.limit,
});
await printSlSources({
rows: sources,
emptyMessage: `No semantic-layer sources matched "${args.query}" in ${project.projectDir}`,
command: 'sl search',
output: args.output,
json: args.json,
io,
});
if (!source) {
throw new Error(`Semantic-layer source "${args.connectionId}/${args.sourceName}" was not found`);
}
if (args.json) {
writeJsonResult(io, {
kind: 'sl.source',
data: source,
meta: { command: 'sl read' },
});
return 0;
}
io.stdout.write(source.yaml);
return 0;
}
if (args.command === 'validate') {
@ -178,14 +195,8 @@ export async function runKtxSl(args: KtxSlArgs, io: KtxSlIo = process, deps: Ktx
io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
return 0;
}
const write = await writeLocalSlSource(project, {
connectionId: args.connectionId,
sourceName: args.sourceName,
yaml: args.yaml,
});
io.stdout.write(`Wrote ${write.path}\n`);
return 0;
const _exhaustive: never = args;
throw new Error(`Unsupported sl command: ${JSON.stringify(_exhaustive)}`);
} catch (error) {
io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
return 1;