openxiangda 1.0.231 → 1.0.232

package/lib/delivery-v2-executor.js

@@ -0,0 +1,955 @@
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const {
+  compileAppPackage,
+  sha256,
+  sha256Canonical,
+} = require('./delivery-v2-package');
+const {
+  buildWorkspaceReleaseSteps,
+  commandFromArgs,
+} = require('./release-plan');
+
+const CONFIG_TARGET_BY_RESOURCE_TYPE = Object.freeze({
+  role: 'roles',
+  connector: 'connectors',
+  notification: 'notifications',
+  menu: 'menus',
+  'data-view': 'dataViews',
+  storage: 'storageConfigs',
+  'auth-config': 'authConfigs',
+  route: 'routes',
+  'public-access': 'publicAccessPolicies',
+  'page-permission-group': 'pagePermissionGroups',
+  'form-permission-group': 'formPermissionGroups',
+  'scope-dimension': 'scopeDimensions',
+  'scope-grant-source': 'scopeGrantSources',
+  'data-scope-policy': 'dataScopePolicies',
+});
+
+function createDeliveryV2Executor(dependencies) {
+  const deps = assertDependencies(dependencies);
+
+  async function inspect(input) {
+    const previous = await latestSuccessfulRun(input.config, input.target);
+    const compiled = await compileAppPackage({
+      workspaceRoot: input.workspaceRoot,
+      previousManifest: previous?.packageManifest || null,
+      skipBuild: input.skipBuild === true,
+      buildCommand: input.buildCommand,
+      distDir: input.distDir,
+      onBuildOutput: input.onBuildOutput,
+    });
+    return {
+      compiled,
+      previous,
+      targets: releaseTargets(
+        compiled.packageManifest,
+        previous?.packageManifest || null
+      ),
+    };
+  }
+
+  async function deploy(input) {
+    const previous = await latestSuccessfulRun(input.config, input.target);
+    let compiled;
+    let executionRoot = path.resolve(input.workspaceRoot || process.cwd());
+    let materialized = false;
+
+    if (input.packageDigest) {
+      const packageManifest = await downloadPackageManifest(
+        input.config,
+        input.target,
+        input.packageDigest
+      );
+      executionRoot = await materializePackageWorkspace({
+        config: input.config,
+        target: input.target,
+        packageDigest: input.packageDigest,
+        packageManifest,
+        sourceWorkspaceRoot: executionRoot,
+      });
+      compiled = {
+        workspaceRoot: executionRoot,
+        packageDigest: input.packageDigest,
+        packageManifest,
+        artifacts: [],
+        summary: packageSummary(packageManifest, previous?.packageManifest),
+      };
+      materialized = true;
+    } else {
+      compiled = await compileAppPackage({
+        workspaceRoot: executionRoot,
+        previousManifest: previous?.packageManifest || null,
+        buildCommand: input.buildCommand,
+        distDir: input.distDir,
+        onBuildOutput: input.onBuildOutput,
+      });
+      await uploadArtifacts(input.config, input.target, compiled.artifacts);
+    }
+
+    const targets = releaseTargets(
+      compiled.packageManifest,
+      previous?.packageManifest || null,
+      { forceAll: input.forceAll === true }
+    );
+    const run = await createRun({
+      config: input.config,
+      target: input.target,
+      packageDigest: compiled.packageDigest,
+      packageManifest: compiled.packageManifest,
+      kind: input.kind || 'deploy',
+      idempotencyKey:
+        input.idempotencyKey ||
+        defaultIdempotencyKey(
+          input.kind || 'deploy',
+          input.target,
+          compiled.packageDigest
+        ),
+      clientSessionId: input.clientSessionId,
+    });
+    if (run.status === 'succeeded') {
+      return {
+        run,
+        packageDigest: compiled.packageDigest,
+        packageManifest: compiled.packageManifest,
+        summary: compiled.summary,
+        targets,
+        materialized,
+        idempotent: true,
+      };
+    }
+
+    const result = await executeRun({
+      config: input.config,
+      target: input.target,
+      run,
+      packageDigest: compiled.packageDigest,
+      packageManifest: compiled.packageManifest,
+      targets,
+      executionRoot,
+      skipCompleted: true,
+    });
+    return {
+      ...result,
+      summary: compiled.summary,
+      targets,
+      materialized,
+      idempotent: false,
+    };
+  }
+
+  async function retry(input) {
+    const current = await runDetail(
+      input.config,
+      input.target,
+      input.runId
+    );
+    if (current.status === 'succeeded') {
+      return { run: current, idempotent: true };
+    }
+    const run = await deps.requestWithAuth(
+      input.config,
+      input.target.profileName,
+      runPath(input.target, `/${encodeURIComponent(input.runId)}/retry`),
+      { method: 'POST', retryTransient: true }
+    );
+    if (run.status !== 'packaged') {
+      throw deliveryError(
+        'DELIVERY_RUN_NOT_EXECUTABLE',
+        `ReleaseRun ${run.id} 当前状态为 ${run.status}`,
+        false
+      );
+    }
+    const executionRoot = await materializePackageWorkspace({
+      config: input.config,
+      target: input.target,
+      packageDigest: run.packageDigest,
+      packageManifest: run.packageManifest,
+      sourceWorkspaceRoot: input.workspaceRoot,
+    });
+    const previous = await latestSuccessfulRun(input.config, input.target, {
+      excludeRunId: run.id,
+    });
+    const targets = releaseTargets(
+      run.packageManifest,
+      previous?.packageManifest || null
+    );
+    return await executeRun({
+      config: input.config,
+      target: input.target,
+      run,
+      packageDigest: run.packageDigest,
+      packageManifest: run.packageManifest,
+      targets,
+      executionRoot,
+      skipCompleted: true,
+    });
+  }
+
+  async function rollback(input) {
+    const targetRun = await findSuccessfulRunByRelease(
+      input.config,
+      input.target,
+      input.releaseId
+    );
+    if (!targetRun) {
+      throw deliveryError(
+        'DELIVERY_ROLLBACK_RELEASE_NOT_FOUND',
+        `未找到 App Release ${input.releaseId} 对应的成功 Delivery V2 记录`,
+        false
+      );
+    }
+    return await deploy({
+      ...input,
+      kind: 'rollback',
+      packageDigest: targetRun.packageDigest,
+      forceAll: true,
+      idempotencyKey:
+        input.idempotencyKey ||
+        `rollback:${targetRun.id}:${Date.now().toString(36)}`,
+    });
+  }
+
+  async function status(input) {
+    return await runDetail(input.config, input.target, input.runId);
+  }
+
+  async function executeRun(input) {
+    const originalCwd = process.cwd();
+    const executionTarget = {
+      ...input.target,
+      deploymentId: input.target.deploymentId || null,
+    };
+    let activeRun = input.run;
+    let currentStep = 'preparing';
+    let currentComponent = 'delivery-v2';
+    try {
+      process.chdir(input.executionRoot);
+      deps.installDeliveryContext(
+        executionTarget,
+        activeRun,
+        input.targets
+      );
+      activeRun = await checkpoint(
+        input.config,
+        executionTarget,
+        activeRun.id,
+        {
+          stage: lifecycleStage('preparing', activeRun.attempt),
+          status: 'preparing',
+          component: 'package',
+          progress: {
+            packageDigest: input.packageDigest,
+          },
+        }
+      );
+      const steps = decorateSteps(
+        buildWorkspaceReleaseSteps(
+          input.targets,
+          input.packageManifest.runtimeMode,
+          executionTarget.profileName,
+          activeRun.control?.changeId
+        ),
+        executionTarget,
+        activeRun,
+        input.packageManifest,
+        input.executionRoot
+      );
+
+      if (steps.some(step => step.id === 'app-finalize')) {
+        activeRun = await checkpoint(
+          input.config,
+          executionTarget,
+          activeRun.id,
+          {
+            stage: lifecycleStage('activating', activeRun.attempt),
+            status: 'activating',
+            component: 'app-release',
+            progress: { stepCount: steps.length },
+          }
+        );
+      }
+
+      const stepResults = {};
+      for (const [index, step] of steps.entries()) {
+        const doneStage = checkpointName('done', step.id);
+        if (input.skipCompleted && activeRun.checkpoints?.[doneStage]) {
+          stepResults[step.id] =
+            activeRun.result?.[doneStage] || { resumed: true };
+          continue;
+        }
+        currentStep = step.id;
+        currentComponent = step.stagedKind || step.id;
+        const result = await deps.runOpenXiangdaInProcess(step.args, {
+          quiet: true,
+        });
+        stepResults[step.id] = result;
+        activeRun = await checkpoint(
+          input.config,
+          executionTarget,
+          activeRun.id,
+          {
+            stage: doneStage,
+            component: currentComponent,
+            progress: {
+              completed: index + 1,
+              total: steps.length,
+            },
+            result: compactStepResult(step.id, result),
+          }
+        );
+      }
+
+      if (activeRun.status !== 'verifying') {
+        if (activeRun.status !== 'activating') {
+          activeRun = await checkpoint(
+            input.config,
+            executionTarget,
+            activeRun.id,
+            {
+              stage: lifecycleStage('activating', activeRun.attempt),
+              status: 'activating',
+              component: 'activation',
+            }
+          );
+        }
+        activeRun = await checkpoint(
+          input.config,
+          executionTarget,
+          activeRun.id,
+          {
+            stage: lifecycleStage('verifying', activeRun.attempt),
+            status: 'verifying',
+            component: 'readback',
+          }
+        );
+      }
+      const verification = await verifyActivation(
+        input.config,
+        executionTarget,
+        stepResults
+      );
+      activeRun = await checkpoint(
+        input.config,
+        executionTarget,
+        activeRun.id,
+        {
+          stage: 'succeeded',
+          status: 'succeeded',
+          component: 'delivery-v2',
+          progress: {
+            completed: steps.length,
+            total: steps.length,
+          },
+          result: {
+            packageDigest: input.packageDigest,
+            appReleaseId: verification.appReleaseId,
+            runtimeReleaseId: verification.runtimeReleaseId,
+          },
+        }
+      );
+      return {
+        run: activeRun,
+        packageDigest: input.packageDigest,
+        packageManifest: input.packageManifest,
+        steps: steps.map(step => ({
+          id: step.id,
+          command: step.command,
+        })),
+        verification,
+      };
+    } catch (error) {
+      const failure = structuredFailure(
+        error,
+        activeRun?.id,
+        currentStep,
+        currentComponent
+      );
+      if (activeRun?.id) {
+        try {
+          await deps.requestWithAuth(
+            input.config,
+            executionTarget.profileName,
+            runPath(
+              executionTarget,
+              `/${encodeURIComponent(activeRun.id)}/fail`
+            ),
+            {
+              method: 'POST',
+              retryTransient: true,
+              body: {
+                stage: failure.stage,
+                component: failure.component,
+                code: failure.code,
+                message: failure.message,
+                retryable: failure.retryable,
+                details: {
+                  progressPreserved: true,
+                },
+              },
+            }
+          );
+        } catch {
+          // The original execution failure remains authoritative.
+        }
+      }
+      error.deliveryFailure = failure;
+      error.data = failure;
+      error.code = failure.code;
+      throw error;
+    } finally {
+      try {
+        deps.clearDeliveryContext(executionTarget, activeRun);
+      } finally {
+        process.chdir(originalCwd);
+      }
+    }
+  }
+
+  async function uploadArtifacts(config, target, artifacts) {
+    for (const artifact of artifacts || []) {
+      if (await artifactExists(config, target, artifact.digest)) continue;
+      const query = new URLSearchParams({
+        kind: artifact.kind,
+        contentType: artifact.contentType || 'application/octet-stream',
+        metadata: JSON.stringify(cleanObject(artifact.metadata)),
+      });
+      await deps.requestFormWithAuth(
+        config,
+        target.profileName,
+        `${artifactPath(target, artifact.digest)}?${query.toString()}`,
+        () => {
+          const form = new FormData();
+          form.append(
+            'file',
+            new Blob([artifact.buffer], {
+              type: artifact.contentType || 'application/octet-stream',
+            }),
+            artifact.metadata?.path || artifact.digest
+          );
+          return form;
+        },
+        { retryTransient: true, retries: 2 }
+      );
+    }
+  }
+
+  async function artifactExists(config, target, digest) {
+    try {
+      await deps.requestWithAuth(
+        config,
+        target.profileName,
+        artifactPath(target, digest),
+        { retryTransient: true }
+      );
+      return true;
+    } catch (error) {
+      if (isNotFound(error)) return false;
+      throw error;
+    }
+  }
+
+  async function downloadPackageManifest(config, target, digestInput) {
+    const digest = normalizeDigest(digestInput);
+    const downloaded = await deps.downloadWithAuth(
+      config,
+      target.profileName,
+      `${artifactPath(target, digest)}/content`,
+      { retries: 2 }
+    );
+    if (sha256(downloaded.buffer) !== digest) {
+      throw deliveryError(
+        'DELIVERY_PACKAGE_DOWNLOAD_DIGEST_MISMATCH',
+        `下载的 package manifest 与 ${digest} 不一致`,
+        true
+      );
+    }
+    let manifest;
+    try {
+      manifest = JSON.parse(downloaded.buffer.toString('utf8'));
+    } catch {
+      throw deliveryError(
+        'DELIVERY_PACKAGE_MANIFEST_INVALID',
+        'package manifest 不是合法 JSON',
+        false
+      );
+    }
+    if (
+      manifest.schemaVersion !== 'openxiangda-app-package-v2' ||
+      sha256Canonical(manifest) !== digest
+    ) {
+      throw deliveryError(
+        'DELIVERY_PACKAGE_MANIFEST_INVALID',
+        'package manifest schema 或摘要无效',
+        false
+      );
+    }
+    return manifest;
+  }
+
+  async function materializePackageWorkspace(input) {
+    const root = path.join(
+      path.resolve(input.sourceWorkspaceRoot || process.cwd()),
+      '.openxiangda',
+      'delivery-v2',
+      'packages',
+      normalizeDigest(input.packageDigest)
+    );
+    fs.mkdirSync(root, { recursive: true });
+    const sourceLayer = layerByKind(input.packageManifest, 'source');
+    if (!sourceLayer) {
+      throw deliveryError(
+        'DELIVERY_PACKAGE_SOURCE_LAYER_MISSING',
+        'package manifest 缺少 source layer',
+        false
+      );
+    }
+    await materializeFiles(
+      input.config,
+      input.target,
+      root,
+      sourceLayer.files || []
+    );
+    const stateSource = path.join(
+      path.resolve(input.sourceWorkspaceRoot || process.cwd()),
+      '.openxiangda',
+      'state.json'
+    );
+    const stateTarget = path.join(root, '.openxiangda', 'state.json');
+    if (fs.existsSync(stateSource)) {
+      fs.mkdirSync(path.dirname(stateTarget), { recursive: true });
+      fs.copyFileSync(stateSource, stateTarget);
+    }
+    const nodeModulesSource = path.join(
+      path.resolve(input.sourceWorkspaceRoot || process.cwd()),
+      'node_modules'
+    );
+    const nodeModulesTarget = path.join(root, 'node_modules');
+    if (
+      fs.existsSync(nodeModulesSource) &&
+      !fs.existsSync(nodeModulesTarget)
+    ) {
+      fs.symlinkSync(nodeModulesSource, nodeModulesTarget, 'dir');
+    }
+    const runtimeLayer = layerByKind(input.packageManifest, 'runtime');
+    if (runtimeLayer) {
+      await materializeFiles(
+        input.config,
+        input.target,
+        path.join(root, 'dist'),
+        runtimeLayer.files || []
+      );
+    }
+    return root;
+  }
+
+  async function materializeFiles(config, target, root, files) {
+    for (const descriptor of files) {
+      const relative = safeRelativePath(descriptor.path);
+      const destination = path.join(root, relative);
+      if (fs.existsSync(destination)) {
+        const existing = fs.readFileSync(destination);
+        if (sha256(existing) === descriptor.digest) continue;
+      }
+      const downloaded = await deps.downloadWithAuth(
+        config,
+        target.profileName,
+        `${artifactPath(target, descriptor.digest)}/content`,
+        { retries: 2 }
+      );
+      if (sha256(downloaded.buffer) !== descriptor.digest) {
+        throw deliveryError(
+          'DELIVERY_ARTIFACT_DOWNLOAD_DIGEST_MISMATCH',
+          `制品 ${descriptor.digest} 下载校验失败`,
+          true
+        );
+      }
+      fs.mkdirSync(path.dirname(destination), { recursive: true });
+      const temporary = `${destination}.${process.pid}.tmp`;
+      fs.writeFileSync(temporary, downloaded.buffer, { mode: 0o600 });
+      fs.renameSync(temporary, destination);
+    }
+  }
+
+  async function latestSuccessfulRun(config, target, options = {}) {
+    const list = await deps.requestWithAuth(
+      config,
+      target.profileName,
+      `${runPath(target)}?limit=100`,
+      { retryTransient: true }
+    );
+    const candidate = (list?.items || []).find(
+      item =>
+        item.status === 'succeeded' &&
+        item.id !== options.excludeRunId &&
+        sameEnvironment(item, target)
+    );
+    return candidate
+      ? await runDetail(config, target, candidate.id)
+      : null;
+  }
+
+  async function findSuccessfulRunByRelease(config, target, releaseId) {
+    const list = await deps.requestWithAuth(
+      config,
+      target.profileName,
+      `${runPath(target)}?limit=100`,
+      { retryTransient: true }
+    );
+    for (const item of list?.items || []) {
+      if (item.status !== 'succeeded' || !sameEnvironment(item, target)) {
+        continue;
+      }
+      const detail = await runDetail(config, target, item.id);
+      if (
+        detail.result?.succeeded?.appReleaseId === releaseId ||
+        detail.result?.activation?.appReleaseId === releaseId
+      ) {
+        return detail;
+      }
+    }
+    return null;
+  }
+
+  async function runDetail(config, target, runId) {
+    return await deps.requestWithAuth(
+      config,
+      target.profileName,
+      runPath(target, `/${encodeURIComponent(runId)}`),
+      { retryTransient: true }
+    );
+  }
+
+  async function createRun(input) {
+    return await deps.requestWithAuth(
+      input.config,
+      input.target.profileName,
+      runPath(input.target),
+      {
+        method: 'POST',
+        retryTransient: true,
+        retries: 2,
+        body: {
+          environmentId: input.target.environmentId || null,
+          environmentKind: input.target.environmentKind || null,
+          kind: input.kind,
+          packageDigest: input.packageDigest,
+          packageManifest: input.packageManifest,
+          idempotencyKey: input.idempotencyKey,
+          clientSessionId: input.clientSessionId,
+        },
+      }
+    );
+  }
+
+  async function checkpoint(config, target, runId, body) {
+    return await deps.requestWithAuth(
+      config,
+      target.profileName,
+      runPath(target, `/${encodeURIComponent(runId)}/checkpoints`),
+      {
+        method: 'POST',
+        retryTransient: true,
+        retries: 2,
+        body,
+      }
+    );
+  }
+
+  async function verifyActivation(config, target, stepResults) {
+    const [appHead, runtimeHead] = await Promise.all([
+      deps.requestWithAuth(
+        config,
+        target.profileName,
+        appApiPath(target, '/app-releases/head'),
+        { retryTransient: true }
+      ),
+      deps.requestWithAuth(
+        config,
+        target.profileName,
+        appApiPath(target, '/runtime/releases/head'),
+        { retryTransient: true }
+      ),
+    ]);
+    const finalized = stepResults['app-finalize'];
+    const expectedAppReleaseId =
+      finalized?.activated?.id ||
+      finalized?.verified?.id ||
+      finalized?.prepared?.id ||
+      null;
+    const activeAppReleaseId =
+      appHead?.activeAppReleaseId || appHead?.release?.id || null;
+    if (
+      expectedAppReleaseId &&
+      activeAppReleaseId &&
+      expectedAppReleaseId !== activeAppReleaseId
+    ) {
+      throw deliveryError(
+        'DELIVERY_ACTIVATION_READBACK_MISMATCH',
+        `App Release 激活读回不一致: expected=${expectedAppReleaseId} actual=${activeAppReleaseId}`,
+        true
+      );
+    }
+    return {
+      appReleaseId: activeAppReleaseId || expectedAppReleaseId,
+      runtimeReleaseId: runtimeHead?.activeRuntimeReleaseId || null,
+      runtimeBuildId: runtimeHead?.activeRuntimeBuildId || null,
+    };
+  }
+
+  return {
+    deploy,
+    inspect,
+    retry,
+    rollback,
+    status,
+  };
+}
+
+function releaseTargets(manifest, previousManifest, options = {}) {
+  const changed = kind =>
+    options.forceAll === true ||
+    layerByKind(manifest, kind)?.digest !==
+      layerByKind(previousManifest, kind)?.digest;
+  const resources = manifest?.resources || {};
+  const resourceSelectors = {};
+  if (changed('configuration')) {
+    for (const [type, values] of Object.entries(
+      resources.configuration || {}
+    )) {
+      const key = CONFIG_TARGET_BY_RESOURCE_TYPE[type];
+      if (key && Array.isArray(values) && values.length > 0) {
+        resourceSelectors[key] = [...new Set(values.map(String))].sort();
+      }
+    }
+  }
+  return {
+    forms: changed('form') ? resources.forms || [] : [],
+    pages: [],
+    functions: changed('backend') ? resources.functions || [] : [],
+    automations: changed('backend') ? resources.automations || [] : [],
+    workflows: changed('workflow') ? resources.workflows || [] : [],
+    jsCodeNodes: [],
+    resources: false,
+    resourceSelectors,
+    resourceDeletes: {},
+    runtime: Boolean(layerByKind(manifest, 'runtime') && changed('runtime')),
+    other: [],
+  };
+}
+
+function decorateSteps(
+  steps,
+  target,
+  run,
+  packageManifest,
+  executionRoot
+) {
+  const result = [];
+  for (const original of steps) {
+    const step = {
+      ...original,
+      args: [...original.args],
+    };
+    if (target.targetName) {
+      step.args.push('--environment', target.targetName);
+    }
+    if (target.deploymentId) {
+      step.args.push('--deployment-id', target.deploymentId);
+    }
+    if (step.id === 'runtime-stage') {
+      const runtime = layerByKind(packageManifest, 'runtime');
+      step.args.push(
+        '--no-build',
+        '--dist',
+        path.join(executionRoot, 'dist'),
+        '--build-id',
+        `pkg-${runtime.digest.slice(0, 20)}`,
+        '--upload-mode',
+        'staged'
+      );
+    }
+    if (step.id === 'app-finalize') {
+      if (target.environmentId) {
+        step.args.push('--environment-id', target.environmentId);
+      }
+      step.args.push('--delivery-run-id', run.id);
+    }
+    step.command = commandFromArgs(step.args);
+    result.push(step);
+  }
+  return result;
+}
+
+function packageSummary(manifest, previousManifest) {
+  return {
+    sourceFileCount: layerByKind(manifest, 'source')?.fileCount || 0,
+    artifactUploadCount: 0,
+    layers: (manifest.layers || []).map(layer => ({
+      kind: layer.kind,
+      digest: layer.digest,
+      sourceHash: layer.sourceHash,
+      reused:
+        layer.digest === layerByKind(previousManifest, layer.kind)?.digest,
+      built: false,
+      fileCount: layer.fileCount,
+      size: layer.size,
+    })),
+  };
+}
+
+function compactStepResult(stepId, result) {
+  if (!result || typeof result !== 'object') return { ok: true };
+  if (stepId === 'app-finalize') {
+    return {
+      appReleaseId:
+        result.activated?.id ||
+        result.verified?.id ||
+        result.prepared?.id ||
+        null,
+    };
+  }
+  return {
+    ok: true,
+    id: result.id || result.release?.id || null,
+  };
+}
+
+function structuredFailure(error, runId, stage, component) {
+  const code =
+    error?.code ||
+    error?.payload?.errorCode ||
+    error?.payload?.data?.code ||
+    'DELIVERY_EXECUTION_FAILED';
+  return {
+    runId: runId || null,
+    stage: stage || 'unknown',
+    component: component || 'unknown',
+    code: String(code),
+    message: String(error?.message || 'Delivery V2 执行失败'),
+    retryable: error?.retryable !== false,
+    progressPreserved: true,
+  };
+}
+
+function layerByKind(manifest, kind) {
+  return (manifest?.layers || []).find(layer => layer.kind === kind) || null;
+}
+
+function runPath(target, suffix = '') {
+  return `${appApiPath(target, '/delivery/runs')}${suffix}`;
+}
+
+function artifactPath(target, digest) {
+  return appApiPath(
+    target,
+    `/delivery/artifacts/${encodeURIComponent(digest)}`
+  );
+}
+
+function appApiPath(target, suffix) {
+  return `/openxiangda-api/v1/apps/${encodeURIComponent(
+    target.appType
+  )}${suffix}`;
+}
+
+function checkpointName(prefix, value) {
+  return `${prefix}-${String(value || 'step')
+    .replace(/[^a-z0-9-]+/gi, '-')
+    .toLowerCase()}`.slice(0, 64);
+}
+
+function lifecycleStage(name, attempt) {
+  return `${name}-attempt-${Math.max(Number(attempt) || 1, 1)}`;
+}
+
+function sameEnvironment(run, target) {
+  return String(run.environmentId || '') === String(target.environmentId || '');
+}
+
+function defaultIdempotencyKey(kind, target, digest) {
+  return [
+    'delivery-v2',
+    kind,
+    target.appType,
+    target.environmentId || 'direct',
+    digest,
+  ].join(':');
+}
+
+function normalizeDigest(value) {
+  const digest = String(value || '')
+    .trim()
+    .toLowerCase();
+  if (!/^[a-f0-9]{64}$/.test(digest)) {
+    throw deliveryError(
+      'DELIVERY_PACKAGE_DIGEST_INVALID',
+      'package digest 必须是 64 位 SHA-256',
+      false
+    );
+  }
+  return digest;
+}
+
+function safeRelativePath(value) {
+  const normalized = String(value || '').replace(/\\/g, '/');
+  if (
+    !normalized ||
+    normalized.startsWith('/') ||
+    normalized.includes('../') ||
+    normalized === '..'
+  ) {
+    throw deliveryError(
+      'DELIVERY_ARTIFACT_PATH_INVALID',
+      `制品路径无效: ${value}`,
+      false
+    );
+  }
+  return normalized;
+}
+
+function isNotFound(error) {
+  return (
+    Number(error?.status || error?.statusCode) === 404 ||
+    /\bHTTP 404\b|NOT_FOUND/i.test(String(error?.message || ''))
+  );
+}
+
+function cleanObject(value) {
+  return Object.fromEntries(
+    Object.entries(value || {}).filter(([, item]) => item !== undefined)
+  );
+}
+
+function deliveryError(code, message, retryable) {
+  const error = new Error(`${code}: ${message}`);
+  error.code = code;
+  error.retryable = retryable;
+  return error;
+}
+
+function assertDependencies(value) {
+  const required = [
+    'clearDeliveryContext',
+    'downloadWithAuth',
+    'installDeliveryContext',
+    'requestFormWithAuth',
+    'requestWithAuth',
+    'runOpenXiangdaInProcess',
+  ];
+  for (const key of required) {
+    if (typeof value?.[key] !== 'function') {
+      throw new Error(`Delivery V2 executor dependency 缺失: ${key}`);
+    }
+  }
+  return value;
+}
+
+module.exports = {
+  CONFIG_TARGET_BY_RESOURCE_TYPE,
+  createDeliveryV2Executor,
+  releaseTargets,
+  structuredFailure,
+};