@git.zone/tsdeploy 0.2.0 → 0.3.0

package/ts/classes.tsdeploy.ts

@@ -1,5 +1,10 @@
 import * as plugins from './plugins.js';
 import type {
+  ITsDeployCommandRunOptions,
+  ITsDeployCommandRunResult,
+  ITsDeployDeployOptions,
+  ITsDeployDeployResult,
+  ITsDeployDeploymentSummary,
   ITsDeployDoctorResult,
   ITsDeployLinkOptions,
   ITsDeployPlan,
@@ -12,14 +17,37 @@ import type {
   TTsDeployTarget,
 } from './types.js';
 
+type TTypedRequestShape = {
+  method: string;
+  request: unknown;
+  response: unknown;
+};
+
+type TCloudlyRequest = <TRequest extends TTypedRequestShape>(
+  originArg: string,
+  methodArg: TRequest['method'],
+  requestArg: TRequest['request'],
+) => Promise<TRequest['response']>;
+
+type TCommandRunner = (optionsArg: ITsDeployCommandRunOptions) => Promise<ITsDeployCommandRunResult>;
+
 export interface ITsDeployOptions {
   projectDir?: string;
   profileStorePath?: string;
   ephemeralProfileStore?: boolean;
+  env?: Record<string, string | undefined>;
+  commandRunner?: TCommandRunner;
+  cloudlyRequest?: TCloudlyRequest;
 }
 
 const schemaVersion = 1 as const;
 const profileNameRegex = /^[a-zA-Z0-9._-]+$/;
+const defaultPlatform = 'linux/amd64';
+const defaultCloudlyRequestTimeoutMs = 30000;
+const defaultCommandTimeoutMs = 30 * 60 * 1000;
+const dockerCommandTimeoutMs = 60 * 60 * 1000;
+const defaultMaxCommandOutputBytes = 1024 * 1024;
+const defaultVerifyUrlTimeoutMs = 15000;
 
 const normalizeProfileName = (profileArg: string): string => {
   const profile = profileArg.trim();
@@ -53,10 +81,16 @@ export const redactProfile = (profileArg: ITsDeployProfile): ITsDeployPublicProf
 export class TsDeploy {
   public readonly projectDir: string;
   private readonly profileStore: plugins.smartconfig.KeyValueStore<ITsDeployUserState>;
+  private readonly env: Record<string, string | undefined>;
+  private readonly commandRunner: TCommandRunner;
+  private readonly cloudlyRequest: TCloudlyRequest;
 
   constructor(optionsArg: ITsDeployOptions = {}) {
     this.projectDir = plugins.path.resolve(optionsArg.projectDir ?? process.cwd());
     this.profileStore = this.createProfileStore(optionsArg);
+    this.env = optionsArg.env ?? process.env;
+    this.commandRunner = optionsArg.commandRunner ?? this.defaultCommandRunner;
+    this.cloudlyRequest = optionsArg.cloudlyRequest ?? this.defaultCloudlyRequest;
   }
 
   public get projectLinkPath(): string {
@@ -178,7 +212,7 @@ export class TsDeploy {
       warnings.push(`Profile "${activeProfile}" is not configured. Run tsdeploy login --profile ${activeProfile}.`);
     }
     if (profile && !profile.token) {
-      warnings.push(`Profile "${profile.name}" has no token. Remote deploy mutations remain unavailable.`);
+      warnings.push(`Profile "${profile.name}" has no token. Cloudly deploy requires a token or username/password at deploy time.`);
     }
     return {
       projectDir: this.projectDir,
@@ -193,11 +227,19 @@ export class TsDeploy {
   public async buildPlan(): Promise<ITsDeployPlan> {
     const status = await this.getStatus();
     const actions: ITsDeployPlan['actions'] = [];
+    const canDeployCloudly = Boolean(status.projectLink?.serviceId && status.profile?.target === 'cloudly');
     if (status.projectLink && status.profile) {
       actions.push({
         type: 'inspect',
         title: 'Inspect linked deployment',
-        description: 'Resolve the linked Cloudly/Onebox deployment and compare desired app metadata once typed deployment APIs are verified.',
+        description: 'Resolve the linked Cloudly service and registry target before deploying.',
+      });
+      actions.push({
+        type: canDeployCloudly ? 'deploy' : 'noop',
+        title: canDeployCloudly ? 'Deploy Cloudly workload image' : 'Deployment link incomplete or unsupported',
+        description: canDeployCloudly
+          ? 'Run project checks, build and push the linked OCI image, and let Cloudly deployOnPush reconcile the service.'
+          : 'Cloudly workload deploy requires a serviceId; Onebox deployment mutations are not implemented yet.',
       });
     } else {
       actions.push({
@@ -206,16 +248,13 @@ export class TsDeploy {
         description: 'Create a profile and project link before a deployment plan can inspect remote state.',
       });
     }
-    actions.push({
-      type: 'noop',
-      title: 'Deployment mutation disabled',
-      description: 'tsdeploy MVP does not install, update, or upgrade apps until Cloudly/Onebox deployment contracts are verified upstream.',
-    });
     return {
       schemaVersion,
       projectDir: this.projectDir,
-      mutationAllowed: false,
-      summary: 'Safe planning only: no remote deployment mutations will be executed.',
+      mutationAllowed: canDeployCloudly,
+      summary: canDeployCloudly
+        ? 'Cloudly workload deploy is available through registry push and deployOnPush reconciliation.'
+        : 'Safe planning only: no remote deployment mutations will be executed.',
       profile: status.activeProfile,
       deploymentId: status.projectLink?.deploymentId,
       serviceId: status.projectLink?.serviceId,
@@ -240,7 +279,9 @@ export class TsDeploy {
       {
         name: 'remote-mutations',
         ok: true,
-        message: 'Remote deployment mutations are intentionally disabled in this MVP.',
+        message: status.profile?.target === 'cloudly'
+          ? 'Cloudly workload deployment is available with deploy-time Cloudly credentials.'
+          : 'Only Cloudly workload deployment is implemented currently.',
       },
     ];
     return {
@@ -249,4 +290,547 @@ export class TsDeploy {
       warnings: status.warnings,
     };
   }
+
+  public async deploy(optionsArg: ITsDeployDeployOptions = {}): Promise<ITsDeployDeployResult> {
+    const status = await this.getStatus();
+    const projectLink = status.projectLink;
+    const profile = await this.getProfile(projectLink?.profile ?? status.activeProfile);
+    const steps: ITsDeployDeployResult['steps'] = [];
+    const warnings: string[] = [];
+    const tag = optionsArg.tag || 'latest';
+    const platform = optionsArg.platform || defaultPlatform;
+    const waitSeconds = optionsArg.waitSeconds ?? 0;
+
+    if (!projectLink) {
+      throw new Error('No .nogit/tsdeploy.json project link found. Run tsdeploy link first.');
+    }
+    if (!projectLink.serviceId) {
+      throw new Error('Project link has no serviceId. Run tsdeploy link --serviceId <id>.');
+    }
+    if (!profile) {
+      throw new Error(`Profile "${projectLink.profile}" is not configured. Run tsdeploy login --profile ${projectLink.profile}.`);
+    }
+    if (profile.target !== 'cloudly') {
+      throw new Error(`Deploy target "${profile.target}" is not implemented. Only Cloudly workload deployment is supported.`);
+    }
+    const deploySecretValues = this.collectSecretValues(undefined, [
+      profile.token,
+      optionsArg.token,
+      optionsArg.password,
+      this.env.TSDEPLOY_TOKEN,
+      this.env.TSDEPLOY_CLOUDLY_PASSWORD,
+      this.env.CLOUDLY_PASSWORD,
+    ]);
+
+    const localConfig = await this.readProjectSmartconfig();
+    const localImage = this.resolveLocalDockerImage(localConfig, tag);
+    let image = optionsArg.image || localImage;
+
+    if (optionsArg.dryRun) {
+      if (!image) {
+        image = '<resolved-from-cloudly-service-registry-target>';
+        warnings.push('Dry run did not contact Cloudly, so the final image URL was not resolved.');
+      }
+      steps.push({ name: 'cloudly-preflight', status: 'skipped', message: 'Dry run skipped Cloudly service validation.' });
+      steps.push({ name: 'checks', status: 'skipped', message: 'Dry run skipped project checks.' });
+      steps.push({ name: 'docker-buildx-push', status: 'skipped', message: `Dry run would push ${image}.` });
+      return {
+        schemaVersion,
+        projectDir: this.projectDir,
+        profile: profile.name,
+        serviceId: projectLink.serviceId,
+        deploymentId: projectLink.deploymentId,
+        dryRun: true,
+        image,
+        tag,
+        platform,
+        pushed: false,
+        triggered: false,
+        verified: false,
+        deployments: [],
+        steps,
+        warnings,
+      };
+    }
+
+    const identity = await this.resolveCloudlyIdentity(profile, optionsArg);
+    steps.push({ name: 'cloudly-auth', status: 'passed', message: 'Cloudly identity resolved.' });
+
+    const service = await this.fireCloudlyRequest<plugins.servezoneInterfaces.requests.service.IRequest_Any_Cloudly_GetServiceById>(
+      profile.origin,
+      'getServiceById',
+      { identity, serviceId: projectLink.serviceId },
+    ).then(response => response.service);
+    if (service.data.deployOnPush === false) {
+      throw new Error(`Service "${service.data.name}" has deployOnPush disabled; refusing to push an image that Cloudly will not deploy.`);
+    }
+    const registryTarget = await this.fireCloudlyRequest<plugins.servezoneInterfaces.requests.service.IRequest_Any_Cloudly_GetServiceRegistryTarget>(
+      profile.origin,
+      'getServiceRegistryTarget',
+      { identity, serviceId: projectLink.serviceId, tag },
+    ).then(response => response.registryTarget);
+    if (!registryTarget.imageUrl) {
+      throw new Error('Cloudly did not return a registry target image URL for the linked service.');
+    }
+    if (optionsArg.image && optionsArg.image !== registryTarget.imageUrl) {
+      throw new Error(`Requested image "${optionsArg.image}" does not match Cloudly registry target "${registryTarget.imageUrl}".`);
+    }
+    image = registryTarget.imageUrl;
+    if (localImage && localImage !== image) {
+      warnings.push(`Local .smartconfig Docker image "${localImage}" differs from Cloudly registry target "${image}". Using Cloudly target.`);
+    }
+    steps.push({ name: 'cloudly-preflight', status: 'passed', message: `Validated service "${service.data.name}" and registry target.` });
+
+    if (optionsArg.skipChecks) {
+      steps.push({ name: 'checks', status: 'skipped', message: 'Project checks skipped by option.' });
+    } else {
+      const checkCommand = await this.resolveProjectCheckCommand();
+      if (checkCommand) {
+        await this.runCheckedCommand({
+          command: checkCommand.command,
+          args: checkCommand.args,
+          cwd: this.projectDir,
+          env: this.env,
+          timeoutMs: defaultCommandTimeoutMs,
+          maxOutputBytes: defaultMaxCommandOutputBytes,
+        }, 'checks', steps, deploySecretValues);
+      } else {
+        steps.push({ name: 'checks', status: 'skipped', message: 'No test or build script found in package.json.' });
+      }
+    }
+
+    let digest: string | undefined;
+    if (optionsArg.skipPush) {
+      steps.push({ name: 'docker-buildx-push', status: 'skipped', message: 'Docker push skipped by option.' });
+    } else {
+      const buildEnv = await this.resolveDockerBuildEnv(localConfig);
+      const buildArgs = Object.keys(buildEnv.buildArgValues);
+      const dockerArgs = [
+        'buildx',
+        'build',
+        ...(optionsArg.builder ? ['--builder', optionsArg.builder] : []),
+        '--platform',
+        platform,
+        '--provenance=false',
+        '--sbom=false',
+        ...buildArgs.flatMap(buildArg => ['--build-arg', buildArg]),
+        '-t',
+        image,
+        '--push',
+        '.',
+      ];
+      const commandResult = await this.runCheckedCommand({
+        command: 'docker',
+        args: dockerArgs,
+        cwd: this.projectDir,
+        env: {
+          ...this.env,
+          ...buildEnv.buildArgValues,
+        },
+        timeoutMs: dockerCommandTimeoutMs,
+        maxOutputBytes: defaultMaxCommandOutputBytes,
+      }, 'docker-buildx-push', steps, [...deploySecretValues, ...buildEnv.secretValues]);
+      digest = this.extractDigest(`${commandResult.stdout}\n${commandResult.stderr}`);
+    }
+
+    let deployments = await this.getCloudlyDeployments(profile.origin, identity, projectLink.serviceId);
+    if (waitSeconds > 0) {
+      deployments = await this.waitForHealthyDeployment(profile.origin, identity, projectLink.serviceId, waitSeconds);
+    }
+
+    let verifyStatus: number | undefined;
+    if (optionsArg.verifyUrl) {
+      verifyStatus = await this.verifyUrl(optionsArg.verifyUrl);
+      steps.push({
+        name: 'verify-url',
+        status: verifyStatus >= 200 && verifyStatus < 400 ? 'passed' : 'failed',
+        message: `${optionsArg.verifyUrl} returned HTTP ${verifyStatus}.`,
+      });
+      if (verifyStatus < 200 || verifyStatus >= 400) {
+        throw new Error(`Verification URL returned HTTP ${verifyStatus}: ${optionsArg.verifyUrl}`);
+      }
+    }
+
+    return {
+      schemaVersion,
+      projectDir: this.projectDir,
+      profile: profile.name,
+      serviceId: projectLink.serviceId,
+      deploymentId: projectLink.deploymentId,
+      dryRun: false,
+      image,
+      tag,
+      platform,
+      pushed: !optionsArg.skipPush,
+      triggered: !optionsArg.skipPush,
+      verified: Boolean(optionsArg.verifyUrl && verifyStatus && verifyStatus >= 200 && verifyStatus < 400),
+      digest,
+      verifyStatus,
+      service: {
+        serviceId: service.id,
+        serviceName: service.data.name,
+        deployOnPush: true,
+        registryTarget: {
+          registryHost: registryTarget.registryHost,
+          repository: registryTarget.repository,
+          tag: registryTarget.tag,
+          imageUrl: registryTarget.imageUrl,
+        },
+      },
+      deployments,
+      steps,
+      warnings,
+    };
+  }
+
+  private defaultCommandRunner: TCommandRunner = async (optionsArg) => {
+    return await new Promise<ITsDeployCommandRunResult>((resolve, reject) => {
+      const timeoutMs = optionsArg.timeoutMs ?? defaultCommandTimeoutMs;
+      const maxOutputBytes = optionsArg.maxOutputBytes ?? defaultMaxCommandOutputBytes;
+      const child = plugins.childProcess.spawn(optionsArg.command, optionsArg.args, {
+        cwd: optionsArg.cwd,
+        env: {
+          ...process.env,
+          ...optionsArg.env,
+        },
+        detached: process.platform !== 'win32',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      const stdoutChunks: Buffer[] = [];
+      const stderrChunks: Buffer[] = [];
+      let stdoutBytes = 0;
+      let stderrBytes = 0;
+      let stdoutTruncated = false;
+      let stderrTruncated = false;
+      let timedOut = false;
+      let timeoutRef: NodeJS.Timeout | undefined;
+      let killTimeoutRef: NodeJS.Timeout | undefined;
+      const appendOutput = (chunksArg: Buffer[], chunkArg: Buffer, bytesArg: number): { bytes: number; truncated: boolean } => {
+        const bytes = bytesArg + chunkArg.length;
+        const remainingBytes = maxOutputBytes - bytesArg;
+        if (remainingBytes > 0) {
+          chunksArg.push(chunkArg.subarray(0, remainingBytes));
+        }
+        return { bytes, truncated: bytes > maxOutputBytes };
+      };
+      child.stdout?.on('data', chunkArg => {
+        const result = appendOutput(stdoutChunks, Buffer.from(chunkArg), stdoutBytes);
+        stdoutBytes = result.bytes;
+        stdoutTruncated ||= result.truncated;
+      });
+      child.stderr?.on('data', chunkArg => {
+        const result = appendOutput(stderrChunks, Buffer.from(chunkArg), stderrBytes);
+        stderrBytes = result.bytes;
+        stderrTruncated ||= result.truncated;
+      });
+      const clearTimers = (clearKillTimerArg = true) => {
+        if (timeoutRef) clearTimeout(timeoutRef);
+        if (clearKillTimerArg && killTimeoutRef) clearTimeout(killTimeoutRef);
+      };
+      const killProcess = (signalArg: NodeJS.Signals) => {
+        if (process.platform !== 'win32' && child.pid) {
+          try {
+            process.kill(-child.pid, signalArg);
+            return;
+          } catch {
+            // Fall back to direct child termination below.
+          }
+        }
+        child.kill(signalArg);
+      };
+      timeoutRef = setTimeout(() => {
+        timedOut = true;
+        killProcess('SIGTERM');
+        killTimeoutRef = setTimeout(() => {
+          killProcess('SIGKILL');
+        }, 10000);
+        killTimeoutRef.unref?.();
+      }, timeoutMs);
+      timeoutRef.unref?.();
+      child.on('error', errorArg => {
+        clearTimers(!timedOut);
+        reject(errorArg);
+      });
+      child.on('close', exitCode => {
+        clearTimers(!timedOut);
+        if (stdoutTruncated) {
+          stdoutChunks.push(Buffer.from('\n[tsdeploy: stdout truncated]\n'));
+        }
+        if (stderrTruncated) {
+          stderrChunks.push(Buffer.from('\n[tsdeploy: stderr truncated]\n'));
+        }
+        if (timedOut) {
+          stderrChunks.push(Buffer.from(`\n[tsdeploy: command timed out after ${timeoutMs}ms]\n`));
+        }
+        resolve({
+          command: optionsArg.command,
+          args: optionsArg.args,
+          exitCode: timedOut ? 124 : exitCode ?? 1,
+          stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+          stderr: Buffer.concat(stderrChunks).toString('utf8'),
+        });
+      });
+    });
+  };
+
+  private defaultCloudlyRequest: TCloudlyRequest = async <TRequest extends TTypedRequestShape>(originArg: string, methodArg: TRequest['method'], requestArg: TRequest['request']): Promise<TRequest['response']> => {
+    const controller = new AbortController();
+    const timeoutRef = setTimeout(() => controller.abort(), defaultCloudlyRequestTimeoutMs);
+    timeoutRef.unref?.();
+    try {
+      const response = await fetch(`${originArg.replace(/\/+$/, '')}/typedrequest`, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify({
+          method: methodArg,
+          request: requestArg,
+          response: {},
+          correlation: {
+            id: plugins.crypto.randomUUID(),
+            phase: 'request',
+          },
+        }),
+        signal: controller.signal,
+      });
+      if (!response.ok) {
+        await response.body?.cancel().catch(() => undefined);
+        throw new Error(`Cloudly request "${methodArg}" failed with HTTP ${response.status}.`);
+      }
+      const payload = await response.json() as {
+        response: TRequest['response'];
+        error?: { text: string; data?: unknown };
+        retry?: { waitForMs: number; reason: string };
+      };
+      if (payload.error) {
+        throw new plugins.typedrequest.TypedResponseError(payload.error.text, payload.error.data);
+      }
+      if (payload.retry) {
+        throw new Error(`Cloudly request "${methodArg}" requested retry after ${payload.retry.waitForMs}ms: ${payload.retry.reason}`);
+      }
+      return payload.response;
+    } catch (error) {
+      if ((error as { name?: string }).name === 'AbortError') {
+        throw new Error(`Cloudly request "${methodArg}" timed out after ${defaultCloudlyRequestTimeoutMs}ms.`);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutRef);
+    }
+  };
+
+  private async fireCloudlyRequest<TRequest extends TTypedRequestShape>(
+    originArg: string,
+    methodArg: TRequest['method'],
+    requestArg: TRequest['request'],
+  ): Promise<TRequest['response']> {
+    return await this.cloudlyRequest<TRequest>(originArg, methodArg, requestArg);
+  }
+
+  private async resolveCloudlyIdentity(
+    profileArg: ITsDeployProfile,
+    optionsArg: ITsDeployDeployOptions,
+  ): Promise<plugins.servezoneInterfaces.data.IIdentity> {
+    const username = optionsArg.username || this.env.TSDEPLOY_CLOUDLY_USERNAME || this.env.CLOUDLY_USERNAME;
+    const password = optionsArg.password || this.env.TSDEPLOY_CLOUDLY_PASSWORD || this.env.CLOUDLY_PASSWORD;
+    if (username && password) {
+      const response = await this.fireCloudlyRequest<plugins.servezoneInterfaces.requests.admin.IReq_Admin_LoginWithUsernameAndPassword>(
+        profileArg.origin,
+        'adminLoginWithUsernameAndPassword',
+        { username, password },
+      );
+      return response.identity;
+    }
+    const token = optionsArg.token || this.env.TSDEPLOY_TOKEN || profileArg.token;
+    if (token) {
+      const response = await this.fireCloudlyRequest<plugins.servezoneInterfaces.requests.identity.IRequest_Any_Cloudly_CoreflowManager_GetIdentityByToken>(
+        profileArg.origin,
+        'getIdentityByToken',
+        { token },
+      );
+      return response.identity;
+    }
+    throw new Error('Cloudly credentials are required for deploy. Provide --token, TSDEPLOY_TOKEN, profile token, or TSDEPLOY_CLOUDLY_USERNAME/TSDEPLOY_CLOUDLY_PASSWORD.');
+  }
+
+  private async readProjectSmartconfig(): Promise<Record<string, any>> {
+    try {
+      const raw = await plugins.fs.readFile(plugins.path.join(this.projectDir, '.smartconfig.json'), 'utf8');
+      return JSON.parse(raw) as Record<string, any>;
+    } catch (error) {
+      if ((error as { code?: string }).code === 'ENOENT') return {};
+      throw error;
+    }
+  }
+
+  private async readProjectPackageJson(): Promise<Record<string, any>> {
+    try {
+      const raw = await plugins.fs.readFile(plugins.path.join(this.projectDir, 'package.json'), 'utf8');
+      return JSON.parse(raw) as Record<string, any>;
+    } catch (error) {
+      if ((error as { code?: string }).code === 'ENOENT') return {};
+      throw error;
+    }
+  }
+
+  private resolveLocalDockerImage(configArg: Record<string, any>, tagArg: string): string | undefined {
+    const dockerConfig = configArg['@git.zone/tsdocker'];
+    const registries = Array.isArray(dockerConfig?.registries) ? dockerConfig.registries : [];
+    const registryRepoMap = dockerConfig?.registryRepoMap ?? {};
+    const registryHost = registries[0] ?? Object.keys(registryRepoMap)[0];
+    const repository = registryHost ? registryRepoMap[registryHost] : undefined;
+    if (!registryHost || !repository) return undefined;
+    return `${registryHost}/${repository}:${tagArg}`;
+  }
+
+  private async resolveProjectCheckCommand(): Promise<{ command: string; args: string[] } | undefined> {
+    const packageJson = await this.readProjectPackageJson();
+    if (packageJson.scripts?.test) {
+      return { command: 'pnpm', args: ['test'] };
+    }
+    if (packageJson.scripts?.build) {
+      return { command: 'pnpm', args: ['run', 'build'] };
+    }
+    return undefined;
+  }
+
+  private async resolveDockerBuildEnv(configArg: Record<string, any>): Promise<{
+    buildArgValues: Record<string, string>;
+    secretValues: string[];
+  }> {
+    const dockerConfig = configArg['@git.zone/tsdocker'] ?? {};
+    const szciConfig = configArg['@ship.zone/szci'] ?? {};
+    const buildArgEnvMap = {
+      ...(dockerConfig.buildArgEnvMap ?? {}),
+      ...(szciConfig.dockerBuildargEnvMap ?? {}),
+    } as Record<string, string>;
+    const buildArgValues: Record<string, string> = {};
+    const secretValues: string[] = [];
+    for (const [buildArg, envName] of Object.entries(buildArgEnvMap)) {
+      const value = this.env[envName];
+      if (!value) {
+        throw new Error(`Missing required Docker build arg environment value: ${envName}`);
+      }
+      buildArgValues[buildArg] = value;
+      secretValues.push(value);
+    }
+    return { buildArgValues, secretValues };
+  }
+
+  private async runCheckedCommand(
+    commandArg: ITsDeployCommandRunOptions,
+    stepNameArg: string,
+    stepsArg: ITsDeployDeployResult['steps'],
+    secretValuesArg: string[],
+  ): Promise<ITsDeployCommandRunResult> {
+    const result = await this.commandRunner(commandArg);
+    if (result.exitCode !== 0) {
+      stepsArg.push({ name: stepNameArg, status: 'failed', message: `${commandArg.command} exited with code ${result.exitCode}.` });
+      const output = this.redactText(`${result.stdout}\n${result.stderr}`, this.collectSecretValues(commandArg.env, secretValuesArg));
+      throw new Error(`${commandArg.command} failed with exit code ${result.exitCode}:\n${output}`.trim());
+    }
+    stepsArg.push({ name: stepNameArg, status: 'passed', message: `${commandArg.command} completed successfully.` });
+    return result;
+  }
+
+  private collectSecretValues(
+    envArg?: Record<string, string | undefined>,
+    additionalValuesArg: Array<string | undefined> = [],
+  ): string[] {
+    const values = new Set<string>();
+    const addValue = (valueArg?: string) => {
+      if (valueArg && valueArg.length >= 4) values.add(valueArg);
+    };
+    for (const value of additionalValuesArg) addValue(value);
+    if (envArg) {
+      for (const [key, value] of Object.entries(envArg)) {
+        if (/(token|password|secret|credential|private|auth|key)/i.test(key)) {
+          addValue(value);
+        }
+      }
+    }
+    return [...values];
+  }
+
+  private redactText(textArg: string, secretValuesArg: string[]): string {
+    let result = textArg;
+    for (const secret of secretValuesArg.filter(Boolean)) {
+      result = result.split(secret).join('[redacted]');
+    }
+    return result;
+  }
+
+  private extractDigest(outputArg: string): string | undefined {
+    const preferredPatterns = [
+      /pushing manifest for .+@(sha256:[a-f0-9]{64})/gi,
+      /exporting manifest list (sha256:[a-f0-9]{64})/gi,
+      /exporting manifest (sha256:[a-f0-9]{64})/gi,
+    ];
+    for (const pattern of preferredPatterns) {
+      const matches = [...outputArg.matchAll(pattern)];
+      const digest = matches.at(-1)?.[1];
+      if (digest) return digest;
+    }
+    return [...outputArg.matchAll(/sha256:[a-f0-9]{64}/gi)].at(-1)?.[0];
+  }
+
+  private async getCloudlyDeployments(
+    originArg: string,
+    identityArg: plugins.servezoneInterfaces.data.IIdentity,
+    serviceIdArg: string,
+  ): Promise<ITsDeployDeploymentSummary[]> {
+    const response = await this.fireCloudlyRequest<plugins.servezoneInterfaces.requests.deployment.IReq_Any_Cloudly_GetDeploymentsByService>(
+      originArg,
+      'getDeploymentsByService',
+      { identity: identityArg, serviceId: serviceIdArg },
+    );
+    return response.deployments.map(deployment => ({
+      deploymentId: deployment.id,
+      serviceId: deployment.serviceId,
+      serviceName: deployment.serviceName,
+      status: deployment.status,
+      healthStatus: deployment.healthStatus,
+      nodeName: deployment.nodeName,
+      version: deployment.version,
+      containerId: deployment.containerId,
+      deployedAt: deployment.deployedAt,
+      updatedAt: deployment.updatedAt,
+    }));
+  }
+
+  private async waitForHealthyDeployment(
+    originArg: string,
+    identityArg: plugins.servezoneInterfaces.data.IIdentity,
+    serviceIdArg: string,
+    waitSecondsArg: number,
+  ): Promise<ITsDeployDeploymentSummary[]> {
+    const deadline = Date.now() + waitSecondsArg * 1000;
+    let deployments: ITsDeployDeploymentSummary[] = [];
+    while (Date.now() <= deadline) {
+      deployments = await this.getCloudlyDeployments(originArg, identityArg, serviceIdArg);
+      if (deployments.some(deployment => deployment.status === 'running' && deployment.healthStatus === 'healthy')) {
+        return deployments;
+      }
+      await new Promise(resolve => setTimeout(resolve, 5000));
+    }
+    throw new Error(`No healthy running deployment observed for service ${serviceIdArg} within ${waitSecondsArg}s.`);
+  }
+
+  private async verifyUrl(urlArg: string): Promise<number> {
+    const controller = new AbortController();
+    const timeoutRef = setTimeout(() => controller.abort(), defaultVerifyUrlTimeoutMs);
+    timeoutRef.unref?.();
+    try {
+      const response = await fetch(urlArg, { method: 'HEAD', signal: controller.signal });
+      return response.status;
+    } catch (error) {
+      if ((error as { name?: string }).name === 'AbortError') {
+        throw new Error(`Verification URL timed out after ${defaultVerifyUrlTimeoutMs}ms: ${urlArg}`);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutRef);
+    }
+  }
 }