@kaelio/ktx 0.1.0 → 0.2.0

package/assets/python/manifest.json

@@ -2,10 +2,10 @@
   "schemaVersion": 1,
   "distributionName": "kaelio-ktx",
   "normalizedName": "kaelio_ktx",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "wheel": {
-    "file": "kaelio_ktx-0.1.0-py3-none-any.whl",
-    "sha256": "1145cf0c90879270dc335a8d0ca49a598f81e0f47a37fdf646fc6c6798fe3c8b",
-    "bytes": 80523
+    "file": "kaelio_ktx-0.2.0-py3-none-any.whl",
+    "sha256": "5ede628d4d72b2a7eb515fb538473be5a5d82eb430ae98daca8ac90596a7a6e3",
+    "bytes": 80524
   }
 }

package/dist/admin-reindex.d.ts

@@ -0,0 +1,15 @@
+import { type ReindexSummary } from '@ktx/context/index-sync';
+import { type Command } from '@commander-js/extra-typings';
+import type { KtxCliCommandContext } from './cli-program.js';
+import type { KtxCliIo } from './cli-runtime.js';
+export interface KtxAdminReindexArgs {
+    projectDir: string;
+    force: boolean;
+    output?: 'pretty' | 'plain' | 'json';
+    json?: boolean;
+    cliVersion: string;
+}
+export declare function registerAdminReindexCommand(admin: Command, context: KtxCliCommandContext): void;
+export declare function reindexHasErrors(summary: ReindexSummary): boolean;
+export declare function renderReindexPlain(summary: ReindexSummary, io: KtxCliIo): void;
+export declare function renderReindexJson(summary: ReindexSummary, io: KtxCliIo): void;

package/dist/admin-reindex.js

@@ -0,0 +1,168 @@
+import { createLocalKtxEmbeddingProviderFromConfig, KtxIngestEmbeddingPortAdapter, MANAGED_SENTENCE_TRANSFORMERS_BASE_URL, } from '@ktx/context';
+import { reindexLocalIndexes } from '@ktx/context/index-sync';
+import { loadKtxProject } from '@ktx/context/project';
+import { Option } from '@commander-js/extra-typings';
+import { cancel, intro, log, note, outro } from '@clack/prompts';
+import { resolveOutputMode } from './io/mode.js';
+import { green, red, SYMBOLS } from './io/symbols.js';
+import { ensureManagedLocalEmbeddingsDaemon } from './managed-local-embeddings.js';
+export function registerAdminReindexCommand(admin, context) {
+    admin
+        .command('reindex')
+        .description('Sync local wiki and semantic-layer search indexes from disk')
+        .option('--force', 'Clear each discovered scope before rebuilding it', false)
+        .option('--json', 'Shortcut for --output=json (overrides --output)', false)
+        .addOption(new Option('--output <mode>', 'Output mode: pretty, plain, or json').choices(['pretty', 'plain', 'json']))
+        .action(async (options, command) => {
+        const runner = context.deps.adminReindex ?? runKtxAdminReindex;
+        const { resolveCommandProjectDir } = await import('./cli-program.js');
+        context.setExitCode(await runner({
+            projectDir: resolveCommandProjectDir(command),
+            force: options.force === true,
+            json: options.json === true,
+            output: options.output,
+            cliVersion: context.packageInfo.version,
+        }, context.io));
+    });
+}
+async function resolveReindexEmbeddingService(project, args, io) {
+    const config = project.config.ingest.embeddings;
+    if (config.backend === 'none') {
+        return null;
+    }
+    if (config.backend === 'sentence-transformers' &&
+        config.sentenceTransformers?.base_url === MANAGED_SENTENCE_TRANSFORMERS_BASE_URL) {
+        const daemon = await ensureManagedLocalEmbeddingsDaemon({
+            cliVersion: args.cliVersion,
+            projectDir: project.projectDir,
+            installPolicy: 'never',
+            io,
+        });
+        const provider = createLocalKtxEmbeddingProviderFromConfig(config, { env: { ...process.env, ...daemon.env } });
+        return provider ? new KtxIngestEmbeddingPortAdapter(provider) : null;
+    }
+    const provider = createLocalKtxEmbeddingProviderFromConfig(config);
+    return provider ? new KtxIngestEmbeddingPortAdapter(provider) : null;
+}
+function scopeKey(scope) {
+    if (scope.kind === 'wiki') {
+        return scope.scope === 'user' ? `wiki/user/${scope.scopeId ?? 'local'}` : 'wiki/global';
+    }
+    return `sl/${scope.connectionId ?? scope.label}`;
+}
+function quotePlainValue(value) {
+    return `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+}
+export function reindexHasErrors(summary) {
+    return summary.scopes.some((scope) => scope.error);
+}
+export function renderReindexPlain(summary, io) {
+    const updateKey = summary.force ? 'rebuilt' : 'updated';
+    for (const scope of summary.scopes) {
+        const cells = [
+            scopeKey(scope),
+            `scanned=${scope.scanned}`,
+            `${updateKey}=${scope.updated}`,
+            `deleted=${scope.deleted}`,
+            `embeddings=${summary.embeddingsAvailable ? String(scope.embeddingsRecomputed) : '-'}`,
+            `duration_ms=${scope.durationMs}`,
+            ...(scope.error ? [`error=${quotePlainValue(scope.error)}`] : []),
+        ];
+        io.stderr.write(`${cells.join('\t')}\n`);
+    }
+    const failed = summary.scopes.filter((scope) => scope.error).length;
+    io.stdout.write([
+        'reindex',
+        `scopes=${summary.scopes.length}`,
+        `scanned=${summary.totals.scanned}`,
+        `${updateKey}=${summary.totals.updated}`,
+        `deleted=${summary.totals.deleted}`,
+        `embeddings=${summary.embeddingsAvailable ? String(summary.totals.embeddingsRecomputed) : '-'}`,
+        `duration_ms=${summary.durationMs}`,
+        ...(failed > 0 ? [`failed=${failed}`] : []),
+    ].join('\t') + '\n');
+}
+export function renderReindexJson(summary, io) {
+    io.stdout.write(`${JSON.stringify({ kind: 'reindex', data: summary, meta: { command: 'admin reindex' } }, null, 2)}\n`);
+}
+function noun(scope) {
+    return scope.kind === 'wiki' ? 'pages' : 'sources';
+}
+function formatScopeLine(scope, force, embeddingsAvailable) {
+    if (scope.error) {
+        return `${scope.kind === 'wiki' ? 'Wiki' : 'SL'}: ${scope.label} ${SYMBOLS.emDash} failed: ${scope.error}`;
+    }
+    const changedLabel = force ? 'rebuilt' : 'updated';
+    const parts = [`${scope.scanned} ${noun(scope)}`];
+    if (scope.updated > 0) {
+        parts.push(`${scope.updated} ${changedLabel}`);
+    }
+    else {
+        parts.push('unchanged');
+    }
+    if (!force && scope.deleted > 0) {
+        parts.push(`${scope.deleted} deleted`);
+    }
+    if (embeddingsAvailable) {
+        parts.push(`${scope.embeddingsRecomputed} embeddings recomputed`);
+    }
+    parts.push(`${scope.durationMs}ms`);
+    return `${scope.kind === 'wiki' ? 'Wiki' : 'SL'}: ${scope.label} ${SYMBOLS.emDash} ${parts.join(` ${SYMBOLS.middot} `)}`;
+}
+function renderReindexPretty(summary, io) {
+    intro(summary.force ? 'ktx admin reindex --force' : 'ktx admin reindex');
+    if (!summary.embeddingsAvailable) {
+        log.warn(`Embeddings: not configured ${SYMBOLS.emDash} indexing lexical only`);
+    }
+    for (const scope of summary.scopes) {
+        const line = formatScopeLine(scope, summary.force, summary.embeddingsAvailable);
+        if (scope.error) {
+            log.error(red(line));
+        }
+        else {
+            log.success(green(line));
+        }
+    }
+    const failed = summary.scopes.filter((scope) => scope.error).length;
+    note([
+        `scopes        ${summary.scopes.length}`,
+        `scanned       ${summary.totals.scanned}`,
+        `${summary.force ? 'rebuilt' : 'updated'}       ${summary.totals.updated}`,
+        `deleted       ${summary.totals.deleted}`,
+        `embeddings    ${summary.embeddingsAvailable ? summary.totals.embeddingsRecomputed : SYMBOLS.emDash}`,
+        `index         ${summary.dbPath}`,
+        ...(failed > 0 ? [`failed        ${failed}`] : []),
+    ].join('\n'), 'Summary');
+    if (failed > 0) {
+        cancel(`reindex completed with ${failed} error${failed === 1 ? '' : 's'}`);
+    }
+    else {
+        outro(`Done in ${(summary.durationMs / 1000).toFixed(1)}s`);
+    }
+    void io;
+}
+async function runKtxAdminReindex(args, io = process) {
+    try {
+        const project = await loadKtxProject({ projectDir: args.projectDir });
+        const embeddingService = await resolveReindexEmbeddingService(project, args, io);
+        const summary = await reindexLocalIndexes(project, { force: args.force, embeddingService });
+        const mode = resolveOutputMode({ explicit: args.output, json: args.json, io });
+        if (!summary.embeddingsAvailable && mode === 'plain') {
+            io.stderr.write(`Embeddings: not configured ${SYMBOLS.emDash} indexing lexical only\n`);
+        }
+        if (mode === 'json') {
+            renderReindexJson(summary, io);
+        }
+        else if (mode === 'plain') {
+            renderReindexPlain(summary, io);
+        }
+        else {
+            renderReindexPretty(summary, io);
+        }
+        return reindexHasErrors(summary) ? 1 : 0;
+    }
+    catch (error) {
+        io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}

package/dist/admin-reindex.test.js

@@ -0,0 +1,116 @@
+import { describe, expect, it, vi } from 'vitest';
+import { renderReindexJson, renderReindexPlain, reindexHasErrors } from './admin-reindex.js';
+import { runKtxCli } from './index.js';
+function makeIo(options = {}) {
+    let stdout = '';
+    let stderr = '';
+    return {
+        io: {
+            stdout: {
+                isTTY: options.stdoutIsTTY,
+                write: (chunk) => {
+                    stdout += chunk;
+                },
+            },
+            stderr: {
+                write: (chunk) => {
+                    stderr += chunk;
+                },
+            },
+        },
+        stdout: () => stdout,
+        stderr: () => stderr,
+    };
+}
+function summary(overrides = {}) {
+    return {
+        scopes: [
+            {
+                kind: 'wiki',
+                label: 'global',
+                scope: 'global',
+                scopeId: null,
+                scanned: 42,
+                updated: 3,
+                deleted: 1,
+                embeddingsRecomputed: 3,
+                embeddingsFailed: 0,
+                durationMs: 412,
+            },
+            {
+                kind: 'sl',
+                label: 'warehouse',
+                connectionId: 'warehouse',
+                scanned: 18,
+                updated: 2,
+                deleted: 0,
+                embeddingsRecomputed: 2,
+                embeddingsFailed: 0,
+                durationMs: 287,
+            },
+        ],
+        totals: { scanned: 60, updated: 5, deleted: 1, embeddingsRecomputed: 5, embeddingsFailed: 0 },
+        dbPath: '.ktx/db.sqlite',
+        force: false,
+        embeddingsAvailable: true,
+        durationMs: 1234,
+        ...overrides,
+    };
+}
+describe('admin reindex renderers', () => {
+    it('renders plain scope lines to stderr and summary to stdout', () => {
+        const io = makeIo();
+        renderReindexPlain(summary(), io.io);
+        expect(io.stderr()).toContain('wiki/global\tscanned=42\tupdated=3\tdeleted=1\tembeddings=3\tduration_ms=412\n');
+        expect(io.stderr()).toContain('sl/warehouse\tscanned=18\tupdated=2\tdeleted=0\tembeddings=2\tduration_ms=287\n');
+        expect(io.stdout()).toBe('reindex\tscopes=2\tscanned=60\tupdated=5\tdeleted=1\tembeddings=5\tduration_ms=1234\n');
+    });
+    it('renders rebuilt labels in plain force mode', () => {
+        const io = makeIo();
+        renderReindexPlain(summary({ force: true }), io.io);
+        expect(io.stderr()).toContain('rebuilt=3');
+        expect(io.stdout()).toContain('rebuilt=5');
+        expect(io.stdout()).not.toContain('updated=5');
+    });
+    it('renders json envelope to stdout only', () => {
+        const io = makeIo();
+        renderReindexJson(summary(), io.io);
+        expect(JSON.parse(io.stdout())).toMatchObject({
+            kind: 'reindex',
+            data: { totals: { scanned: 60, updated: 5 } },
+            meta: { command: 'admin reindex' },
+        });
+        expect(io.stderr()).toBe('');
+    });
+    it('detects per-scope errors', () => {
+        expect(reindexHasErrors(summary({
+            scopes: [{ ...summary().scopes[0], error: 'provider failed' }],
+        }))).toBe(true);
+    });
+});
+describe('admin reindex Commander routing', () => {
+    it('routes flags to the injectable reindex runner', async () => {
+        const { mkdir, mkdtemp, rm, writeFile } = await import('node:fs/promises');
+        const { tmpdir } = await import('node:os');
+        const { join } = await import('node:path');
+        const tempDir = await mkdtemp(join(tmpdir(), 'ktx-admin-reindex-cli-'));
+        const projectDir = join(tempDir, 'project');
+        const io = makeIo();
+        const adminReindex = vi.fn(async () => 0);
+        try {
+            await mkdir(projectDir, { recursive: true });
+            await writeFile(join(projectDir, 'ktx.yaml'), '{}\n', 'utf-8');
+            await expect(runKtxCli(['--project-dir', projectDir, 'admin', 'reindex', '--force', '--json', '--output', 'plain'], io.io, { adminReindex })).resolves.toBe(0);
+        }
+        finally {
+            await rm(tempDir, { recursive: true, force: true });
+        }
+        expect(adminReindex).toHaveBeenCalledWith({
+            projectDir,
+            force: true,
+            json: true,
+            output: 'plain',
+            cliVersion: '0.1.0-rc.1',
+        }, io.io);
+    });
+});

package/dist/{dev.d.ts → admin.d.ts}

@@ -1,3 +1,3 @@
 import type { Command } from '@commander-js/extra-typings';
 import { type KtxCliCommandContext } from './cli-program.js';
-export declare function registerDevCommands(program: Command, context: KtxCliCommandContext): void;
+export declare function registerAdminCommands(program: Command, context: KtxCliCommandContext): void;

package/dist/{dev.js → admin.js}

@@ -1,21 +1,22 @@
 import { resolve } from 'node:path';
 import { resolveCommandProjectDir } from './cli-program.js';
+import { registerAdminReindexCommand } from './admin-reindex.js';
 import { registerRuntimeCommands } from './commands/runtime-commands.js';
 import { profileMark } from './startup-profile.js';
-profileMark('module:dev');
-export function registerDevCommands(program, context) {
-    const dev = program
-        .command('dev')
-        .description('Low-level project initialization and runtime management')
+profileMark('module:admin');
+export function registerAdminCommands(program, context) {
+    const admin = program
+        .command('admin')
+        .description('Low-level project initialization, runtime, and index management')
         .showHelpAfterError();
-    dev.hook('preAction', (_thisCommand, actionCommand) => {
-        context.writeDebug?.('dev', actionCommand);
+    admin.hook('preAction', (_thisCommand, actionCommand) => {
+        context.writeDebug?.('admin', actionCommand);
     });
-    dev.action(() => {
-        dev.outputHelp();
+    admin.action(() => {
+        admin.outputHelp();
         context.setExitCode(0);
     });
-    dev
+    admin
         .command('init')
         .description('Initialize a Git-backed KTX project directory for maintenance scripts')
         .argument('[directory]', 'Project directory')
@@ -26,7 +27,7 @@ export function registerDevCommands(program, context) {
             force: commandOptions.force === true,
         }, context.io));
     });
-    dev
+    admin
         .command('schema')
         .description('Print a JSON Schema describing ktx.yaml (for editors and LLM agents)')
         .option('--output <file>', 'Write the schema to a file instead of stdout')
@@ -44,5 +45,6 @@ export function registerDevCommands(program, context) {
         }
         context.setExitCode(0);
     });
-    registerRuntimeCommands(dev, context);
+    registerRuntimeCommands(admin, context);
+    registerAdminReindexCommand(admin, context);
 }

package/dist/admin.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/{dev.test.js → admin.test.js}

@@ -20,12 +20,12 @@ function makeIo() {
         stderr: () => stderr,
     };
 }
-describe('dev Commander tree', () => {
-    it('prints visible dev help with only supported low-level command groups', async () => {
+describe('admin Commander tree', () => {
+    it('prints visible admin help with supported low-level command groups', async () => {
         const testIo = makeIo();
-        await expect(runKtxCli(['dev', '--help'], testIo.io)).resolves.toBe(0);
-        expect(testIo.stdout()).toContain('Usage: ktx dev [options] [command]');
-        for (const command of ['init', 'runtime']) {
+        await expect(runKtxCli(['admin', '--help'], testIo.io)).resolves.toBe(0);
+        expect(testIo.stdout()).toContain('Usage: ktx admin [options] [command]');
+        for (const command of ['init', 'runtime', 'reindex']) {
             expect(testIo.stdout()).toContain(command);
         }
         for (const removed of [
@@ -47,23 +47,28 @@ describe('dev Commander tree', () => {
         }
         expect(testIo.stderr()).toBe('');
     });
-    it('lists dev in root command rows', async () => {
+    it('lists admin in root command rows', async () => {
         const testIo = makeIo();
         await expect(runKtxCli(['--help'], testIo.io)).resolves.toBe(0);
         expect(testIo.stdout()).not.toContain('Advanced:');
-        expect(testIo.stdout()).toContain('dev');
-        expect(testIo.stdout()).toMatch(/Low-level project initialization and runtime\s+management/);
+        expect(testIo.stdout()).toContain('admin');
+        expect(testIo.stdout()).toMatch(/Low-level project initialization,\s+runtime,\s+and index management/);
         expect(testIo.stderr()).toBe('');
     });
-    it('keeps project scaffolding under dev init', async () => {
+    it('does not keep a dev alias', async () => {
+        const testIo = makeIo();
+        await expect(runKtxCli(['dev', '--help'], testIo.io)).resolves.toBe(1);
+        expect(testIo.stderr()).toContain("unknown command 'dev'");
+    });
+    it('keeps project scaffolding under admin init', async () => {
         const { mkdtemp, readFile, rm } = await import('node:fs/promises');
         const { tmpdir } = await import('node:os');
         const { join } = await import('node:path');
-        const tempDir = await mkdtemp(join(tmpdir(), 'ktx-dev-init-'));
+        const tempDir = await mkdtemp(join(tmpdir(), 'ktx-admin-init-'));
         const projectDir = join(tempDir, 'warehouse');
         const testIo = makeIo();
         try {
-            await expect(runKtxCli(['dev', 'init', projectDir], testIo.io)).resolves.toBe(0);
+            await expect(runKtxCli(['admin', 'init', projectDir], testIo.io)).resolves.toBe(0);
             expect(testIo.stdout()).toContain(`Initialized KTX project at ${projectDir}`);
             await expect(readFile(join(projectDir, 'ktx.yaml'), 'utf-8')).resolves.not.toContain('project:');
             expect(testIo.stderr()).toBe('');
@@ -72,15 +77,15 @@ describe('dev Commander tree', () => {
             await rm(tempDir, { recursive: true, force: true });
         }
     });
-    it('uses global project-dir for dev init when the positional directory is omitted', async () => {
+    it('uses global project-dir for admin init when the positional directory is omitted', async () => {
         const { mkdtemp, rm } = await import('node:fs/promises');
         const { tmpdir } = await import('node:os');
         const { join } = await import('node:path');
-        const tempDir = await mkdtemp(join(tmpdir(), 'ktx-dev-init-global-'));
+        const tempDir = await mkdtemp(join(tmpdir(), 'ktx-admin-init-global-'));
         const projectDir = join(tempDir, 'global-init');
         const testIo = makeIo();
         try {
-            await expect(runKtxCli(['--project-dir', projectDir, 'dev', 'init'], testIo.io)).resolves.toBe(0);
+            await expect(runKtxCli(['--project-dir', projectDir, 'admin', 'init'], testIo.io)).resolves.toBe(0);
             expect(testIo.stdout()).toContain(`Initialized KTX project at ${projectDir}`);
             expect(testIo.stderr()).toBe('');
         }
@@ -92,13 +97,13 @@ describe('dev Commander tree', () => {
         const { mkdtemp, rm } = await import('node:fs/promises');
         const { tmpdir } = await import('node:os');
         const { join } = await import('node:path');
-        const tempDir = await mkdtemp(join(tmpdir(), 'ktx-dev-schema-'));
+        const tempDir = await mkdtemp(join(tmpdir(), 'ktx-admin-schema-'));
         const missingProjectDir = join(tempDir, 'missing-project');
         const originalProjectDir = process.env.KTX_PROJECT_DIR;
         const testIo = makeIo();
         try {
             process.env.KTX_PROJECT_DIR = missingProjectDir;
-            await expect(runKtxCli(['dev', 'schema'], testIo.io)).resolves.toBe(0);
+            await expect(runKtxCli(['admin', 'schema'], testIo.io)).resolves.toBe(0);
             expect(JSON.parse(testIo.stdout())).toMatchObject({
                 title: 'ktx.yaml',
                 type: 'object',
@@ -115,19 +120,19 @@ describe('dev Commander tree', () => {
             await rm(tempDir, { recursive: true, force: true });
         }
     });
-    it('rejects removed dev command groups', async () => {
+    it('rejects removed admin command groups', async () => {
         for (const argv of [
-            ['dev', 'doctor', 'setup'],
-            ['dev', 'runtime', 'doctor'],
-            ['dev', 'runtime', 'prune', '--dry-run'],
-            ['dev', 'scan', 'warehouse'],
-            ['dev', 'ingest', 'run'],
-            ['dev', 'mapping', 'list'],
-            ['dev', 'completion', 'zsh'],
-            ['dev', '__complete', '--shell', 'zsh', '--position', '2', '--', 'ktx', ''],
-            ['dev', 'knowledge', 'list'],
-            ['dev', 'model', 'list'],
-            ['dev', 'artifacts'],
+            ['admin', 'doctor', 'setup'],
+            ['admin', 'runtime', 'doctor'],
+            ['admin', 'runtime', 'prune', '--dry-run'],
+            ['admin', 'scan', 'warehouse'],
+            ['admin', 'ingest', 'run'],
+            ['admin', 'mapping', 'list'],
+            ['admin', 'completion', 'zsh'],
+            ['admin', '__complete', '--shell', 'zsh', '--position', '2', '--', 'ktx', ''],
+            ['admin', 'knowledge', 'list'],
+            ['admin', 'model', 'list'],
+            ['admin', 'artifacts'],
         ]) {
             const testIo = makeIo();
             await expect(runKtxCli(argv, testIo.io)).resolves.toBe(1);
@@ -136,8 +141,8 @@ describe('dev Commander tree', () => {
     });
     it.each([
         {
-            argv: ['dev', 'runtime', '--help'],
-            expected: ['Usage: ktx dev runtime', 'install', 'start', 'stop', 'status'],
+            argv: ['admin', 'runtime', '--help'],
+            expected: ['Usage: ktx admin runtime', 'install', 'start', 'stop', 'status'],
         },
     ])('prints generated nested help for $argv', async ({ argv, expected }) => {
         const io = makeIo();
@@ -146,7 +151,7 @@ describe('dev Commander tree', () => {
         for (const text of expected) {
             expect(io.stdout()).toContain(text);
         }
-        if (argv.join(' ') === 'dev runtime --help') {
+        if (argv.join(' ') === 'admin runtime --help') {
             expect(io.stdout()).not.toContain('prune');
             expect(io.stdout()).not.toContain('doctor');
         }

package/dist/cli-program.js

@@ -9,14 +9,14 @@ import { registerSetupCommands } from './commands/setup-commands.js';
 import { registerSlCommands } from './commands/sl-commands.js';
 import { registerSqlCommands } from './commands/sql-commands.js';
 import { registerStatusCommands } from './commands/status-commands.js';
-import { registerDevCommands } from './dev.js';
+import { registerAdminCommands } from './admin.js';
 import { renderMissingProjectMessage } from './doctor.js';
 import { findNearestKtxProjectDir, resolveKtxProjectDir } from './project-resolver.js';
 import { profileMark, profileSpan } from './startup-profile.js';
 profileMark('module:cli-program');
 const PROJECT_AWARE_ROOT_COMMANDS = new Set(['setup', 'connection', 'ingest', 'wiki', 'sl', 'sql', 'status', 'mcp']);
-const PROJECT_INDEPENDENT_DEV_COMMANDS = new Set(['runtime', 'schema']);
-const COMMANDS_THAT_CREATE_PROJECT = new Set(['setup', 'ktx dev init']);
+const PROJECT_INDEPENDENT_ADMIN_COMMANDS = new Set(['runtime', 'schema']);
+const COMMANDS_THAT_CREATE_PROJECT = new Set(['setup', 'ktx admin init']);
 const COMMANDS_WITH_OWN_MISSING_PROJECT_HANDLING = new Set(['status']);
 const GLOBAL_OPTIONS_WITH_VALUE = new Set(['--project-dir']);
 const GLOBAL_OPTIONS_WITHOUT_VALUE = new Set(['--debug', '--help', '-h', '--version', '-v']);
@@ -105,14 +105,14 @@ function isProjectAwareCommand(path) {
         return false;
     }
     const rootCommand = path[1];
-    if (rootCommand === 'dev') {
-        return path[2] !== undefined && !PROJECT_INDEPENDENT_DEV_COMMANDS.has(path[2]);
+    if (rootCommand === 'admin') {
+        return path[2] !== undefined && !PROJECT_INDEPENDENT_ADMIN_COMMANDS.has(path[2]);
     }
     return rootCommand !== undefined && PROJECT_AWARE_ROOT_COMMANDS.has(rootCommand);
 }
 function shouldSuppressProjectDirLine(path, options) {
     const commandPathKey = path.join(' ');
-    if (commandPathKey === 'ktx dev init') {
+    if (commandPathKey === 'ktx admin init') {
         return true;
     }
     if (commandPathKey === 'ktx setup') {
@@ -315,7 +315,7 @@ export function buildKtxProgram(options) {
     registerSqlCommands(program, context);
     registerStatusCommands(program, context);
     registerMcpCommands(program, context);
-    registerDevCommands(program, context);
+    registerAdminCommands(program, context);
     return program;
 }
 export async function runCommanderKtxCli(argv, io, deps, info, options) {

package/dist/cli-program.test.js

@@ -25,7 +25,7 @@ describe('buildKtxProgram', () => {
         });
         expect(program.name()).toBe('ktx');
         const topLevel = program.commands.map((command) => command.name()).sort();
-        for (const expected of ['setup', 'connection', 'ingest', 'sl', 'dev']) {
+        for (const expected of ['setup', 'connection', 'ingest', 'sl', 'admin']) {
             expect(topLevel).toContain(expected);
         }
     });

package/dist/cli-runtime.d.ts

@@ -1,4 +1,5 @@
 import type { KtxConnectionArgs } from './connection.js';
+import type { KtxAdminReindexArgs } from './admin-reindex.js';
 import type { KtxDoctorArgs } from './doctor.js';
 import type { KtxKnowledgeArgs } from './knowledge.js';
 import type { KtxPublicIngestArgs } from './public-ingest.js';
@@ -25,6 +26,7 @@ export interface KtxCliIo {
     };
 }
 export interface KtxCliDeps {
+    adminReindex?: (args: KtxAdminReindexArgs, io: KtxCliIo) => Promise<number>;
     setup?: (args: KtxSetupArgs, io: KtxCliIo) => Promise<number>;
     connection?: (args: KtxConnectionArgs, io: KtxCliIo) => Promise<number>;
     doctor?: (args: KtxDoctorArgs, io: KtxCliIo) => Promise<number>;

package/dist/commands/connection-commands.js

@@ -1,5 +1,6 @@
 import { resolveCommandProjectDir } from '../cli-program.js';
 import { profileMark } from '../startup-profile.js';
+import { resolveConnectionSelection } from './connection-selection.js';
 profileMark('module:commands/connection-commands');
 async function runConnectionArgs(context, args) {
     const runner = context.deps.connection ?? (await import('../connection.js')).runKtxConnection;
@@ -10,7 +11,10 @@ export function registerConnectionCommands(program, context, commandName = 'conn
         .command(commandName)
         .description('List and test configured connections')
         .showHelpAfterError()
-        .addHelpText('after', '\nProject directory defaults to KTX_PROJECT_DIR when set, otherwise the nearest ktx.yaml or current working directory.\n');
+        .addHelpText('after', '\nProject directory defaults to KTX_PROJECT_DIR when set, otherwise the nearest ktx.yaml or current working directory.\n')
+        .action(async (_options, command) => {
+        await runConnectionArgs(context, { command: 'list', projectDir: resolveCommandProjectDir(command) });
+    });
     connection.hook('preAction', (_thisCommand, actionCommand) => {
         context.writeDebug?.(commandName, actionCommand);
     });
@@ -22,25 +26,22 @@ export function registerConnectionCommands(program, context, commandName = 'conn
     });
     connection
         .command('test')
-        .description('Test a configured connection')
-        .argument('[connectionId]', 'KTX connection id (omit when --all is set)')
+        .description('Test one or all configured connections (default: all)')
+        .argument('[connectionId]', 'KTX connection id to test (omit to test all)')
         .option('--all', 'Test every configured connection and print a summary list')
         .action(async (connectionId, options, command) => {
-        const all = options.all === true;
-        if (all && connectionId !== undefined) {
+        if (options.all === true && connectionId !== undefined) {
             command.error('error: --all cannot be combined with a connection id argument');
         }
-        if (!all && connectionId === undefined) {
-            command.error('error: missing required argument <connectionId> (or pass --all)');
-        }
-        if (all) {
+        const selection = resolveConnectionSelection({ connectionId, all: options.all === true });
+        if (selection.kind === 'all') {
             await runConnectionArgs(context, { command: 'test-all', projectDir: resolveCommandProjectDir(command) });
             return;
         }
         await runConnectionArgs(context, {
             command: 'test',
             projectDir: resolveCommandProjectDir(command),
-            connectionId: connectionId,
+            connectionId: selection.connectionId,
         });
     });
 }

package/dist/commands/connection-selection.d.ts

@@ -0,0 +1,11 @@
+export type ConnectionSelection = {
+    kind: 'all';
+} | {
+    kind: 'single';
+    connectionId: string;
+};
+export interface ResolveConnectionSelectionInput {
+    connectionId?: string | undefined;
+    all: boolean;
+}
+export declare function resolveConnectionSelection(input: ResolveConnectionSelectionInput): ConnectionSelection;