@quantum-hub/qhubctl 2.0.0 → 2.1.0

package/dist/commands/up.js

@@ -1,18 +1,24 @@
-import { confirm } from '@inquirer/prompts';
-import { Command } from 'commander';
+import { confirm, input, password } from '@inquirer/prompts';
+import { HubPlatform } from '@quantum-hub/qhub-api/platform';
 import { waitUntil } from 'async-wait-until';
+import { Command } from 'commander';
 import fs from 'node:fs';
 import path from 'node:path';
-import { HubPlatform } from '@quantum-hub/qhub-api/platform';
+import { error, spinner, stdout, warn } from '../lib/output.js';
 import { streamToBlob } from '../lib/stream-to-blob.js';
 import { getDescriptionText } from '../lib/up/get-description.js';
-import { zipProjectFolder } from '../lib/up/zip.js';
 import { enforceRequiredFiles } from '../lib/up/required-files.js';
-import { handleError } from '../lib/error.js';
-import { error, spinner, stdout, warn } from '../lib/output.js';
+import { buildServiceSource, isRegistrySource, resolveRegistryCredentials } from '../lib/up/source.js';
+import { zipProjectFolder } from '../lib/up/zip.js';
 import { requireAuth } from '../model/command.js';
 import QuantumHubService from '../service/quantum-hub-service.js';
 import { readServiceConfig, writeServiceConfig } from '../service/service-config-service.js';
+/**
+ * Prints an error message and exits. Service-layer errors already carry a resolved message.
+ */
+function fail(err) {
+    error(err instanceof Error ? err.message : String(err));
+}
 async function getOpenapi() {
     const openapiYamlPath = path.join(process.cwd(), 'openapi.yaml');
     const openapiYmlPath = path.join(process.cwd(), 'openapi.yml');
@@ -25,6 +31,28 @@ async function getOpenapi() {
         return streamToBlob(openapi);
     return undefined;
 }
+/**
+ * Gathers the optional service metadata files (OpenAPI contract and the
+ * configured description) from the project. Both are independent of the source
+ * kind, so file and registry deploys gather them the same way.
+ */
+async function getServiceMetadata() {
+    return {
+        openapi: await getOpenapi(),
+        descriptionText: await getDescriptionText(process.cwd()),
+    };
+}
+/**
+ * Uploads the optional service metadata that is independent of the source: the
+ * description and the OpenAPI contract. Each is uploaded only when present, so
+ * an image-only service deploys with neither.
+ */
+async function uploadServiceMetadata(qhubService, serviceConfig, metadata) {
+    if (metadata.descriptionText)
+        await qhubService.updateDescription(serviceConfig, metadata.descriptionText);
+    if (metadata.openapi)
+        await qhubService.updateOpenapi(serviceConfig, metadata.openapi);
+}
 async function buildServiceJob(qhubService, service, silentMode) {
     let buildJob;
     let spin;
@@ -66,47 +94,56 @@ async function buildServiceJob(qhubService, service, silentMode) {
     }
     return buildJob;
 }
-async function createService(qhubService, serviceConfig, files, silentMode, noSaveId = false, customName) {
+async function createService(qhubService, serviceConfig, source, metadata, sourceCode, silentMode, noSaveId = false, customName) {
     const spin = silentMode ? undefined : spinner('Creating service');
     const configToUse = { ...serviceConfig };
     if (customName)
         configToUse.name = customName;
-    const service = await qhubService.createService(configToUse, files.sourceCode, files.openapi);
-    serviceConfig.serviceId = service?.id;
+    const service = await qhubService.createService(configToUse, source, sourceCode);
+    serviceConfig.serviceId = service.id;
     if (!noSaveId)
         writeServiceConfig(process.cwd(), serviceConfig);
-    if (files.descriptionText)
-        await qhubService.updateDescription(serviceConfig, files.descriptionText);
-    if (files.openapi)
-        await qhubService.updateOpenapi(serviceConfig, files.openapi);
+    await uploadServiceMetadata(qhubService, serviceConfig, metadata);
     spin?.succeed();
     return service;
 }
-async function updateService(qhubService, serviceConfig, files, silentMode) {
+async function updateService(qhubService, serviceConfig, source, metadata, sourceCode, silentMode) {
     const spin = silentMode ? undefined : spinner('Updating service');
-    const result = await qhubService.updateService(serviceConfig, files.descriptionText, files.sourceCode, files.openapi);
+    // A registry source is set via the platform's update-source operation; a file
+    // source uploads a fresh code archive. Either way the optional metadata follows.
+    if (source.type === 'registry') {
+        await qhubService.updateServiceSource(serviceConfig.serviceId, source);
+        await uploadServiceMetadata(qhubService, serviceConfig, metadata);
+        spin?.succeed();
+        return undefined;
+    }
+    const result = await qhubService.updateService(serviceConfig, metadata.descriptionText, sourceCode, metadata.openapi);
     spin?.succeed();
     return result;
 }
-const EXAMPLES = `
-Examples:
-  $ qhubctl up
-  $ qhubctl up --no-save-id
-  $ qhubctl up --name "my-custom-service-name"
-  $ qhubctl up --name "test-service" --no-save-id`;
-export const upCommand = new Command('up')
-    .description('Creates or updates a service')
-    .option('--silent', 'Suppresses all outputs, helpful when executed in a CI/CD pipeline.', false)
-    .option('--no-save-id', 'Prevents storing the created service ID in qhub.json file.')
-    .option('--name <value>', 'Override the service name from qhub.json with a custom name.')
-    .addHelpText('after', EXAMPLES)
-    .action(async (opts) => {
-    const userConfig = await requireAuth();
-    const qhubService = new QuantumHubService(userConfig);
-    const silentMode = opts.silent;
-    // Commander inverts --no-save-id into opts.saveId = false
-    const noSaveId = !opts.saveId;
-    const serviceConfig = readServiceConfig(process.cwd());
+/**
+ * Resolves registry pull credentials, falling back to an interactive prompt
+ * when none are supplied via flags or environment. A blank username means a
+ * public/anonymous pull. Never prompts in silent mode. Credentials are never
+ * persisted to qhub.json (see ADR 0001).
+ */
+async function resolveCredentialsInteractively(opts, silentMode) {
+    const credentials = resolveRegistryCredentials({ username: opts.registryUsername, password: opts.registryPassword }, process.env);
+    if (credentials.username || silentMode) {
+        return credentials;
+    }
+    const username = await input({ message: 'Registry username (leave blank for a public image)' });
+    if (!username) {
+        return credentials;
+    }
+    const registryPassword = await password({ message: 'Registry password' });
+    return { username, password: registryPassword };
+}
+/**
+ * Emits non-fatal warnings for deprecated qhub.json fields and legacy file
+ * names in the project. Purely informational; never throws.
+ */
+function warnAboutDeprecations(serviceConfig) {
     if (!('descriptionFile' in serviceConfig)) {
         stdout('Warning: Since version 2.14.0, the "description" property in qhub.json has changed to "descriptionFile".\nFor more information, visit: https://docs.hub.kipu-quantum.com/qhub-json-reference.html\n');
     }
@@ -114,46 +151,67 @@ export const upCommand = new Command('up')
     if (fs.existsSync(deprecatedOpenapiFile)) {
         warn('You are having the deprecated file "openapi-spec.yml" in your project. Please consider renaming it to "openapi.yaml".');
     }
-    let serviceExistsInPlatform = false;
-    if (serviceConfig.serviceId) {
-        try {
-            await qhubService.getService(serviceConfig.serviceId);
-            serviceExistsInPlatform = true;
-        }
-        catch {
-            serviceExistsInPlatform = false;
-        }
+}
+/**
+ * Checks whether the configured service still exists in the platform. When a
+ * service ID is set in qhub.json but no matching service is found, prompts to
+ * create a new one and exits if the user declines.
+ */
+async function resolveServiceExists(qhubService, serviceConfig) {
+    if (!serviceConfig.serviceId)
+        return false;
+    let serviceExistsInPlatform;
+    try {
+        await qhubService.getService(serviceConfig.serviceId);
+        serviceExistsInPlatform = true;
+    }
+    catch {
+        serviceExistsInPlatform = false;
     }
-    if (serviceConfig.serviceId && !serviceExistsInPlatform) {
+    if (!serviceExistsInPlatform) {
         stdout(`We could not find a service with id '${serviceConfig.serviceId}' in the current context!`);
         const createNewService = await confirm({ message: 'Do you want to create a new service?' });
         if (!createNewService)
             process.exit(0);
     }
-    try {
-        await enforceRequiredFiles(process.cwd());
-    }
-    catch (err) {
-        error(err.message);
+    return serviceExistsInPlatform;
+}
+/**
+ * Resolves the platform ServiceSource for this deploy: enforces the required
+ * files for a file source, gathers pull credentials for a registry source, and
+ * builds the final source descriptor. Exits on a build error.
+ */
+async function resolveServiceSource(serviceConfig, opts, silentMode) {
+    const registrySource = isRegistrySource(serviceConfig, opts.image);
+    // A registry source is pre-built and never packaged locally, so the
+    // required-files check (Dockerfile / requirements.txt) does not apply.
+    if (!registrySource) {
+        try {
+            await enforceRequiredFiles(process.cwd());
+        }
+        catch (err) {
+            error(err.message);
+        }
     }
-    const serviceFiles = {
-        openapi: await getOpenapi(),
-        descriptionText: await getDescriptionText(process.cwd()),
-        sourceCode: await zipProjectFolder('./'),
-    };
-    let service;
+    // A registry source needs pull credentials (flags / env / prompt); a file
+    // source needs none. Both then resolve to a single platform ServiceSource.
+    const credentials = registrySource
+        ? await resolveCredentialsInteractively(opts, silentMode)
+        : undefined;
     try {
-        service = serviceExistsInPlatform
-            ? await updateService(qhubService, serviceConfig, serviceFiles, silentMode)
-            : await createService(qhubService, serviceConfig, serviceFiles, silentMode, noSaveId, opts.name);
+        return buildServiceSource(serviceConfig, opts.image, credentials);
     }
     catch (err) {
-        error(await handleError(err));
+        fail(err);
     }
-    const buildJob = await buildServiceJob(qhubService, service, silentMode);
+}
+/**
+ * Reports the outcome of a build job: a success message, a failure with the
+ * platform's validation summary when available, or a pending notice.
+ */
+function reportBuildResult(buildJob, serviceExistsInPlatform) {
     if (buildJob?.status === HubPlatform.BuildJobDto.Status.Success) {
-        const msg = `Service ${serviceExistsInPlatform ? 'updated' : 'created'} \u{1F680}`;
-        stdout(msg);
+        stdout(`Service ${serviceExistsInPlatform ? 'updated' : 'created'} \u{1F680}`);
     }
     else if (buildJob?.status === HubPlatform.BuildJobDto.Status.Failure) {
         const { validationResult } = buildJob;
@@ -166,4 +224,57 @@ export const upCommand = new Command('up')
     else {
         error('Still pending, please check the platform UI to determine the status');
     }
+}
+const EXAMPLES = `
+Examples:
+  $ qhubctl up
+  $ qhubctl up --no-save-id
+  $ qhubctl up --name "my-custom-service-name"
+  $ qhubctl up --name "test-service" --no-save-id
+  $ qhubctl up --image ghcr.io/acme/my-service:1.2.3`;
+export const upCommand = new Command('up')
+    .description('Creates or updates a service')
+    .option('--silent', 'Suppresses all outputs, helpful when executed in a CI/CD pipeline.', false)
+    .option('--no-save-id', 'Prevents storing the created service ID in qhub.json file.')
+    .option('--name <value>', 'Override the service name from qhub.json with a custom name.')
+    .option('--image <ref>', 'Deploy a pre-built image from a container registry, given as registry/repo:tag (the tag defaults to "latest").')
+    .option('--registry-username <value>', 'Username to pull a private registry image. Falls back to the QHUB_REGISTRY_USERNAME environment variable.')
+    .option('--registry-password <value>', 'Password to pull a private registry image. Falls back to the QHUB_REGISTRY_PASSWORD environment variable.')
+    .addHelpText('after', EXAMPLES)
+    .action(async (opts) => {
+    const userConfig = await requireAuth();
+    const qhubService = new QuantumHubService(userConfig);
+    const silentMode = opts.silent;
+    // Commander inverts --no-save-id into opts.saveId = false
+    const noSaveId = !opts.saveId;
+    const serviceConfig = readServiceConfig(process.cwd());
+    warnAboutDeprecations(serviceConfig);
+    const serviceExistsInPlatform = await resolveServiceExists(qhubService, serviceConfig);
+    const source = await resolveServiceSource(serviceConfig, opts, silentMode);
+    // Metadata (openapi + description) is independent of the source kind.
+    const metadata = await getServiceMetadata();
+    // Only a file source ships local code; a registry source is pre-built.
+    const sourceCode = source.type === 'file' ? await zipProjectFolder('./') : undefined;
+    // The platform has no rename operation, so --name only takes effect on create.
+    if (serviceExistsInPlatform && opts.name && !silentMode) {
+        warn('Ignoring --name: the service name cannot be changed on update.');
+    }
+    let service;
+    try {
+        service = serviceExistsInPlatform
+            ? await updateService(qhubService, serviceConfig, source, metadata, sourceCode, silentMode)
+            : await createService(qhubService, serviceConfig, source, metadata, sourceCode, silentMode, noSaveId, opts.name);
+    }
+    catch (err) {
+        fail(err);
+    }
+    // A registry source is pre-built — the platform runs no build job, so
+    // success is reported immediately. A file source must wait for the build.
+    if (source.type !== 'file') {
+        if (!silentMode)
+            stdout(`Service ${serviceExistsInPlatform ? 'updated' : 'created'} \u{1F680}`);
+        return;
+    }
+    const buildJob = await buildServiceJob(qhubService, service, silentMode);
+    reportBuildResult(buildJob, serviceExistsInPlatform);
 });

package/dist/lib/up/source.d.ts

@@ -0,0 +1,37 @@
+import { HubPlatform } from '@quantum-hub/qhub-api/platform';
+import ManagedServiceConfig from '../../model/managed-service-config.js';
+export interface RegistryCredentials {
+    username?: string;
+    password?: string;
+}
+export interface ImageRef {
+    image: string;
+    tag: string;
+}
+/**
+ * Splits an image reference (`registry/repo:tag`) into its image and tag.
+ * The tag defaults to `latest`. A colon belonging to a registry `host:port`
+ * (i.e. before the last path segment) is not treated as a tag separator.
+ */
+export declare function parseImageRef(ref: string): ImageRef;
+/**
+ * Resolves registry pull credentials with precedence flag > environment.
+ * Returns an empty object when nothing is supplied; credentials are never
+ * persisted to qhub.json (see ADR 0001).
+ */
+export declare function resolveRegistryCredentials(flags: {
+    username?: string;
+    password?: string;
+}, env: NodeJS.ProcessEnv): RegistryCredentials;
+/**
+ * A service uses a registry source when its qhub.json declares
+ * `source.type: "registry"`, or when an `--image` override is supplied.
+ */
+export declare function isRegistrySource(config: ManagedServiceConfig, imageOverride?: string): boolean;
+/**
+ * Builds the platform ServiceSource for an `up` deploy.
+ * Returns a file source unless the config or an `--image` override selects a
+ * registry source, in which case the image (override wins over qhub.json) and
+ * optional pull credentials are included.
+ */
+export declare function buildServiceSource(config: ManagedServiceConfig, imageOverride?: string, credentials?: RegistryCredentials): HubPlatform.ServiceSource;

package/dist/lib/up/source.js

@@ -0,0 +1,63 @@
+const DEFAULT_TAG = 'latest';
+/**
+ * Splits an image reference (`registry/repo:tag`) into its image and tag.
+ * The tag defaults to `latest`. A colon belonging to a registry `host:port`
+ * (i.e. before the last path segment) is not treated as a tag separator.
+ */
+export function parseImageRef(ref) {
+    const lastSlash = ref.lastIndexOf('/');
+    const lastColon = ref.lastIndexOf(':');
+    if (lastColon > lastSlash) {
+        return { image: ref.slice(0, lastColon), tag: ref.slice(lastColon + 1) || DEFAULT_TAG };
+    }
+    return { image: ref, tag: DEFAULT_TAG };
+}
+/**
+ * Resolves registry pull credentials with precedence flag > environment.
+ * Returns an empty object when nothing is supplied; credentials are never
+ * persisted to qhub.json (see ADR 0001).
+ */
+export function resolveRegistryCredentials(flags, env) {
+    const username = flags.username ?? env.QHUB_REGISTRY_USERNAME;
+    const password = flags.password ?? env.QHUB_REGISTRY_PASSWORD;
+    const credentials = {};
+    if (username)
+        credentials.username = username;
+    if (password)
+        credentials.password = password;
+    return credentials;
+}
+/**
+ * A service uses a registry source when its qhub.json declares
+ * `source.type: "registry"`, or when an `--image` override is supplied.
+ */
+export function isRegistrySource(config, imageOverride) {
+    return Boolean(imageOverride) || config.source?.type === 'registry';
+}
+/**
+ * Builds the platform ServiceSource for an `up` deploy.
+ * Returns a file source unless the config or an `--image` override selects a
+ * registry source, in which case the image (override wins over qhub.json) and
+ * optional pull credentials are included.
+ */
+export function buildServiceSource(config, imageOverride, credentials) {
+    if (!isRegistrySource(config, imageOverride)) {
+        return { type: 'file' };
+    }
+    const { image, tag } = resolveImageRef(config, imageOverride);
+    if (!image) {
+        throw new Error('A registry source requires an image. Set "source.image" in qhub.json or pass --image.');
+    }
+    const source = { type: 'registry', image, tag };
+    if (credentials?.username)
+        source.username = credentials.username;
+    if (credentials?.password)
+        source.password = credentials.password;
+    return source;
+}
+function resolveImageRef(config, imageOverride) {
+    if (imageOverride) {
+        return parseImageRef(imageOverride);
+    }
+    return { image: config.source?.image ?? '', tag: config.source?.tag ?? DEFAULT_TAG };
+}

package/dist/model/managed-service-config.d.ts

@@ -5,6 +5,12 @@ export default interface ManagedServiceConfig {
     resources?: ResourceConfiguration;
     runtime?: Runtime;
     serviceId?: string;
+    source?: ServiceSourceConfig;
+}
+export interface ServiceSourceConfig {
+    type: 'file' | 'registry';
+    image?: string;
+    tag?: string;
 }
 export declare enum Runtime {
     DOCKER = "DOCKER",

package/dist/service/quantum-hub-service.d.ts

@@ -6,7 +6,7 @@ export default class QuantumHubService extends CommandService {
     apiClient: HubPlatformClient;
     constructor(userConfig: UserConfig);
     getAccounts(): Promise<HubPlatform.AccountDto[]>;
-    createService(serviceConfig: ManagedServiceConfig, sourceCode: Blob, apiDefinition?: Blob): Promise<HubPlatform.ServiceDto>;
+    createService(serviceConfig: ManagedServiceConfig, source: HubPlatform.ServiceSource, sourceCode?: Blob): Promise<HubPlatform.ServiceDto>;
     getBuildJob(id: string): Promise<HubPlatform.BuildJobDto>;
     getBuildLogs(id: string): Promise<HubPlatform.LogEntry[]>;
     getJobById(id: string): Promise<HubPlatform.ServiceJobDto>;
@@ -15,6 +15,18 @@ export default class QuantumHubService extends CommandService {
     runJob(request: HubPlatform.CreateServiceJobRequest): Promise<HubPlatform.ServiceJobDto>;
     updateDescription(serviceConfig: ManagedServiceConfig, description: string): Promise<void>;
     updateOpenapi(serviceConfig: ManagedServiceConfig, openapi: Blob): Promise<void>;
+    /**
+     * Updates an existing service's source via the platform's update-source
+     * operation, instead of uploading a code archive. A registry source forces
+     * the DOCKER runtime; switching between file and registry sources goes
+     * through this same operation, so the service is not recreated.
+     *
+     * The platform exposes no endpoint that sets runtime and source together, so
+     * a registry update is two sequential calls and is not atomic. The runtime is
+     * set first, so a failure leaves the (unchanged) source on the DOCKER runtime
+     * rather than a registry source stranded on a non-DOCKER runtime.
+     */
+    updateServiceSource(serviceId: string, source: HubPlatform.ServiceSource): Promise<void>;
     updateService(serviceConfig: ManagedServiceConfig, description: string, sourceCode: Blob, openapi?: Blob): Promise<HubPlatform.ServiceDto>;
     private uploadSourceCode;
 }

package/dist/service/quantum-hub-service.js

@@ -24,16 +24,18 @@ export default class QuantumHubService extends CommandService {
             throw new Error(errorMessage, { cause: error });
         }
     }
-    async createService(serviceConfig, sourceCode, apiDefinition) {
+    async createService(serviceConfig, source, sourceCode) {
         const milliCpus = (serviceConfig.resources?.cpu || 1) * 1000;
         const memoryInMegabytes = (serviceConfig.resources?.memory || 2) * 1024;
         const gpuAccelerator = serviceConfig.resources?.gpu?.type || 'NONE';
         const gpuCount = serviceConfig.resources?.gpu?.count || 0;
+        // A registry source references a pre-built image, so it always runs the DOCKER runtime.
+        const runtime = source.type === 'registry' ? 'DOCKER' : serviceConfig.runtime;
         try {
             const service = await this.apiClient.managedServices.createManagedService({
                 name: serviceConfig.name,
                 runtimeConfiguration: {
-                    runtime: serviceConfig.runtime,
+                    runtime: runtime,
                 },
                 resourceConfigurations: [
                     { type: 'cpu', amount: milliCpus, unit: 'm' },
@@ -44,12 +46,12 @@ export default class QuantumHubService extends CommandService {
                         accelerator: gpuAccelerator
                     },
                 ],
-                source: { type: 'file' },
+                source,
                 summary: serviceConfig.summary,
             });
-            await this.uploadSourceCode(service.id, sourceCode);
-            if (apiDefinition) {
-                await this.apiClient.services.updateServiceOpenApi(service.id, { file: apiDefinition });
+            // A registry source is pre-built — there is no local code to upload.
+            if (sourceCode) {
+                await this.uploadSourceCode(service.id, sourceCode);
             }
             return service;
         }
@@ -133,6 +135,29 @@ export default class QuantumHubService extends CommandService {
             throw new Error(errorMessage, { cause: error });
         }
     }
+    /**
+     * Updates an existing service's source via the platform's update-source
+     * operation, instead of uploading a code archive. A registry source forces
+     * the DOCKER runtime; switching between file and registry sources goes
+     * through this same operation, so the service is not recreated.
+     *
+     * The platform exposes no endpoint that sets runtime and source together, so
+     * a registry update is two sequential calls and is not atomic. The runtime is
+     * set first, so a failure leaves the (unchanged) source on the DOCKER runtime
+     * rather than a registry source stranded on a non-DOCKER runtime.
+     */
+    async updateServiceSource(serviceId, source) {
+        try {
+            if (source.type === 'registry') {
+                await this.apiClient.managedServices.updateManagedServiceRuntimeConfiguration(serviceId, { runtime: 'DOCKER' });
+            }
+            await this.apiClient.managedServices.updateManagedServiceSource(serviceId, source);
+        }
+        catch (error) {
+            const errorMessage = await handleError(error);
+            throw new Error(errorMessage, { cause: error });
+        }
+    }
     async updateService(serviceConfig, description, sourceCode, openapi) {
         const serviceId = serviceConfig.serviceId;
         const milliCpus = (serviceConfig.resources?.cpu || 1) * 1000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quantum-hub/qhubctl",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Kipu Quantum Hub CLI",
   "author": "Kipu Quantum GmbH",
   "contributors": [