openxiangda 1.0.251 → 1.0.253

package/README.md

@@ -1,4 +1,4 @@
-<!-- OpenXiangda-Policy-Version: 5 -->
+<!-- OpenXiangda-Policy-Version: 7 -->
 # OpenXiangda
 
 OpenXiangda is a lightweight CLI and skill package for private low-code platforms.
@@ -28,6 +28,23 @@ checkpoints live on the platform, so a CLI/AI interruption does not discard
 completed work. V2 does not require SDD, a clean/pushed Git mainline,
 `--change`, `--only`, or candidate/ship orchestration.
 
+`check --json` reports the exact changed resources, dependency-only Form
+bindings, and ordered execution plan. Authored Form/Backend/Workflow code is
+built only with the CLI-sealed toolchain; a V2 package never links the caller's
+`node_modules`, and undeclared third-party build dependencies fail before any
+remote write. Resource removals also fail closed until a dedicated migration
+path is used.
+
+`status` and `retry` locate the run across preproduction and production when
+`--environment` is omitted. Retry resumes only unfinished checkpoints, safely
+replays local Form bindings on another machine, and uses a server-side attempt
+fence so an older executor cannot continue writing after takeover. Runtime
+build IDs include both the Runtime layer and sealed package digests, so a newly
+sealed package cannot collide with an older package that happens to contain the
+same Runtime bytes. An exact same-package retry may reuse an `uploaded` release
+only after verifying its content hash, source revision, and Runtime parent;
+immutable storage objects are never overwritten.
+
 The lower-level commands later in this README remain available for V1
 compatibility and diagnostics; do not use them to assemble a normal V2 release.
 

package/lib/cli.js

@@ -10656,6 +10656,7 @@ async function form(args) {
       fail('用法: openxiangda form ensure --only <formCode1,formCode2>');
     }
     const target = getWorkspaceTarget(config, profileName, flags);
+    const replayLocal = Boolean(flags['replay-local']);
     await ensureDirectMutationPublishContext(
       config,
       target,
@@ -10669,22 +10670,30 @@ async function form(args) {
         target.bound.resources?.formSettings?.[formCode],
       ].find(entry => String(entry?.formUuid || '').trim());
       if (existing?.formUuid) {
+        if (replayLocal) {
+          try {
+            await requestWithAuth(
+              config,
+              target.profileName,
+              `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/forms/${encodeURIComponent(existing.formUuid)}`
+            );
+          } catch (error) {
+            if (!isHttpNotFound(error)) throw error;
+            const missing = new Error(
+              `FORM_ENSURE_REPLAY_TARGET_MISSING: ${formCode} 的已绑定表单 ${existing.formUuid} 在目标环境不存在，不能以 replay-local 补写远端资源`
+            );
+            missing.code = 'FORM_ENSURE_REPLAY_TARGET_MISSING';
+            missing.retryable = false;
+            throw missing;
+          }
+        }
         results.push({
           code: formCode,
           formUuid: existing.formUuid,
-          action: 'noop',
+          action: replayLocal ? 'verify-local' : 'noop',
         });
         continue;
       }
-      const localSchema = await loadLocalFormSchema(
-        process.cwd(),
-        formCode
-      );
-      if (!localSchema) {
-        fail(
-          `FORM_ENSURE_SCHEMA_REQUIRED: ${formCode} 缺少 src/forms/${formCode}/schema.ts`
-        );
-      }
       const formUuid = managedFormUuidForCode(
         target.appType,
         formCode
@@ -10699,6 +10708,22 @@ async function form(args) {
       } catch (error) {
         if (!isHttpNotFound(error)) throw error;
       }
+      if (!existingRemote && replayLocal) {
+        const missing = new Error(
+          `FORM_ENSURE_REPLAY_TARGET_MISSING: ${formCode} 对应的确定性表单 ${formUuid} 在目标环境不存在；replay-local 禁止创建远端资源`
+        );
+        missing.code = 'FORM_ENSURE_REPLAY_TARGET_MISSING';
+        missing.retryable = false;
+        throw missing;
+      }
+      const localSchema = existingRemote
+        ? null
+        : await loadLocalFormSchema(process.cwd(), formCode);
+      if (!existingRemote && !localSchema) {
+        fail(
+          `FORM_ENSURE_SCHEMA_REQUIRED: ${formCode} 缺少 src/forms/${formCode}/schema.ts`
+        );
+      }
       if (!existingRemote) {
         await requestWithAuth(
           config,
@@ -10718,12 +10743,16 @@ async function form(args) {
         );
       }
       saveFormResource(target, formCode, formUuid, {
-        name: localSchema.name || formCode,
+        name: localSchema?.name || existingRemote?.name || formCode,
       });
       results.push({
         code: formCode,
         formUuid,
-        action: existingRemote ? 'bind' : 'create',
+        action: replayLocal
+          ? 'rebind-local'
+          : existingRemote
+            ? 'bind'
+            : 'create',
       });
     }
     const result = {
@@ -10734,6 +10763,9 @@ async function form(args) {
         create: results.filter(item => item.action === 'create').length,
         bind: results.filter(item => item.action === 'bind').length,
         noop: results.filter(item => item.action === 'noop').length,
+        replayed: results.filter(item =>
+          ['verify-local', 'rebind-local'].includes(item.action)
+        ).length,
       },
     };
     if (flags.json) return writeJson(result);
@@ -15642,7 +15674,13 @@ async function runtime(args) {
     const files = collectRuntimeDistFiles(distDir, {
       includeSourceMaps: Boolean(flags['include-sourcemaps']),
     });
+    const declaredReleaseFiles = runtimeReleaseFileDescriptors(files);
     const totalBytes = files.reduce((sum, file) => sum + file.size, 0);
+    const reusableRuntimeRelease = await telemetry.runPhase(
+      'reuse-check',
+      async () =>
+        findRuntimeReleaseByBuildId(config, target, buildId)
+    );
     printRuntimeProgress(
       `runtime release upload: mode=${effectiveUploadMode} traceId=${traceId} files=${files.length} size=${formatBytes(totalBytes)} timeout=${uploadTimeoutMs}ms`
     );
@@ -15650,6 +15688,20 @@ async function runtime(args) {
       'upload',
       { fileCount: files.length, totalBytes, mode: effectiveUploadMode },
       async () => {
+        if (reusableRuntimeRelease) {
+          assertRuntimeReleaseReusable(reusableRuntimeRelease, {
+            appType: target.appType,
+            buildId,
+            files: declaredReleaseFiles,
+            sourceRevision: runtimeLineage.sourceRevision,
+            parentReleaseId: runtimeLineage.parentReleaseId,
+          });
+          effectiveUploadMode = 'reuse-existing';
+          printRuntimeProgress(
+            `runtime immutable release reused: releaseId=${reusableRuntimeRelease.id} buildId=${buildId} traceId=${traceId}`
+          );
+          return declaredReleaseFiles;
+        }
         if (uploadMode === 'legacy-json') {
           effectiveUploadMode = 'legacy-json';
           return files.map(file => ({
@@ -15682,6 +15734,27 @@ async function runtime(args) {
             timeoutMs: uploadTimeoutMs,
           });
         } catch (error) {
+          if (isRuntimeBuildImmutableConflict(error)) {
+            const racedRuntimeRelease = await findRuntimeReleaseByBuildId(
+              config,
+              target,
+              buildId
+            );
+            if (racedRuntimeRelease) {
+              assertRuntimeReleaseReusable(racedRuntimeRelease, {
+                appType: target.appType,
+                buildId,
+                files: declaredReleaseFiles,
+                sourceRevision: runtimeLineage.sourceRevision,
+                parentReleaseId: runtimeLineage.parentReleaseId,
+              });
+              effectiveUploadMode = 'reuse-existing';
+              printRuntimeProgress(
+                `runtime immutable release won upload race and was reused: releaseId=${racedRuntimeRelease.id} buildId=${buildId} traceId=${traceId}`
+              );
+              return declaredReleaseFiles;
+            }
+          }
           if (uploadMode !== 'auto' || !isRuntimeStagedUploadBlocked(error)) {
             throw error;
           }
@@ -16044,6 +16117,134 @@ function collectRuntimeDistFiles(distDir, options = {}) {
   return files;
 }
 
+function runtimeReleaseFileDescriptors(files) {
+  return (files || []).map(file => ({
+    path: file.path,
+    size: file.size,
+    sha256: file.sha256,
+    contentType: file.contentType,
+  }));
+}
+
+function calculateRuntimeReleaseContentHash(files) {
+  const hash = crypto.createHash('sha256');
+  for (const file of files || []) {
+    const filePath = String(file?.path || '').trim();
+    const fileSha256 = String(file?.sha256 || '').trim().toLowerCase();
+    if (!filePath || !/^[a-f0-9]{64}$/.test(fileSha256)) {
+      throw runtimeReleaseReuseError(
+        'RUNTIME_RELEASE_REUSE_LOCAL_MANIFEST_INVALID',
+        `本地 Runtime 文件描述不完整: ${filePath || '(unknown)'}`,
+        { filePath: filePath || null }
+      );
+    }
+    hash.update(filePath);
+    hash.update(fileSha256);
+  }
+  return hash.digest('hex');
+}
+
+async function findRuntimeReleaseByBuildId(config, target, buildId) {
+  const appPath = `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/runtime/releases`;
+  try {
+    const exact = await requestWithAuth(
+      config,
+      target.profileName,
+      `${appPath}/by-build/${encodeURIComponent(buildId)}`
+    );
+    return exact?.id ? exact : null;
+  } catch (error) {
+    if (Number(error?.status) !== 404) throw error;
+  }
+  const releases = await requestWithAuth(
+    config,
+    target.profileName,
+    appPath
+  );
+  const items = Array.isArray(releases)
+    ? releases
+    : Array.isArray(releases?.items)
+      ? releases.items
+      : [];
+  return (
+    items.find(item => String(item?.buildId || '') === String(buildId)) ||
+    null
+  );
+}
+
+function assertRuntimeReleaseReusable(existing, expected) {
+  const context = {
+    appType: expected.appType,
+    buildId: expected.buildId,
+    existingReleaseId: existing?.id || null,
+  };
+  if (String(existing?.status || '') !== 'uploaded') {
+    throw runtimeReleaseReuseError(
+      'RUNTIME_RELEASE_REUSE_STATUS_INVALID',
+      `相同 buildId 的 Runtime Release 状态为 ${existing?.status || '(unknown)'}，仅 uploaded 状态可作为失败发布的暂存恢复点`,
+      { ...context, existingStatus: existing?.status || null }
+    );
+  }
+  const expectedContentHash = calculateRuntimeReleaseContentHash(
+    expected.files
+  );
+  if (
+    String(existing?.contentHash || '').trim().toLowerCase() !==
+    expectedContentHash
+  ) {
+    throw runtimeReleaseReuseError(
+      'RUNTIME_RELEASE_REUSE_CONTENT_MISMATCH',
+      '相同 buildId 的历史 Runtime Release 内容与当前密封包不一致，拒绝复用',
+      {
+        ...context,
+        expectedContentHash,
+        existingContentHash: existing?.contentHash || null,
+      }
+    );
+  }
+  if (
+    !runtimeSourceRevisionEquals(
+      existing?.sourceRevision,
+      expected.sourceRevision
+    )
+  ) {
+    throw runtimeReleaseReuseError(
+      'RUNTIME_RELEASE_REUSE_SOURCE_MISMATCH',
+      '相同 buildId 的历史 Runtime Release 源码血缘与当前密封包不一致，拒绝复用',
+      context
+    );
+  }
+  const existingParentReleaseId =
+    String(existing?.parentReleaseId || '').trim() || null;
+  const expectedParentReleaseId =
+    String(expected.parentReleaseId || '').trim() || null;
+  if (existingParentReleaseId !== expectedParentReleaseId) {
+    throw runtimeReleaseReuseError(
+      'RUNTIME_RELEASE_REUSE_PARENT_MISMATCH',
+      '相同 buildId 的历史 Runtime Release 父版本已与当前 Runtime head 不一致，拒绝复用',
+      {
+        ...context,
+        existingParentReleaseId,
+        expectedParentReleaseId,
+      }
+    );
+  }
+  return existing;
+}
+
+function runtimeSourceRevisionEquals(left, right) {
+  return ['repo', 'baseCommit', 'treeHash'].every(
+    key => String(left?.[key] || '').trim() === String(right?.[key] || '').trim()
+  );
+}
+
+function runtimeReleaseReuseError(code, message, data = {}) {
+  const error = new Error(`${code}: ${message}`);
+  error.code = code;
+  error.data = data;
+  return error;
+}
+
 function walkRuntimeDist(rootDir, currentDir, files, options) {
   const entries = fs.readdirSync(currentDir, { withFileTypes: true });
   for (const entry of entries) {
@@ -16279,6 +16480,16 @@ function isRuntimeStagedUploadBlocked(error) {
   return /^HTTP 403\b/.test(String(error?.message || ''));
 }
 
+function isRuntimeBuildImmutableConflict(error) {
+  return (
+    Number(error?.status) === 409 &&
+    (String(error?.code || '') === 'RUNTIME_BUILD_IMMUTABLE' ||
+      /Runtime buildId .*禁止覆盖|RUNTIME_BUILD_IMMUTABLE/.test(
+        String(error?.message || '')
+      ))
+  );
+}
+
 function normalizeRuntimeUploadTimeoutMs(value) {
   const candidate =
     value === undefined || value === null || value === ''
@@ -20068,7 +20279,8 @@ async function prepareManifestJsCodeBundlesForPlan(manifest) {
       sourceInfos.map(item => ({
         sourceKind: item.sourceKind,
         scriptCode: item.scriptCode,
-      }))
+      })),
+      { forceCanonical: Boolean(activeDeliveryV2Context) }
     );
     if (result.status !== 0) {
       const legacyFallback = result.openxiangdaBuildMode === 'workspace-script'
@@ -28056,7 +28268,8 @@ function ensureJsCodeBundleForPlan(sourceInfo) {
         sourceKind: sourceInfo.sourceKind,
         scriptCode: sourceInfo.scriptCode,
       },
-    ]
+    ],
+    { forceCanonical: Boolean(activeDeliveryV2Context) }
   );
   if (result.stdout) process.stderr.write(result.stdout);
   if (result.stderr) process.stderr.write(result.stderr);
@@ -28399,7 +28612,8 @@ async function resolveJsCodeBundlePath(localPath, scriptCode) {
 function runWorkspaceJsCodeBuild(workspaceRoot, resolvedScriptCode, sourceKind) {
   return runWorkspaceJsCodeBuildBatch(
     workspaceRoot,
-    [{ sourceKind, scriptCode: resolvedScriptCode }]
+    [{ sourceKind, scriptCode: resolvedScriptCode }],
+    { forceCanonical: Boolean(activeDeliveryV2Context) }
   );
 }
 
@@ -30629,12 +30843,14 @@ function buildWorkspacePublishEnv(
 }
 
 module.exports = {
+  assertRuntimeReleaseReusable,
   buildResourceManifestSddTargets,
   buildScopeGrantSourceSyncDecision,
   deploymentEvidencePendingError,
   deploymentQueueWaitDecision,
   inspectSucceededPreproductionDeployment,
   main,
+  calculateRuntimeReleaseContentHash,
   recoveredPreproductionShipPatch,
   resolveReleaseCommandScopedFiles,
   selectSucceededPreproductionDeployment,

package/lib/delivery-v2-cli.js

@@ -33,6 +33,7 @@ function createDeliveryV2Cli(dependencies) {
           packageDigest: inspected.compiled.packageDigest,
           summary: inspected.compiled.summary,
           targets: inspected.targets,
+          plan: inspected.plan,
           previousPackageDigest: inspected.previous?.packageDigest || null,
         },
         `Delivery V2 检查通过: ${inspected.compiled.packageDigest}`
@@ -62,8 +63,8 @@ function createDeliveryV2Cli(dependencies) {
       if (!runId) {
         throw usageError('用法: openxiangda status <runId> [--json]');
       }
-      const target = resolveTarget(config, flags, [], false);
-      const result = await executor.status({ config, target, runId });
+      const resolved = await resolveRunTarget(config, flags, runId);
+      const result = resolved.run;
       return output(
         flags,
         result,
@@ -75,7 +76,8 @@ function createDeliveryV2Cli(dependencies) {
       if (!runId) {
         throw usageError('用法: openxiangda retry <runId> [--json]');
       }
-      const target = resolveTarget(config, flags, [], false);
+      const resolved = await resolveRunTarget(config, flags, runId);
+      const target = resolved.target;
       const result = await executor.retry({
         config,
         target,
@@ -132,9 +134,83 @@ function createDeliveryV2Cli(dependencies) {
     );
   }
 
+  async function resolveRunTarget(config, flags, runId) {
+    const explicitEnvironment =
+      stringFlag(flags, 'environment') || stringFlag(flags, 'target');
+    if (explicitEnvironment) {
+      const target = resolveTarget(
+        config,
+        { ...flags, environment: explicitEnvironment },
+        [],
+        false
+      );
+      return {
+        target,
+        run: await executor.status({ config, target, runId }),
+      };
+    }
+
+    const candidates = [];
+    const addCandidate = candidate => {
+      if (!candidate) return;
+      const key = [
+        candidate.profileName,
+        candidate.appType,
+        candidate.environmentId || 'direct',
+      ].join(':');
+      if (candidates.some(item => item.key === key)) return;
+      candidates.push({ key, target: candidate });
+    };
+    try {
+      addCandidate(resolveTarget(config, flags, [], false));
+    } catch {
+      // A multi-environment workspace may require an explicit target; probe
+      // the canonical targets below before returning a not-found error.
+    }
+    for (const environment of ['preproduction', 'production']) {
+      try {
+        addCandidate(
+          deps.getWorkspaceTarget(
+            config,
+            stringFlag(flags, 'profile') || config.currentProfile,
+            { ...flags, environment }
+          )
+        );
+      } catch {
+        // This workspace does not define the candidate environment.
+      }
+    }
+
+    let notFound = null;
+    for (const candidate of candidates) {
+      try {
+        const run = await executor.status({
+          config,
+          target: candidate.target,
+          runId,
+        });
+        return { target: candidate.target, run };
+      } catch (error) {
+        if (!isRunNotFoundError(error)) throw error;
+        notFound = error;
+      }
+    }
+    if (notFound) throw notFound;
+    throw usageError(
+      `无法解析 ReleaseRun ${runId} 所属环境；请显式添加 --environment preproduction|production`
+    );
+  }
+
   return { run };
 }
 
+function isRunNotFoundError(error) {
+  return (
+    Number(error?.status || error?.statusCode) === 404 ||
+    /DELIVERY_RUN_NOT_FOUND|HTTP 404/i.test(String(error?.message || ''))
+  );
+}
+
 function output(flags, value, message) {
   if (flags.json) return writeJson(value);
   print(message);
@@ -206,14 +282,21 @@ function printHelp(command) {
   const lines = {
     check: [
       '用法: openxiangda check [--environment <name>] [--build] [--json]',
-      '编译并校验 App Package V2；默认复用现有 dist，不执行 Runtime 构建。',
+      '编译并校验密封 App Package，输出精确资源差异和执行计划；默认复用现有 dist。',
+      '删除或未进入密封工具链的第三方构建依赖会在远程写入前失败。',
     ],
     deploy: [
       '用法: openxiangda deploy <environment> [--package <sha256>] [--json]',
       '不带 --package 时从当前工作区构建；带 --package 时直接部署已封存制品。',
     ],
-    status: ['用法: openxiangda status <runId> [--json]'],
-    retry: ['用法: openxiangda retry <runId> [--json]'],
+    status: [
+      '用法: openxiangda status <runId> [--environment <name>] [--json]',
+      '未指定环境时自动在预发和生产定位 ReleaseRun。',
+    ],
+    retry: [
+      '用法: openxiangda retry <runId> [--environment <name>] [--json]',
+      '从服务端检查点继续；隔离旧 attempt，并在跨机器场景重建本地 Form 绑定。',
+    ],
     rollback: [
       '用法: openxiangda rollback <environment> --to <appReleaseId> [--json]',
     ],