@quantum-hub/qhubctl 1.2.0 → 1.3.0

package/README.md

@@ -1,40 +1,156 @@
-# Quantum Hub Control
+# qhubctl
 
-The Quantum Hub Control, qhubctl, is a Command Line Interface (CLI) which lets you interact with the Kipu Quantum Platform from your terminal.
-We have installation instructions to guide you through the initial setup in our
-[quickstart](https://docs.hub.kipu-quantum.com/quickstart.html) guide.
+`qhubctl`, is a Command Line Interface (CLI) which lets you interact with the Kipu Quantum Hub from your terminal.
 
-Detailed information about the supported commands can be found in our
-[CLI reference](https://docs.hub.kipu-quantum.com/cli-reference.html).
+Detailed information about the supported commands can be found in our [CLI reference](https://docs.hub.kipu-quantum.com/cli-reference.html).
 
 ## Installation
 
-To install qhubctl, you must install Node.js and the npm command line interface using either a
-[Node version manager](https://github.com/nvm-sh/nvm) or a [Node installer](https://nodejs.org/en/download).
-
-**Make sure you install Node.js version 18 or higher.**
-
-Then install the qhubctl globally using npm:
+Node.js 18 or higher is required.
+Install it via a [Node version manager](https://github.com/nvm-sh/nvm) or a [Node installer](https://nodejs.org/en/download).
 
 ```bash
 npm install -g @quantum-hub/qhubctl
 ```
 
-You can use the `--help` flag to get information about the supported commands:
+> **Troubleshooting:** If you see `EACCES permissions` errors, use [nvm](https://github.com/nvm-sh/nvm) or see the [npm docs](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally).
+
+## Usage
 
-``` bash
+```bash
 qhubctl --help
+qhubctl <command> --help
 ```
 
-You may also get information about a specific command:
+## Development
 
-``` bash
-qhubctl <command> --help
+### Build
+
+```bash
+npm install
+npm run build
 ```
 
-> **Troubleshooting:**
-> If you experience `EACCES permissions` errors during installation, we recommend using [Node version manager](https://github.com/nvm-sh/nvm) (nvm).
-> Further, you may refer to the official [npm documentation](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) how to resolve such issues.
+Compiles TypeScript from `src/` to `dist/`. 
+The CLI entry point is `dist/main.js`.
+
+### Run locally
+
+```bash
+node dist/main.js <command>
+```
+
+### Watch mode
+
+For active development, run the TypeScript compiler in watch mode so every file save triggers an incremental rebuild:
+
+```bash
+npm run dev
+```
+
+`qhubctl` will reflect your latest changes on the next invocation without any manual rebuild step.
+
+### Linking globally with npm link
+
+`npm link` registers a global `qhubctl` symlink that points permanently to `dist/main.js` in your local checkout. Run it once after the initial setup:
+
+```bash
+npm run build
+npm link
+qhubctl <command>   # now resolves to your local build
+```
+
+The symlink persists across rebuilds and watch-mode recompiles — you never need to run `npm link` again unless you delete and re-clone the repo or change the `"bin"` entry in `package.json`.
+
+> **Note:** `npm link` and a globally installed published version of qhubctl are mutually exclusive — they occupy the same path. The last one to run wins. Use `which qhubctl` or `qhubctl --version` to confirm which is currently active.
+
+To switch back to the published version from npm:
+
+```bash
+npm unlink -g @quantum-hub/qhubctl   # removes the local symlink
+npm install -g @quantum-hub/qhubctl  # installs the published version
+```
+
+To go back to your local dev version:
+
+```bash
+npm link
+```
+
+### Run against staging
+
+```bash
+node dist/main.js login --base-path https://api.hub.34.90.225.20.nip.io -t <personal access token>
+```
+
+### Debug output
+
+Set `DEBUG=*` to print all debug output:
+
+```bash
+DEBUG=* node dist/main.js <command>
+```
+
+On Windows, set the variable separately:
+
+```cmd
+set DEBUG=*
+node dist\main.js <command>
+```
+
+### Tests
+
+```bash
+npm test                    # run tests + lint
+npm run test:coverage       # run tests with lcov coverage report
+```
+
+### Lint
+
+```bash
+npm run lint
+```
+
+### Generate docs
+
+Produces a Markdown CLI reference at `docs/cli-reference.md` from the compiled program:
+
+```bash
+npm run build
+npm run docs:generate
+```
+
+## Regenerating the API client
+
+The generated clients in `src/client/` are produced from the platform OpenAPI specs using [openapi-generator-cli](https://github.com/OpenAPITools/openapi-generator-cli).
+
+```bash
+npm install -g @openapitools/openapi-generator-cli
+```
+
+Against production:
+
+```bash
+openapi-generator-cli generate -g typescript-fetch \
+  -i https://api.hub.kipu-quantum.com/qc-catalog/docs \
+  -o src/client/kqh
+
+openapi-generator-cli generate -g typescript-fetch \
+  -i https://api.hub.kipu-quantum.com/user-service/docs \
+  -o src/client/users
+```
+
+Against staging:
+
+```bash
+openapi-generator-cli generate -g typescript-fetch \
+  -i https://api.hub.34.90.225.20.nip.io/qc-catalog/docs \
+  -o src/client/kqh
+
+openapi-generator-cli generate -g typescript-fetch \
+  -i https://api.hub.34.90.225.20.nip.io/user-service/docs \
+  -o src/client/users
+```
 
 ## License
 

package/dist/client/kqh/models/UpdateWorkflowServiceRequest.js

@@ -1,16 +1,5 @@
 /* tslint:disable */
 /* eslint-disable */
-/**
- * Quantum Hub Platform API
- * Part of the OpenAPI specification for the Quantum Hub Platform.
- *
- * The version of the OpenAPI document: v1
- * Contact: info@anaqor.io
- *
- * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
- * https://openapi-generator.tech
- * Do not edit the class manually.
- */
 /**
  * Check if a given object implements the UpdateWorkflowServiceRequest interface.
  */

package/dist/commands/compress.d.ts

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

package/dist/commands/compress.js

@@ -0,0 +1,23 @@
+import { Command } from 'commander';
+import fs from 'fs-extra';
+import path from 'node:path';
+import { zipProjectFolder } from '../lib/up/zip.js';
+import { spinner, stdout } from '../lib/output.js';
+const EXAMPLES = `
+Examples:
+  $ qhubctl compress`;
+export const compressCommand = new Command('compress')
+    .description("Compresses the current project and creates a ZIP file. Use the '.dockerignore' file to exclude files and directories from the ZIP file.")
+    .addHelpText('after', EXAMPLES)
+    .action(async () => {
+    const spin = spinner('Compressing project');
+    const targetDirectory = process.cwd();
+    const targetFilename = 'service.zip';
+    const targetFilePath = path.join(targetDirectory, '/', targetFilename);
+    if (fs.existsSync(targetFilePath)) {
+        fs.unlinkSync(targetFilePath);
+    }
+    await zipProjectFolder('./', targetDirectory, targetFilename);
+    spin.succeed('Project compressed');
+    stdout(`\nFile created at: ${targetFilePath}`);
+});

package/dist/commands/datapool-upload.d.ts

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

package/dist/commands/datapool-upload.js

@@ -0,0 +1,184 @@
+import { input, select } from '@inquirer/prompts';
+import { Command } from 'commander';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spinner, stdout } from '../lib/output.js';
+import { requireAuth } from '../model/command.js';
+import { HubPlatformClient, HubPlatformError } from '@quantum-hub/qhub-api/platform';
+function extractError(err) {
+    const bodyObj = err.body;
+    if (bodyObj.errorMessage)
+        return bodyObj.errorMessage;
+    if (bodyObj.detail)
+        return bodyObj.detail;
+    if (bodyObj.message)
+        return bodyObj.message;
+    return JSON.stringify(err.body);
+}
+function printHttpSpecificError(datapoolId, statusCode, errorMessage) {
+    if (statusCode === 404)
+        throw new Error(`Data pool not found: ${datapoolId}`);
+    if (statusCode === 403)
+        throw new Error(`Access denied. You don't have permission to upload to data pool: ${datapoolId}`);
+    if (statusCode === 400)
+        throw new Error(`Bad request. Please check the data pool ID and file format. Details: ${errorMessage}`);
+    if (statusCode === 401)
+        throw new Error(`Authentication failed. Please login again using 'qhubctl login'`);
+    if (statusCode === 413)
+        throw new Error(`File too large. The file exceeds the maximum allowed size for data pool uploads`);
+    if (statusCode === 415)
+        throw new Error(`Unsupported file type. Please check if the file format is supported`);
+    throw new Error(`Failed to upload file (HTTP ${statusCode}): ${errorMessage}`);
+}
+function handleUploadError(err, datapoolId) {
+    if (err instanceof HubPlatformError) {
+        const statusCode = err.statusCode ?? 500;
+        let errorMessage = 'Unknown API error occurred';
+        if (err.body) {
+            if (typeof err.body === 'string')
+                errorMessage = err.body;
+            else if (typeof err.body === 'object')
+                errorMessage = extractError(err);
+            else if (err.message)
+                errorMessage = err.message;
+        }
+        else if (err.message) {
+            errorMessage = err.message;
+        }
+        printHttpSpecificError(datapoolId || 'unknown', statusCode, errorMessage);
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Unexpected Error: ${msg}`);
+}
+async function promptForDatapoolAction(client) {
+    try {
+        const dataPools = await client.dataPools.getDataPools();
+        if (dataPools.length === 0) {
+            stdout('No data pools found. Creating a new one...');
+            return 'create';
+        }
+        return await select({
+            message: 'What would you like to do?',
+            choices: [
+                { name: 'Create a new data pool', value: 'create' },
+                { name: 'Select an existing data pool', value: 'select' },
+            ],
+            default: 'create',
+        });
+    }
+    catch {
+        return 'create';
+    }
+}
+async function createDatapool(client, suggestedName) {
+    try {
+        const name = await input({
+            message: 'Enter a name for the new data pool:',
+            default: `Data Pool for ${suggestedName}`,
+        });
+        const datapool = await client.dataPools.createDataPool({ name });
+        stdout(`\u2713 Created new data pool: ${datapool.name} (${datapool.id})`);
+        return datapool.id;
+    }
+    catch (err) {
+        if (err instanceof HubPlatformError) {
+            const errorMessage = err.body || err.message || 'Unknown API error occurred';
+            throw new Error(`Failed to create data pool (HTTP ${err.statusCode}): ${JSON.stringify(errorMessage)}`);
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to create data pool: ${msg}`);
+    }
+}
+async function selectExistingDatapool(client) {
+    try {
+        const dataPools = await client.dataPools.getDataPools();
+        if (dataPools.length === 0) {
+            stdout('No existing data pools found. Creating a new one...');
+            return createDatapool(client, 'upload');
+        }
+        stdout('\nAvailable data pools:');
+        dataPools.forEach((pool, index) => {
+            stdout(`${index + 1}. ${pool.name} (${pool.id})`);
+        });
+        const selection = await input({
+            message: `Select a data pool (1-${dataPools.length}) or enter the ID directly:`,
+        });
+        const index = parseInt(selection, 10);
+        if (!isNaN(index) && index >= 1 && index <= dataPools.length) {
+            return dataPools[index - 1].id;
+        }
+        return selection;
+    }
+    catch {
+        throw new Error('Failed to retrieve data pools');
+    }
+}
+async function ensureDatapoolExists(client, datapoolId, filePaths) {
+    if (!datapoolId) {
+        stdout('No data pool ID provided. You can create a new data pool or select an existing one.');
+        const action = await promptForDatapoolAction(client);
+        return action === 'create'
+            ? createDatapool(client, filePaths[0])
+            : selectExistingDatapool(client);
+    }
+    try {
+        await client.dataPools.getDataPool({ id: datapoolId });
+        return datapoolId;
+    }
+    catch (err) {
+        if (err instanceof HubPlatformError && err.statusCode === 404) {
+            stdout(`Data pool ${datapoolId} not found. Would you like to create a new data pool instead?`);
+            const action = await promptForDatapoolAction(client);
+            return action === 'create'
+                ? createDatapool(client, filePaths[0])
+                : selectExistingDatapool(client);
+        }
+        handleUploadError(err, datapoolId);
+    }
+}
+const EXAMPLES = `
+Examples:
+  $ qhubctl datapool upload --file ./data/dataset.csv
+  $ qhubctl datapool upload --file ./data/dataset.csv --file ./data/metadata.json
+  $ qhubctl datapool upload -f ./data/dataset.csv -f ./data/metadata.json --datapool-id 550e8400-e29b-41d4-a716-446655440000`;
+export const datapoolUploadCommand = new Command('upload')
+    .description('Upload files to a data pool')
+    .requiredOption('-f, --file <value...>', 'Path to a file to upload (can be specified multiple times)')
+    .option('-d, --datapool-id <value>', 'ID of the data pool to upload the files to (optional - will prompt to create a new one if not provided)')
+    .addHelpText('after', EXAMPLES)
+    .action(async (opts) => {
+    const userConfig = await requireAuth();
+    const baseUrl = userConfig.endpoint?.basePath
+        ? `${userConfig.endpoint.basePath}/qc-catalog`
+        : undefined;
+    const apiKey = userConfig.auth?.value;
+    const organizationId = userConfig.context?.isOrganization ? userConfig.context.id : undefined;
+    const client = new HubPlatformClient({ baseUrl, apiKey, organizationId });
+    const filePaths = opts.file;
+    for (const filePath of filePaths) {
+        if (!fs.existsSync(filePath))
+            throw new Error(`File not found: ${filePath}`);
+        try {
+            fs.accessSync(filePath, fs.constants.R_OK);
+        }
+        catch {
+            throw new Error(`Cannot read file: ${filePath}`);
+        }
+    }
+    const datapoolId = await ensureDatapoolExists(client, opts.datapoolId, filePaths);
+    for (const filePath of filePaths) {
+        const fileName = path.basename(filePath);
+        const spin = spinner(`Uploading ${fileName} to data pool ${datapoolId}`);
+        try {
+            const fileStream = fs.createReadStream(filePath);
+            const result = await client.dataPools.addDataPoolFile({ id: datapoolId, file: fileStream });
+            spin.succeed('\u2713');
+            stdout(`Successfully uploaded ${fileName} to data pool ${datapoolId}`);
+            stdout(`File ID: ${result.id}`);
+        }
+        catch (err) {
+            spin.fail('\u2717');
+            handleUploadError(err, datapoolId);
+        }
+    }
+});

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

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

package/dist/commands/get-context.js

@@ -0,0 +1,12 @@
+import { Command } from 'commander';
+import { requireAuth } from '../model/command.js';
+const EXAMPLES = `
+Examples:
+  $ qhubctl get-context`;
+export const getContextCommand = new Command('get-context')
+    .description('Get the current context, i.e., the personal or organization account you are currently working with.')
+    .addHelpText('after', EXAMPLES)
+    .action(async () => {
+    // requireAuth prints "Current context: ..." as a side-effect
+    await requireAuth();
+});

package/dist/commands/init.d.ts

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

package/dist/commands/init.js

@@ -0,0 +1,66 @@
+import { Command } from 'commander';
+import fs from 'fs-extra';
+import path from 'node:path';
+import { DEFAULT_STARTER, promptUserInput } from '../lib/init-user-input.js';
+import { randomName } from '../lib/random-name.js';
+import { downloadRepository, extractStarter } from '../lib/repository.js';
+import { error, stdout } from '../lib/output.js';
+import { Runtime } from '../model/managed-service-config.js';
+import { writeServiceConfig } from '../service/service-config-service.js';
+const EXAMPLES = `
+Examples:
+  $ qhubctl init`;
+export const initCommand = new Command('init')
+    .description('Bootstrap project to create a service.')
+    .option('--name <value>', 'The name of the service')
+    .option('--non-interactive', 'Run it in non-interactive mode', false)
+    .addHelpText('after', EXAMPLES)
+    .action(async (opts) => {
+    const nonInteractive = opts.nonInteractive;
+    let name = opts.name ?? randomName();
+    const input = nonInteractive ? {
+        cpu: 1,
+        descriptionFile: 'README.md',
+        gpu: undefined,
+        memory: 1,
+        name: name,
+        starter: DEFAULT_STARTER,
+    } : await promptUserInput(name);
+    name = input.name || name;
+    const targetDirectory = input.starter ? path.join(process.cwd(), name) : path.join(process.cwd());
+    if (input.starter && fs.existsSync(targetDirectory)) {
+        error(`Destination ${targetDirectory} already exists. Please choose another name.`);
+    }
+    const serviceConfig = {
+        name,
+        descriptionFile: input.descriptionFile ?? 'README.md',
+        resources: {
+            cpu: input.cpu,
+            memory: input.memory,
+        },
+        runtime: input.starter ? input.starter.runtime : Runtime.PYTHON_TEMPLATE,
+    };
+    if (input.gpu) {
+        serviceConfig.resources.gpu = {
+            count: 1,
+            type: input.gpu,
+        };
+    }
+    if (input.starter) {
+        fs.mkdirSync(targetDirectory);
+    }
+    writeServiceConfig(targetDirectory, serviceConfig);
+    if (input.starter) {
+        const zip = await downloadRepository(input.starter.url);
+        const starterName = path.basename(input.starter.url, '.zip');
+        extractStarter(zip, starterName, targetDirectory);
+    }
+    stdout('\u{1F389} Initialized project. Happy hacking!');
+    if (input.starter) {
+        stdout('\n Next steps:');
+        stdout(`  \u{2022} cd ${name}`);
+        stdout('  \u{2022} qhubctl up   (deploys your code as a service to Kipu Quantum Hub)');
+        stdout('  \u{2022} qhubctl run  (executes your service using the data from the input directory)');
+    }
+    stdout('');
+});

package/dist/commands/list-contexts.d.ts

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

package/dist/commands/list-contexts.js

@@ -0,0 +1,28 @@
+import { Command } from 'commander';
+import Table from 'tty-table';
+import { spinner, stdout } from '../lib/output.js';
+import { requireAuth } from '../model/command.js';
+import QuantumHubService from '../service/quantum-hub-service.js';
+const EXAMPLES = `
+Examples:
+  $ qhubctl list-contexts`;
+export const listContextsCommand = new Command('list-contexts')
+    .description('Retrieves the available contexts, i.e., the personal or organizational accounts available to you to work with.')
+    .addHelpText('after', EXAMPLES)
+    .action(async () => {
+    const userConfig = await requireAuth();
+    const quantumHubService = new QuantumHubService(userConfig);
+    const spin = spinner('Loading available contexts');
+    const accounts = await quantumHubService.getAccounts();
+    spin.succeed('Contexts loaded');
+    const tableData = accounts
+        .map(account => ({ displayName: account.displayName, id: account.id, isOrganization: account.isOrganization }));
+    const header = [
+        { value: "displayName", alias: "Name", align: "left" },
+        { value: "id", alias: "ID", align: "left" },
+        { value: "isOrganization", alias: "Account", width: 14, formatter: (value) => value ? "Organization" : "Personal" },
+    ];
+    const t = Table(header, tableData);
+    stdout(t.render());
+    stdout();
+});

package/dist/commands/login.d.ts

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

package/dist/commands/login.js

@@ -0,0 +1,59 @@
+import { password } from '@inquirer/prompts';
+import { Command } from 'commander';
+import { spinner } from '../lib/output.js';
+import { configDir, getUserConfig, showCustomBasePathWarning } from '../model/command.js';
+import { AuthType, defaultBasePath } from '../model/user-config.js';
+import AuthService from '../service/auth-service.js';
+import { writeUserConfig } from '../service/user-config-service.js';
+const EXAMPLES = `
+Examples:
+  $ qhubctl login -t <personal access token>
+  $ qhubctl login -t <personal access token> --base-path ${defaultBasePath}`;
+export const loginCommand = new Command('login')
+    .description('Login with your credentials')
+    .option('-t, --token <value>', 'Your personal access token')
+    .option('--base-path <value>', 'Custom base path for authentication (development)')
+    .addHelpText('after', EXAMPLES)
+    .action(async (opts) => {
+    let { token } = opts;
+    const { basePath } = opts;
+    if (!token) {
+        token = await password({ message: 'Enter or paste your personal access token?', mask: true });
+    }
+    if (!token) {
+        throw new Error('Invalid credentials. Please try again.');
+    }
+    if (basePath) {
+        showCustomBasePathWarning();
+    }
+    const spin = spinner('Login...');
+    const userConfig = getUserConfig();
+    const tempUserConfig = basePath ? {
+        ...userConfig,
+        endpoint: {
+            basePath,
+            defaultHeaders: userConfig.endpoint?.defaultHeaders || {}
+        }
+    } : userConfig;
+    const user = await new AuthService(tempUserConfig).authenticate(token);
+    const newUserConfig = {
+        ...userConfig,
+        auth: {
+            type: AuthType.API_KEY,
+            value: token,
+        },
+        context: {
+            id: user.id,
+            displayName: `${user.firstname} ${user.lastname}`,
+            isOrganization: false,
+        },
+        ...(basePath && {
+            endpoint: {
+                basePath,
+                defaultHeaders: userConfig.endpoint?.defaultHeaders || {}
+            }
+        })
+    };
+    writeUserConfig(configDir, newUserConfig);
+    spin.succeed('Login successful');
+});

package/dist/commands/logout.d.ts

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

package/dist/commands/logout.js

@@ -0,0 +1,20 @@
+import { Command } from 'commander';
+import { spinner } from '../lib/output.js';
+import { configDir } from '../model/command.js';
+import { writeUserConfig } from '../service/user-config-service.js';
+import { getUserConfig } from '../model/command.js';
+const EXAMPLES = `
+Examples:
+  $ qhubctl logout`;
+export const logoutCommand = new Command('logout')
+    .description('Logout')
+    .addHelpText('after', EXAMPLES)
+    .action(async () => {
+    const spin = spinner('Logout');
+    writeUserConfig(configDir, {
+        ...getUserConfig(),
+        auth: undefined,
+        context: undefined,
+    });
+    spin.succeed('Logout successful');
+});

package/dist/commands/openapi.d.ts

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