openxiangda 1.0.213 → 1.0.215

package/README.md

@@ -82,7 +82,7 @@ openxiangda app snapshot APP_XXXX --profile dev --json
 
 User tokens are stored in `~/.openxiangda/profiles.json` with `0600` permissions. Shared workspace environment values, including `APP_OSS_*`, can live in `~/.openxiangda/.env` and are inherited by new workspaces. Project `.env` files still work and override the global defaults. Project state is stored in `.openxiangda/state.json` and contains only durable profile-specific resource IDs and environment bindings; volatile candidate/deployment progress lives in the private `.openxiangda/releases/` journal so a release does not dirty the reviewed Git state. Durable CLI writes use a workspace lock plus atomic merge/rename so concurrent processes do not truncate another profile's state.
 
-An environment-managed workspace keeps one logical application with independent `preproduction` and `production` targets. Each target owns its own `appType`, resource IDs, release heads, data, and side-effect policy; IDs must never be copied across targets. `release ship` is deliberately two-phase: the first invocation seals the clean authoritative Git revision and deploys one immutable candidate only to preproduction; it always stops at `awaiting_production_confirmation`. A later invocation includes `--confirm-production` and promotes that exact candidate to production without rebuilding it. Real human acceptance is the recommended default; an optional `--acceptance-note` records it in the deployment evidence, but the platform does not force every low-risk or emergency release through a rigid approval gate. It is impossible to prepare and promote in one invocation. For an audited catch-up whose exact non-delete targets are already merged but whose active resources came from several historical release lineages, the first invocation may explicitly add `--adopt-online-baseline --adoption-reason "..."`; ship validates and freezes this pair before creating a candidate/deployment, then automatically reuses it during the later production confirmation and forwards it only to exact scoped resource stages. A reviewed complete Function/Automation manifest replacement may similarly add the inseparable `--replace-manifest --reason "..."` pair; ship forwards it only to an exact Backend stage and requires the production confirmation to repeat the exact preproduction intent. Frozen online heads, change/lease ownership, server CAS, staged children, and the single App finalize remain mandatory. Supported configuration resources use exact `resourceSelectors`; a legacy `resources=true` category marker is narrowed by those selectors, while unknown, wildcard, destructive, and genuinely unscoped generic resources remain blocked. The lower-level `candidate/deploy/test/promote` commands remain available for recovery and diagnostics. Direct `release publish` is retained only for legacy, unmanaged workspaces and fails closed for either target of an environment-managed application.
+An environment-managed workspace keeps one logical application with independent `preproduction` and `production` targets. Each target owns its own `appType`, resource IDs, release heads, data, and side-effect policy; IDs must never be copied across targets. `release ship` always executes the same ordered candidate → preproduction → production protocol. The normal first invocation seals the candidate, deploys only to preproduction, and stops at `awaiting_production_confirmation`; a later invocation with `--confirm-production` promotes it. For an explicitly authorized emergency, supplying `--confirm-production` on the first invocation runs both phases in one command without bypassing preproduction, CAS, evidence, or production confirmation. Candidate sealing covers source, `public/`, build controls/scripts, stable environment/resource bindings, and target-specific hashed Runtime artifacts. Both deployments upload those artifacts with `--no-build`; each deployment is completed with evidence and reaches terminal `succeeded`, so it cannot leave the target slot blocked. Unrelated commits may land on authoritative mainline between phases only while the sealed commit remains an ancestor and every sealed input/binding/artifact still validates. Real human acceptance remains the recommended default and `--acceptance-note` records it. For audited historical-lineage adoption or reviewed Backend manifest replacement, the existing paired flags and exact-scope gates remain mandatory. Supported configuration resources use exact `resourceSelectors`; unknown, wildcard, destructive, and genuinely unscoped generic resources remain blocked. Lower-level candidate/deploy/test/promote commands are recovery primitives. Direct `release publish` is retained only for legacy unmanaged workspaces.
 
 Exact, non-destructive configuration selectors such as Data Views and permission groups are now sequenced automatically inside the same ship journal instead of requiring separate SDD changes. New forms are idempotently ensured per environment before their immutable FormRelease is staged. Unscoped resources and destructive configuration deletes remain fail-closed.
 
@@ -108,6 +108,8 @@ Parallel tasks develop and test in isolated worktrees, but feature worktrees do
 
 Because promotion starts from an already-pushed authoritative mainline commit, `openxiangda release integration-status --change <change> --profile <name>` should pass immediately after activation. After a managed ship has ended, `--change` recovers lineage directly from the private `ship.json` or follows its production/preproduction deployment IDs to the matching `execution.json`; a recovery failure names the missing file or field. Run it and `release end`; there is no post-release merge step.
 
+Task worktrees are disposable only after the release lifecycle is closed. From the synchronized canonical main checkout, run `openxiangda workspace cleanup` for a dry-run inventory. A worktree is `SAFE` only when it is OpenXiangda/Codex-managed, its commit is contained in live remote mainline, it is clean and unowned, and it has no private candidate/release journal or promotion lease/baseline. `--apply` is bound to the exact hashed dry-run plan, revalidates under the worktree owner lock, and removes only those reviewed entries plus their unchanged local branches. Newly-safe worktrees are left for the next review. Malformed owner state fails closed. Stale records are reported for explicit manual review because the CLI never runs repository-wide `git worktree prune`. Remote branches are retained.
+
 `openxiangda task status --change <id>` is the compact, read-only answer to
 “现在到哪一步”：it combines SDD、TaskResult、IntegrationBundle、execution
 journal、lease 和 post-commit outbox，输出进度、ETA、是否已经发生平台写入、
@@ -175,6 +177,8 @@ L1 quick records are generated in a compact form and should not be expanded into
 
 Every concurrent task uses its own Git worktree/branch and development change. The canonical main checkout is reserved for integration and release; tasks never stash/restore each other's files to make it publishable. The mainline release coordinator bundles selected approved changes after merge; dependency impact outside the approved scope is reported as a warning rather than silently widening a small release. Live commands still require canonical exact selectors, and app-wide/delete operations need explicit authority.
 
+After the mainline release and `release end`, the coordinator runs `workspace cleanup` from canonical main and applies only `SAFE` entries. Dirty/unmerged/owned worktrees and worktrees with private release or promotion state remain blocked for recovery.
+
 Agent investigation is bounded to one complete CodeGraph survey plus at most one focused follow-up, and ordinary work loads one domain skill. Unchanged lease/build waits use `task status --watch` and produce updates only on material transitions.
 
 Before confirmation, agents may read, inspect, snapshot, dry-run, ask questions, and output/write the architecture document. They must not edit source files, mutate platform resources, publish, deploy, send notifications, or call live write/delete endpoints.
@@ -502,7 +506,7 @@ const PublicAccessError = ({ error }: { error: { message?: string } }) => (
 
 多表只读查询和固定口径统计优先声明 `src/resources/data-views/*.json` 数据视图，而不是在页面里手写多次单表查询再拼数据。默认 `storageMode: "materialized"` 会创建 PostgreSQL materialized view，适合读多写少和可接受刷新延迟的列表/报表；`storageMode: "live"` 每次查询实时编译逻辑视图，适合强实时但数据量可控的复杂查询。`viewType: "aggregate"` 是统计聚合视图，适合按客户、状态、月份等维度聚合 count/sum/avg/min/max。发布时 CLI 会把 `formCode` 解析为当前 profile 的 `formUuid`；页面通过 `sdk.dataView.query(code, params)` 查询行级视图，通过 `sdk.dataView.stats(code, params)` 查询聚合视图，也可以用 `sdk.dataSource.run()` 路由 `dataView.query` / `dataView.stats`。materialized 模式应为常用筛选、排序、统计维度和时间桶声明 `indexes`，并确认用户能接受的刷新延迟；live 模式忽略 `indexes`，不需要刷新。
 
-后端业务逻辑优先声明为 App Function：源码放在 `src/functions/<functionCode>/index.ts`，资源 manifest 放在 `src/resources/functions/<functionCode>.json`。函数运行在 trusted_node 中，通过 `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`、`ctx.dataView`、`ctx.connector`、`ctx.notification`、`ctx.organization`、`ctx.platform.roles`、`ctx.platform.api` 等受控 API 访问平台能力；自动化、流程和运行时接口都可以调用同一个 function。角色查询和角色成员维护优先使用 `ctx.platform.roles.list/findByCode/addUsers/removeUser`，底层 `ctx.platform.api` 返回 HTTP 包装和平台 envelope，需要业务代码自行解包。运行时页面调用会在 `ctx.operator`、`ctx.currentUser`、`ctx.permissions` 中注入可信的 `roleCodes`、`currentRoleCode`、`hasFullAccess`、`isAppAdmin`、`isPlatformAdmin`，敏感动作必须读取这些服务端上下文做授权，不要信任页面 input 里传入的角色字段。`ctx.form.createOne/updateOne/updateById` 是后端受控写入，授权边界是函数 manifest 的 `resources.forms` 绑定和函数调用授权，不是页面用户对目标表单的直接提交入口；报名、签到、福利选择等内部多表写入应走 App Function，不要为了写内部表单给普通用户开放原始 submit 权限。JS_CODE V2 仍兼容，但新逻辑建议写成 function，再由 `function_call` 节点、`sdk.function.invoke(code, { input })` 或 `/:appType/v1/functions/:code/invoke.json` 调用。直接运行时接口默认要求调用者具备应用自动化管理权限；普通页面调用必须在函数 `definitionJson.runtimeInvoke.audience` 声明 `authenticated`、`page_permission_group`、`app_roles` 或 `scope_policy`，`roleCodes` 只用于当前应用角色精确匹配，不支持 `"*"` / `"all-app-roles"`。自动化/流程内部调用走服务端受控上下文。内部业务表单需要关闭原始写入接口时，在表单 settings 中设置 `runtimeWrite.mode="function_only"`。
+后端业务逻辑优先声明为 App Function：源码放在 `src/functions/<functionCode>/index.ts`，资源 manifest 放在 `src/resources/functions/<functionCode>.json`。函数运行在 trusted_node 中，通过 `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`、`ctx.process.startFromExistingInstance/resolveCapabilities/resubmitTask/withdraw/transferTask`、`ctx.dataView`、`ctx.connector`、`ctx.notification`、`ctx.organization`、`ctx.platform.roles`、`ctx.platform.api` 等受控 API 访问平台能力；自动化、流程和运行时接口都可以调用同一个 function。`ctx.process` 复用正式工作流服务，以真实运行时 operator 执行，并严格限制在当前应用及 Function `resources.forms` 已绑定的流程表单；流程实例、任务授权、操作日志、事件和 replay 语义与 PageSdk 后端接口一致。角色查询和角色成员维护优先使用 `ctx.platform.roles.list/findByCode/addUsers/removeUser`，底层 `ctx.platform.api` 返回 HTTP 包装和平台 envelope，需要业务代码自行解包。运行时页面调用会在 `ctx.operator`、`ctx.currentUser`、`ctx.permissions` 中注入可信的 `roleCodes`、`currentRoleCode`、`hasFullAccess`、`isAppAdmin`、`isPlatformAdmin`，敏感动作必须读取这些服务端上下文做授权，不要信任页面 input 里传入的角色字段。`ctx.form.createOne/updateOne/updateById` 是后端受控写入，授权边界是函数 manifest 的 `resources.forms` 绑定和函数调用授权，不是页面用户对目标表单的直接提交入口；报名、签到、福利选择等内部多表写入应走 App Function，不要为了写内部表单给普通用户开放原始 submit 权限。JS_CODE V2 仍兼容，但新逻辑建议写成 function，再由 `function_call` 节点、`sdk.function.invoke(code, { input })` 或 `/:appType/v1/functions/:code/invoke.json` 调用。直接运行时接口默认要求调用者具备应用自动化管理权限；普通页面调用必须在函数 `definitionJson.runtimeInvoke.audience` 声明 `authenticated`、`page_permission_group`、`app_roles` 或 `scope_policy`，`roleCodes` 只用于当前应用角色精确匹配，不支持 `"*"` / `"all-app-roles"`。自动化/流程内部调用走服务端受控上下文。内部业务表单需要关闭原始写入接口时，在表单 settings 中设置 `runtimeWrite.mode="function_only"`。
 
 App Function 访问第三方凭据时使用 `app_function_secrets_v1`：manifest 顶层只声明 `secretRefs: [{ "name": "dingtalk_org_app_key", "required": true }]`，同时使用 `definitionJson.version="function_v2"`、`runtimeContractVersion="trusted_node_v2"`；源码通过 `await ctx.secrets.get(name)` 解析，并通过 `ctx.utils.http` 访问受控公网 HTTPS（该桥接不会携带平台 Runtime token）。值只能经 `openxiangda secret create|rotate --value-stdin --change <id> --profile <name>` 或隐藏 TTY 输入，禁止进入 Git、manifest、源码、构建产物、plan、日志或异常。带 `secretRefs` 的 Function 必须走 `backend_release_v2`；需要整应用原子发布时先执行 `resource publish function --only <code> --stage-only`，再把返回的真实 `stagedResource` 交给 `release app-finalize --staged-resources-json ...` 完成 `atomic_staged_children_v2`。默认直接激活的 Backend Release 只返回 `activeResource`，不会伪装成 staged；旧平台 capability 不完整时 CLI 会失败关闭，绝不忽略绑定。
 

package/lib/application-environments.js

@@ -570,20 +570,163 @@ function hashWorkspaceFile(cwd, relativePath) {
   if (
     !normalized ||
     relative.startsWith('..') ||
-    path.isAbsolute(relative) ||
-    !fs.existsSync(absolute) ||
-    !fs.statSync(absolute).isFile()
+    path.isAbsolute(relative)
   ) {
     return null;
   }
+  if (!fs.existsSync(absolute)) {
+    return {
+      path: normalized,
+      exists: false,
+      size: 0,
+      sha256: null,
+    };
+  }
+  if (!fs.statSync(absolute).isFile()) return null;
   const buffer = fs.readFileSync(absolute);
   return {
     path: normalized,
+    exists: true,
     size: buffer.length,
     sha256: crypto.createHash('sha256').update(buffer).digest('hex'),
   };
 }
 
+function buildCandidateEnvironmentBindings(state) {
+  const targets =
+    state?.targets && typeof state.targets === 'object'
+      ? state.targets
+      : {};
+  return Object.fromEntries(
+    Object.entries(targets)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([targetName, binding]) => [
+        targetName,
+        {
+          targetName,
+          profile: binding?.profile || null,
+          environmentId: binding?.environmentId || null,
+          kind: binding?.kind || null,
+          appType: binding?.appType || null,
+          publicOrigin: binding?.publicOrigin || null,
+          sideEffectPolicy:
+            cloneJsonValue(binding?.sideEffectPolicy || {}) || {},
+          revision:
+            binding?.revision === undefined
+              ? null
+              : binding.revision,
+          resources: cloneJsonValue(binding?.resources || {}) || {},
+        },
+      ])
+  );
+}
+
+function candidateBindingValueContains(expected, current) {
+  if (Array.isArray(expected)) {
+    return (
+      Array.isArray(current) &&
+      expected.length === current.length &&
+      expected.every((item, index) =>
+        candidateBindingValueContains(item, current[index])
+      )
+    );
+  }
+  if (expected && typeof expected === 'object') {
+    if (!current || typeof current !== 'object' || Array.isArray(current)) {
+      return false;
+    }
+    return Object.entries(expected).every(([key, value]) =>
+      candidateBindingValueContains(value, current[key])
+    );
+  }
+  return expected === current;
+}
+
+function inspectCandidateEnvironmentBindings(candidate, state) {
+  const expected =
+    candidate?.sourceBundleManifest?.environmentBindings ||
+    candidate?.environmentBindings ||
+    {};
+  const current = buildCandidateEnvironmentBindings(state);
+  const mismatches = [];
+  const expectedNames = Object.keys(expected).sort();
+  const currentNames = Object.keys(current).sort();
+  if (canonicalJson(expectedNames) !== canonicalJson(currentNames)) {
+    mismatches.push({
+      targetName: '(targets)',
+      reason: 'target-set-changed',
+      expected: expectedNames,
+      current: currentNames,
+    });
+  }
+  for (const targetName of expectedNames) {
+    const expectedBinding = expected[targetName];
+    const currentBinding = current[targetName];
+    if (!currentBinding) continue;
+    for (const field of [
+      'targetName',
+      'profile',
+      'environmentId',
+      'kind',
+      'appType',
+      'publicOrigin',
+      'sideEffectPolicy',
+      'revision',
+    ]) {
+      if (
+        canonicalJson(expectedBinding?.[field]) !==
+        canonicalJson(currentBinding?.[field])
+      ) {
+        mismatches.push({
+          targetName,
+          field,
+          reason: 'changed',
+          expected: expectedBinding?.[field],
+          current: currentBinding?.[field],
+        });
+      }
+    }
+    if (
+      !candidateBindingValueContains(
+        expectedBinding?.resources || {},
+        currentBinding.resources || {}
+      )
+    ) {
+      mismatches.push({
+        targetName,
+        field: 'resources',
+        reason: 'sealed-resource-binding-changed',
+        expected: expectedBinding?.resources || {},
+        current: currentBinding.resources || {},
+      });
+    }
+  }
+  return {
+    valid: mismatches.length === 0,
+    checked: expectedNames.length,
+    mismatches,
+  };
+}
+
+function assertCandidateEnvironmentBindingsCurrent(candidate, state) {
+  const inspection = inspectCandidateEnvironmentBindings(candidate, state);
+  if (inspection.valid) return inspection;
+  const error = new Error(
+    `CANDIDATE_ENVIRONMENT_BINDINGS_CHANGED: sealed candidate 的环境或资源绑定已变化: ${inspection.mismatches
+      .slice(0, 8)
+      .map(
+        item =>
+          `${item.targetName}${
+            item.field ? `.${item.field}` : ''
+          }(${item.reason})`
+      )
+      .join(', ')}`
+  );
+  error.code = 'CANDIDATE_ENVIRONMENT_BINDINGS_CHANGED';
+  error.details = inspection;
+  throw error;
+}
+
 function buildCandidateBundle(input) {
   const cwd = path.resolve(input.cwd || process.cwd());
   const files = Array.from(new Set(input.files || []))
@@ -610,10 +753,17 @@ function buildCandidateBundle(input) {
     sourceRevision: input.sourceRevision,
     runtimeMode: input.runtimeMode,
     targets: input.targets,
+    inputPolicy: 'candidate-inputs-v2',
     files,
+    environmentBindings:
+      cloneJsonValue(input.environmentBindings || {}) || {},
+    runtimeArtifacts:
+      cloneJsonValue(input.runtimeArtifacts || []) || [],
     testPlanHash: sha256Canonical(testPlan),
     prepublishVerificationHash:
       input.prepublishVerificationHash || null,
+    candidatePreflightHash:
+      input.candidatePreflightHash || null,
     openxiangdaVersion: input.openxiangdaVersion,
   };
   return {
@@ -624,6 +774,75 @@ function buildCandidateBundle(input) {
   };
 }
 
+function inspectCandidateBundleFiles(candidate, cwd = process.cwd()) {
+  const manifest =
+    candidate?.sourceBundleManifest &&
+    typeof candidate.sourceBundleManifest === 'object'
+      ? candidate.sourceBundleManifest
+      : candidate;
+  const expectedFiles = Array.isArray(manifest?.files)
+    ? manifest.files
+    : [];
+  const mismatches = [];
+  const seen = new Set();
+  for (const expected of expectedFiles) {
+    const file = String(expected?.path || '').replace(/\\/g, '/');
+    if (!file || seen.has(file)) {
+      mismatches.push({
+        path: file || '(missing path)',
+        reason: seen.has(file) ? 'duplicate' : 'invalid',
+      });
+      continue;
+    }
+    seen.add(file);
+    const current = hashWorkspaceFile(path.resolve(cwd), file);
+    const expectedExists = expected.exists !== false;
+    if (!current || (expectedExists && current.exists === false)) {
+      mismatches.push({ path: file, reason: 'missing' });
+      continue;
+    }
+    if (!expectedExists) {
+      if (current.exists !== false) {
+        mismatches.push({ path: file, reason: 'reappeared', current });
+      }
+      continue;
+    }
+    if (
+      current.size !== Number(expected.size) ||
+      current.sha256 !== String(expected.sha256 || '').toLowerCase()
+    ) {
+      mismatches.push({
+        path: file,
+        reason: 'changed',
+        expected: {
+          size: Number(expected.size),
+          sha256: String(expected.sha256 || '').toLowerCase(),
+        },
+        current,
+      });
+    }
+  }
+  return {
+    valid: mismatches.length === 0,
+    checked: expectedFiles.length,
+    mismatches,
+  };
+}
+
+function assertCandidateBundleFilesCurrent(candidate, cwd = process.cwd()) {
+  const inspection = inspectCandidateBundleFiles(candidate, cwd);
+  if (inspection.valid) return inspection;
+  const error = new Error(
+    `CANDIDATE_INPUTS_CHANGED: sealed candidate 的发布输入已变化: ${inspection.mismatches
+      .slice(0, 8)
+      .map(item => `${item.path}(${item.reason})`)
+      .join(', ')}`
+  );
+  error.code = 'CANDIDATE_INPUTS_CHANGED';
+  error.details = inspection;
+  throw error;
+}
+
 function releaseExecutionPath(changeId, deploymentId, cwd = process.cwd()) {
   const base = path.join(
     cwd,
@@ -706,7 +925,10 @@ function isRecoverablePostActivationDeploymentError(error, deployment) {
 }
 
 module.exports = {
+  assertCandidateBundleFilesCurrent,
+  assertCandidateEnvironmentBindingsCurrent,
   bindEnvironmentTarget,
+  buildCandidateEnvironmentBindings,
   buildSideEffectPolicyDiff,
   buildCandidateBundle,
   canonicalJson,
@@ -718,6 +940,8 @@ module.exports = {
   normalizeSideEffectPolicyInput,
   normalizeTargetName,
   hasStateResourceMappings,
+  inspectCandidateBundleFiles,
+  inspectCandidateEnvironmentBindings,
   managedTargetDeploymentFile,
   readCandidate,
   readJsonInput,