@aipt/idp-deploy 0.1.2

package/src/gitops.mjs

@@ -0,0 +1,285 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { parse as parseYaml } from 'yaml';
+import { IdpError, invariant } from './errors.mjs';
+import { hashFile, inventoryDirectory, sha256, stableJson } from './hash.mjs';
+import { buildContract, validateReleaseCandidate } from './foundation-contracts.mjs';
+
+const NAME = /^[a-z][a-z0-9-]{1,62}$/u;
+const ENVIRONMENT = /^[a-z][a-z0-9-]{1,62}$/u;
+const DIGEST = /^sha256:[0-9a-f]{64}$/u;
+const PINNED_IMAGE = /^([^\s@]+)@(sha256:[0-9a-f]{64})$/u;
+
+function exactObject(value, fields, role) {
+  invariant(value && typeof value === 'object' && !Array.isArray(value), 'IDP_GITOPS_INPUT_INVALID', `${role}必须是对象`);
+  invariant(stableJson(Object.keys(value).sort()) === stableJson([...fields].sort()), 'IDP_GITOPS_INPUT_INVALID', `${role}字段集合无效`);
+}
+
+function readDocumentFile(candidate, role) {
+  invariant(path.isAbsolute(candidate ?? ''), 'IDP_GITOPS_PATH_NOT_ABSOLUTE', `${role}必须使用绝对路径`);
+  const resolved = path.resolve(candidate);
+  const stat = fs.lstatSync(resolved, { throwIfNoEntry: false });
+  invariant(stat?.isFile() && !stat.isSymbolicLink() && stat.nlink === 1 && stat.size > 1 && stat.size <= 4 * 1024 * 1024, 'IDP_GITOPS_INPUT_UNSAFE', `${role}必须是1 byte到4 MiB的普通非链接文件`);
+  try { return { path: resolved, digest: hashFile(resolved), value: parseYaml(fs.readFileSync(resolved, 'utf8'), { maxAliasCount: 0, uniqueKeys: true }) }; }
+  catch (error) { throw new IdpError('IDP_GITOPS_DOCUMENT_INVALID', `${role}不是有效JSON或YAML`, { cause: error.message }); }
+}
+
+function validateComponent(document) {
+  exactObject(document, ['apiVersion', 'kind', 'metadata', 'spec'], 'ComponentContract');
+  invariant(document.apiVersion === 'idp.company.io/v1alpha1' && document.kind === 'ComponentContract', 'IDP_GITOPS_COMPONENT_INVALID', 'ComponentContract版本或kind无效');
+  invariant(NAME.test(document.metadata?.name ?? '') && typeof document.metadata.version === 'string', 'IDP_GITOPS_COMPONENT_INVALID', 'ComponentContract metadata无效');
+  const image = document.spec?.image;
+  invariant(Number.isInteger(image?.port) && image.port > 0 && image.port < 65536, 'IDP_GITOPS_COMPONENT_INVALID', 'ComponentContract image.port无效');
+  invariant(stableJson(image.platforms) === stableJson(['linux/amd64', 'linux/arm64']), 'IDP_GITOPS_COMPONENT_INVALID', 'ComponentContract必须支持amd64与arm64');
+  invariant(typeof document.spec?.health?.liveness === 'string' && document.spec.health.liveness.startsWith('/'), 'IDP_GITOPS_COMPONENT_INVALID', 'ComponentContract liveness无效');
+  invariant(typeof document.spec?.health?.readiness === 'string' && document.spec.health.readiness.startsWith('/'), 'IDP_GITOPS_COMPONENT_INVALID', 'ComponentContract readiness无效');
+  invariant(document.spec?.runtime?.stateless === true, 'IDP_GITOPS_COMPONENT_INVALID', '首批GitOps Renderer只接收无状态应用');
+  invariant(Number.isInteger(document.spec.runtime.runAsUser) && document.spec.runtime.runAsUser > 0, 'IDP_GITOPS_COMPONENT_INVALID', 'ComponentContract必须声明非root runAsUser');
+  invariant(Number.isInteger(document.spec.runtime.runAsGroup) && document.spec.runtime.runAsGroup > 0, 'IDP_GITOPS_COMPONENT_INVALID', 'ComponentContract必须声明非root runAsGroup');
+  invariant(document.spec.runtime.args === undefined || (Array.isArray(document.spec.runtime.args) && document.spec.runtime.args.every((entry) => typeof entry === 'string' && entry.length > 0)), 'IDP_GITOPS_COMPONENT_INVALID', 'ComponentContract runtime.args无效');
+  return document;
+}
+
+function validateUrl(value, role) {
+  let parsed;
+  try { parsed = new URL(value); } catch { throw new IdpError('IDP_GITOPS_BINDING_INVALID', `${role}不是有效URL`); }
+  invariant(['https:', 'http:'].includes(parsed.protocol) && !parsed.username && !parsed.password, 'IDP_GITOPS_BINDING_INVALID', `${role}只能使用不含凭据的HTTP(S) URL`);
+}
+
+export function validateEnvironmentBinding(document) {
+  const forbidden = /(?:password|passwd|secretvalue|token|privatekey|accesskey|kubeconfig)/iu;
+  const inspect = (value, keyPath = '') => {
+    if (Array.isArray(value)) return value.forEach((entry, index) => inspect(entry, `${keyPath}[${index}]`));
+    if (!value || typeof value !== 'object') return;
+    for (const [key, child] of Object.entries(value)) {
+      invariant(!forbidden.test(key), 'IDP_GITOPS_BINDING_INVALID', `EnvironmentBinding包含敏感字段：${keyPath}${key}`);
+      inspect(child, `${keyPath}${key}.`);
+    }
+  };
+  inspect(document);
+  invariant(document?.apiVersion === 'infrastructure.bench.dev/v1' && document.kind === 'EnvironmentBinding', 'IDP_GITOPS_BINDING_INVALID', 'EnvironmentBinding版本或kind无效');
+  const metadata = document.metadata;
+  invariant(typeof metadata?.id === 'string' && typeof metadata?.consumer === 'string' && ENVIRONMENT.test(metadata?.environment ?? ''), 'IDP_GITOPS_BINDING_INVALID', 'EnvironmentBinding metadata无效');
+  const capabilities = document.spec?.capabilities;
+  for (const key of ['cluster', 'namespace', 'dns', 'ingress', 'tls', 'secretStore', 'imageRegistry', 'rollout', 'observability']) {
+    invariant(capabilities?.[key] && typeof capabilities[key] === 'object', 'IDP_GITOPS_BINDING_INVALID', `EnvironmentBinding缺少${key}能力`);
+  }
+  invariant(capabilities.cluster.kind === 'kubernetes.cluster' && typeof capabilities.cluster.clusterRef === 'string', 'IDP_GITOPS_BINDING_INVALID', '集群能力无效');
+  validateUrl(capabilities.cluster.server, 'cluster.server');
+  invariant(capabilities.namespace.kind === 'kubernetes.namespace' && NAME.test(capabilities.namespace.name ?? '') && capabilities.namespace.isolation === 'namespace', 'IDP_GITOPS_BINDING_INVALID', 'Namespace能力无效');
+  invariant(capabilities.dns.kind === 'dns.record' && capabilities.dns.controller === 'external-dns' && typeof capabilities.dns.hostname === 'string', 'IDP_GITOPS_BINDING_INVALID', 'DNS能力无效');
+  invariant(capabilities.ingress.kind === 'network.ingress' && capabilities.ingress.controller === 'ingress-nginx' && typeof capabilities.ingress.className === 'string' && ['public', 'internal'].includes(capabilities.ingress.exposure), 'IDP_GITOPS_BINDING_INVALID', 'Ingress能力无效');
+  invariant(capabilities.tls.kind === 'tls.certificate' && capabilities.tls.controller === 'cert-manager' && ['Issuer', 'ClusterIssuer'].includes(capabilities.tls.issuerKind), 'IDP_GITOPS_BINDING_INVALID', 'TLS能力无效');
+  invariant(capabilities.secretStore.kind === 'secret-store.external' && capabilities.secretStore.controller === 'external-secrets', 'IDP_GITOPS_BINDING_INVALID', 'Secret Store能力无效');
+  invariant(capabilities.imageRegistry.kind === 'artifact.oci-registry' && capabilities.imageRegistry.immutableReferenceRequired === true, 'IDP_GITOPS_BINDING_INVALID', '镜像仓能力必须要求不可变引用');
+  invariant(capabilities.rollout.kind === 'deployment.progressive-delivery' && capabilities.rollout.controller === 'argo-rollouts' && ['canary', 'blue-green'].includes(capabilities.rollout.strategy), 'IDP_GITOPS_BINDING_INVALID', 'Rollout能力无效');
+  invariant(capabilities.observability.kind === 'observability.telemetry', 'IDP_GITOPS_BINDING_INVALID', '观测能力无效');
+  validateUrl(capabilities.observability.otlpEndpoint, 'observability.otlpEndpoint');
+  invariant(document.spec?.authority?.contract === 'bench' && document.spec.authority.deploymentTransaction === 'idp-deploy' && document.spec.authority.desiredState === 'gitops', 'IDP_GITOPS_BINDING_INVALID', 'EnvironmentBinding authority无效');
+  return document;
+}
+
+function repositoryHead(root) {
+  invariant(path.isAbsolute(root ?? ''), 'IDP_GITOPS_PATH_NOT_ABSOLUTE', '--gitops-root必须使用绝对路径');
+  const resolved = path.resolve(root);
+  invariant(fs.statSync(resolved, { throwIfNoEntry: false })?.isDirectory(), 'IDP_GITOPS_REPOSITORY_INVALID', 'GitOps仓库不存在');
+  const result = spawnSync('git', ['-C', resolved, 'rev-parse', 'HEAD'], { encoding: 'utf8' });
+  invariant(result.status === 0 && /^[0-9a-f]{40}\n?$/u.test(result.stdout), 'IDP_GITOPS_REPOSITORY_INVALID', 'GitOps目录必须是已有初始提交的Git仓库');
+  return { root: resolved, head: result.stdout.trim() };
+}
+
+function treeState(target) {
+  const stat = fs.lstatSync(target, { throwIfNoEntry: false });
+  if (!stat) return { exists: false, digest: sha256('absent'), files: [] };
+  invariant(stat.isDirectory() && !stat.isSymbolicLink(), 'IDP_GITOPS_TARGET_UNSAFE', 'GitOps应用目标必须是普通目录');
+  const files = inventoryDirectory(target);
+  invariant(!files.some((entry) => entry.unsupported), 'IDP_GITOPS_TARGET_UNSAFE', 'GitOps应用目标包含链接或特殊文件');
+  return { exists: true, digest: sha256(stableJson(files)), files };
+}
+
+const jsonYaml = (value) => `${JSON.stringify(value, null, 2)}\n`;
+
+function render(component, binding, candidate) {
+  const application = component.metadata.name;
+  const environment = binding.metadata.environment;
+  const caps = binding.spec.capabilities;
+  const imageMatch = candidate.image.ref.match(PINNED_IMAGE);
+  invariant(imageMatch && imageMatch[2] === candidate.image.digest, 'IDP_GITOPS_IMAGE_INVALID', '镜像引用与OCI digest不一致');
+  invariant(candidate.application === application && binding.metadata.consumer === application, 'IDP_GITOPS_CROSS_CONTRACT_INVALID', 'Component、Binding与ReleaseCandidate应用不一致');
+  invariant(candidate.rolloutStrategy === caps.rollout.strategy, 'IDP_GITOPS_CROSS_CONTRACT_INVALID', 'ReleaseCandidate与EnvironmentBinding发布策略不一致');
+  invariant(candidate.targetEnvironmentRef === `environment:${environment}@v1`, 'IDP_GITOPS_CROSS_CONTRACT_INVALID', 'ReleaseCandidate目标环境与EnvironmentBinding不一致');
+  invariant(candidate.image.ref.startsWith(`${caps.imageRegistry.registry}/${caps.imageRegistry.repository}@`) || (caps.imageRegistry.registry === 'docker.io' && candidate.image.ref.startsWith(`docker.io/${caps.imageRegistry.repository}@`)), 'IDP_GITOPS_CROSS_CONTRACT_INVALID', 'ReleaseCandidate镜像不属于EnvironmentBinding批准的Registry/Repository');
+  invariant(caps.tls.dnsNames.includes(caps.dns.hostname), 'IDP_GITOPS_CROSS_CONTRACT_INVALID', 'TLS dnsNames必须包含DNS hostname');
+  const container = {
+    name: application,
+    image: `invalid.local/${application}@sha256:${'0'.repeat(64)}`,
+    ...(component.spec.runtime.args ? { args: component.spec.runtime.args } : {}),
+    ports: [{ name: 'http', containerPort: component.spec.image.port, protocol: 'TCP' }],
+    readinessProbe: { httpGet: { path: component.spec.health.readiness, port: 'http' }, periodSeconds: 5, failureThreshold: 6 },
+    livenessProbe: { httpGet: { path: component.spec.health.liveness, port: 'http' }, periodSeconds: 10, failureThreshold: 3 },
+    securityContext: { allowPrivilegeEscalation: false, readOnlyRootFilesystem: true, runAsNonRoot: true, runAsUser: component.spec.runtime.runAsUser, runAsGroup: component.spec.runtime.runAsGroup, capabilities: { drop: ['ALL'] } },
+    resources: { requests: { cpu: '20m', memory: '32Mi' }, limits: { cpu: '200m', memory: '128Mi' } },
+    env: [{ name: 'OTEL_EXPORTER_OTLP_ENDPOINT', value: caps.observability.otlpEndpoint }],
+  };
+  const strategy = caps.rollout.strategy === 'canary'
+    ? { canary: { stableService: `${application}-stable`, canaryService: `${application}-canary`, steps: [{ setWeight: 10 }, { pause: { duration: '30s' } }, { setWeight: 50 }, { pause: { duration: '60s' } }] } }
+    : { blueGreen: { activeService: `${application}-stable`, previewService: `${application}-preview`, autoPromotionEnabled: caps.rollout.promotion === 'automatic' } };
+  const rollout = {
+    apiVersion: 'argoproj.io/v1alpha1', kind: 'Rollout', metadata: { name: application },
+    spec: { replicas: 2, strategy, selector: { matchLabels: { 'app.kubernetes.io/name': application } }, template: { metadata: { labels: { 'app.kubernetes.io/name': application } }, spec: { serviceAccountName: caps.namespace.serviceAccountRef, containers: [container] } } },
+  };
+  const service = (suffix) => ({ apiVersion: 'v1', kind: 'Service', metadata: { name: `${application}-${suffix}` }, spec: { selector: { 'app.kubernetes.io/name': application }, ports: [{ name: 'http', port: 80, targetPort: 'http' }] } });
+  const ingress = {
+    apiVersion: 'networking.k8s.io/v1', kind: 'Ingress',
+    metadata: { name: application, annotations: { 'cert-manager.io/cluster-issuer': caps.tls.issuerKind === 'ClusterIssuer' ? caps.tls.issuerRef : undefined, 'cert-manager.io/issuer': caps.tls.issuerKind === 'Issuer' ? caps.tls.issuerRef : undefined, 'external-dns.alpha.kubernetes.io/hostname': caps.dns.hostname } },
+    spec: { ingressClassName: caps.ingress.className, tls: [{ hosts: caps.tls.dnsNames, secretName: caps.tls.certificateRef }], rules: [{ host: caps.dns.hostname, http: { paths: [{ path: '/', pathType: 'Prefix', backend: { service: { name: `${application}-stable`, port: { name: 'http' } } } }] } }] },
+  };
+  for (const [key, value] of Object.entries(ingress.metadata.annotations)) if (value === undefined) delete ingress.metadata.annotations[key];
+  const base = `applications/${application}/base`;
+  const overlay = `applications/${application}/overlays/${environment}`;
+  const services = [service('stable'), service(caps.rollout.strategy === 'canary' ? 'canary' : 'preview')];
+  const patch = [{ op: 'replace', path: '/spec/template/spec/containers/0/image', value: candidate.image.ref }];
+  const registration = { apiVersion: 'delivery.idp.dyyto/v1alpha1', kind: 'ApplicationRegistration', metadata: { name: `${application}-${environment}` }, spec: { application, environment, project: 'idp-workloads', owner: component.metadata.owner ?? binding.metadata.consumer, source: { path: overlay }, destination: { server: caps.cluster.server, namespace: caps.namespace.name } } };
+  const planId = `dp-${sha256(stableJson({ application, environment, candidate: candidate.digest, binding: binding.metadata.id })).slice(7, 23)}`;
+  const state = { apiVersion: 'delivery.idp.dyyto/v1alpha1', kind: 'ReleaseState', metadata: { name: `${application}-${environment}` }, spec: { candidateId: candidate.digest, planId, approvedAt: candidate.createdAt, image: candidate.image.ref } };
+  const files = {
+    [`${base}/kustomization.yaml`]: jsonYaml({ apiVersion: 'kustomize.config.k8s.io/v1beta1', kind: 'Kustomization', resources: ['service-account.yaml', 'rollout.yaml', 'services.yaml'] }),
+    [`${base}/service-account.yaml`]: jsonYaml({ apiVersion: 'v1', kind: 'ServiceAccount', metadata: { name: caps.namespace.serviceAccountRef }, automountServiceAccountToken: false }),
+    [`${base}/rollout.yaml`]: jsonYaml(rollout),
+    [`${base}/services.yaml`]: services.map(jsonYaml).join('---\n'),
+    [`${overlay}/kustomization.yaml`]: jsonYaml({ apiVersion: 'kustomize.config.k8s.io/v1beta1', kind: 'Kustomization', namespace: caps.namespace.name, resources: ['../../base', 'ingress.yaml'], patches: [{ target: { group: 'argoproj.io', version: 'v1alpha1', kind: 'Rollout', name: application }, path: 'deployment-patch.yaml' }] }),
+    [`${overlay}/deployment-patch.yaml`]: jsonYaml(patch),
+    [`${overlay}/ingress.yaml`]: jsonYaml(ingress),
+    [`${overlay}/application.yaml`]: jsonYaml(registration),
+    [`${overlay}/release-state.yaml`]: jsonYaml(state),
+  };
+  return Object.entries(files).sort(([left], [right]) => left.localeCompare(right)).map(([file, content]) => ({ path: file, digest: sha256(content), content }));
+}
+
+function preserveUnmanagedApplicationFiles(repositoryRoot, application, environment, before, renderedFiles) {
+  if (!before.exists) return renderedFiles;
+  const managed = [`base/`, `overlays/${environment}/`];
+  const existing = before.files
+    .filter((entry) => !managed.some((prefix) => entry.path.startsWith(prefix)))
+    .map((entry) => {
+      const content = fs.readFileSync(path.join(repositoryRoot, 'applications', application, entry.path), 'utf8');
+      return { path: `applications/${application}/${entry.path}`, digest: sha256(content), content };
+    });
+  const combined = [...renderedFiles, ...existing].sort((left, right) => left.path.localeCompare(right.path));
+  invariant(new Set(combined.map((entry) => entry.path)).size === combined.length, 'IDP_GITOPS_RENDER_CONFLICT', 'Renderer输出路径冲突');
+  return combined;
+}
+
+function safeOutput(output, configRoot) {
+  invariant(path.isAbsolute(output ?? ''), 'IDP_GITOPS_PATH_NOT_ABSOLUTE', '--output必须使用绝对路径');
+  const plans = path.resolve(configRoot, 'plans');
+  fs.mkdirSync(plans, { recursive: true, mode: 0o700 });
+  const resolved = path.resolve(output);
+  const relative = path.relative(plans, resolved);
+  invariant(relative && !relative.startsWith('..') && !path.isAbsolute(relative), 'IDP_GITOPS_PLAN_OUTSIDE_CONFIG', 'Plan必须写入IDP_CONFIG_DIR/plans');
+  invariant(!fs.existsSync(resolved), 'IDP_GITOPS_PLAN_EXISTS', '不可覆盖已有Plan');
+  return resolved;
+}
+
+export function createGitOpsPlan({ operation, componentFile, bindingFile, candidateFile, gitopsRoot, output, configRoot, now = new Date().toISOString() }) {
+  invariant(['create', 'update', 'remove'].includes(operation), 'IDP_GITOPS_OPERATION_INVALID', 'GitOps Plan操作无效');
+  const componentInput = readDocumentFile(componentFile, 'ComponentContract');
+  const bindingInput = readDocumentFile(bindingFile, 'EnvironmentBinding');
+  const candidateInput = readDocumentFile(candidateFile, 'ReleaseCandidate');
+  const component = validateComponent(componentInput.value);
+  const binding = validateEnvironmentBinding(bindingInput.value);
+  const candidate = validateReleaseCandidate(candidateInput.value);
+  const repository = repositoryHead(gitopsRoot);
+  const applicationRoot = path.join(repository.root, 'applications', component.metadata.name);
+  const before = treeState(applicationRoot);
+  invariant(operation === 'create' ? !before.exists : before.exists, 'IDP_GITOPS_OPERATION_CONFLICT', operation === 'create' ? 'create目标已存在' : `${operation}目标不存在`);
+  const renderedFiles = operation === 'remove' ? [] : preserveUnmanagedApplicationFiles(repository.root, component.metadata.name, binding.metadata.environment, before, render(component, binding, candidate));
+  const payload = {
+    schemaVersion: 'idp.deployment-plan/v1', operation, application: component.metadata.name, environment: binding.metadata.environment,
+    inputs: { component: { path: componentInput.path, digest: componentInput.digest }, environmentBinding: { path: bindingInput.path, digest: bindingInput.digest }, releaseCandidate: { path: candidateInput.path, digest: candidateInput.digest, contractDigest: candidate.digest } },
+    repository: { root: repository.root, expectedHead: repository.head, applicationPath: `applications/${component.metadata.name}`, preimageDigest: before.digest },
+    renderedFiles, createdAt: now,
+  };
+  const plan = buildContract(payload);
+  const target = safeOutput(output, configRoot);
+  fs.writeFileSync(target, `${JSON.stringify(plan, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+  return { schemaVersion: 'idp.gitops-plan-receipt/v1', status: 'planned', operation, plan: target, digest: plan.digest, files: renderedFiles.map((entry) => entry.path) };
+}
+
+function validatePlan(plan) {
+  invariant(plan?.schemaVersion === 'idp.deployment-plan/v1' && ['create', 'update', 'remove'].includes(plan.operation) && NAME.test(plan.application ?? '') && ENVIRONMENT.test(plan.environment ?? ''), 'IDP_GITOPS_PLAN_INVALID', 'DeploymentPlan基础字段无效');
+  const { digest, ...payload } = plan;
+  invariant(DIGEST.test(digest ?? '') && digest === sha256(stableJson(payload)), 'IDP_GITOPS_PLAN_INVALID', 'DeploymentPlan摘要不匹配');
+  invariant(Array.isArray(plan.renderedFiles) && plan.renderedFiles.every((entry) => typeof entry.path === 'string' && !path.isAbsolute(entry.path) && !entry.path.split('/').includes('..') && entry.digest === sha256(entry.content)), 'IDP_GITOPS_PLAN_INVALID', 'DeploymentPlan渲染文件无效');
+  return plan;
+}
+
+function restoreTree(target, backup, existed) {
+  fs.rmSync(target, { recursive: true, force: true });
+  if (existed) fs.cpSync(backup, target, { recursive: true, errorOnExist: true, force: false });
+}
+
+export function applyGitOpsPlan({ planFile, configRoot }) {
+  const planInput = readDocumentFile(planFile, 'DeploymentPlan');
+  const plan = validatePlan(planInput.value);
+  for (const input of Object.values(plan.inputs)) {
+    const current = readDocumentFile(input.path, 'Plan输入');
+    invariant(current.digest === input.digest, 'IDP_GITOPS_INPUT_CHANGED', `Plan输入已变化：${input.path}`);
+  }
+  const repository = repositoryHead(plan.repository.root);
+  invariant(repository.head === plan.repository.expectedHead, 'IDP_GITOPS_HEAD_CONFLICT', 'GitOps HEAD已变化，请重新生成Plan');
+  const target = path.join(repository.root, plan.repository.applicationPath);
+  const before = treeState(target);
+  invariant(before.digest === plan.repository.preimageDigest, 'IDP_GITOPS_PREIMAGE_CONFLICT', 'GitOps目标已被人工或并发修改，请重新生成Plan');
+  const evidenceRoot = path.join(configRoot, 'gitops-preimages', plan.digest.slice(7));
+  invariant(!fs.existsSync(evidenceRoot), 'IDP_GITOPS_PLAN_ALREADY_APPLIED', '该Plan已存在Preimage，拒绝重复Apply');
+  fs.mkdirSync(evidenceRoot, { recursive: true, mode: 0o700 });
+  if (before.exists) fs.cpSync(target, path.join(evidenceRoot, 'tree'), { recursive: true, errorOnExist: true, force: false });
+  fs.writeFileSync(path.join(evidenceRoot, 'manifest.json'), `${JSON.stringify({ planDigest: plan.digest, repositoryHead: repository.head, target: plan.repository.applicationPath, preimage: before }, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+  const stage = path.join(repository.root, 'applications', `.idp-stage-${plan.digest.slice(7, 19)}`);
+  invariant(!fs.existsSync(stage), 'IDP_GITOPS_STAGE_EXISTS', 'GitOps暂存目录已存在');
+  try {
+    if (plan.operation !== 'remove') {
+      fs.mkdirSync(stage, { recursive: true, mode: 0o755 });
+      const prefix = `${plan.repository.applicationPath}/`;
+      for (const entry of plan.renderedFiles) {
+        invariant(entry.path.startsWith(prefix), 'IDP_GITOPS_PLAN_INVALID', '渲染路径越过应用边界');
+        const relative = entry.path.slice(prefix.length);
+        const destination = path.join(stage, relative);
+        fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o755 });
+        fs.writeFileSync(destination, entry.content, { mode: 0o644, flag: 'wx' });
+      }
+    }
+    fs.rmSync(target, { recursive: true, force: true });
+    if (plan.operation !== 'remove') fs.renameSync(stage, target);
+    const add = spawnSync('git', ['-C', repository.root, 'add', '-A', '--', plan.repository.applicationPath], { encoding: 'utf8' });
+    invariant(add.status === 0, 'IDP_GITOPS_GIT_FAILED', 'GitOps变更暂存失败');
+    const commit = spawnSync('git', ['-C', repository.root, '-c', 'user.name=idp-deploy', '-c', 'user.email=idp-deploy@local.invalid', 'commit', '--only', '-m', `idp(${plan.application}): ${plan.operation} ${plan.environment}`, '--', plan.repository.applicationPath], { encoding: 'utf8' });
+    invariant(commit.status === 0, 'IDP_GITOPS_GIT_FAILED', 'GitOps提交失败', { stderr: commit.stderr });
+    const applied = repositoryHead(repository.root);
+    const receipt = { schemaVersion: 'idp.gitops-apply-receipt/v1', status: 'applied', operation: plan.operation, planDigest: plan.digest, repository: repository.root, commit: applied.head, preimage: evidenceRoot };
+    fs.writeFileSync(path.join(evidenceRoot, 'receipt.json'), `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+    return receipt;
+  } catch (error) {
+    try { restoreTree(target, path.join(evidenceRoot, 'tree'), before.exists); } catch {}
+    try { fs.rmSync(stage, { recursive: true, force: true }); } catch {}
+    spawnSync('git', ['-C', repository.root, 'reset', '--quiet', '--', plan.repository.applicationPath], { encoding: 'utf8' });
+    throw error;
+  }
+}
+
+export function verifyGitOpsRepository({ gitopsRoot, application, environment }) {
+  invariant(NAME.test(application ?? '') && ENVIRONMENT.test(environment ?? ''), 'IDP_GITOPS_VERIFY_ARGUMENT_INVALID', 'verify需要合法application与environment');
+  const repository = repositoryHead(gitopsRoot);
+  const overlay = path.join(repository.root, 'applications', application, 'overlays', environment);
+  const required = ['kustomization.yaml', 'deployment-patch.yaml', 'application.yaml', 'release-state.yaml'];
+  invariant(required.every((name) => fs.statSync(path.join(overlay, name), { throwIfNoEntry: false })?.isFile()), 'IDP_GITOPS_VERIFY_FAILED', 'GitOps overlay不完整');
+  const state = JSON.parse(fs.readFileSync(path.join(overlay, 'release-state.yaml'), 'utf8'));
+  const image = state.spec?.image;
+  const imageDigest = typeof image === 'string' && image.includes('@') ? image.slice(image.lastIndexOf('@') + 1) : '';
+  invariant(DIGEST.test(imageDigest), 'IDP_GITOPS_VERIFY_FAILED', 'release-state未使用OCI digest');
+  const rendered = spawnSync('kubectl', ['kustomize', overlay], { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+  invariant(rendered.status === 0 && rendered.stdout.includes(`@${imageDigest}`), 'IDP_GITOPS_VERIFY_FAILED', 'Kustomize渲染失败或实际镜像摘要不匹配');
+  return { schemaVersion: 'idp.gitops-repository-verification/v1', status: 'valid', application, environment, commit: repository.head, imageDigest, renderedDigest: sha256(rendered.stdout) };
+}

package/src/hash.mjs

@@ -0,0 +1,47 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function sha256(value) {
+  return `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`;
+}
+
+export function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.filter((entry) => entry !== undefined).map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).filter((key) => value[key] !== undefined).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function hashFile(candidate) {
+  const hash = crypto.createHash('sha256');
+  const handle = fs.openSync(candidate, 'r');
+  const buffer = Buffer.allocUnsafe(1024 * 1024);
+  try {
+    for (;;) {
+      const bytesRead = fs.readSync(handle, buffer, 0, buffer.length, null);
+      if (bytesRead === 0) break;
+      hash.update(buffer.subarray(0, bytesRead));
+    }
+  } finally {
+    fs.closeSync(handle);
+  }
+  return `sha256:${hash.digest('hex')}`;
+}
+
+export function inventoryDirectory(root) {
+  const result = [];
+  function visit(directory) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
+      const absolute = path.join(directory, entry.name);
+      const relative = path.relative(root, absolute);
+      const stat = fs.lstatSync(absolute);
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile()) result.push({ path: relative, mode: stat.mode & 0o777, size: stat.size, digest: hashFile(absolute) });
+      else result.push({ path: relative, unsupported: true });
+    }
+  }
+  visit(root);
+  return result;
+}

package/src/image-lock.mjs

@@ -0,0 +1,160 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { IdpError, invariant } from './errors.mjs';
+import { sha256, stableJson } from './hash.mjs';
+import { assertSafeRegularFile } from './security.mjs';
+
+export const IMAGE_KEYS = Object.freeze([
+  'IDP_POSTGRES_IMAGE',
+  'IDP_CADDY_IMAGE',
+  'IDP_REGISTRY_IMAGE',
+  'IDP_TECH_IMAGE',
+  'IDP_PORTAL_IMAGE',
+  'IDP_FLOW_IMAGE',
+  'IDP_SMARTGO_IMAGE',
+  'IDP_SMARTGO_OBJECT_STORE_IMAGE',
+  'IDP_SMARTGO_OBJECT_STORE_CLIENT_IMAGE',
+]);
+
+export const REQUIRED_IMAGE_PLATFORMS = Object.freeze(['linux/amd64', 'linux/arm64']);
+
+const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/u;
+const PINNED_REF_PATTERN = /^\S+@sha256:[0-9a-f]{64}$/u;
+const DOCUMENT_KEYS_V1 = ['schemaVersion', 'platform', 'generatedAt', 'images', 'digest'];
+const ENTRY_KEYS_V1 = ['key', 'sourceRef', 'pinnedRef', 'digest', 'platform', 'evidence'];
+const DOCUMENT_KEYS_V2 = ['schemaVersion', 'requiredPlatforms', 'generatedAt', 'images', 'digest'];
+const ENTRY_KEYS_V2 = ['key', 'sourceRef', 'pinnedRef', 'digest', 'platforms'];
+const PLATFORM_EVIDENCE_KEYS = ['platform', 'evidence'];
+
+function exactKeys(value, expected, code, role) {
+  invariant(value && typeof value === 'object' && !Array.isArray(value), code, `${role}必须是对象`);
+  const actual = Object.keys(value).sort();
+  invariant(stableJson(actual) === stableJson([...expected].sort()), code, `${role}字段集合无效`);
+}
+
+function lockPayload(document) {
+  const { digest: _digest, ...payload } = document;
+  return payload;
+}
+
+function validatePlatformList(platforms, code, role) {
+  invariant(Array.isArray(platforms) && platforms.length > 0, code, `${role}不能为空`);
+  const values = platforms.map((entry) => typeof entry === 'string' ? entry : entry?.platform);
+  invariant(values.every((value) => REQUIRED_IMAGE_PLATFORMS.includes(value)), code, `${role}包含不支持的平台`);
+  invariant(stableJson(values) === stableJson([...new Set(values)].sort()), code, `${role}必须唯一并按字典序排列`);
+  return values;
+}
+
+function validateCommonEntry(entry, entries) {
+  invariant(IMAGE_KEYS.includes(entry.key), 'IDP_IMAGE_LOCK_KEY_UNKNOWN', `镜像锁包含未知镜像键：${entry.key}`);
+  invariant(!entries.has(entry.key), 'IDP_IMAGE_LOCK_KEY_DUPLICATE', `镜像锁包含重复镜像键：${entry.key}`);
+  invariant(typeof entry.sourceRef === 'string' && entry.sourceRef.length > 0 && !/\s/u.test(entry.sourceRef), 'IDP_IMAGE_LOCK_SOURCE_INVALID', `${entry.key}的sourceRef无效`);
+  invariant(PINNED_REF_PATTERN.test(entry.pinnedRef), 'IDP_IMAGE_LOCK_PIN_INVALID', `${entry.key}的pinnedRef无效`);
+  invariant(DIGEST_PATTERN.test(entry.digest), 'IDP_IMAGE_LOCK_DIGEST_INVALID', `${entry.key}的digest无效`);
+  invariant(entry.pinnedRef.endsWith(`@${entry.digest}`), 'IDP_IMAGE_LOCK_DIGEST_MISMATCH', `${entry.key}的pinnedRef与digest不一致`);
+}
+
+function validateEnvironmentBindings(entries, env, requiredKeys) {
+  for (const key of requiredKeys) invariant(entries.has(key), 'IDP_IMAGE_LOCK_REQUIRED_MISSING', `镜像锁缺少必需镜像：${key}`);
+  if (!env) return;
+  // Profile-scoped callers only validate images used by that profile. Future
+  // profile tags may already be present in .env without becoming deployment
+  // facts for the currently active profile.
+  const scopedKeys = requiredKeys.length > 0 ? new Set(requiredKeys) : new Set(IMAGE_KEYS);
+  for (const key of scopedKeys) {
+    const configured = env[key];
+    if (!configured || configured === 'UNCONFIGURED') continue;
+    const entry = entries.get(key);
+    invariant(entry, 'IDP_IMAGE_LOCK_CONFIG_MISSING', `已配置镜像没有锁定证据：${key}`);
+    invariant(entry.pinnedRef === configured, 'IDP_IMAGE_LOCK_CONFIG_MISMATCH', `${key}与镜像锁不一致`);
+  }
+  for (const [key, entry] of entries) {
+    if (!scopedKeys.has(key)) continue;
+    invariant(env[key] && env[key] !== 'UNCONFIGURED', 'IDP_IMAGE_LOCK_CONFIG_EXTRA', `镜像锁包含.env未配置的镜像：${key}`);
+    invariant(env[key] === entry.pinnedRef, 'IDP_IMAGE_LOCK_CONFIG_MISMATCH', `${key}与镜像锁不一致`);
+  }
+}
+
+function validateLegacyImageLock(document, { env, requiredKeys, allowLegacy }) {
+  invariant(allowLegacy, 'IDP_IMAGE_LOCK_VERSION_UNSUPPORTED', '旧版单平台镜像锁证据不足；请使用新的不可变版本执行./deploy.sh重新发布并锁定双平台镜像');
+  exactKeys(document, DOCUMENT_KEYS_V1, 'IDP_IMAGE_LOCK_INVALID', '镜像锁');
+  invariant(document.platform === 'linux/arm64', 'IDP_IMAGE_LOCK_PLATFORM_INVALID', '旧版镜像锁平台必须是linux/arm64');
+  const generatedAt = typeof document.generatedAt === 'string' ? Date.parse(document.generatedAt) : Number.NaN;
+  invariant(Number.isFinite(generatedAt) && new Date(generatedAt).toISOString() === document.generatedAt, 'IDP_IMAGE_LOCK_TIME_INVALID', '旧版镜像锁generatedAt无效');
+  invariant(Array.isArray(document.images), 'IDP_IMAGE_LOCK_IMAGES_INVALID', '镜像锁images必须是数组');
+  const entries = new Map();
+  for (const entry of document.images) {
+    exactKeys(entry, ENTRY_KEYS_V1, 'IDP_IMAGE_LOCK_ENTRY_INVALID', '镜像锁条目');
+    validateCommonEntry(entry, entries);
+    invariant(entry.platform === document.platform, 'IDP_IMAGE_LOCK_ENTRY_PLATFORM_MISMATCH', `${entry.key}的平台与镜像锁不一致`);
+    invariant(typeof entry.evidence === 'string' && entry.evidence.length > 0, 'IDP_IMAGE_LOCK_EVIDENCE_INVALID', `${entry.key}缺少平台证据`);
+    entries.set(entry.key, entry);
+  }
+  validateEnvironmentBindings(entries, env, requiredKeys);
+  return { document, entries, legacy: true };
+}
+
+export function buildImageLock(images, { requiredPlatforms = REQUIRED_IMAGE_PLATFORMS, generatedAt = new Date().toISOString() } = {}) {
+  const canonicalPlatforms = [...requiredPlatforms];
+  validatePlatformList(canonicalPlatforms, 'IDP_IMAGE_LOCK_REQUIRED_PLATFORMS_INVALID', '镜像锁requiredPlatforms');
+  const payload = {
+    schemaVersion: 2,
+    requiredPlatforms: canonicalPlatforms,
+    generatedAt,
+    images: [...images].sort((left, right) => left.key < right.key ? -1 : left.key > right.key ? 1 : 0),
+  };
+  return { ...payload, digest: sha256(stableJson(payload)) };
+}
+
+export function validateImageLockDocument(document, {
+  env,
+  requiredPlatforms = REQUIRED_IMAGE_PLATFORMS,
+  requiredKeys = [],
+  allowLegacy = false,
+} = {}) {
+  invariant(document && typeof document === 'object' && !Array.isArray(document), 'IDP_IMAGE_LOCK_INVALID', '镜像锁必须是对象');
+  const expectedDigest = sha256(stableJson(lockPayload(document)));
+  invariant(document.digest === expectedDigest, 'IDP_IMAGE_LOCK_DOCUMENT_DIGEST_MISMATCH', '镜像锁整体摘要不匹配');
+  if (document.schemaVersion === 1) return validateLegacyImageLock(document, { env, requiredKeys, allowLegacy });
+  invariant(document.schemaVersion === 2, 'IDP_IMAGE_LOCK_VERSION_UNSUPPORTED', '只支持schemaVersion=2的双平台镜像锁');
+  exactKeys(document, DOCUMENT_KEYS_V2, 'IDP_IMAGE_LOCK_INVALID', '镜像锁');
+  const declaredPlatforms = validatePlatformList(document.requiredPlatforms, 'IDP_IMAGE_LOCK_REQUIRED_PLATFORMS_INVALID', '镜像锁requiredPlatforms');
+  const expectedPlatforms = validatePlatformList([...requiredPlatforms], 'IDP_IMAGE_LOCK_REQUIRED_PLATFORMS_INVALID', '要求的平台集合');
+  for (const platform of expectedPlatforms) {
+    invariant(declaredPlatforms.includes(platform), 'IDP_IMAGE_LOCK_PLATFORM_MISSING', `镜像锁没有证明必需平台：${platform}`);
+  }
+  const generatedAt = typeof document.generatedAt === 'string' ? Date.parse(document.generatedAt) : Number.NaN;
+  invariant(Number.isFinite(generatedAt) && new Date(generatedAt).toISOString() === document.generatedAt, 'IDP_IMAGE_LOCK_TIME_INVALID', '镜像锁generatedAt无效');
+  invariant(Array.isArray(document.images), 'IDP_IMAGE_LOCK_IMAGES_INVALID', '镜像锁images必须是数组');
+
+  const entries = new Map();
+  for (const entry of document.images) {
+    exactKeys(entry, ENTRY_KEYS_V2, 'IDP_IMAGE_LOCK_ENTRY_INVALID', '镜像锁条目');
+    validateCommonEntry(entry, entries);
+    const entryPlatforms = validatePlatformList(entry.platforms, 'IDP_IMAGE_LOCK_ENTRY_PLATFORMS_INVALID', `${entry.key}的平台证据`);
+    for (const platformEvidence of entry.platforms) {
+      exactKeys(platformEvidence, PLATFORM_EVIDENCE_KEYS, 'IDP_IMAGE_LOCK_ENTRY_PLATFORMS_INVALID', `${entry.key}的平台证据项`);
+      invariant(typeof platformEvidence.evidence === 'string' && platformEvidence.evidence.length > 0, 'IDP_IMAGE_LOCK_EVIDENCE_INVALID', `${entry.key}的${platformEvidence.platform}缺少平台证据`);
+    }
+    for (const platform of declaredPlatforms) {
+      invariant(entryPlatforms.includes(platform), 'IDP_IMAGE_LOCK_ENTRY_PLATFORM_MISSING', `${entry.key}没有证明必需平台：${platform}`);
+    }
+    entries.set(entry.key, entry);
+  }
+
+  validateEnvironmentBindings(entries, env, requiredKeys);
+  return { document, entries, legacy: false };
+}
+
+export function readImageLock(configRoot, options = {}) {
+  invariant(path.isAbsolute(configRoot), 'IDP_CONFIG_NOT_ABSOLUTE', 'IDP_CONFIG_DIR必须是绝对路径');
+  const candidate = path.join(configRoot, 'images.lock.json');
+  assertSafeRegularFile(candidate, 0o600, { allowEmpty: false, role: '镜像锁' });
+  let document;
+  try {
+    document = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+  } catch (error) {
+    throw new IdpError('IDP_IMAGE_LOCK_JSON_INVALID', '镜像锁不是有效JSON', { cause: error.message });
+  }
+  return { path: candidate, ...validateImageLockDocument(document, options) };
+}