@aipt/idp-deploy 0.1.2

package/src/delivery.mjs

@@ -0,0 +1,123 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { IdpError, invariant } from './errors.mjs';
+import { buildContract } from './foundation-contracts.mjs';
+import { hashFile, sha256, stableJson } from './hash.mjs';
+
+const NAME = /^[a-z][a-z0-9-]{1,62}$/u;
+const COMMIT = /^[0-9a-f]{40}$/u;
+const REPOSITORY = /^(?:https:\/\/\S+|git@\S+:[^\s]+)$/u;
+
+function read(candidate, role) {
+  invariant(path.isAbsolute(candidate ?? ''), 'IDP_DELIVERY_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_DELIVERY_INPUT_UNSAFE', `${role}必须是安全普通文件`);
+  try { return { path: resolved, digest: hashFile(resolved), value: parseYaml(fs.readFileSync(resolved, 'utf8'), { maxAliasCount: 0, uniqueKeys: true }) }; }
+  catch (error) { throw new IdpError('IDP_DELIVERY_DOCUMENT_INVALID', `${role}不是有效JSON或YAML`, { cause: error.message }); }
+}
+
+function component(input) {
+  const value = input.value;
+  invariant(value?.apiVersion === 'idp.company.io/v1alpha1' && value.kind === 'ComponentContract', 'IDP_DELIVERY_COMPONENT_INVALID', 'ComponentContract版本无效');
+  invariant(NAME.test(value.metadata?.name ?? '') && typeof value.metadata?.version === 'string', 'IDP_DELIVERY_COMPONENT_INVALID', 'ComponentContract metadata无效');
+  invariant(Number.isInteger(value.spec?.image?.port) && value.spec.image.port > 0 && value.spec.image.port < 65536, 'IDP_DELIVERY_COMPONENT_INVALID', 'ComponentContract端口无效');
+  invariant(stableJson(value.spec.image.platforms) === stableJson(['linux/amd64', 'linux/arm64']), 'IDP_DELIVERY_COMPONENT_INVALID', 'ComponentContract必须支持amd64与arm64');
+  return value;
+}
+
+function safeNewOutput(candidate, role) {
+  invariant(path.isAbsolute(candidate ?? ''), 'IDP_DELIVERY_PATH_NOT_ABSOLUTE', `${role}必须使用绝对路径`);
+  const target = path.resolve(candidate);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  invariant(!fs.existsSync(target), 'IDP_DELIVERY_OUTPUT_EXISTS', `${role}已存在，拒绝覆盖用户修改`);
+  return target;
+}
+
+export function inspectApplication({ componentFile, environmentBindingFile }) {
+  const input = read(componentFile, 'ComponentContract');
+  const contract = component(input);
+  let environment = { status: 'not-required', reason: '本地开发、Workflow和交付计划不依赖Kubernetes或云资源' };
+  if (environmentBindingFile) {
+    const binding = read(environmentBindingFile, 'EnvironmentBinding').value;
+    invariant(binding?.kind === 'EnvironmentBinding' && binding.metadata?.consumer === contract.metadata.name, 'IDP_DELIVERY_BINDING_INVALID', 'EnvironmentBinding与应用不匹配');
+    const capabilities = binding.spec?.capabilities ?? {};
+    const required = ['cluster', 'namespace', 'imageRegistry', 'rollout'];
+    const missing = required.filter((name) => !capabilities[name]);
+    environment = { name: binding.metadata.environment, status: missing.length ? 'missing' : 'ready', missing, blocks: missing.length ? ['release-apply'] : [] };
+  }
+  return { schemaVersion: 'idp.application-inspection/v1', status: 'ready', application: contract.metadata.name, version: contract.metadata.version, componentDigest: input.digest, platforms: contract.spec.image.platforms, actions: { workflowGenerate: 'ready', buildPlan: 'ready', gitopsRender: environment.status === 'ready' ? 'ready' : 'waiting-environment', releaseApply: environment.status === 'ready' ? 'ready' : 'blocked' }, environment };
+}
+
+export function createBuildPlan({ componentFile, repository, commit, imageRepository, workflow = 'idp-delivery.yml', output, now = new Date().toISOString() }) {
+  const input = read(componentFile, 'ComponentContract');
+  const contract = component(input);
+  invariant(REPOSITORY.test(repository ?? ''), 'IDP_BUILD_REPOSITORY_INVALID', '源码仓库地址无效');
+  invariant(COMMIT.test(commit ?? ''), 'IDP_BUILD_COMMIT_INVALID', '源码提交必须是40位Git SHA');
+  invariant(typeof imageRepository === 'string' && /^[a-z0-9.-]+(?::[0-9]+)?\/[a-z0-9._/-]+$/u.test(imageRepository), 'IDP_BUILD_IMAGE_REPOSITORY_INVALID', '镜像仓库地址无效且不能包含tag或digest');
+  invariant(/^[A-Za-z0-9._/-]+\.ya?ml$/u.test(workflow) && !workflow.split('/').includes('..'), 'IDP_BUILD_WORKFLOW_INVALID', 'Workflow文件名无效');
+  const plan = buildContract({ schemaVersion: 'idp.build-plan/v1', application: contract.metadata.name, version: contract.metadata.version, source: { repository, commit }, component: { path: input.path, digest: input.digest }, image: { repository: imageRepository, platforms: contract.spec.image.platforms }, provider: { kind: 'github-actions', workflow }, createdAt: now });
+  const target = safeNewOutput(output, 'Build Plan输出');
+  fs.writeFileSync(target, `${JSON.stringify(plan, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+  return { schemaVersion: 'idp.build-plan-receipt/v1', status: 'planned', application: plan.application, plan: target, digest: plan.digest, next: '可人工检查Plan后执行build trigger；该步骤不需要Kubernetes' };
+}
+
+export function validateBuildPlanFile(planFile) {
+  const input = read(planFile, 'Build Plan');
+  const plan = input.value;
+  const { digest, ...payload } = plan ?? {};
+  invariant(plan?.schemaVersion === 'idp.build-plan/v1' && NAME.test(plan.application ?? '') && COMMIT.test(plan.source?.commit ?? '') && digest === sha256(stableJson(payload)), 'IDP_BUILD_PLAN_INVALID', 'Build Plan字段或摘要无效');
+  invariant(hashFile(plan.component.path) === plan.component.digest, 'IDP_BUILD_INPUT_CHANGED', 'ComponentContract已变化，请重新生成Build Plan');
+  return plan;
+}
+
+export function triggerBuild({ planFile, provider = 'manual', output, providerAdapter }) {
+  const plan = validateBuildPlanFile(planFile);
+  invariant(['manual', 'github-actions'].includes(provider), 'IDP_BUILD_PROVIDER_UNKNOWN', `未知构建Provider：${provider}`);
+  let dispatch;
+  if (provider === 'manual') dispatch = { provider, state: 'waiting-manual', workflow: plan.provider.workflow, ref: plan.source.commit, inputs: { buildPlanDigest: plan.digest } };
+  else {
+    invariant(typeof providerAdapter === 'function', 'IDP_BUILD_PROVIDER_NOT_CONFIGURED', 'GitHub Actions Provider尚未绑定；可使用manual生成可审计触发单，或由Portal/idp门面注入Provider');
+    dispatch = providerAdapter(Object.freeze({ repository: plan.source.repository, workflow: plan.provider.workflow, ref: plan.source.commit, inputs: Object.freeze({ buildPlanDigest: plan.digest }) }));
+    invariant(dispatch?.id && typeof dispatch.id === 'string', 'IDP_BUILD_PROVIDER_RESPONSE_INVALID', '构建Provider未返回任务ID');
+  }
+  const receipt = buildContract({ schemaVersion: 'idp.build-trigger/v1', planDigest: plan.digest, application: plan.application, provider, dispatch, triggeredAt: new Date().toISOString() });
+  const target = safeNewOutput(output, 'Build Trigger输出');
+  fs.writeFileSync(target, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+  return { status: dispatch.state ?? 'triggered', receipt: target, digest: receipt.digest, next: provider === 'manual' ? '在GitHub界面运行Workflow后，以任务ID生成状态Evidence' : '执行build status查询Provider状态' };
+}
+
+export function buildStatus({ triggerFile, providerAdapter }) {
+  const input = read(triggerFile, 'Build Trigger');
+  const trigger = input.value;
+  const { digest, ...payload } = trigger ?? {};
+  invariant(trigger?.schemaVersion === 'idp.build-trigger/v1' && digest === sha256(stableJson(payload)), 'IDP_BUILD_TRIGGER_INVALID', 'Build Trigger字段或摘要无效');
+  if (trigger.provider === 'manual') return { schemaVersion: 'idp.build-status/v1', status: 'waiting-manual', application: trigger.application, planDigest: trigger.planDigest, next: '在GitHub Actions工作台触发并记录任务ID；尚未伪造构建成功' };
+  invariant(typeof providerAdapter === 'function', 'IDP_BUILD_PROVIDER_NOT_CONFIGURED', '查询GitHub Actions需要由Portal/idp门面绑定Provider');
+  return { schemaVersion: 'idp.build-status/v1', application: trigger.application, planDigest: trigger.planDigest, ...providerAdapter(trigger.dispatch.id) };
+}
+
+export function generateGithubWorkflow({ output }) {
+  const target = safeNewOutput(output, 'Workflow输出');
+  const document = {
+    name: 'IDP 构建与交付',
+    on: { push: { branches: ['main'] }, workflow_dispatch: { inputs: { buildPlanDigest: { description: '不可变Build Plan摘要', required: false, type: 'string' } } } },
+    permissions: { contents: 'read', packages: 'write', 'id-token': 'write' },
+    jobs: { build: { 'runs-on': 'ubuntu-latest', steps: [{ uses: 'actions/checkout@v4' }, { name: '验证工程', run: 'npm ci && npm test' }, { name: '构建双架构OCI镜像', run: 'echo "由已绑定的OCI Builder能力执行；禁止在Workflow保存长期云密钥"' }] } },
+  };
+  fs.writeFileSync(target, stringifyYaml(document), { mode: 0o644, flag: 'wx' });
+  return { schemaVersion: 'idp.workflow-generation/v1', status: 'generated', target, digest: hashFile(target), provider: 'github-actions' };
+}
+
+export function verifyGithubWorkflow({ workflowFile }) {
+  const input = read(workflowFile, 'GitHub Workflow');
+  const workflow = input.value;
+  const triggers = workflow.on ?? workflow.true;
+  invariant(workflow?.permissions?.contents === 'read' && workflow.permissions.packages === 'write' && workflow.permissions['id-token'] === 'write', 'IDP_WORKFLOW_PERMISSION_INVALID', 'Workflow必须使用最小权限并启用OIDC');
+  invariant(triggers?.push || triggers?.workflow_dispatch, 'IDP_WORKFLOW_TRIGGER_INVALID', 'Workflow必须声明push或workflow_dispatch触发器');
+  const serialized = stableJson(workflow);
+  invariant(!/(?:access[_-]?key|secret[_-]?key|password|private[_-]?key)\s*[:=]\s*["']?[^${\s]/iu.test(serialized), 'IDP_WORKFLOW_SECRET_INVALID', 'Workflow疑似内联长期凭据');
+  invariant(serialized.includes('actions/checkout@v4'), 'IDP_WORKFLOW_STEP_INVALID', 'Workflow缺少固定主版本的checkout步骤');
+  return { schemaVersion: 'idp.workflow-verification/v1', status: 'valid', workflow: input.path, digest: input.digest, triggers: Object.keys(triggers).sort(), kubernetesRequired: false };
+}

package/src/errors.mjs

@@ -0,0 +1,12 @@
+export class IdpError extends Error {
+  constructor(code, message, details = undefined) {
+    super(message);
+    this.name = 'IdpError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function invariant(condition, code, message, details) {
+  if (!condition) throw new IdpError(code, message, details);
+}

package/src/foundation-contracts.mjs

@@ -0,0 +1,128 @@
+import { IdpError, invariant } from './errors.mjs';
+import { sha256, stableJson } from './hash.mjs';
+
+const DIGEST = /^sha256:[0-9a-f]{64}$/u;
+const NAME = /^[a-z][a-z0-9-]{1,62}$/u;
+const ENVIRONMENT_REF = /^environment:[a-z][a-z0-9-]*(?:\.[a-z0-9-]+)*@v[1-9][0-9]*$/u;
+const COMMIT = /^[0-9a-f]{40}$/u;
+const PINNED_IMAGE = /^\S+@sha256:[0-9a-f]{64}$/u;
+
+function exactKeys(value, expected, code, role) {
+  invariant(value && typeof value === 'object' && !Array.isArray(value), code, `${role}必须是对象`);
+  invariant(stableJson(Object.keys(value).sort()) === stableJson([...expected].sort()), code, `${role}字段集合无效`);
+}
+
+function validTime(value) {
+  const parsed = typeof value === 'string' ? Date.parse(value) : Number.NaN;
+  return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+}
+
+function validateDigestList(values, code, role, { minItems = 0 } = {}) {
+  invariant(Array.isArray(values) && values.length >= minItems, code, `${role}数量无效`);
+  invariant(values.every((value) => DIGEST.test(value)), code, `${role}包含无效摘要`);
+  invariant(stableJson(values) === stableJson([...new Set(values)].sort()), code, `${role}必须唯一并按字典序排列`);
+}
+
+function verifySelfDigest(document, code) {
+  const { digest, ...payload } = document;
+  invariant(DIGEST.test(digest ?? '') && digest === sha256(stableJson(payload)), code, '合同整体摘要不匹配');
+}
+
+export function buildContract(payload) {
+  return { ...payload, digest: sha256(stableJson(payload)) };
+}
+
+export function validateConfigRelease(document) {
+  const code = 'IDP_CONFIG_RELEASE_INVALID';
+  exactKeys(document, ['schemaVersion', 'application', 'environmentRef', 'reloadMode', 'source', 'files', 'secretBindingDigests', 'createdAt', 'digest'], code, 'ConfigRelease');
+  invariant(document.schemaVersion === 'idp.config-release/v1', code, 'ConfigRelease版本无效');
+  invariant(NAME.test(document.application ?? ''), code, 'ConfigRelease应用名无效');
+  invariant(ENVIRONMENT_REF.test(document.environmentRef ?? ''), code, 'ConfigRelease环境引用无效');
+  invariant(['restart', 'watch', 'dynamic-provider'].includes(document.reloadMode), code, 'ConfigRelease reloadMode无效');
+  exactKeys(document.source, ['kind', 'ref', 'digest'], code, 'ConfigRelease source');
+  invariant(['git', 'oci', 'config-provider'].includes(document.source.kind), code, 'ConfigRelease source.kind无效');
+  invariant(typeof document.source.ref === 'string' && document.source.ref.length > 0 && !/\s/u.test(document.source.ref), code, 'ConfigRelease source.ref无效');
+  invariant(DIGEST.test(document.source.digest ?? ''), code, 'ConfigRelease source.digest无效');
+  invariant(Array.isArray(document.files), code, 'ConfigRelease files必须是数组');
+  const paths = [];
+  for (const entry of document.files) {
+    exactKeys(entry, ['path', 'digest', 'sensitive'], code, 'ConfigRelease file');
+    invariant(typeof entry.path === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/u.test(entry.path) && !entry.path.split('/').includes('..'), code, 'ConfigRelease file.path无效');
+    invariant(DIGEST.test(entry.digest ?? '') && entry.sensitive === false, code, 'ConfigRelease只能登记非敏感配置摘要');
+    paths.push(entry.path);
+  }
+  invariant(stableJson(paths) === stableJson([...new Set(paths)].sort()), code, 'ConfigRelease files必须按path唯一排序');
+  validateDigestList(document.secretBindingDigests, code, 'ConfigRelease secretBindingDigests');
+  invariant(validTime(document.createdAt), code, 'ConfigRelease createdAt无效');
+  verifySelfDigest(document, code);
+  return document;
+}
+
+export function validateReleaseCandidate(document) {
+  const code = 'IDP_RELEASE_CANDIDATE_INVALID';
+  exactKeys(document, ['schemaVersion', 'application', 'version', 'source', 'componentContractDigest', 'image', 'configReleaseDigest', 'acceptanceEvidenceDigests', 'targetEnvironmentRef', 'rolloutStrategy', 'createdAt', 'digest'], code, 'ReleaseCandidate');
+  invariant(document.schemaVersion === 'idp.release-candidate/v1', code, 'ReleaseCandidate版本无效');
+  invariant(NAME.test(document.application ?? '') && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(document.version ?? ''), code, 'ReleaseCandidate应用名或版本无效');
+  exactKeys(document.source, ['repository', 'commit', 'digest'], code, 'ReleaseCandidate source');
+  invariant(/^https:\/\/\S+$/u.test(document.source.repository ?? '') || /^git@\S+:[^\s]+$/u.test(document.source.repository ?? ''), code, 'ReleaseCandidate repository无效');
+  invariant(COMMIT.test(document.source.commit ?? '') && DIGEST.test(document.source.digest ?? ''), code, 'ReleaseCandidate source身份无效');
+  invariant(DIGEST.test(document.componentContractDigest ?? ''), code, 'ReleaseCandidate componentContractDigest无效');
+  exactKeys(document.image, ['ref', 'digest', 'platforms'], code, 'ReleaseCandidate image');
+  invariant(PINNED_IMAGE.test(document.image.ref ?? '') && DIGEST.test(document.image.digest ?? '') && document.image.ref.endsWith(`@${document.image.digest}`), code, 'ReleaseCandidate镜像必须使用匹配的OCI digest引用');
+  invariant(stableJson(document.image.platforms) === stableJson(['linux/amd64', 'linux/arm64']), code, 'ReleaseCandidate镜像必须证明amd64与arm64');
+  invariant(document.configReleaseDigest === null || DIGEST.test(document.configReleaseDigest ?? ''), code, 'ReleaseCandidate configReleaseDigest无效');
+  validateDigestList(document.acceptanceEvidenceDigests, code, 'ReleaseCandidate acceptanceEvidenceDigests', { minItems: 1 });
+  invariant(ENVIRONMENT_REF.test(document.targetEnvironmentRef ?? ''), code, 'ReleaseCandidate目标环境无效');
+  invariant(['rolling', 'canary', 'blue-green'].includes(document.rolloutStrategy), code, 'ReleaseCandidate rolloutStrategy无效');
+  invariant(validTime(document.createdAt), code, 'ReleaseCandidate createdAt无效');
+  verifySelfDigest(document, code);
+  return document;
+}
+
+export function validateDeploymentEvidence(document) {
+  const code = 'IDP_DEPLOYMENT_EVIDENCE_INVALID';
+  exactKeys(document, ['schemaVersion', 'planDigest', 'releaseCandidateDigest', 'runtime', 'environmentRef', 'repositoryState', 'rollout', 'resources', 'checks', 'observedAt', 'digest'], code, 'DeploymentEvidence');
+  invariant(document.schemaVersion === 'idp.deployment-evidence/v1', code, 'DeploymentEvidence版本无效');
+  invariant(DIGEST.test(document.planDigest ?? '') && DIGEST.test(document.releaseCandidateDigest ?? ''), code, 'DeploymentEvidence计划或候选摘要无效');
+  invariant(['compose', 'kubernetes-gitops'].includes(document.runtime), code, 'DeploymentEvidence runtime无效');
+  invariant(ENVIRONMENT_REF.test(document.environmentRef ?? ''), code, 'DeploymentEvidence环境引用无效');
+  if (document.runtime === 'compose') invariant(document.repositoryState === null, code, 'Compose Evidence不能伪造GitOps Repository State');
+  else {
+    exactKeys(document.repositoryState, ['repository', 'commit'], code, 'DeploymentEvidence repositoryState');
+    invariant(typeof document.repositoryState.repository === 'string' && document.repositoryState.repository.length > 0 && COMMIT.test(document.repositoryState.commit ?? ''), code, 'DeploymentEvidence Repository State无效');
+  }
+  exactKeys(document.rollout, ['strategy', 'status', 'stableImageDigest'], code, 'DeploymentEvidence rollout');
+  invariant(['rolling', 'canary', 'blue-green'].includes(document.rollout.strategy) && ['healthy', 'degraded', 'aborted'].includes(document.rollout.status) && DIGEST.test(document.rollout.stableImageDigest ?? ''), code, 'DeploymentEvidence rollout无效');
+  invariant(Array.isArray(document.resources), code, 'DeploymentEvidence resources必须是数组');
+  const resourceKeys = [];
+  for (const resource of document.resources) {
+    exactKeys(resource, ['apiVersion', 'kind', 'namespace', 'name', 'uid', 'imageDigest'], code, 'DeploymentEvidence resource');
+    invariant([resource.apiVersion, resource.kind, resource.namespace, resource.name, resource.uid].every((value) => typeof value === 'string' && value.length > 0), code, 'DeploymentEvidence resource身份无效');
+    invariant(resource.imageDigest === null || DIGEST.test(resource.imageDigest ?? ''), code, 'DeploymentEvidence resource.imageDigest无效');
+    resourceKeys.push(`${resource.apiVersion}/${resource.kind}/${resource.namespace}/${resource.name}`);
+  }
+  invariant(stableJson(resourceKeys) === stableJson([...new Set(resourceKeys)].sort()), code, 'DeploymentEvidence resources必须唯一排序');
+  invariant(Array.isArray(document.checks) && document.checks.length > 0, code, 'DeploymentEvidence checks不能为空');
+  const checkNames = [];
+  for (const check of document.checks) {
+    exactKeys(check, ['name', 'status', 'evidenceDigest'], code, 'DeploymentEvidence check');
+    invariant(NAME.test(check.name ?? '') && ['passed', 'failed'].includes(check.status) && DIGEST.test(check.evidenceDigest ?? ''), code, 'DeploymentEvidence check无效');
+    checkNames.push(check.name);
+  }
+  invariant(stableJson(checkNames) === stableJson([...new Set(checkNames)].sort()), code, 'DeploymentEvidence checks必须唯一排序');
+  invariant(validTime(document.observedAt), code, 'DeploymentEvidence observedAt无效');
+  verifySelfDigest(document, code);
+  return document;
+}
+
+export const FOUNDATION_CONTRACT_VALIDATORS = Object.freeze({
+  'config-release': validateConfigRelease,
+  'release-candidate': validateReleaseCandidate,
+  'deployment-evidence': validateDeploymentEvidence,
+});
+
+export function validateFoundationContract(kind, document) {
+  const validator = FOUNDATION_CONTRACT_VALIDATORS[kind];
+  if (!validator) throw new IdpError('IDP_CONTRACT_KIND_UNKNOWN', `未知基座合同：${kind}`);
+  return validator(document);
+}

package/src/foundation.mjs

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { IdpError, invariant } from './errors.mjs';
+import { hashFile, sha256, stableJson } from './hash.mjs';
+
+function command(command, args, { required = true } = {}) {
+  const result = spawnSync(command, args, { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+  if (required && (result.error || result.status !== 0)) throw new IdpError('IDP_FOUNDATION_COMMAND_FAILED', `${command}检查失败`, { stderr: result.stderr?.trim() });
+  return result;
+}
+
+function kubectl(context, args, options) {
+  return command('kubectl', ['--context', context, ...args], options);
+}
+
+function commandAvailable(name) {
+  return spawnSync('sh', ['-c', 'command -v "$1" >/dev/null 2>&1', 'foundation-doctor', name], { encoding: 'utf8' }).status === 0;
+}
+
+export function doctorFoundation({ context = 'kind-idp-foundation' } = {}) {
+  const tools = Object.fromEntries(['docker', 'kubectl', 'kind', 'helm', 'git'].map((name) => [name, commandAvailable(name)]));
+  const contextResult = tools.kubectl ? command('kubectl', ['config', 'get-contexts', context, '-o', 'name'], { required: false }) : { status: 1, stdout: '' };
+  const nodeResult = contextResult.status === 0 ? kubectl(context, ['get', 'nodes', '-o', 'json'], { required: false }) : { status: 1, stdout: '' };
+  let nodes = [];
+  if (nodeResult.status === 0) {
+    const document = JSON.parse(nodeResult.stdout);
+    nodes = document.items.map((node) => ({ name: node.metadata.name, version: node.status.nodeInfo.kubeletVersion, ready: node.status.conditions.some((entry) => entry.type === 'Ready' && entry.status === 'True') }));
+  }
+  const dockerInfo = tools.docker ? command('docker', ['info', '--format', '{{json .}}'], { required: false }) : { status: 1 };
+  let dockerMemoryBytes = null;
+  if (dockerInfo.status === 0) dockerMemoryBytes = JSON.parse(dockerInfo.stdout).MemTotal;
+  const cloudCredentialKeys = ['ALIBABA_CLOUD_ACCESS_KEY_ID', 'ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'ALICLOUD_ACCESS_KEY', 'ALICLOUD_SECRET_KEY'];
+  const cloudConfigured = cloudCredentialKeys.some((key) => Boolean(process.env[key]));
+  return {
+    schemaVersion: 'idp.foundation-doctor/v1', status: Object.values(tools).every(Boolean) && nodes.length > 0 && nodes.every((node) => node.ready) ? 'ready' : 'degraded',
+    context, tools, nodes, resources: { dockerMemoryBytes, localProfile: 'gitops-core', heavyObservabilityRecommendedTarget: dockerMemoryBytes !== null && dockerMemoryBytes < 12 * 1024 ** 3 ? 'aliyun-ack' : 'local-or-aliyun-ack' },
+    aliyun: { credentialsConfigured: cloudConfigured, action: cloudConfigured ? '可验证已有ACK context；仍不自动创建云资源' : '未配置凭据，只渲染production profile，不创建云资源' },
+  };
+}
+
+const REQUIRED_WORKLOADS = [
+  ['Deployment', 'argocd', 'argocd-server'],
+  ['Deployment', 'argocd', 'argocd-repo-server'],
+  ['StatefulSet', 'argocd', 'argocd-application-controller'],
+  ['Deployment', 'argocd', 'argocd-applicationset-controller'],
+  ['Deployment', 'argo-rollouts', 'argo-rollouts'],
+  ['Deployment', 'cert-manager', 'cert-manager'],
+  ['Deployment', 'cert-manager', 'cert-manager-webhook'],
+  ['Deployment', 'external-secrets', 'external-secrets'],
+  ['Deployment', 'external-dns', 'external-dns'],
+  ['Deployment', 'ingress-nginx', 'ingress-nginx-controller'],
+  ['DaemonSet', 'observability', 'opentelemetry-collector-agent'],
+];
+
+function workloadStatus(context, [kind, namespace, name]) {
+  const result = kubectl(context, ['get', kind, name, '-n', namespace, '-o', 'json'], { required: false });
+  if (result.status !== 0) return { kind, namespace, name, status: 'missing' };
+  const resource = JSON.parse(result.stdout);
+  const desired = kind === 'DaemonSet' ? resource.status.desiredNumberScheduled : resource.spec.replicas;
+  const ready = kind === 'DaemonSet' ? resource.status.numberReady ?? 0 : resource.status.readyReplicas ?? 0;
+  return { kind, namespace, name, desired, ready, status: desired > 0 && ready === desired ? 'healthy' : 'degraded' };
+}
+
+export function verifyFoundation({ context = 'kind-idp-foundation' } = {}) {
+  const workloads = REQUIRED_WORKLOADS.map((entry) => workloadStatus(context, entry));
+  const crds = ['applications.argoproj.io', 'applicationsets.argoproj.io', 'rollouts.argoproj.io', 'certificates.cert-manager.io', 'externalsecrets.external-secrets.io'];
+  const crdStatuses = crds.map((name) => ({ name, installed: kubectl(context, ['get', 'crd', name, '-o', 'name'], { required: false }).status === 0 }));
+  const applicationsResult = kubectl(context, ['get', 'applications.argoproj.io', '-n', 'argocd', '-o', 'json'], { required: false });
+  const applications = applicationsResult.status === 0 ? JSON.parse(applicationsResult.stdout).items.map((application) => ({ name: application.metadata.name, sync: application.status?.sync?.status ?? 'Unknown', health: application.status?.health?.status ?? 'Unknown', revision: application.status?.sync?.revision ?? null })).sort((left, right) => left.name.localeCompare(right.name)) : [];
+  const failures = [...workloads.filter((entry) => entry.status !== 'healthy').map((entry) => `${entry.namespace}/${entry.name}:${entry.status}`), ...crdStatuses.filter((entry) => !entry.installed).map((entry) => `crd/${entry.name}:missing`), ...applications.filter((entry) => entry.sync !== 'Synced' || !['Healthy', 'Progressing'].includes(entry.health)).map((entry) => `application/${entry.name}:${entry.sync}/${entry.health}`)];
+  return { schemaVersion: 'idp.foundation-verification/v1', status: failures.length === 0 ? 'healthy' : 'degraded', context, workloads, crds: crdStatuses, applications, failures, evidenceDigest: sha256(stableJson({ context, workloads, crdStatuses, applications })) };
+}
+
+function validLocalUrl(value, role) {
+  let parsed;
+  try { parsed = new URL(value); } catch { throw new IdpError('IDP_FOUNDATION_DIRECTORY_INVALID', `${role}不是有效URL`); }
+  invariant(['http:', 'https:'].includes(parsed.protocol) && !parsed.username && !parsed.password, 'IDP_FOUNDATION_DIRECTORY_INVALID', `${role}必须是不含凭据的HTTP(S) URL`);
+  return parsed.toString();
+}
+
+export function syncFoundationDirectory({ configRoot, argoUrl = 'http://127.0.0.1:9081/', rolloutsUrl = 'http://127.0.0.1:9082/rollouts/', registryUrl = 'http://127.0.0.1:4873/', now = new Date().toISOString() }) {
+  const snapshotRoot = path.join(configRoot, 'components', 'portal', 'snapshots');
+  const target = path.join(snapshotRoot, 'foundation-directory.json');
+  fs.mkdirSync(snapshotRoot, { recursive: true, mode: 0o700 });
+  const preimage = fs.lstatSync(target, { throwIfNoEntry: false });
+  if (preimage) {
+    invariant(preimage.isFile() && !preimage.isSymbolicLink() && preimage.nlink === 1, 'IDP_FOUNDATION_DIRECTORY_UNSAFE', '现有基座目录不是安全普通文件');
+    const backupRoot = path.join(configRoot, 'preimages', 'foundation-directory');
+    fs.mkdirSync(backupRoot, { recursive: true, mode: 0o700 });
+    const backup = path.join(backupRoot, `${Date.now()}-${hashFile(target).slice(7, 19)}.json`);
+    fs.copyFileSync(target, backup, fs.constants.COPYFILE_EXCL);
+    fs.chmodSync(backup, 0o600);
+  }
+  const document = {
+    schemaVersion: 'portal.foundation-directory/v1', generatedAt: now,
+    systems: [
+      { id: 'gitops', title: 'GitOps 发布', description: 'Argo CD 应用差异、同步和健康状态', uiUrl: validLocalUrl(argoUrl, 'Argo CD URL'), healthUrl: new URL('healthz', validLocalUrl(argoUrl, 'Argo CD URL')).toString(), owner: 'idp-deploy' },
+      { id: 'rollouts', title: '渐进发布', description: 'Argo Rollouts 金丝雀与蓝绿发布状态', uiUrl: validLocalUrl(rolloutsUrl, 'Rollouts URL'), owner: 'idp-deploy' },
+      { id: 'registry', title: '本机制品仓', description: 'Verdaccio 包制品与版本', uiUrl: validLocalUrl(registryUrl, 'Registry URL'), owner: 'platform-runtime' },
+    ],
+  };
+  const temporary = `${target}.tmp-${process.pid}`;
+  fs.writeFileSync(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+  fs.renameSync(temporary, target);
+  return { schemaVersion: 'idp.foundation-directory-receipt/v1', status: 'synced', target, digest: hashFile(target), systems: document.systems.map((entry) => entry.id) };
+}