openxiangda 1.0.178 → 1.0.180

package/README.md

@@ -1,4 +1,4 @@
-<!-- OpenXiangda-Policy-Version: 3 -->
+<!-- OpenXiangda-Policy-Version: 4 -->
 # OpenXiangda
 
 OpenXiangda is a lightweight CLI and skill package for private low-code platforms.
@@ -48,6 +48,17 @@ openxiangda sdd bundle mainline-release --changes add-customer-page,fix-customer
 openxiangda release publish --change mainline-release --profile dev
 openxiangda release status --change mainline-release --watch
 openxiangda release explain --change mainline-release --profile dev
+# 环境托管应用一次性登记（已有应用通常作为 preproduction）
+openxiangda environment init --logical-app example-app --name "示例应用" --kind preproduction --app-type APP_PRE --profile dev
+openxiangda environment bind production --app-type APP_PROD --profile dev
+openxiangda environment attach --logical-app example-app --preproduction-target example-pre --production-target example-prod --profile dev
+openxiangda environment status --json
+openxiangda studio
+# 环境托管应用日常发布：冻结候选 → 预发 → 测试证据 → 同候选晋级正式
+openxiangda release candidate --change mainline-release --environment preproduction
+openxiangda release deploy --candidate <candidate-id> --environment preproduction
+openxiangda release test --deployment <deployment-id> --environment preproduction --evidence-json ./test-evidence.json
+openxiangda release promote --candidate <candidate-id> --environment production --confirm-production
 openxiangda policy check
 openxiangda resource explain public-access --json
 openxiangda inspect app --profile dev --json
@@ -56,6 +67,12 @@ 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 profile-specific resource IDs; 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 candidate` seals the clean authoritative Git revision, exact changed files, resource targets, SDD change, and test plan into an immutable candidate. `release deploy` can only deploy it to preproduction. `release test` attaches deployment-bound, hash-verified evidence. `release promote` can only promote that exact candidate to production after the platform verifies fresh passing preproduction evidence and zero candidate drift. Direct `release publish` is retained only for legacy, unmanaged workspaces and fails closed for either target of an environment-managed application.
+
+Existing workspaces connect to a server-side environment set with `environment attach`. If the legacy `profiles.<profile>` binding has the same `appType` as one environment, its resource mappings are copied only into that matching target (normally preproduction). Production starts with an empty mapping, and later writes update only the selected target even when both targets reuse one login profile.
+
+`openxiangda studio` starts a loopback-only local Developer Center with a random session token. It shows target bindings, candidate/deployment status, Git state, test evidence, drift, and the next safe action. Its buttons invoke only registered OpenXiangda operations; it does not expose arbitrary shell execution. Production promotion and rollback still require an explicit production confirmation.
+
 `resource plan` and `resource publish --dry-run` run behind a strict GET/HEAD-only HTTP guard. If a read receives HTTP 401, the command fails with `READ_ONLY_AUTH_REQUIRED` and never calls the token refresh POST from inside the plan. Run `openxiangda auth refresh --profile <name>` (or log in again) before retrying; a plan must not mutate auth state or platform resources.
 
 For Function/Automation plans, `formFieldContracts` checks statically declared

package/lib/application-environments.js

@@ -0,0 +1,282 @@
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const ENVIRONMENT_KINDS = new Set(['preproduction', 'production']);
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(item => canonicalJson(item)).join(',')}]`;
+  }
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value)
+      .sort()
+      .map(key => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sha256Canonical(value) {
+  return crypto.createHash('sha256').update(canonicalJson(value)).digest('hex');
+}
+
+function normalizeEnvironmentKind(value, label = 'environment') {
+  const kind = String(value || '').trim().toLowerCase();
+  if (!ENVIRONMENT_KINDS.has(kind)) {
+    throw new Error(`${label} 必须是 preproduction 或 production`);
+  }
+  return kind;
+}
+
+function normalizeTargetName(value, kind) {
+  const targetName = String(value || kind || '').trim();
+  if (!/^[a-z][a-z0-9-]*$/.test(targetName)) {
+    throw new Error(
+      'target 名称必须以小写字母开头，且只包含小写字母、数字和连字符'
+    );
+  }
+  return targetName;
+}
+
+function cloneJsonValue(value) {
+  return value === undefined
+    ? undefined
+    : JSON.parse(JSON.stringify(value));
+}
+
+function hasStateResourceMappings(value) {
+  if (Array.isArray(value)) return value.length > 0;
+  if (!value || typeof value !== 'object') {
+    return value !== undefined && value !== null && value !== '';
+  }
+  return Object.values(value).some(item => hasStateResourceMappings(item));
+}
+
+function resolveEnvironmentTarget(state, selector) {
+  const targets = state?.targets || {};
+  const requested = String(selector || state?.currentTarget || '').trim();
+  if (!requested) {
+    throw new Error(
+      '当前工作区已启用应用环境，请显式使用 --environment <target|preproduction|production>'
+    );
+  }
+  if (targets[requested]) {
+    return { targetName: requested, binding: targets[requested] };
+  }
+  const matches = Object.entries(targets).filter(
+    ([, binding]) => binding?.kind === requested
+  );
+  if (matches.length !== 1) {
+    throw new Error(`应用环境 target 不存在或不唯一: ${requested}`);
+  }
+  return { targetName: matches[0][0], binding: matches[0][1] };
+}
+
+function bindEnvironmentTarget(state, input) {
+  const kind = normalizeEnvironmentKind(input.kind);
+  const targetName = normalizeTargetName(input.targetName, kind);
+  const appType = String(input.appType || '').trim();
+  const profile = String(input.profile || '').trim();
+  const environmentId = String(input.environmentId || '').trim();
+  if (!appType || !profile || !environmentId) {
+    throw new Error('环境 target 缺少 appType、profile 或 environmentId');
+  }
+  state.targets = state.targets || {};
+  const previous = state.targets[targetName] || {};
+  const previousResources = previous.resources || {};
+  const resources = hasStateResourceMappings(previousResources)
+    ? previousResources
+    : cloneJsonValue(input.seedResources || previousResources) || {};
+  state.targets[targetName] = {
+    ...previous,
+    targetName,
+    profile,
+    environmentId,
+    kind,
+    appType,
+    displayName: input.displayName || previous.displayName || kind,
+    publicOrigin:
+      input.publicOrigin === undefined
+        ? previous.publicOrigin || null
+        : input.publicOrigin,
+    sideEffectPolicy:
+      input.sideEffectPolicy === undefined
+        ? previous.sideEffectPolicy || {}
+        : input.sideEffectPolicy,
+    resources,
+    updatedAt: new Date().toISOString(),
+  };
+  if (!state.currentTarget || kind === 'preproduction') {
+    state.currentTarget = targetName;
+  }
+  return state.targets[targetName];
+}
+
+function resolveManagedStateBinding(target) {
+  if (!target?.targetName) return null;
+  const binding = target.state?.targets?.[target.targetName];
+  if (!binding) {
+    throw new Error(`环境 target 状态不存在: ${target.targetName}`);
+  }
+  if (
+    binding.appType !== target.appType ||
+    (target.environmentId &&
+      binding.environmentId !== target.environmentId)
+  ) {
+    throw new Error(
+      `环境 target 状态与当前写入目标不一致: ${target.targetName}`
+    );
+  }
+  return binding;
+}
+
+function candidateDirectory(cwd = process.cwd()) {
+  return path.join(cwd, '.openxiangda', 'candidates');
+}
+
+function candidateFile(candidateId, cwd = process.cwd()) {
+  const normalized = String(candidateId || '').trim();
+  if (!/^[0-9a-f-]{36}$/i.test(normalized)) {
+    throw new Error('candidateId 必须是 UUID');
+  }
+  return path.join(candidateDirectory(cwd), `${normalized}.json`);
+}
+
+function writePrivateJsonAtomic(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  fs.renameSync(temp, file);
+}
+
+function saveCandidate(candidate, cwd = process.cwd()) {
+  if (!candidate?.id) throw new Error('候选版本缺少 id');
+  const file = candidateFile(candidate.id, cwd);
+  writePrivateJsonAtomic(file, candidate);
+  return file;
+}
+
+function readCandidate(candidateId, cwd = process.cwd()) {
+  const file = candidateFile(candidateId, cwd);
+  if (!fs.existsSync(file)) {
+    throw new Error(
+      `本地候选版本不存在: ${path.relative(cwd, file)}；请先执行 release candidate`
+    );
+  }
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    throw new Error(`候选版本文件无效: ${error.message}`);
+  }
+}
+
+function readJsonInput(value, label, cwd = process.cwd()) {
+  const input = String(value || '').trim();
+  if (!input) throw new Error(`${label} 不能为空`);
+  const possibleFile = path.resolve(cwd, input);
+  const text = fs.existsSync(possibleFile)
+    ? fs.readFileSync(possibleFile, 'utf8')
+    : input;
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`${label} 必须是 JSON 或 JSON 文件: ${error.message}`);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${label} 必须是 JSON 对象`);
+  }
+  return parsed;
+}
+
+function hashWorkspaceFile(cwd, relativePath) {
+  const normalized = String(relativePath || '').replace(/\\/g, '/');
+  const absolute = path.resolve(cwd, normalized);
+  const relative = path.relative(cwd, absolute);
+  if (
+    !normalized ||
+    relative.startsWith('..') ||
+    path.isAbsolute(relative) ||
+    !fs.existsSync(absolute) ||
+    !fs.statSync(absolute).isFile()
+  ) {
+    return null;
+  }
+  const buffer = fs.readFileSync(absolute);
+  return {
+    path: normalized,
+    size: buffer.length,
+    sha256: crypto.createHash('sha256').update(buffer).digest('hex'),
+  };
+}
+
+function buildCandidateBundle(input) {
+  const cwd = path.resolve(input.cwd || process.cwd());
+  const files = Array.from(new Set(input.files || []))
+    .sort()
+    .map(file => hashWorkspaceFile(cwd, file))
+    .filter(Boolean);
+  const testPlan = input.testPlan || {
+    schemaVersion: 1,
+    requiredGates: [
+      'static',
+      'schema',
+      'appFunctions',
+      'roles',
+      'browser',
+      'lifecycle',
+      'cleanup',
+    ],
+    maximumEvidenceAgeHours: 24,
+  };
+  const sourceBundleManifest = {
+    schemaVersion: 1,
+    logicalAppCode: input.logicalAppCode,
+    changeId: input.changeId,
+    sourceRevision: input.sourceRevision,
+    runtimeMode: input.runtimeMode,
+    targets: input.targets,
+    files,
+    testPlanHash: sha256Canonical(testPlan),
+    openxiangdaVersion: input.openxiangdaVersion,
+  };
+  return {
+    sourceBundleManifest,
+    candidateHash: sha256Canonical(sourceBundleManifest),
+    testPlan,
+    testPlanHash: sourceBundleManifest.testPlanHash,
+  };
+}
+
+function releaseExecutionPath(changeId, deploymentId, cwd = process.cwd()) {
+  const base = path.join(
+    cwd,
+    '.openxiangda',
+    'releases',
+    String(changeId || '').trim()
+  );
+  const deployment = String(deploymentId || '').trim();
+  return deployment
+    ? path.join(base, deployment, 'execution.json')
+    : path.join(base, 'execution.json');
+}
+
+module.exports = {
+  bindEnvironmentTarget,
+  buildCandidateBundle,
+  canonicalJson,
+  normalizeEnvironmentKind,
+  normalizeTargetName,
+  hasStateResourceMappings,
+  readCandidate,
+  readJsonInput,
+  releaseExecutionPath,
+  resolveManagedStateBinding,
+  resolveEnvironmentTarget,
+  saveCandidate,
+  sha256Canonical,
+  writePrivateJsonAtomic,
+};