@quantum-hub/qhubctl 1.1.5 → 1.3.0

package/dist/commands/openapi.js

@@ -0,0 +1,244 @@
+import { confirm } from '@inquirer/prompts';
+import { Command } from 'commander';
+import fs from 'fs-extra';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { executeAsyncCommand } from '../lib/command.js';
+import { EntrypointResolver } from '../lib/entrypoint-resolver.js';
+import { randomString } from '../lib/random-string.js';
+import { error, spinner, stdout, warn } from '../lib/output.js';
+import { Runtime } from '../model/managed-service-config.js';
+import { readServiceConfig } from '../service/service-config-service.js';
+const SUPPORTED_FORMATS = ['yaml'];
+const DEFAULT_OUTPUT_FILE = 'openapi.yaml';
+const DEPRECATED_FILE_NAME = 'openapi-spec.yml';
+function getErrorMessage(err) {
+    if (typeof err === 'object' && err !== null && 'message' in err &&
+        typeof err.message === 'string') {
+        return err.message;
+    }
+    if (typeof err === 'string')
+        return err;
+    if (err instanceof Error)
+        return err.message;
+    return 'An unknown error occurred';
+}
+function checkDeprecatedFiles() {
+    const deprecatedFile = path.join(process.cwd(), DEPRECATED_FILE_NAME);
+    if (fs.existsSync(deprecatedFile)) {
+        warn(`Found deprecated file "${DEPRECATED_FILE_NAME}". Consider renaming it to "${DEFAULT_OUTPUT_FILE}".`);
+    }
+}
+async function determineOutputPath(opts) {
+    const defaultPath = path.join(process.cwd(), DEFAULT_OUTPUT_FILE);
+    const outputPath = opts.file ? path.resolve(opts.file) : defaultPath;
+    const outputExists = fs.existsSync(outputPath);
+    if (opts.file) {
+        const outputDir = path.dirname(outputPath);
+        if (!fs.existsSync(outputDir)) {
+            try {
+                fs.mkdirpSync(outputDir);
+            }
+            catch (err) {
+                throw new Error(`Cannot create output directory: ${outputDir}. ${getErrorMessage(err)}`);
+            }
+        }
+    }
+    if (outputExists && !opts.force) {
+        const shouldOverwrite = await confirm({
+            message: `File "${path.basename(outputPath)}" already exists. Overwrite?`,
+            default: false,
+        });
+        if (!shouldOverwrite) {
+            const newPath = path.join(path.dirname(outputPath), `${path.basename(outputPath, '.yaml')}-${randomString(5)}.yaml`);
+            stdout(`Creating new file: ${path.basename(newPath)}`);
+            return newPath;
+        }
+    }
+    return outputPath;
+}
+function isProjectSupported(opts) {
+    let serviceConfig;
+    try {
+        serviceConfig = readServiceConfig(process.cwd());
+    }
+    catch (err) {
+        warn(`Failed to read project configuration: ${getErrorMessage(err)}`);
+        warn('Ensure you have a valid qhub.json file in your project root.');
+        return false;
+    }
+    const hasExplicitEntrypoint = !!(opts.entrypoint || opts.package || opts.method);
+    const supportedRuntimes = [Runtime.PYTHON_TEMPLATE, Runtime.PYTHON, Runtime.DOCKER];
+    if (hasExplicitEntrypoint) {
+        const isSupported = supportedRuntimes.includes(serviceConfig.runtime);
+        if (!isSupported) {
+            warn(`Runtime "${serviceConfig.runtime}" is not supported for OpenAPI generation.`);
+            warn('');
+            warn('Supported configurations:');
+            warn('  \u2022 PYTHON_TEMPLATE: Automatic (requires src/program.py)');
+            warn('  \u2022 PYTHON/DOCKER: With explicit entrypoint flags');
+            warn('');
+            warn('Examples:');
+            warn('  qhubctl openapi --entrypoint=myapp.main:handler');
+            warn('  qhubctl openapi --package=myapp.core --method=process');
+        }
+        return isSupported;
+    }
+    const programFile = path.join(process.cwd(), 'src', 'program.py');
+    const hasProgramFile = fs.existsSync(programFile);
+    const isPythonTemplate = serviceConfig.runtime === Runtime.PYTHON_TEMPLATE;
+    const isSupported = isPythonTemplate && hasProgramFile;
+    if (!isSupported) {
+        warn('Cannot generate OpenAPI description from your code.');
+        warn('');
+        if (isPythonTemplate && !hasProgramFile) {
+            warn('Missing required file: src/program.py');
+            warn('');
+            warn('Solutions:');
+            warn('  \u2022 Create src/program.py with your main function, or');
+            warn('  \u2022 Use explicit entrypoint: --entrypoint=yourmodule.main:function');
+        }
+        else if (!isPythonTemplate) {
+            warn(`Runtime "${serviceConfig.runtime}" requires explicit entrypoint specification.`);
+            warn('');
+            warn('Use one of these flags:');
+            warn('  --entrypoint=package.module:function');
+            warn('  --package=package.module --method=function');
+            warn('');
+            warn('Examples:');
+            warn('  qhubctl openapi --entrypoint=myapp.main:handler');
+            warn('  qhubctl openapi --package=myapp.core --method=process');
+        }
+    }
+    return isSupported;
+}
+function formatPythonError(stderr) {
+    const commonErrors = {
+        'ModuleNotFoundError': 'Missing dependency. Install qhub-commons: pip install qhub-commons',
+        'ImportError': 'Cannot import module. Check your entrypoint path and ensure the module exists',
+        'AttributeError': 'Function not found. Check your method name and ensure it exists in the specified module',
+        'SyntaxError': 'Python syntax error in your code. Fix the syntax errors and try again',
+        'TypeError': 'Type error in your function. Ensure proper type annotations for parameters and return values',
+    };
+    for (const [errorType, helpText] of Object.entries(commonErrors)) {
+        if (stderr.includes(errorType))
+            return `${helpText}\n\nDetails: ${stderr}`;
+    }
+    return `Failed to generate OpenAPI description: ${stderr}`;
+}
+function validateCommandResult(result) {
+    if (typeof result === 'object' && result !== null &&
+        'stdout' in result && 'stderr' in result &&
+        typeof result.stdout === 'string' &&
+        typeof result.stderr === 'string') {
+        const { stdout: out, stderr } = result;
+        if (!out.trim()) {
+            const detail = stderr.trim() ? formatPythonError(stderr) : 'OpenAPI generation returned empty output. Check your entrypoint and ensure it has proper type annotations.';
+            throw new Error(detail);
+        }
+        return { stdout: out, stderr };
+    }
+    throw new Error('Invalid command result format');
+}
+async function generateFromCode(entrypoint) {
+    let title = 'Service API';
+    let description;
+    try {
+        const serviceConfig = readServiceConfig(process.cwd());
+        title = serviceConfig.name || 'Service API';
+        description = serviceConfig.summary || '';
+    }
+    catch {
+        warn(`Could not load qhub.json configuration. Using default title: ${title}`);
+    }
+    const safeEntrypoint = entrypoint.replace(/"/g, '\\"');
+    const safeTitle = title.replace(/"/g, '\\"');
+    const safeDescription = description ? description.replace(/"/g, '\\"') : 'None';
+    const pySnippet = `from qhub.commons.openapi.generator import generate_openapi; generate_openapi(entrypoint='${safeEntrypoint}', title='${safeTitle}', description=${safeDescription === 'None' ? 'None' : `'${safeDescription}'`})`;
+    const command = `uv run --no-sync --project ${process.cwd()} python -c "${pySnippet}"`;
+    try {
+        const result = await executeAsyncCommand(command);
+        const { stdout: out } = validateCommandResult(result);
+        return out;
+    }
+    catch (err) {
+        const errorMessage = getErrorMessage(err);
+        throw new Error(`Failed to generate OpenAPI description:\n${errorMessage}`);
+    }
+}
+const EXAMPLES = `
+Examples:
+  $ qhubctl openapi
+  $ qhubctl openapi --file=./openapi.yaml --format=yaml --force
+  $ qhubctl openapi --entrypoint=src.program:run
+  $ qhubctl openapi --package=src.program --method=run
+  $ qhubctl openapi --package=src.program`;
+export const openapiCommand = new Command('openapi')
+    .description('Generates the OpenAPI description for your project based on the parameter and return types of your run() method. ' +
+    'The output of this command will be used when creating or updating your service. ' +
+    'Supports PYTHON_TEMPLATE (with src/program.py), PYTHON and DOCKER runtimes (with explicit entrypoint). ' +
+    'Requires uv and a valid uv project in the workspace. The "qhub-commons" dependency is installed/upgraded automatically as a dependency.')
+    .option('-f, --force', 'Overwrite the output file if it already exists', false)
+    .option('--file <value>', 'The file to write the OpenAPI description to')
+    .option('--format <value>', `The format to generate the OpenAPI description [possible values: ${SUPPORTED_FORMATS.join(', ')}]`)
+    .option('--entrypoint <value>', 'The entrypoint to your program in the format "package.module:function" (default: "src.program:run"). Overrides package and method flags.')
+    .option('--package <value>', 'The package/module path to your program (e.g., "src.program" or "my_package.main"). Only used if entrypoint is not provided.')
+    .option('--method <value>', 'The method/function name in your program (default: "run"). Only used if entrypoint is not provided.')
+    .addHelpText('after', EXAMPLES)
+    .action(async (opts) => {
+    checkDeprecatedFiles();
+    if (opts.format && !SUPPORTED_FORMATS.includes(opts.format)) {
+        throw new Error(`Unsupported format: ${opts.format}. Supported formats: ${SUPPORTED_FORMATS.join(', ')}`);
+    }
+    let entrypoint;
+    try {
+        entrypoint = EntrypointResolver.resolveEntrypoint(opts);
+    }
+    catch (err) {
+        throw new Error(`Invalid entrypoint format: ${getErrorMessage(err)}\n\n` +
+            'Expected format: "package.module:function"\nExample: "src.program:run"\n\n' +
+            'Use --help for more examples.');
+    }
+    const outputPath = await determineOutputPath(opts);
+    const shouldGenerateFile = isProjectSupported(opts);
+    if (!shouldGenerateFile) {
+        warn(`Cannot generate OpenAPI description from your code. Supported configurations:\n` +
+            '  \u2022 PYTHON_TEMPLATE runtime with "./src/program.py" file\n' +
+            '  \u2022 DOCKER, PYTHON, or PYTHON_TEMPLATE runtimes with explicit entrypoint (--entrypoint, or (--package, --method))');
+        return;
+    }
+    // Ensure qhub-commons is installed (or upgraded) in the project venv
+    stdout('Ensuring qhub-commons is up to date...');
+    const addResult = spawnSync('uv', ['add', '--upgrade', 'qhub-commons', '--project', process.cwd()], { stdio: 'inherit' });
+    if (addResult.status !== 0) {
+        error('Failed to install qhub-commons via uv. ' +
+            'Make sure uv is installed and the workspace is a valid uv project.');
+    }
+    const spin = spinner('Generating OpenAPI description');
+    let fileContent;
+    try {
+        fileContent = await generateFromCode(entrypoint);
+    }
+    catch (err) {
+        spin.fail('Failed');
+        throw err;
+    }
+    try {
+        fs.writeFileSync(outputPath, fileContent, 'utf8');
+        spin.succeed('Done');
+    }
+    catch (err) {
+        spin.fail('Failed');
+        throw new Error(`Failed to write file ${outputPath}: ${getErrorMessage(err)}`);
+    }
+    const relativePath = path.relative(process.cwd(), outputPath);
+    const displayPath = relativePath.startsWith('..') ? outputPath : relativePath;
+    stdout('');
+    stdout(`OpenAPI description created: ${displayPath}`);
+    if (fs.statSync(outputPath).size > 0) {
+        stdout('');
+        stdout('Next steps:');
+        stdout(' \u2022 Review the generated OpenAPI description');
+        stdout(' \u2022 Use it to create or update your service');
+    }
+});

package/dist/commands/run.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const runCommand: Command;

package/dist/commands/run.js

@@ -0,0 +1,126 @@
+import { confirm } from '@inquirer/prompts';
+import { Command } from 'commander';
+import { waitUntil } from 'async-wait-until';
+import fsExtra from 'fs-extra';
+const { readJsonSync } = fsExtra;
+import fs from 'node:fs';
+import path from 'node:path';
+import { error, spinner, stdout, warn } from '../lib/output.js';
+import { requireAuth } from '../model/command.js';
+import { defaultBasePath } from '../model/user-config.js';
+import QuantumHubService from '../service/quantum-hub-service.js';
+import { readServiceConfig } from '../service/service-config-service.js';
+import { HubPlatform } from '@quantum-hub/qhub-api/platform';
+async function getInputFromFiles(filePaths) {
+    const paths = filePaths.split(',').map(p => p.trim());
+    const mergedInput = {};
+    let hasValidFile = false;
+    for (const filePath of paths) {
+        let file = filePath;
+        if (!fs.existsSync(filePath)) {
+            file = path.join(process.cwd(), filePath);
+        }
+        if (fs.existsSync(file)) {
+            try {
+                const content = readJsonSync(file, { encoding: 'utf8' });
+                Object.assign(mergedInput, content);
+                hasValidFile = true;
+            }
+            catch {
+                warn(`Failed to parse JSON from ${filePath}. Skipping this file.`);
+            }
+        }
+    }
+    if (!hasValidFile) {
+        const confirmed = await confirm({ message: 'No valid input files found. Run without input?' });
+        if (confirmed)
+            return {};
+        process.exit(0);
+    }
+    return mergedInput;
+}
+const EXAMPLES = `
+Examples:
+  $ qhubctl run
+  $ qhubctl run --detached
+  $ qhubctl run -i '{"values": [10,12], "round_up": true}'
+  $ qhubctl run --input-files=./input/data.json,./input/params.json
+  $ qhubctl run --input-files=./config.json,./overrides.json`;
+export const runCommand = new Command('run')
+    .description('Creates a job execution')
+    .argument('[serviceId]', 'The ID of the service to run (optional — reads from qhub.json if omitted)')
+    .option('-i, --input <value>', 'Input as JSON string.')
+    .option('--input-files <value>', 'Comma-separated paths to files containing input to be merged (default: ./input/data.json,./input/params.json).')
+    .option('--detached', 'Executes the job in detached mode, i.e., without waiting for it to finish.', false)
+    .addHelpText('after', EXAMPLES)
+    .action(async (serviceId, opts) => {
+    const userConfig = await requireAuth();
+    const hubService = new QuantumHubService(userConfig);
+    if (!serviceId) {
+        try {
+            const serviceConfig = readServiceConfig(process.cwd());
+            serviceId = serviceConfig.serviceId;
+        }
+        catch {
+            serviceId = undefined;
+        }
+    }
+    if (!serviceId) {
+        error('Missing service ID. Please provide a service ID as argument or set it in the qhub.json of your project.');
+    }
+    const service = await hubService.getService(serviceId);
+    let input;
+    if (opts.input) {
+        try {
+            input = JSON.parse(opts.input);
+        }
+        catch {
+            error('Invalid JSON provided.');
+        }
+    }
+    else {
+        input = await getInputFromFiles(opts.inputFiles || './input/data.json,./input/params.json');
+    }
+    let job;
+    const payload = { serviceId: service.id, tags: ['cli'], input };
+    job = await hubService.runJob(payload);
+    if (opts.detached) {
+        stdout(`Job (${job.id}) created.`);
+        return;
+    }
+    const spin = spinner(`Running Job (${job.id})`);
+    try {
+        await waitUntil(async () => {
+            job = await hubService.getJobById(job.id);
+            return (job.status === HubPlatform.ServiceJobDto.Status.Succeeded ||
+                job.status === HubPlatform.ServiceJobDto.Status.Failed ||
+                job.status === HubPlatform.ServiceJobDto.Status.Cancelled);
+        }, {
+            intervalBetweenAttempts: 5000,
+            timeout: 10 * 60 * 1000,
+        });
+    }
+    catch {
+        // ignore — status printed below
+    }
+    const basePath = userConfig.endpoint?.basePath || defaultBasePath;
+    const jobDetailsLink = `${basePath}/service-jobs/${job.id}`;
+    switch (job.status) {
+        case HubPlatform.ServiceJobDto.Status.Cancelled:
+            spin.warn('Job canceled.');
+            stdout(`See details at \u001B]8;;${jobDetailsLink}\u0007${jobDetailsLink}\u001B]8;;\u0007`);
+            break;
+        case HubPlatform.ServiceJobDto.Status.Failed:
+            spin.fail('Job failed.');
+            stdout(`See details at \u001B]8;;${jobDetailsLink}\u0007${jobDetailsLink}\u001B]8;;\u0007`);
+            break;
+        case HubPlatform.ServiceJobDto.Status.Succeeded:
+            spin.succeed('Job succeeded.');
+            stdout(`See result at \u001B]8;;${jobDetailsLink}\u0007${jobDetailsLink}\u001B]8;;\u0007`);
+            break;
+        default:
+            spin.stop();
+            stdout('Timeout polling status.');
+            stdout(`See status details at \u001B]8;;${jobDetailsLink}\u0007${jobDetailsLink}\u001B]8;;\u0007`);
+    }
+});

package/dist/commands/serve.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const serveCommand: Command;

package/dist/commands/serve.js

@@ -0,0 +1,35 @@
+import { Command } from 'commander';
+import { spawnSync } from 'node:child_process';
+import { error, stdout } from '../lib/output.js';
+const LOG_LEVELS = ['TRACE', 'DEBUG', 'INFO', 'SUCCESS', 'WARNING', 'ERROR', 'CRITICAL'];
+const EXAMPLES = `
+Examples:
+  $ qhubctl serve
+  $ qhubctl serve -p 8081
+  $ qhubctl serve --workspace /path/to/workspace`;
+export const serveCommand = new Command('serve')
+    .description('Runs your project locally via qhub-serve inside the workspace virtual environment, ' +
+    'exposing the same HTTP endpoints as Kipu Quantum Hub (start execution, check status, ' +
+    'cancel, retrieve results).')
+    .option('-p, --port <number>', 'The port on which the local web server accepts requests', '8081')
+    .option('--log-level <level>', `Log level for qhub-serve. Possible values: ${LOG_LEVELS.join(', ')}`, 'INFO')
+    .option('-w, --workspace <path>', 'Path to the workspace directory (must be a valid uv project). Defaults to the current directory.')
+    .addHelpText('after', EXAMPLES)
+    .action(async (opts) => {
+    const workspaceDir = opts.workspace ?? process.cwd();
+    const port = opts.port;
+    const logLevel = opts.logLevel;
+    // Step 1: Add (or upgrade) qhub-serve as a dev dependency
+    stdout('Ensuring qhub-serve is up to date...');
+    const addResult = spawnSync('uv', ['add', '--dev', '--upgrade', 'qhub-serve', '--project', workspaceDir], { stdio: 'inherit' });
+    if (addResult.status !== 0) {
+        error('Failed to install qhub-serve via uv. ' +
+            'Make sure uv is installed and the workspace is a valid uv project.');
+    }
+    // Step 2: Run qhub-serve inside the workspace venv
+    stdout('\nStarting qhub-serve...');
+    const runResult = spawnSync('uv', ['run', '--project', workspaceDir, 'qhub-serve', '--workspace', workspaceDir, '--port', String(port), '--log-level', logLevel], { stdio: 'inherit' });
+    if (runResult.status !== 0) {
+        error('qhub-serve exited with a non-zero status code.');
+    }
+});

package/dist/commands/services.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const servicesCommand: Command;

package/dist/commands/services.js

@@ -0,0 +1,48 @@
+import { Command } from 'commander';
+import Table from 'tty-table';
+import { spinner, stdout, warn } from '../lib/output.js';
+import { requireAuth } from '../model/command.js';
+import QuantumHubService from '../service/quantum-hub-service.js';
+const EXAMPLES = `
+Examples:
+  $ qhubctl services
+  $ qhubctl services --json
+  $ qhubctl services --name "my-service"
+  $ qhubctl services --name "my-service" --json
+  $ qhubctl services --json --all`;
+export const servicesCommand = new Command('services')
+    .description('List all services of the current context.')
+    .option('--json', 'Output in JSON format', false)
+    .option('--name <value>', 'Filter services by name (case-insensitive full match)')
+    .option('--all', 'Display all service properties (only available with --json)', false)
+    .addHelpText('after', EXAMPLES)
+    .action(async (opts) => {
+    // suppress "Current context: ..." line when outputting JSON
+    const userConfig = await requireAuth({ printContext: !opts.json });
+    const quantumHubService = new QuantumHubService(userConfig);
+    if (opts.all && !opts.json) {
+        warn('The --all flag can only be used with --json output. Continuing without --all.');
+    }
+    const spin = spinner('Loading services');
+    let services = await quantumHubService.getServices();
+    spin.succeed('Services loaded');
+    if (opts.name) {
+        const nameFilter = opts.name.toLowerCase();
+        services = services.filter(service => service.name?.toLowerCase() === nameFilter);
+    }
+    const tableData = services.map(service => ({ id: service.id, name: service.name }));
+    if (opts.json) {
+        stdout(JSON.stringify(opts.all ? services : tableData, null, 2));
+        return;
+    }
+    const header = [
+        { value: "id", alias: "ID", align: "left" },
+        { value: "name", alias: "Name", align: "left" },
+    ];
+    const t = Table(header, tableData);
+    const contextName = userConfig.context?.displayName;
+    const filterInfo = opts.name ? ` (filtered by name: "${opts.name}")` : '';
+    stdout(`Available services for ${contextName}${filterInfo}:`);
+    stdout(t.render());
+    stdout();
+});

package/dist/commands/set-context.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const setContextCommand: Command;

package/dist/commands/set-context.js

@@ -0,0 +1,52 @@
+import { select } from '@inquirer/prompts';
+import { Command } from 'commander';
+import { error, spinner, stdout } from '../lib/output.js';
+import { configDir, requireAuth } from '../model/command.js';
+import QuantumHubService from '../service/quantum-hub-service.js';
+import { writeUserConfig } from '../service/user-config-service.js';
+function getPromptOptions(accounts) {
+    return accounts.map(account => ({
+        name: account.isOrganization ? `${account.displayName} (Organization)` : account.displayName,
+        value: account,
+    }));
+}
+const EXAMPLES = `
+Examples:
+  $ qhubctl set-context
+  $ qhubctl set-context <context-id>`;
+export const setContextCommand = new Command('set-context')
+    .description('Set the current context, i.e., the personal or organization account you are currently working with.')
+    .argument('[contextId]', 'The ID of the context to switch to')
+    .addHelpText('after', EXAMPLES)
+    .action(async (contextId) => {
+    const userConfig = await requireAuth();
+    const quantumHubService = new QuantumHubService(userConfig);
+    if (!contextId) {
+        const spin = spinner('Loading available contexts');
+        const accounts = await quantumHubService.getAccounts();
+        spin.succeed('Contexts loaded');
+        const response = await select({
+            choices: getPromptOptions(accounts),
+            message: 'Choose a context',
+            default: accounts[0],
+        });
+        contextId = response.id;
+    }
+    else {
+        const accounts = await quantumHubService.getAccounts();
+        const selectedContext = accounts.find(account => account.id === contextId);
+        if (!selectedContext) {
+            error(`Context with id "${contextId}" not found.`);
+        }
+    }
+    const accounts = await quantumHubService.getAccounts();
+    const selectedContext = accounts.find(account => account.id === contextId);
+    if (!selectedContext) {
+        error(`Context with id "${contextId}" not found.`);
+    }
+    writeUserConfig(configDir, {
+        ...userConfig,
+        context: selectedContext,
+    });
+    stdout(`Switched to context "${selectedContext?.displayName}".`);
+});

package/dist/commands/up.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const upCommand: Command;