openxiangda 1.0.174 → 1.0.176

package/lib/release-explain.js

@@ -0,0 +1,75 @@
+function explainReleaseExecution(execution) {
+  if (!execution) {
+    return {
+      state: 'not-started',
+      resumable: false,
+      writeReviewRequired: false,
+      summary: '本地没有该 change 的 release execution journal。',
+      nextAction: '先运行 release publish --dry-run 检查计划，再开始正式发布。',
+    };
+  }
+  const steps = Array.isArray(execution.steps) ? execution.steps : [];
+  const failedStep = steps.find(step => step.status === 'failed');
+  const runningStep = steps.find(step =>
+    ['running', 'write-started'].includes(step.status)
+  );
+  const pendingSteps = steps.filter(step => step.status === 'pending');
+  const completedSteps = steps.filter(step => step.status === 'completed');
+  const state = execution.status || 'unknown';
+  const common = {
+    state,
+    resumable: state === 'staged-resumable',
+    writeReviewRequired: state === 'write-review-required',
+    progress: {
+      completed: completedSteps.length,
+      pending: pendingSteps.length,
+      total: steps.length,
+      currentStep: runningStep?.id || failedStep?.id || pendingSteps[0]?.id || null,
+    },
+    failedStep: failedStep
+      ? {
+          id: failedStep.id,
+          code: failedStep.errorCode || null,
+          message: failedStep.error || null,
+        }
+      : null,
+  };
+  if (state === 'completed') {
+    return {
+      ...common,
+      summary: '本次应用原子发布已完成。',
+      nextAction: '执行验收；确认无误后可归档 SDD change。',
+    };
+  }
+  if (state === 'write-review-required') {
+    return {
+      ...common,
+      summary: '上次写请求的结果不确定，CLI 已停止自动重试以避免重复写入。',
+      nextAction:
+        '先只读核对 staged child/App Release；确认可安全重试后追加 --resume-after-review。',
+    };
+  }
+  if (state === 'staged-resumable') {
+    return {
+      ...common,
+      summary: '已有 staged child，active head 尚未全部切换，可以从执行日志继续。',
+      nextAction: '重新运行同一条 release publish 命令继续，不要另起全量发布。',
+    };
+  }
+  if (state === 'failed') {
+    return {
+      ...common,
+      summary: '发布在确认没有成功写入后失败，可以修复原因后重试。',
+      nextAction: '修复 failedStep 后重新运行同一条 release publish 命令。',
+    };
+  }
+  return {
+    ...common,
+    summary: runningStep
+      ? `发布停在 ${runningStep.id}。`
+      : '发布尚未完成。',
+    nextAction: '使用同一 change/profile 重新运行 release publish，让执行日志决定续跑位置。',
+  };
+}
+
+module.exports = { explainReleaseExecution };

package/lib/release-plan.js

@@ -11,6 +11,11 @@ function uniqueSorted(values = []) {
 }
 
 function normalizeReleaseTargets(targets = {}, runtimeMode = 'legacy') {
+  const resourceSelectors = Object.fromEntries(
+    Object.entries(targets.resourceSelectors || targets.resourceTargets || {})
+      .map(([type, values]) => [type, uniqueSorted(values || [])])
+      .filter(([, values]) => values.length > 0)
+  );
   const logicalTargets = {
     forms: uniqueSorted(targets.forms || []),
     pages: uniqueSorted(targets.pages || []),
@@ -19,6 +24,7 @@ function normalizeReleaseTargets(targets = {}, runtimeMode = 'legacy') {
     workflows: uniqueSorted(targets.workflows || []),
     jsCodeNodes: uniqueSorted(targets.jsCodeNodes || []),
     resources: Boolean(targets.resources),
+    resourceSelectors,
     runtime: Boolean(targets.runtime),
     other: uniqueSorted(targets.other || []),
   };
@@ -36,6 +42,35 @@ function normalizeReleaseTargets(targets = {}, runtimeMode = 'legacy') {
   return { logicalTargets, activationTargets };
 }
 
+function unsupportedAtomicReleaseTargets(targets = {}) {
+  const unsupported = [];
+  if (targets.resources) unsupported.push('generic-resources');
+  for (const [type, selectors] of Object.entries(targets.resourceSelectors || {})) {
+    if ((selectors || []).length > 0) {
+      unsupported.push(`${type}:${selectors.join(',')}`);
+    }
+  }
+  if (
+    (targets.jsCodeNodes || []).length > 0 &&
+    (targets.functions || []).length === 0 &&
+    (targets.automations || []).length === 0
+  ) {
+    unsupported.push(`js-code-owner:${targets.jsCodeNodes.join(',')}`);
+  }
+  return unsupported;
+}
+
+function assertAtomicReleaseTargetsSupported(targets) {
+  const unsupported = unsupportedAtomicReleaseTargets(targets);
+  if (unsupported.length === 0) return;
+  const error = new Error(
+    `RELEASE_ATOMIC_TARGET_UNSUPPORTED: 以下资源尚无 immutable staged child，禁止与原子发布混合后降级为直接写入: ${unsupported.join('; ')}`
+  );
+  error.code = 'RELEASE_ATOMIC_TARGET_UNSUPPORTED';
+  error.unsupportedTargets = unsupported;
+  throw error;
+}
+
 function buildTargetedResourceReleaseCommands(
   targets,
   profileArg,
@@ -116,7 +151,7 @@ function buildTargetedResourceReleaseSteps(
   if (workflows.length > 0) {
     steps.push(
       createStep(
-        'workflow-publish',
+        'workflow-stage',
         appendProfileAndChange(
           [
             'resource',
@@ -124,10 +159,12 @@ function buildTargetedResourceReleaseSteps(
             'workflow',
             '--only',
             workflows.join(','),
+            '--stage-only',
           ],
           profileArg,
           changeId
-        )
+        ),
+        { stagedKind: 'WorkflowRelease' }
       )
     );
   }
@@ -159,6 +196,7 @@ function buildWorkspaceReleaseSteps(
     targetsInput,
     runtimeMode
   );
+  assertAtomicReleaseTargetsSupported(targets);
   const steps = [];
   const hasResourceTargets =
     Boolean(targets.resources) ||
@@ -212,6 +250,7 @@ function buildWorkspaceReleaseSteps(
       targets.forms.length > 0 ||
       targets.functions.length > 0 ||
       targets.automations.length > 0 ||
+      targets.workflows.length > 0 ||
       targets.runtime
     ) {
       steps.push(
@@ -223,6 +262,7 @@ function buildWorkspaceReleaseSteps(
               'app-finalize',
               '--staged-resources-json',
               `.openxiangda/releases/${changeId || 'change'}/staged-resources.json`,
+              '--wait',
             ],
             profileArg,
             changeId
@@ -260,6 +300,28 @@ function buildWorkspaceReleaseSteps(
       ...buildTargetedResourceReleaseSteps(targets, profileArg, changeId)
     );
   }
+  if (
+    targets.functions.length > 0 ||
+    targets.automations.length > 0 ||
+    targets.workflows.length > 0
+  ) {
+    steps.push(
+      createStep(
+        'app-finalize',
+        appendProfileAndChange(
+          [
+            'release',
+            'app-finalize',
+            '--staged-resources-json',
+            `.openxiangda/releases/${changeId || 'change'}/staged-resources.json`,
+            '--wait',
+          ],
+          profileArg,
+          changeId
+        )
+      )
+    );
+  }
   return steps;
 }
 
@@ -291,4 +353,5 @@ module.exports = {
   commandFromArgs,
   normalizeReleaseTargets,
   releasePlanHash,
+  unsupportedAtomicReleaseTargets,
 };

package/lib/sdd.js

@@ -166,6 +166,12 @@ function getSddGovernanceConfig(options = {}) {
   const strictDocumentation = Boolean(
     configured && /strictDocumentation\s*:\s*true/.test(block)
   );
+  const documentationModeMatch = block.match(
+    /documentationMode\s*:\s*['"]?(structured|full)['"]?/
+  );
+  const documentationMode = strictDocumentation
+    ? 'full'
+    : documentationModeMatch?.[1] || 'structured';
   const pathMatch = block.match(/path\s*:\s*['"]([^'"]+)['"]/);
   const schemaMatch = block.match(/schemaVersion\s*:\s*['"]([^'"]+)['"]/);
   const sddPath = normalizeRelPath(pathMatch?.[1] || DEFAULT_SDD_DIR);
@@ -182,6 +188,7 @@ function getSddGovernanceConfig(options = {}) {
     enabled,
     strictHighRisk,
     strictDocumentation,
+    documentationMode,
     path: sddPath,
     rootDir,
     initialized,
@@ -204,6 +211,7 @@ function buildDefaultConfigYaml() {
     '  coverage: coverage.json',
     '  release: release.json',
     '  metadata: change.json',
+    '  documentationMode: structured',
     'rules:',
     '  requireApprovalForHighRisk: true',
     '  requireAffectedCoverage: true',
@@ -324,6 +332,18 @@ function splitList(value) {
     .filter(Boolean);
 }
 
+function normalizeResourceSelectors(value = {}) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value)
+      .map(([key, selectors]) => [
+        String(key || '').trim(),
+        Array.from(new Set(splitList(selectors))).sort(),
+      ])
+      .filter(([key, selectors]) => key && selectors.length > 0)
+  );
+}
+
 function normalizeAffected(input = {}) {
   const affected = input.affected || input;
   return {
@@ -334,6 +354,9 @@ function normalizeAffected(input = {}) {
     workflows: splitList(affected.workflows || affected.workflow),
     jsCodeNodes: splitList(affected.jsCodeNodes || affected.jsCode || affected['js-code-nodes']),
     files: splitList(affected.files || affected.file),
+    resourceSelectors: normalizeResourceSelectors(
+      affected.resourceSelectors || affected.resourceTargets
+    ),
     resources: affected.resources === true || affected.resources === 'true' || splitList(affected.resources).includes('*'),
     runtime: affected.runtime === true || affected.runtime === 'true',
     backend: affected.backend === true || affected.backend === 'true',
@@ -346,6 +369,9 @@ function mergeAffectedScopes(...inputs) {
   const mergeList = key =>
     Array.from(new Set(scopes.flatMap(scope => scope[key] || []))).sort();
   const hasFlag = key => scopes.some(scope => Boolean(scope[key]));
+  const resourceSelectorKeys = Array.from(
+    new Set(scopes.flatMap(scope => Object.keys(scope.resourceSelectors || {})))
+  ).sort();
   return {
     forms: mergeList('forms'),
     pages: mergeList('pages'),
@@ -354,6 +380,16 @@ function mergeAffectedScopes(...inputs) {
     workflows: mergeList('workflows'),
     jsCodeNodes: mergeList('jsCodeNodes'),
     files: mergeList('files'),
+    resourceSelectors: Object.fromEntries(
+      resourceSelectorKeys.map(key => [
+        key,
+        Array.from(
+          new Set(
+            scopes.flatMap(scope => scope.resourceSelectors?.[key] || [])
+          )
+        ).sort(),
+      ])
+    ),
     resources: hasFlag('resources'),
     runtime: hasFlag('runtime'),
     backend: hasFlag('backend'),
@@ -769,6 +805,52 @@ The application SHALL provide the approved "${meta.title}" behavior for the affe
 `;
 }
 
+function renderSddDocumentation(options = {}) {
+  const loaded = options.loaded || loadSddChange(options);
+  const meta = loaded.meta;
+  const requirementSpec = loaded.coverage?.requirements?.find(
+    item => typeof item?.spec === 'string' && item.spec.trim()
+  )?.spec;
+  const specRelativePath =
+    requirementSpec && !requirementSpec.includes('..')
+      ? requirementSpec.replace(/\\/g, '/')
+      : 'specs/app/spec.md';
+  const specMatch = specRelativePath.match(/^specs\/([^/]+)\/spec\.md$/);
+  const domain = options.domain || specMatch?.[1] || 'app';
+  const files = {
+    proposal: path.join(loaded.changeDir, 'proposal.md'),
+    design: path.join(loaded.changeDir, 'design.md'),
+    tasks: path.join(loaded.changeDir, 'tasks.md'),
+    evidence: path.join(loaded.changeDir, 'evidence.md'),
+    spec: path.join(loaded.changeDir, 'specs', domain, 'spec.md'),
+  };
+  const contents = {
+    proposal: createProposalContent(meta),
+    design: createDesignContent(meta),
+    tasks: createTasksContent(meta),
+    evidence: createEvidenceContent(meta),
+    spec: createDeltaSpecContent(meta, domain),
+  };
+  const rendered = [];
+  const skipped = [];
+  for (const [kind, file] of Object.entries(files)) {
+    if (fs.existsSync(file) && !options.force) {
+      skipped.push(path.relative(options.cwd || process.cwd(), file).replace(/\\/g, '/'));
+      continue;
+    }
+    ensureDir(path.dirname(file));
+    fs.writeFileSync(file, contents[kind]);
+    rendered.push(path.relative(options.cwd || process.cwd(), file).replace(/\\/g, '/'));
+  }
+  return {
+    schemaVersion: meta.schemaVersion || SDD_SCHEMA_VERSION,
+    changeId: loaded.changeId,
+    mode: 'full',
+    rendered,
+    skipped,
+  };
+}
+
 function createCoverageManifest(meta, domain) {
   const reqId = `req-${slug(meta.title || meta.id, meta.id)}`;
   return {
@@ -860,25 +942,45 @@ function proposeSddChange(options = {}) {
   writeJsonFile(path.join(changeDir, CHANGE_META_FILE), meta, jsonWriteOptions);
   writeJsonFile(path.join(changeDir, COVERAGE_FILE), coverage, jsonWriteOptions);
   writeJsonFile(path.join(changeDir, RELEASE_FILE), release, jsonWriteOptions);
-  fs.writeFileSync(path.join(changeDir, 'proposal.md'), createProposalContent(meta));
-  fs.writeFileSync(path.join(changeDir, 'design.md'), createDesignContent(meta));
-  fs.writeFileSync(path.join(changeDir, 'tasks.md'), createTasksContent(meta));
-  fs.writeFileSync(path.join(changeDir, 'evidence.md'), createEvidenceContent(meta));
-  fs.writeFileSync(
-    path.join(changeDir, 'specs', domain, 'spec.md'),
-    createDeltaSpecContent(meta, domain)
-  );
+  const loaded = {
+    governance,
+    changeId,
+    changeDir,
+    meta,
+    coverage,
+  };
+  const documentation =
+    governance.documentationMode === 'full' || options.renderDocumentation
+      ? renderSddDocumentation({
+          cwd: options.cwd,
+          loaded,
+          domain,
+          force: true,
+        })
+      : {
+          mode: 'structured',
+          rendered: [],
+          skipped: [],
+        };
   return {
     schemaVersion: SDD_SCHEMA_VERSION,
     change: meta,
     coverage,
     release,
+    documentation,
     dir: path.relative(options.cwd || process.cwd(), changeDir).replace(/\\/g, '/'),
-    nextActions: [
-      `Review openspec/changes/${changeId}/proposal.md`,
-      `Sharpen openspec/changes/${changeId}/specs/${domain}/spec.md`,
-      `Run openxiangda sdd approve ${changeId} after user confirmation`,
-    ],
+    nextActions:
+      documentation.mode === 'full'
+        ? [
+            `Review openspec/changes/${changeId}/proposal.md`,
+            `Sharpen openspec/changes/${changeId}/specs/${domain}/spec.md`,
+            `Run openxiangda sdd approve ${changeId} after user confirmation`,
+          ]
+        : [
+            `Review openspec/changes/${changeId}/change.json and coverage.json`,
+            `Run openxiangda sdd approve ${changeId} after user confirmation`,
+            `Optional: openxiangda sdd render ${changeId}`,
+          ],
   };
 }
 
@@ -981,6 +1083,7 @@ function createMainlineSddBundle(options = {}) {
     changeId,
     mainlinePolicy: 'publish-from-main-v1',
     bundledChanges: sourceIds,
+    ...(options.integration ? { integration: options.integration } : {}),
     targets: normalizedTargets.activationTargets,
     logicalTargets: normalizedTargets.logicalTargets,
     changedFiles: affected.files,
@@ -1221,6 +1324,16 @@ function affectedCoversTargets(affected, targets = {}) {
     missing.push(`${key}:${required.filter(item => !normalized[key].includes(item)).join(',')}`);
   }
   if (targets.resources && !normalized.resources && !normalized.backend) missing.push('resources');
+  for (const [key, required] of Object.entries(targets.resourceSelectors || {})) {
+    if (normalized.resources || includesAll(normalized.resourceSelectors?.[key], required)) {
+      continue;
+    }
+    missing.push(
+      `resourceSelectors.${key}:${required
+        .filter(item => !(normalized.resourceSelectors?.[key] || []).includes(item))
+        .join(',')}`
+    );
+  }
   if (targets.runtime && !normalized.runtime) missing.push('runtime');
   return {
     covered: missing.length === 0,
@@ -1305,6 +1418,14 @@ function normalizeCoverageResources(coverage, fallbackAffected = {}, options = {
     resources[key] === 'true' ||
     requirementCovers.some(item => item[key] === true || item[key] === 'true') ||
     Boolean(fallback[key]);
+  const selectorSources = [
+    resources.resourceSelectors,
+    ...requirementCovers.map(item => item.resourceSelectors),
+    fallback.resourceSelectors,
+  ].map(normalizeResourceSelectors);
+  const selectorKeys = Array.from(
+    new Set(selectorSources.flatMap(item => Object.keys(item)))
+  ).sort();
   return {
     forms: Array.from(new Set(mergeList('forms'))),
     pages: Array.from(new Set(mergeList('pages'))),
@@ -1313,6 +1434,14 @@ function normalizeCoverageResources(coverage, fallbackAffected = {}, options = {
     workflows: Array.from(new Set(mergeList('workflows'))),
     jsCodeNodes: Array.from(new Set(mergeList('jsCodeNodes'))),
     files: Array.from(new Set(mergeList('files'))),
+    resourceSelectors: Object.fromEntries(
+      selectorKeys.map(key => [
+        key,
+        Array.from(
+          new Set(selectorSources.flatMap(item => item[key] || []))
+        ).sort(),
+      ])
+    ),
     resources: hasBool('resources'),
     runtime: hasBool('runtime'),
     backend: hasBool('backend'),
@@ -1425,6 +1554,26 @@ function getSddChangeScope(options = {}) {
     automations: mergeList('automations'),
     workflows: mergeList('workflows'),
     jsCodeNodes: mergeList('jsCodeNodes'),
+    resourceSelectors: Object.fromEntries(
+      Array.from(
+        new Set([
+          ...Object.keys(releaseTargets.resourceSelectors || {}),
+          ...Object.keys(coverage.resourceSelectors || {}),
+          ...Object.keys(affected.resourceSelectors || {}),
+        ])
+      )
+        .sort()
+        .map(key => [
+          key,
+          Array.from(
+            new Set([
+              ...splitList(releaseTargets.resourceSelectors?.[key]),
+              ...splitList(coverage.resourceSelectors?.[key]),
+              ...splitList(affected.resourceSelectors?.[key]),
+            ])
+          ).sort(),
+        ])
+    ),
     resources: Boolean(releaseTargets.resources || coverage.resources || affected.resources),
     runtime: Boolean(releaseTargets.runtime || coverage.runtime || affected.runtime),
     other: Array.from(new Set(splitList(releaseTargets.other))).sort(),
@@ -2854,6 +3003,7 @@ module.exports = {
   proposeQuickSddChange,
   proposeSddChange,
   recordSddReleaseSourceRevision,
+  renderSddDocumentation,
   approveSddChange,
   syncSddChange,
   validateQuickSddScope,