k6ctl 1.2.0 → 1.3.0

package/src/commands/delete.ts

@@ -4,7 +4,7 @@ import logger from '../utils/logger';
 
 interface DeleteOptions {
   namespace?: string;
-  keepConfigmap?: boolean;
+  keepScript?: boolean;
   pod?: string;
   testrun?: string;
   configmap?: string;
@@ -13,7 +13,7 @@ interface DeleteOptions {
 export async function deleteLastRun(options: DeleteOptions) {
   const kubernetesService = createDefaultKubernetesService();
 
-  const lastRun = !options.namespace ? await loadLastRun() : null;
+  const lastRun = await loadLastRun();
   const namespace = options.namespace ?? lastRun?.namespace ?? 'default';
 
   if (options.pod) {
@@ -42,9 +42,15 @@ export async function deleteLastRun(options: DeleteOptions) {
   logger.info(`Deleting TestRun: ${lastRun.testRunName} (namespace: ${namespace})`);
   await kubernetesService.deleteTestRunByName(lastRun.testRunName, namespace);
 
-  if (!options.keepConfigmap) {
-    logger.info(`Deleting ConfigMap: ${lastRun.configMapName} (namespace: ${namespace})`);
-    await kubernetesService.deleteConfigMap(lastRun.configMapName, namespace);
+  if (!options.keepScript) {
+    if (lastRun.configMapName) {
+      logger.info(`Deleting ConfigMap: ${lastRun.configMapName} (namespace: ${namespace})`);
+      await kubernetesService.deleteConfigMap(lastRun.configMapName, namespace);
+    }
+    if (lastRun.volumeClaimName) {
+      logger.info(`Deleting PVC: ${lastRun.volumeClaimName} (namespace: ${namespace})`);
+      await kubernetesService.deleteVolumeClaimByName(lastRun.volumeClaimName, namespace);
+    }
   }
 
   await clearLastRun();

package/src/commands/run.ts

@@ -6,8 +6,13 @@ import { ScriptService } from '../services/script.service';
 import { loadK6Config } from '../utils/configLoader';
 import { loadAndValidateEnv } from '../utils/env';
 import logger, { setLogLevel } from '../utils/logger';
-import { buildTestRunManifest } from '../utils/testRunManifestBuilder';
+import { buildTestRunManifest, buildTestRunManifestWithVolumeClaim } from '../utils/testRunManifestBuilder';
 import { saveLastRun } from '../utils/lastRunStore';
+import { K6StageMetrics, K6ScenarioOptions, K6ScenarioMetrics, K6InspectResult } from "../types/script.types";
+import { ConfigMapResult } from '../types/kubernetes.types';
+
+const DEFAULT_VUS_PER_POD = process.env.DEFAULT_VUS_PER_POD ? parseInt(process.env.DEFAULT_VUS_PER_POD, 10) : 100;
+const MAX_ITERATION_DURATION_SECONDS = process.env.MAX_ITERATION_DURATION_SECONDS ? parseInt(process.env.MAX_ITERATION_DURATION_SECONDS, 10) : 60;
 
 function listTestFiles(dir: string): string[] {
   if (!fs.existsSync(dir)) {
@@ -54,6 +59,7 @@ interface RunOptions {
   parallelism?: number;
   verbose?: boolean;
   dir: string;
+  smart?: boolean;
 }
 
 export async function runTest(scriptPath: string, options: RunOptions) {
@@ -82,11 +88,45 @@ export async function runTest(scriptPath: string, options: RunOptions) {
     const kubernetesService = createDefaultKubernetesService();
 
     // Load test script
-    const archive = await scriptService.archiveTest(scriptPath);
+    let archive = await scriptService.archiveTest(scriptPath);
 
     // Load config
     const config = loadK6Config(options.config);
 
+
+    // Analyze script if smart option is enabled
+    if (options.smart) {
+      logger.info(`Analyzing script: ${scriptPath}`);
+      const inspectResult = await scriptService.inspectScript(scriptPath);
+      const scenarioMetrics: K6ScenarioMetrics[] = await analyzeScript(inspectResult);
+      if (scenarioMetrics) {
+        const estimatedTotalIterations = scenarioMetrics.reduce((sum, metrics) => sum + (metrics?.totalIterations ?? 0), 0);
+        const totalRecommendedMaxVUs = scenarioMetrics.reduce((sum, metrics) => sum + (metrics?.recommendedMaxVUs ?? 0), 0);
+        const parallelism = Math.ceil(totalRecommendedMaxVUs / DEFAULT_VUS_PER_POD) || 1;
+        const peakTps = scenarioMetrics.reduce((max, metrics) => Math.max(max, metrics?.peakTps ?? 0), 0);
+
+        config.parallelism = parallelism;
+
+        logger.info(`Total recommendedMaxVUs: ${Math.ceil(totalRecommendedMaxVUs)} 
+        based on scenario analysis and MAX_ITERATION_DURATION_SECONDS=${MAX_ITERATION_DURATION_SECONDS} seconds
+        per iteration assumption with a safety factor of 1.2 applied to account for variability in iteration duration and ensure we have enough VUs 
+        to meet the target TPS. This is an estimate and actual resource needs may vary based on the specific workload and environment.
+        Consider monitoring the test run and adjusting resources as needed.`);
+
+        logger.info(`Calculated parallelism: ${parallelism} (based on DEFAULT_VUS_PER_POD=${DEFAULT_VUS_PER_POD})`);
+        logger.info(`Peak TPS: ${peakTps.toFixed(2)}`);
+        logger.info(`Estimated Total Iterations: ${Math.round(estimatedTotalIterations)}`);
+        logger.info(`Using MAX_ITERATION_DURATION_SECONDS=${MAX_ITERATION_DURATION_SECONDS} seconds`);
+        logger.info(`Using safety factor of 1.2 to calculate recommended VUs.`);
+        logger.info(`Using DEFAULT_VUS_PER_POD=${DEFAULT_VUS_PER_POD} to calculate parallelism.`);
+
+        // Extract, modify, and recompress the archive
+        archive = await scriptService.extractModifyAndRecompress(archive, scenarioMetrics);
+      }
+    } else {
+      logger.info('Smart scenario analysis is disabled. Running test without previous analysis.');
+    }
+
     // Load environment variables
     let envVars;
     try {
@@ -96,6 +136,25 @@ export async function runTest(scriptPath: string, options: RunOptions) {
       logger.debug(`Error loading environment variables: ${error instanceof Error ? error.message : String(error)}`);
     }
 
+    if (archive.archiveSize > 1024 * 1024) {
+      // Volume flow
+      logger.info(`Test script archive size (${(archive.archiveSize / (1024 * 1024)).toFixed(2)} MB) exceeds 1 MB, using volume flow.`);
+
+      const volumeClaimResult = await kubernetesService.createPVCWithArchive(archive, config.namespace);
+      const testRunManifest = buildTestRunManifestWithVolumeClaim(volumeClaimResult, config, envVars);
+      await kubernetesService.createTestRun(testRunManifest);
+
+      await saveLastRun({
+        testRunName: testRunManifest.metadata.name,
+        namespace: testRunManifest.metadata.namespace,
+        volumeClaimName: volumeClaimResult.volumeClaimName,
+        scriptPath,
+        createdAt: new Date().toISOString(),
+      });
+      logger.info(`Last run saved: ${testRunManifest.metadata.name} (namespace: ${testRunManifest.metadata.namespace})`);
+      return;
+    }
+
     // Create configmap for test script
     const configMap = await kubernetesService.createConfigMap(archive, config.namespace);
 
@@ -119,3 +178,100 @@ export async function runTest(scriptPath: string, options: RunOptions) {
     logger.error(`Error running test: ${error instanceof Error ? error.message : String(error)}`);
   }
 }
+
+async function analyzeScript(inspectResult: K6InspectResult): Promise<K6ScenarioMetrics[]> {
+  if (!inspectResult.scenarios) {
+    logger.info('No scenarios found in the script. Smart analysis cannot be performed.');
+    return [];
+  }
+  const allMetrics: K6ScenarioMetrics[] = Object.entries(inspectResult.scenarios).map(([name, scenario]) => {
+    return calculateScenarioMetrics(name, scenario) as K6ScenarioMetrics;
+  });
+  return allMetrics;
+}
+
+function calculateScenarioMetrics(
+  name: string,
+  scenario: K6ScenarioOptions,
+  avgIterationDurationSeconds: number = MAX_ITERATION_DURATION_SECONDS,
+  safetyFactor: number = 1.2
+): K6ScenarioMetrics | null {
+  if (scenario.executor !== 'ramping-arrival-rate') {
+    return null;
+  }
+  if (!scenario.stages || scenario.stages.length === 0) {
+    return null;
+  }
+  const timeUnitSeconds = parseTimeUnitToSeconds(scenario.timeUnit);
+  let previousRate = scenario.startRate ?? 0;
+  let peakTps = previousRate / timeUnitSeconds;
+  let totalIterations = 0;
+  const stageMetrics: K6StageMetrics[] = scenario.stages.map((stage, index) => {
+    const durationSeconds = parseDurationToSeconds(stage.duration);
+    const fromTps = previousRate / timeUnitSeconds;
+    const toTps = stage.target / timeUnitSeconds;
+    const avgTps = (fromTps + toTps) / 2;
+    const estimatedIterations = avgTps * durationSeconds;
+    totalIterations += estimatedIterations;
+    peakTps = Math.max(peakTps, toTps);
+    const requiredVUsAtTarget = toTps * avgIterationDurationSeconds;
+    const recommendedVUsAtTarget = requiredVUsAtTarget * safetyFactor;
+    previousRate = stage.target;
+    return {
+      stageIndex: index + 1,
+      duration: stage.duration,
+      durationSeconds,
+      fromTps,
+      toTps,
+      avgTps,
+      estimatedIterations,
+      requiredVUsAtTarget,
+      recommendedVUsAtTarget,
+    };
+  });
+  const requiredMaxVUs = peakTps * avgIterationDurationSeconds;
+  const recommendedMaxVUs = requiredMaxVUs * safetyFactor;
+  return {
+    name,
+    peakTps,
+    totalIterations,
+    requiredMaxVUs,
+    recommendedMaxVUs,
+    stageMetrics,
+  };
+}
+
+function parseDurationToSeconds(duration: string): number {
+  const regex = /(\d+)(ms|s|m|h)/g;
+  let match: RegExpExecArray | null;
+  let totalMs = 0;
+  while ((match = regex.exec(duration)) !== null) {
+    const value = Number(match[1]);
+    const unit = match[2];
+    switch (unit) {
+      case 'h':
+        totalMs += value * 60 * 60 * 1000;
+        break;
+      case 'm':
+        totalMs += value * 60 * 1000;
+        break;
+      case 's':
+        totalMs += value * 1000;
+        break;
+      case 'ms':
+        totalMs += value;
+        break;
+      default:
+        throw new Error(`Unsupported duration unit: ${unit}`);
+    }
+  }
+  if (totalMs === 0) {
+    throw new Error(`Invalid duration format: ${duration}`);
+  }
+  return totalMs / 1000;
+}
+
+function parseTimeUnitToSeconds(timeUnit?: string): number {
+  if (!timeUnit) return 1;
+  return parseDurationToSeconds(timeUnit);
+}

package/src/commands/status.ts

@@ -21,6 +21,10 @@ export async function status(options: StatusOptions) {
   const kubernetesService = createDefaultKubernetesService();
 
   const testRun = await kubernetesService.getTestRun(lastRun.testRunName, namespace);
+  if (!testRun) {
+    logger.error(`TestRun ${lastRun.testRunName} not found in namespace ${namespace}. It may have been deleted externally.`);
+    process.exit(1);
+  }
   printTestRunsTable([testRun]);
 
   const podList = await kubernetesService.getPodsForTestRun(lastRun.testRunName, namespace);

package/src/services/kubernetes.service.ts

@@ -1,13 +1,30 @@
-import { existsSync, promises as fs_promises } from 'fs';
+import { existsSync, promises as fs_promises, createReadStream } from 'fs';
 import { parse } from 'node:path';
 import * as k8s from '@kubernetes/client-node';
 import logger from '../utils/logger';
-import type { ArchivedFile, ConfigMapResult } from '../types/kubernetes.types';
+import type { ArchivedFile, ConfigMapResult, VolumeClaimResult } from '../types/kubernetes.types';
 import { TestRunManifest } from '../types/testRunManifest.types';
 import { printTableGeneric } from '../utils/table.util';
 
 export class KubernetesService {
-  constructor(private readonly k8sApi: k8s.CoreV1Api, private readonly k8sCustomApi: k8s.CustomObjectsApi) { }
+  constructor(
+    private readonly k8sApi: k8s.CoreV1Api,
+    private readonly k8sCustomApi: k8s.CustomObjectsApi,
+    private readonly kc?: k8s.KubeConfig,
+  ) { }
+
+  private getKubeConfig(): k8s.KubeConfig {
+    if (this.kc) return this.kc;
+    const kc = new k8s.KubeConfig();
+    kc.loadFromDefault();
+    return kc;
+  }
+
+  private isNotFoundError(error: unknown): boolean {
+    if ((error as any)?.statusCode === 404) return true;
+    if ((error as Error)?.message?.includes('HTTP-Code: 404')) return true;
+    return false;
+  }
 
   async createConfigMap(archiveFile: ArchivedFile, namespace: string): Promise<ConfigMapResult> {
     // Check if the archive file exists
@@ -44,11 +61,119 @@ export class KubernetesService {
     return { namespace, configMapName };
   }
 
+  async createPVCWithArchive(archiveFile: ArchivedFile, namespace: string): Promise<VolumeClaimResult> {
+    if (!existsSync(archiveFile.archivePath)) {
+      throw new Error(`Archive file not found at path: ${archiveFile.archivePath}`);
+    }
+
+    const stats = await fs_promises.stat(archiveFile.archivePath);
+    const storageMi = Math.max(10, Math.ceil(stats.size * 2 / (1024 * 1024)));
+    const volumeClaimName = parse(archiveFile.archiveFilename).name;
+
+    // Create PVC
+    const pvc: k8s.V1PersistentVolumeClaim = {
+      apiVersion: 'v1',
+      kind: 'PersistentVolumeClaim',
+      metadata: { name: volumeClaimName, namespace },
+      spec: {
+        accessModes: ['ReadWriteOnce'],
+        resources: { requests: { storage: `${storageMi}Mi` } },
+      },
+    };
+    await this.k8sApi.createNamespacedPersistentVolumeClaim({ namespace, body: pvc });
+    logger.info(`PVC ${volumeClaimName} created in namespace ${namespace} (${storageMi}Mi)`);
+
+    // Create helper pod mounting the PVC
+    const helperPodName = `archive-uploader-${Date.now()}`;
+    const helperPod: k8s.V1Pod = {
+      apiVersion: 'v1',
+      kind: 'Pod',
+      metadata: { name: helperPodName, namespace },
+      spec: {
+        restartPolicy: 'Never',
+        containers: [{
+          name: 'helper',
+          image: 'busybox',
+          command: ['sleep', 'infinity'],
+          volumeMounts: [{ name: 'data', mountPath: '/data' }],
+        }],
+        volumes: [{ name: 'data', persistentVolumeClaim: { claimName: volumeClaimName } }],
+      },
+    };
+    await this.k8sApi.createNamespacedPod({ namespace, body: helperPod });
+    logger.info(`Helper pod ${helperPodName} created in namespace ${namespace}`);
+
+    // Wait for pod to reach Running state
+    await this.waitForPodRunning(helperPodName, namespace);
+
+    // Stream archive into pod via exec (like kubectl cp)
+    const exec = new k8s.Exec(this.getKubeConfig());
+    const stdin = createReadStream(archiveFile.archivePath);
+    await new Promise<void>((resolve, reject) => {
+      exec.exec(
+        namespace,
+        helperPodName,
+        'helper',
+        ['tee', `/data/${archiveFile.archiveFilename}`],
+        null,
+        null,
+        stdin,
+        false,
+        (status: k8s.V1Status) => {
+          if (status.status === 'Success') resolve();
+          else reject(new Error(`Failed to upload archive to pod: ${status.message ?? JSON.stringify(status)}`));
+        },
+      ).catch(reject);
+    });
+    logger.info(`Archive ${archiveFile.archiveFilename} uploaded to PVC ${volumeClaimName}`);
+
+    // Delete helper pod
+    await this.k8sApi.deleteNamespacedPod({ name: helperPodName, namespace })
+      .catch(err => logger.debug(`Error deleting helper pod ${helperPodName}: ${(err as Error).message}`));
+    logger.info(`Helper pod ${helperPodName} deleted`);
+
+    // Clean up local archive file
+    await fs_promises.unlink(archiveFile.archivePath)
+      .catch(err => logger.debug(`Error deleting archive file ${archiveFile.archivePath}: ${(err as Error).message}`));
+
+    return { namespace, volumeClaimName, archiveFilename: archiveFile.archiveFilename };
+  }
+
+  private async waitForPodRunning(podName: string, namespace: string, maxWaitMs: number = 60_000): Promise<void> {
+    const pollInterval = 2_000;
+    const start = Date.now();
+    while (Date.now() - start < maxWaitMs) {
+      const pod = await this.k8sApi.readNamespacedPod({ name: podName, namespace });
+      if (pod.status?.phase === 'Running') return;
+      if (pod.status?.phase === 'Failed') throw new Error(`Helper pod ${podName} failed to start`);
+      await new Promise(r => setTimeout(r, pollInterval));
+    }
+    throw new Error(`Helper pod ${podName} did not reach Running state within ${maxWaitMs}ms`);
+  }
+
+  async deleteVolumeClaimByName(volumeClaimName: string, namespace: string = "default"): Promise<void> {
+    try {
+      await this.k8sApi.deleteNamespacedPersistentVolumeClaim({ name: volumeClaimName, namespace });
+      logger.info(`PVC ${volumeClaimName} deleted from namespace ${namespace}`);
+    } catch (error) {
+      if (this.isNotFoundError(error)) {
+        logger.warn(`PVC ${volumeClaimName} not found in namespace ${namespace}, skipping deletion`);
+        return;
+      }
+      const errorMessage = (error as Error).message ?? 'Unknown error';
+      throw new Error(`Failed to delete PVC ${volumeClaimName} from namespace ${namespace}: ${errorMessage}`);
+    }
+  }
+
   async deleteConfigMap(configMapName: string, namespace: string): Promise<void> {
     try {
       await this.k8sApi.deleteNamespacedConfigMap({ name: configMapName, namespace });
       logger.info(`ConfigMap ${configMapName} deleted from namespace ${namespace}`);
     } catch (error) {
+      if (this.isNotFoundError(error)) {
+        logger.warn(`ConfigMap ${configMapName} not found in namespace ${namespace}, skipping deletion`);
+        return;
+      }
       const errorMessage = (error as Error).message ?? 'Unknown error';
       throw new Error(`Failed to delete ConfigMap ${configMapName} from namespace ${namespace}: ${errorMessage}`);
     }
@@ -127,6 +252,10 @@ export class KubernetesService {
       await this.k8sCustomApi.deleteNamespacedCustomObject(this.getTestRunCustomObjectParams(testRunName, namespace));
       logger.info(`TestRun ${testRunName} deleted from namespace ${namespace}`);
     } catch (error) {
+      if (this.isNotFoundError(error)) {
+        logger.warn(`TestRun ${testRunName} not found in namespace ${namespace}, skipping deletion`);
+        return;
+      }
       const errorMessage = (error as Error).message ?? 'Unknown error';
       throw new Error(`Failed to delete TestRun ${testRunName} from namespace ${namespace}: ${errorMessage}`);
     }
@@ -137,16 +266,23 @@ export class KubernetesService {
       await this.k8sApi.deleteNamespacedPod({ name: podName, namespace });
       logger.info(`Pod ${podName} deleted from namespace ${namespace}`);
     } catch (error) {
+      if (this.isNotFoundError(error)) {
+        logger.warn(`Pod ${podName} not found in namespace ${namespace}, skipping deletion`);
+        return;
+      }
       const errorMessage = (error as Error).message ?? 'Unknown error';
       throw new Error(`Failed to delete Pod ${podName} from namespace ${namespace}: ${errorMessage}`);
     }
   }
 
-  async getTestRun(testRunName: string, namespace: string = "default"): Promise<TestRunManifest> {
+  async getTestRun(testRunName: string, namespace: string = "default"): Promise<TestRunManifest | null> {
     try {
       const response = await this.k8sCustomApi.getNamespacedCustomObject(this.getTestRunCustomObjectParams(testRunName, namespace));
       return response as TestRunManifest;
     } catch (error) {
+      if (this.isNotFoundError(error)) {
+        return null;
+      }
       const errorMessage = (error as Error).message ?? 'Unknown error';
       throw new Error(`Failed to get TestRun ${testRunName} in namespace ${namespace}: ${errorMessage}`);
     }
@@ -211,7 +347,7 @@ export function createDefaultKubernetesService(context?: string): KubernetesServ
   if (context) kc.setCurrentContext(context);
   const k8sApi = kc.makeApiClient(k8s.CoreV1Api);
   const k8sCustomApi = kc.makeApiClient(k8s.CustomObjectsApi);
-  return new KubernetesService(k8sApi, k8sCustomApi);
+  return new KubernetesService(k8sApi, k8sCustomApi, kc);
 }
 
 export function printPodsTable(data: k8s.V1PodList): void {

package/src/services/script.service.ts

@@ -1,10 +1,13 @@
 import { exec } from 'child_process';
-import { existsSync } from 'fs';
-import { basename, join, parse } from 'node:path';
+import { existsSync, statSync } from 'fs';
+import { promises as fsPromises } from 'node:fs';
+import { dirname, basename, join, parse } from 'node:path';
+import { tmpdir } from 'node:os';
 import { promisify } from 'util';
 import logger from '../utils/logger';
+import * as tar from 'tar';
 
-import type { ArchiveResult, ExecFn } from '../types/script.types';
+import type { ArchiveResult, ExecFn, K6InspectResult, K6ScenarioMetrics } from '../types/script.types';
 
 const defaultExecAsync = promisify(exec);
 
@@ -45,10 +48,12 @@ export class ScriptService {
       if (!existsSync(archiveOutput)) {
         throw new Error(`Failed to create archive: ${stderr}`);
       }
-      logger.info(`Archive created successfully at: ${archiveOutput}`);
+      const archiveSize = statSync(archiveOutput).size;
+      logger.info(`Archive created successfully at: ${archiveOutput} (size: ${archiveSize} bytes)`);
       return {
         archivePath: archiveOutput,
         archiveFilename: basename(archiveOutput),
+        archiveSize,
         scriptPath: scriptPath,
         scriptFilename: basename(scriptPath),
       };
@@ -57,6 +62,69 @@ export class ScriptService {
       throw new Error(`Failed to archive the script: ${errorMessage}`);
     }
   }
+
+  async inspectScript(scriptPath: string): Promise<K6InspectResult> {
+    const { stdout, stderr } = await this.execCmd(`k6 inspect ${scriptPath}`);
+    if (stderr) {
+      logger.error(`Error inspecting script: ${stderr}`);
+      throw new Error(`Failed to inspect the script: ${stderr}`);
+    }
+    return JSON.parse(stdout) as K6InspectResult;
+  }
+
+  async extractModifyAndRecompress(archive: ArchiveResult, scenarioMetrics: K6ScenarioMetrics[]): Promise<ArchiveResult> {
+    if (!existsSync(archive.archivePath)) {
+      throw new Error(`Archive file not found at path: ${archive.archivePath}`);
+    }
+
+    const tempRoot = await fsPromises.mkdtemp(join(tmpdir(), 'k6ctl-archive-'));
+    const extractDir = join(tempRoot, 'extracted');
+
+    try {
+      await fsPromises.mkdir(extractDir, { recursive: true });
+
+      await tar.x({
+        file: archive.archivePath,
+        cwd: extractDir,        
+      });
+
+      const metadataPath = join(extractDir, 'metadata.json');
+      if (!existsSync(metadataPath)) {
+        throw new Error(`metadata.json not found in extracted archive: ${archive.archiveFilename}`);
+      }
+
+      const metadataRaw = await fsPromises.readFile(metadataPath, 'utf8');
+      const metadata = JSON.parse(metadataRaw) as Record<string, unknown>;
+      const updatedMetadata = updateMetadata(metadata, scenarioMetrics);
+      await fsPromises.writeFile(metadataPath, `${JSON.stringify(updatedMetadata, null, 2)}\n`, 'utf8');
+
+      const outputArchivePath = join(dirname(archive.archivePath), `${parse(archive.archiveFilename).name}.tar`);
+
+      await tar.c({
+        file: outputArchivePath,
+        cwd: extractDir,
+      }, ['metadata.json', 'data', 'file']);
+
+      if (!existsSync(outputArchivePath)) {
+        throw new Error(`Failed to create modified archive at path: ${outputArchivePath}`);
+      }
+
+      logger.info(`Archive metadata updated successfully: ${outputArchivePath}`);
+
+      return {
+        archivePath: outputArchivePath,
+        archiveFilename: basename(outputArchivePath),
+        scriptPath: archive.scriptPath,
+        scriptFilename: archive.scriptFilename,
+        archiveSize: statSync(outputArchivePath).size,
+      };
+    } catch (error) {
+      const errorMessage = (error as Error).message ?? 'Unknown error';
+      throw new Error(`Failed to extract, modify, and recompress archive: ${errorMessage}`);
+    } finally {
+      await fsPromises.rm(tempRoot, { recursive: true, force: true });
+    }
+  }
 }
 
 export function createDefaultScriptService(): ScriptService {
@@ -77,3 +145,33 @@ function sanitizeText(text: string): string {
   sanitized = sanitized.replace(/^[.-]+|[.-]+$/g, '');
   return sanitized;
 }
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function updateMetadata(metadata: Record<string, unknown>, scenarioMetrics: K6ScenarioMetrics[]): Record<string, unknown> {
+  if (isRecord(metadata.options) && isRecord(metadata.options.scenarios)) {
+    applyScenarioMetricsToScenarios(metadata.options.scenarios, scenarioMetrics);
+  }
+  return metadata;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function applyScenarioMetricsToScenarios(
+  scenarios: Record<string, unknown>,
+  scenarioMetrics: K6ScenarioMetrics[]
+) {
+  for (const metric of scenarioMetrics) {
+    const scenario = scenarios[metric.name];
+    if (!isRecord(scenario)) {
+      continue;
+    }
+    const recommendedMaxVUs = Math.ceil(metric.recommendedMaxVUs);
+    scenario.maxVUs = recommendedMaxVUs;
+    scenario.preAllocatedVUs = Math.max(1, Math.ceil(recommendedMaxVUs * 0.7));
+  }
+}

package/src/types/kubernetes.types.ts

@@ -7,3 +7,9 @@ export interface ConfigMapResult {
   namespace: string;
   configMapName: string;
 }
+
+export interface VolumeClaimResult {
+  namespace: string;
+  volumeClaimName: string;
+  archiveFilename: string;
+}

package/src/types/lastRun.types.ts

@@ -1,7 +1,8 @@
 export interface LastRunState {
   testRunName: string;
   namespace: string;
-  configMapName: string;
+  configMapName?: string;
+  volumeClaimName?: string;
   scriptPath: string;
   createdAt: string;
 }

package/src/types/script.types.ts

@@ -1,8 +1,48 @@
 export interface ArchiveResult {
   archivePath: string;
   archiveFilename: string;
+  archiveSize: number;
   scriptPath: string;
   scriptFilename: string;
 }
 
+export interface K6ScenarioOptions {
+  executor: string;
+  startTime?: string;
+  gracefulStop?: string;
+  env?: Record<string, string>;
+  exec?: string;
+  tags?: Record<string, string>;
+  startRate?: number;
+  timeUnit?: string;  // e.g. "1s", "500ms"
+  stages?: Array<{ duration: string; target: number }>;
+  preAllocatedVUs?: number;
+  maxVUs?: number;
+}
+
+export interface K6InspectResult {
+  scenarios?: Record<string, K6ScenarioOptions>;
+}
+
+export interface K6StageMetrics {
+  stageIndex: number;
+  duration: string;
+  durationSeconds: number;
+  fromTps: number;
+  toTps: number;
+  avgTps: number;
+  estimatedIterations: number;
+  requiredVUsAtTarget: number;
+  recommendedVUsAtTarget: number;
+}
+
+export interface K6ScenarioMetrics {
+  name: string;
+  peakTps: number;
+  totalIterations: number;
+  requiredMaxVUs: number;
+  recommendedMaxVUs: number;
+  stageMetrics: K6StageMetrics[];
+}
+
 export type ExecFn = (cmd: string) => Promise<{ stdout: string; stderr: string }>;