kontexted 0.1.0

package/README.md

@@ -0,0 +1,75 @@
+# Kontexted CLI
+
+A command-line tool for Kontexted that provides MCP proxy functionality and workspace management.
+
+## Installation
+
+```bash
+npm install -g kontexted
+```
+
+## Usage
+
+### Authentication
+
+Log in to a Kontexted server:
+
+```bash
+kontexted login --url https://app.example.com --workspace my-workspace --alias prod
+```
+
+With an alias and write permissions:
+
+```bash
+kontexted login --url https://app.example.com --workspace my-workspace --alias prod --write
+```
+
+### MCP Proxy Mode
+
+Start the MCP proxy server (for use with Claude Desktop or other MCP clients):
+
+```bash
+# Using alias
+kontexted --alias prod
+
+# Using workspace name
+kontexted --workspace my-workspace
+
+# Enable write mode for this session
+kontexted --alias prod --write
+
+# Disable write mode for this session
+kontexted --alias prod --write-off
+```
+
+### Manage Profiles
+
+Show stored profiles:
+
+```bash
+kontexted show-config
+```
+
+Remove a profile:
+
+```bash
+kontexted logout --alias prod
+```
+
+Remove all profiles:
+
+```bash
+kontexted logout
+```
+
+## Configuration
+
+Profiles are stored in `~/.kontexted/profile.json` with OAuth tokens.
+
+## Requirements
+
+- Node.js 18 or higher
+
+## License
+
+MIT

package/dist/commands/login.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerLoginCommand(program: Command): void;

package/dist/commands/login.js

@@ -0,0 +1,48 @@
+import { readConfig, writeConfig } from "../lib/config.js";
+import { addProfile } from "../lib/profile.js";
+import { resolveServerUrl } from "../lib/server-url.js";
+import { createOAuthProvider, waitForOAuthCallback } from "../lib/oauth.js";
+import { logDebug } from "../lib/logger.js";
+export function registerLoginCommand(program) {
+    program
+        .command("login")
+        .description("Authenticate and store a new profile")
+        .requiredOption("--url <url>", "Kontexted server URL (e.g. https://app.example.com or app.example.com)")
+        .requiredOption("--alias <name>", "Profile alias")
+        .requiredOption("--workspace <slug>", "Workspace slug")
+        .option("--write", "Enable write operations for this profile by default", false)
+        .action(async (options) => {
+        const baseUrl = resolveServerUrl(options.url);
+        logDebug(`[LOGIN] Starting login flow - URL: ${baseUrl}, Alias: ${options.alias}, Workspace: ${options.workspace}`);
+        const config = await readConfig();
+        const oauth = {};
+        const persist = async () => {
+            await writeConfig(config);
+        };
+        // Create OAuth provider
+        const provider = createOAuthProvider(oauth, persist, baseUrl);
+        // 1. Register OAuth client
+        logDebug(`[LOGIN] Registering OAuth client...`);
+        await provider.registerClient();
+        // 2. Get authorization URL and open browser
+        const authUrl = await provider.getAuthorizationUrl();
+        logDebug(`[LOGIN] Opening browser for authorization...`);
+        provider.redirectToAuthorization(authUrl);
+        // 3. Wait for callback with auth code
+        logDebug(`[LOGIN] Waiting for authorization callback...`);
+        const authCode = await waitForOAuthCallback();
+        // 4. Exchange code for tokens
+        logDebug(`[LOGIN] Exchanging authorization code for tokens...`);
+        await provider.exchangeCodeForToken(authCode);
+        // Store the profile
+        const profile = {
+            serverUrl: baseUrl,
+            workspace: options.workspace,
+            write: options.write ?? false,
+            oauth,
+        };
+        addProfile(config, options.alias, profile);
+        await writeConfig(config);
+        console.log(`✓ Login successful. Profile stored as: ${options.alias}`);
+    });
+}

package/dist/commands/logout.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from "commander";
+/**
+ * Register the logout command
+ */
+export declare function registerLogoutCommand(program: Command): void;

package/dist/commands/logout.js

@@ -0,0 +1,33 @@
+import { readConfig, writeConfig, removeConfig } from "../lib/config.js";
+import { profileExists, removeProfile } from "../lib/profile.js";
+/**
+ * Register the logout command
+ */
+export function registerLogoutCommand(program) {
+    program
+        .command("logout")
+        .description("Remove stored profiles")
+        .option("--alias <name>", "Remove specific profile by alias")
+        .action(async (options) => {
+        const config = await readConfig();
+        // No alias specified: remove all profiles
+        if (!options.alias) {
+            await removeConfig();
+            console.log("✓ Removed all profiles.");
+            return;
+        }
+        const profileKey = options.alias;
+        if (!profileExists(config, profileKey)) {
+            throw new Error(`Profile not found: ${profileKey}`);
+        }
+        removeProfile(config, profileKey);
+        if (Object.keys(config.profiles).length === 0) {
+            await removeConfig();
+            console.log("✓ Removed last profile. Config file removed.");
+        }
+        else {
+            await writeConfig(config);
+            console.log(`✓ Removed profile: ${profileKey}`);
+        }
+    });
+}

package/dist/commands/mcp.d.ts

@@ -0,0 +1,15 @@
+import type { Command } from "commander";
+interface McpOptions {
+    alias?: string;
+    write?: boolean;
+    writeOff?: boolean;
+}
+/**
+ * Start the MCP proxy server
+ */
+declare function startMcpProxy(options: McpOptions): Promise<void>;
+/**
+ * Register the MCP proxy command
+ */
+export declare function registerMcpCommand(program: Command): void;
+export { startMcpProxy };

package/dist/commands/mcp.js

@@ -0,0 +1,65 @@
+import { readConfig, writeConfig } from "../lib/config.js";
+import { getProfile } from "../lib/profile.js";
+import { connectRemoteClient, UnauthorizedError } from "../lib/mcp-client.js";
+import { startProxyServer } from "../lib/proxy-server.js";
+/**
+ * Start the MCP proxy server
+ */
+async function startMcpProxy(options) {
+    const config = await readConfig();
+    const profileKey = options.alias;
+    if (!profileKey) {
+        throw new Error("Missing --alias. Required for MCP proxy mode.\n" +
+            "Run 'kontexted mcp --help' for usage information.");
+    }
+    if (options.write && options.writeOff) {
+        throw new Error("Cannot specify both --write and --write-off");
+    }
+    const profile = getProfile(config, profileKey);
+    if (!profile) {
+        throw new Error(`Profile not found: ${profileKey}. Run 'kontexted login' first.`);
+    }
+    // Determine write mode
+    let writeEnabled = profile.write ?? false;
+    if (options.write) {
+        writeEnabled = true;
+    }
+    else if (options.writeOff) {
+        writeEnabled = false;
+    }
+    const persist = async () => {
+        await writeConfig(config);
+    };
+    try {
+        const { client } = await connectRemoteClient(profile.serverUrl, profile.oauth, persist, { allowInteractive: false });
+        const toolList = await client.listTools();
+        await startProxyServer({
+            client,
+            workspaceSlug: profile.workspace,
+            tools: toolList.tools,
+            writeEnabled,
+        });
+    }
+    catch (error) {
+        if (error instanceof UnauthorizedError) {
+            console.error("Error: Unauthorized. Run 'kontexted login' first.");
+            process.exit(1);
+        }
+        throw error;
+    }
+}
+/**
+ * Register the MCP proxy command
+ */
+export function registerMcpCommand(program) {
+    program
+        .command("mcp")
+        .description("Start MCP proxy server")
+        .requiredOption("--alias <name>", "Profile alias to use")
+        .option("--write", "Override to enable write operations")
+        .option("--write-off", "Override to disable write operations")
+        .action(async (options) => {
+        await startMcpProxy(options);
+    });
+}
+export { startMcpProxy };

package/dist/commands/server/doctor.d.ts

@@ -0,0 +1,4 @@
+export declare const command = "doctor";
+export declare const desc = "Run diagnostic checks";
+export declare const builder: (yargs: any) => any;
+export declare const handler: () => Promise<void>;

package/dist/commands/server/doctor.js

@@ -0,0 +1,33 @@
+import { existsSync } from 'fs';
+import { isPlatformSupported, getPlatform, getBinaryPath, configExists, loadConfig, getServerStatus, } from '../../lib/server/index.js';
+import { CONFIG_FILE, DATA_DIR } from '../../lib/server/constants.js';
+const DOCKER_URL = 'https://hub.docker.com/r/kontexted/kontexted';
+// ============ Yargs Command Module ============
+export const command = 'doctor';
+export const desc = 'Run diagnostic checks';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const builder = (yargs) => yargs;
+export const handler = async () => {
+    console.log('--- Server Diagnostics ---\n');
+    const platform = getPlatform();
+    const platformOk = isPlatformSupported();
+    console.log(`${platformOk ? '✓' : '✗'} Platform: ${platform} ${platformOk ? '(supported)' : '(not supported)'}`);
+    if (!platformOk)
+        console.log(`  → Consider using Docker: ${DOCKER_URL}`);
+    const binaryPath = getBinaryPath();
+    console.log(`${binaryPath ? '✓' : '✗'} Binary: ${binaryPath || 'not found'}`);
+    if (!binaryPath)
+        console.log('  → Reinstall @kontexted/cli');
+    const configOk = configExists();
+    console.log(`${configOk ? '✓' : '✗'} Config: ${configOk ? CONFIG_FILE : 'not found'}`);
+    if (!configOk)
+        console.log('  → Run: kontexted server init');
+    if (configOk) {
+        const config = loadConfig();
+        const dbPath = config?.database?.url || `${DATA_DIR}/kontexted.db`;
+        const dbOk = existsSync(dbPath);
+        console.log(`${dbOk ? '✓' : '⚠'} Database: ${dbPath}`);
+    }
+    const serverStatus = getServerStatus();
+    console.log(`Server: ${serverStatus.running ? `Running (PID: ${serverStatus.pid})` : 'Not running'}`);
+};

package/dist/commands/server/index.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from 'commander';
+export declare const command = "server";
+export declare const desc = "Manage Kontexted server";
+export declare const builder: (yargs: any) => any;
+export declare const handler: () => void;
+export declare function registerServerCommand(program: Command): void;

package/dist/commands/server/index.js

@@ -0,0 +1,100 @@
+import yargs from 'yargs';
+import * as initCmd from './init.js';
+import * as startCmd from './start.js';
+import * as stopCmd from './stop.js';
+import * as statusCmd from './status.js';
+import * as logsCmd from './logs.js';
+import * as doctorCmd from './doctor.js';
+// Yargs-style exports (as requested by user)
+export const command = 'server';
+export const desc = 'Manage Kontexted server';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const builder = (yargs) => {
+    return yargs
+        .command(initCmd)
+        .command(startCmd)
+        .command(stopCmd)
+        .command(statusCmd)
+        .command(logsCmd)
+        .command(doctorCmd)
+        .demandCommand()
+        .help();
+};
+export const handler = () => { };
+// ============ Register with Commander ============
+export function registerServerCommand(program) {
+    const serverCmd = program.command('server').description('Manage Kontexted server');
+    // init
+    serverCmd
+        .command('init')
+        .description(initCmd.desc)
+        .option('-i, --interactive', 'Interactive mode to customize configuration')
+        .action(async (opts) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        await yargs(['init'])
+            .command(initCmd)
+            .option('interactive', { type: 'boolean', default: false })
+            .parse();
+    });
+    // start
+    serverCmd
+        .command('start')
+        .description(startCmd.desc)
+        .option('-f, --foreground', 'Run server in foreground (blocking)')
+        .action(async (opts) => {
+        const args = opts.foreground ? ['start', '--foreground'] : ['start'];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        await yargs(args)
+            .command(startCmd)
+            .parse();
+    });
+    // stop
+    serverCmd
+        .command('stop')
+        .description(stopCmd.desc)
+        .option('--force', 'Force kill the server (SIGKILL)')
+        .action(async (opts) => {
+        const args = opts.force ? ['stop', '--force'] : ['stop'];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        await yargs(args)
+            .command(stopCmd)
+            .parse();
+    });
+    // status
+    serverCmd
+        .command('status')
+        .description(statusCmd.desc)
+        .action(async () => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        await yargs(['status'])
+            .command(statusCmd)
+            .parse();
+    });
+    // logs
+    serverCmd
+        .command('logs')
+        .description(logsCmd.desc)
+        .option('-f, --follow', 'Follow log output in real-time')
+        .option('-n, --lines <number>', 'Number of lines to show', '50')
+        .action(async (opts) => {
+        const args = ['logs'];
+        if (opts.follow)
+            args.push('--follow');
+        if (opts.lines)
+            args.push('--lines', opts.lines.toString());
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        await yargs(args)
+            .command(logsCmd)
+            .parse();
+    });
+    // doctor
+    serverCmd
+        .command('doctor')
+        .description(doctorCmd.desc)
+        .action(async () => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        await yargs(['doctor'])
+            .command(doctorCmd)
+            .parse();
+    });
+}

package/dist/commands/server/init.d.ts

@@ -0,0 +1,6 @@
+export declare const command = "init";
+export declare const desc = "Initialize server configuration";
+export declare const builder: (yargs: any) => any;
+export declare const handler: (argv: {
+    interactive?: boolean;
+}) => Promise<void>;

package/dist/commands/server/init.js

@@ -0,0 +1,81 @@
+import { configExists, getDefaultConfig, saveConfig, } from '../../lib/server/index.js';
+import { CONFIG_FILE, DATA_DIR } from '../../lib/server/constants.js';
+import * as readline from 'readline';
+// ============ Helper Functions ============
+function createPrompt() {
+    return readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+}
+function promptQuestion(rl, question) {
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => resolve(answer));
+    });
+}
+async function runInit(interactive) {
+    if (interactive) {
+        const rl = createPrompt();
+        try {
+            if (configExists()) {
+                const answer = await promptQuestion(rl, 'Config already exists. Overwrite? (y/N): ');
+                if (answer.trim().toLowerCase() !== 'y') {
+                    console.log('Initialization cancelled.');
+                    return;
+                }
+            }
+            console.log('\n--- Server Configuration ---');
+            const dialectAnswer = await promptQuestion(rl, 'Database dialect (sqlite/postgresql) [sqlite]: ');
+            const dialect = (dialectAnswer.trim().toLowerCase() || 'sqlite');
+            if (dialect !== 'sqlite' && dialect !== 'postgresql') {
+                console.log('Invalid dialect. Using sqlite.');
+            }
+            const defaultUrl = dialect === 'sqlite' ? `${DATA_DIR}/kontexted.db` : 'postgresql://localhost:5432/kontexted';
+            const urlAnswer = await promptQuestion(rl, `Database URL [${defaultUrl}]: `);
+            const databaseUrl = urlAnswer.trim() || defaultUrl;
+            const portAnswer = await promptQuestion(rl, 'Server port [3000]: ');
+            const port = parseInt(portAnswer.trim(), 10) || 3000;
+            const hostAnswer = await promptQuestion(rl, 'Server host [127.0.0.1]: ');
+            const host = hostAnswer.trim() || '127.0.0.1';
+            const levelAnswer = await promptQuestion(rl, 'Log level (debug/info/warn/error) [info]: ');
+            const level = (levelAnswer.trim().toLowerCase() || 'info');
+            const config = {
+                database: { dialect, url: databaseUrl },
+                server: { port, host },
+                logging: { level },
+                collab: { tokenSecret: getDefaultConfig().collab.tokenSecret },
+            };
+            saveConfig(config);
+            console.log('\n✓ Configuration saved to:', CONFIG_FILE);
+        }
+        finally {
+            rl.close();
+        }
+    }
+    else {
+        if (configExists()) {
+            console.error('Error: Configuration already exists.');
+            console.log('  Run with --interactive to reinitialize.');
+            process.exit(1);
+        }
+        const config = getDefaultConfig();
+        saveConfig(config);
+        console.log('✓ Configuration created:', CONFIG_FILE);
+        console.log('  Database:', config.database.url);
+        console.log('  Server:', `${config.server.host}:${config.server.port}`);
+    }
+}
+// ============ Yargs Command Module ============
+export const command = 'init';
+export const desc = 'Initialize server configuration';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const builder = (yargs) => {
+    return yargs.option('interactive', {
+        alias: 'i',
+        type: 'boolean',
+        description: 'Interactive mode to customize configuration',
+    });
+};
+export const handler = async (argv) => {
+    await runInit(argv.interactive ?? false);
+};

package/dist/commands/server/logs.d.ts

@@ -0,0 +1,7 @@
+export declare const command = "logs";
+export declare const desc = "View server logs";
+export declare const builder: (yargs: any) => any;
+export declare const handler: (argv: {
+    follow?: boolean;
+    lines?: number;
+}) => Promise<void>;

package/dist/commands/server/logs.js

@@ -0,0 +1,39 @@
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { LOG_FILE } from '../../lib/server/constants.js';
+// ============ Yargs Command Module ============
+export const command = 'logs';
+export const desc = 'View server logs';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const builder = (yargs) => {
+    return yargs
+        .option('follow', {
+        alias: 'f',
+        type: 'boolean',
+        description: 'Follow log output in real-time',
+    })
+        .option('lines', {
+        alias: 'n',
+        type: 'number',
+        description: 'Number of lines to show',
+        default: 50,
+    });
+};
+export const handler = async (argv) => {
+    if (!existsSync(LOG_FILE)) {
+        console.log('No logs available');
+        return;
+    }
+    if (argv.follow) {
+        console.log(`Following ${LOG_FILE}... (Ctrl+C to exit)`);
+        const tail = spawn('tail', ['-f', LOG_FILE]);
+        tail.stdout.on('data', (data) => process.stdout.write(data));
+        tail.stderr.on('data', (data) => process.stderr.write(data));
+        process.on('SIGINT', () => { tail.kill(); process.exit(0); });
+    }
+    else {
+        const lines = argv.lines ?? 50;
+        const tail = spawn('tail', ['-n', lines.toString(), LOG_FILE]);
+        tail.stdout.on('data', (data) => process.stdout.write(data));
+    }
+};

package/dist/commands/server/start.d.ts

@@ -0,0 +1,6 @@
+export declare const command = "start";
+export declare const desc = "Start the Kontexted server";
+export declare const builder: (yargs: any) => any;
+export declare const handler: (argv: {
+    foreground?: boolean;
+}) => Promise<void>;

package/dist/commands/server/start.js

@@ -0,0 +1,44 @@
+import { isPlatformSupported, getPlatform, getBinaryPath, configExists, getServerStatus, startServer, } from '../../lib/server/index.js';
+const DOCKER_URL = 'https://hub.docker.com/r/kontexted/kontexted';
+function checkPrerequisites() {
+    if (!isPlatformSupported()) {
+        return { valid: false, error: `Platform not supported: ${getPlatform()}. Consider using Docker: ${DOCKER_URL}` };
+    }
+    if (!getBinaryPath()) {
+        return { valid: false, error: 'Server binary not found. Run `kontexted server install` first.' };
+    }
+    if (!configExists()) {
+        return { valid: false, error: 'Configuration not found. Run `kontexted server init` first.' };
+    }
+    const status = getServerStatus();
+    if (status.running && status.pid) {
+        return { valid: false, error: `Server is already running (PID: ${status.pid})` };
+    }
+    return { valid: true };
+}
+// ============ Yargs Command Module ============
+export const command = 'start';
+export const desc = 'Start the Kontexted server';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const builder = (yargs) => {
+    return yargs.option('foreground', {
+        alias: 'f',
+        type: 'boolean',
+        description: 'Run server in foreground (blocking)',
+    });
+};
+export const handler = async (argv) => {
+    const check = checkPrerequisites();
+    if (!check.valid) {
+        console.error('Error:', check.error);
+        process.exit(1);
+    }
+    try {
+        const pid = await startServer({ foreground: argv.foreground });
+        console.log(argv.foreground ? `Server running (PID: ${pid})` : `Server started (PID: ${pid})`);
+    }
+    catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : 'Unknown error');
+        process.exit(1);
+    }
+};

package/dist/commands/server/status.d.ts

@@ -0,0 +1,4 @@
+export declare const command = "status";
+export declare const desc = "Show server status";
+export declare const builder: (yargs: any) => any;
+export declare const handler: () => Promise<void>;

package/dist/commands/server/status.js

@@ -0,0 +1,23 @@
+import { getServerStatus, loadConfig } from '../../lib/server/index.js';
+import { CONFIG_FILE, LOG_FILE } from '../../lib/server/constants.js';
+// ============ Yargs Command Module ============
+export const command = 'status';
+export const desc = 'Show server status';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const builder = (yargs) => yargs;
+export const handler = async () => {
+    const status = getServerStatus();
+    if (!status.running) {
+        console.log('Server Status: Not running');
+        return;
+    }
+    const config = loadConfig();
+    console.log('Server Status: Running');
+    console.log(`  PID: ${status.pid}`);
+    if (config) {
+        console.log(`  Port: ${config.server.port}`);
+        console.log(`  Host: ${config.server.host}`);
+    }
+    console.log(`  Config: ${CONFIG_FILE}`);
+    console.log(`  Logs: ${LOG_FILE}`);
+};

package/dist/commands/server/stop.d.ts

@@ -0,0 +1,6 @@
+export declare const command = "stop";
+export declare const desc = "Stop the Kontexted server";
+export declare const builder: (yargs: any) => any;
+export declare const handler: (argv: {
+    force?: boolean;
+}) => Promise<void>;

package/dist/commands/server/stop.js

@@ -0,0 +1,32 @@
+import { getServerStatus, stopServer } from '../../lib/server/index.js';
+// ============ Yargs Command Module ============
+export const command = 'stop';
+export const desc = 'Stop the Kontexted server';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const builder = (yargs) => {
+    return yargs.option('force', {
+        type: 'boolean',
+        description: 'Force kill the server (SIGKILL)',
+    });
+};
+export const handler = async (argv) => {
+    const status = getServerStatus();
+    if (!status.running) {
+        console.log('Server is not running');
+        return;
+    }
+    try {
+        const stopped = await stopServer({ force: argv.force ?? false });
+        if (stopped) {
+            console.log('Server stopped');
+        }
+        else {
+            console.error('Error: Failed to stop server');
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : 'Unknown error');
+        process.exit(1);
+    }
+};

package/dist/commands/show-config.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from "commander";
+/**
+ * Register the show-config command
+ */
+export declare function registerShowConfigCommand(program: Command): void;