@quantum-hub/qhubctl 1.19.2 → 2.1.0

package/dist/commands/compress.js

@@ -2,18 +2,36 @@ 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';
+import { enforceRequiredFiles } from '../lib/up/required-files.js';
+import { error, spinner, stdout } from '../lib/output.js';
 const EXAMPLES = `
 Examples:
-  $ qhubctl compress`;
+  $ qhubctl compress
+
+The '.qhubignore' file uses gitignore syntax. To ship only 'src' and the
+Dockerfile, re-include the directory AND its contents:
+
+  *
+  !src
+  !src/**
+  !Dockerfile
+
+These paths are always excluded: .git, node_modules, .venv, __pycache__, service.zip`;
 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.")
+    .description("Compresses the current project and creates a ZIP file. Use a '.qhubignore' file (gitignore syntax) 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);
+    try {
+        await enforceRequiredFiles(targetDirectory);
+    }
+    catch (err) {
+        spin.fail('Compression aborted');
+        error(err.message);
+    }
     if (fs.existsSync(targetFilePath)) {
         fs.unlinkSync(targetFilePath);
     }

package/dist/commands/openapi.js

@@ -68,7 +68,7 @@ function isProjectSupported(opts) {
         return false;
     }
     const hasExplicitEntrypoint = !!(opts.entrypoint || opts.package || opts.method);
-    const supportedRuntimes = [Runtime.PYTHON_TEMPLATE, Runtime.PYTHON, Runtime.DOCKER];
+    const supportedRuntimes = [Runtime.PYTHON_TEMPLATE, Runtime.DOCKER];
     if (hasExplicitEntrypoint) {
         const isSupported = supportedRuntimes.includes(serviceConfig.runtime);
         if (!isSupported) {
@@ -76,7 +76,7 @@ function isProjectSupported(opts) {
             warn('');
             warn('Supported configurations:');
             warn('  \u2022 PYTHON_TEMPLATE: Automatic (requires src/program.py)');
-            warn('  \u2022 PYTHON/DOCKER: With explicit entrypoint flags');
+            warn('  \u2022 DOCKER: With explicit entrypoint flags');
             warn('');
             warn('Examples:');
             warn('  qhubctl openapi --entrypoint=myapp.main:handler');
@@ -176,7 +176,7 @@ Examples:
 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). ' +
+    'Supports PYTHON_TEMPLATE (with src/program.py) and DOCKER runtime (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')
@@ -204,7 +204,7 @@ export const openapiCommand = new Command('openapi')
     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))');
+            '  \u2022 DOCKER or PYTHON_TEMPLATE runtimes with explicit entrypoint (--entrypoint, or (--package, --method))');
         return;
     }
     // Ensure qhub-commons is installed (or upgraded) in the project venv

package/dist/commands/up.js

@@ -1,17 +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 { enforceRequiredFiles } from '../lib/up/required-files.js';
+import { buildServiceSource, isRegistrySource, resolveRegistryCredentials } from '../lib/up/source.js';
 import { zipProjectFolder } from '../lib/up/zip.js';
-import { handleError } from '../lib/error.js';
-import { error, spinner, stdout, warn } from '../lib/output.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');
@@ -24,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;
@@ -65,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');
     }
@@ -113,40 +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);
     }
-    const serviceFiles = {
-        openapi: await getOpenapi(),
-        descriptionText: await getDescriptionText(process.cwd()),
-        sourceCode: await zipProjectFolder('./'),
-    };
-    let service;
+    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);
+        }
+    }
+    // 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;
@@ -159,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/ignore.js

@@ -3,13 +3,15 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { promisify } from 'node:util';
 const readFile = promisify(fs.readFile);
+// Always excluded from the upload archive. Added before user patterns so a
+// user can re-include any of them with a negation (e.g. `!node_modules`).
+const DEFAULT_IGNORES = ['.git', 'node_modules', '.venv', '__pycache__', 'service.zip'];
 export async function createIgnoreFileChecker(filePath = process.cwd()) {
-    const ignoreFilePath = path.join(filePath, '.dockerignore');
-    if (!fs.existsSync(ignoreFilePath)) {
-        return () => false;
+    const ig = ignore().add(DEFAULT_IGNORES);
+    const ignoreFilePath = path.join(filePath, '.qhubignore');
+    if (fs.existsSync(ignoreFilePath)) {
+        const ignoreFileContents = await readFile(ignoreFilePath, 'utf8');
+        ig.add(ignoreFileContents.split('\n'));
     }
-    const ignoreFileContents = await readFile(ignoreFilePath, 'utf8');
-    const ig = ignore().add(ignoreFileContents.split('\n'));
-    ig.add('service.zip');
     return (fullPath) => ig.ignores(fullPath);
 }

package/dist/lib/up/required-files.d.ts

@@ -0,0 +1,8 @@
+export interface RequiredFilesResult {
+    skipped: boolean;
+    runtimeMissing: boolean;
+    missing: string[];
+    excluded: string[];
+}
+export declare function evaluateRequiredFiles(workingDirectory: string): Promise<RequiredFilesResult>;
+export declare function enforceRequiredFiles(workingDirectory: string): Promise<void>;

package/dist/lib/up/required-files.js

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Runtime } from '../../model/managed-service-config.js';
+import { readServiceConfig } from '../../service/service-config-service.js';
+import { createIgnoreFileChecker } from './ignore.js';
+import { warn } from '../output.js';
+const REQUIRED_FILES = {
+    [Runtime.DOCKER]: ['Dockerfile'],
+    [Runtime.PYTHON_TEMPLATE]: ['requirements.txt', 'src/program.py'],
+};
+export async function evaluateRequiredFiles(workingDirectory) {
+    const result = { skipped: false, runtimeMissing: false, missing: [], excluded: [] };
+    if (!fs.existsSync(path.join(workingDirectory, 'qhub.json'))) {
+        result.skipped = true;
+        return result;
+    }
+    const { runtime } = readServiceConfig(workingDirectory);
+    if (!runtime) {
+        result.runtimeMissing = true;
+        return result;
+    }
+    const required = REQUIRED_FILES[runtime] ?? [];
+    const isIgnored = await createIgnoreFileChecker(workingDirectory);
+    for (const file of required) {
+        const onDisk = fs.existsSync(path.join(workingDirectory, file));
+        if (onDisk && isIgnored(file)) {
+            result.excluded.push(file);
+        }
+        else if (!onDisk) {
+            result.missing.push(file);
+        }
+    }
+    return result;
+}
+export async function enforceRequiredFiles(workingDirectory) {
+    const { runtimeMissing, missing, excluded } = await evaluateRequiredFiles(workingDirectory);
+    if (runtimeMissing) {
+        warn('No "runtime" set in qhub.json; skipping required-file validation.');
+        return;
+    }
+    if (missing.length > 0) {
+        warn(`Required file(s) missing for the configured runtime: ${missing.join(', ')}`);
+    }
+    if (excluded.length > 0) {
+        throw new Error(`Required file(s) are present but excluded by .qhubignore: ${excluded.join(', ')}. ` +
+            `Re-include them with a negation (e.g. "!Dockerfile").`);
+    }
+}

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,10 +5,15 @@ 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",
-    PYTHON = "PYTHON",
     PYTHON_TEMPLATE = "PYTHON_TEMPLATE"
 }
 export interface ResourceConfiguration {

package/dist/model/managed-service-config.js

@@ -1,7 +1,6 @@
 export var Runtime;
 (function (Runtime) {
     Runtime["DOCKER"] = "DOCKER";
-    Runtime["PYTHON"] = "PYTHON";
     Runtime["PYTHON_TEMPLATE"] = "PYTHON_TEMPLATE";
 })(Runtime || (Runtime = {}));
 export var GpuType;

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": "1.19.2",
+  "version": "2.1.0",
   "description": "Kipu Quantum Hub CLI",
   "author": "Kipu Quantum GmbH",
   "contributors": [