@aipt/idp-deploy 0.1.2

package/src/cli.mjs

@@ -0,0 +1,360 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { initializeConfig, doctorConfig, generateSecrets } from './config.mjs';
+import { acceptMacM4 } from './acceptance.mjs';
+import { syncManagedBindings } from './bindings.mjs';
+import { applyRestore, composeOperation, createBackup, promoteRestore, verifyBackup, verifyDeployment, verifyRestoreCandidate, testRestore } from './operations.mjs';
+import { IdpError } from './errors.mjs';
+import { lockImages } from './images.mjs';
+import { releaseDeploy } from './release.mjs';
+import { importSourceSnapshot } from './sources.mjs';
+import { verifyAssetLifecycle } from './lifecycle.mjs';
+import { assertSafeDirectory, assertSafeRegularFile, resolveContained } from './security.mjs';
+import { validateFoundationContract } from './foundation-contracts.mjs';
+import { applyGitOpsPlan, createGitOpsPlan, verifyGitOpsRepository } from './gitops.mjs';
+import { doctorFoundation, syncFoundationDirectory, verifyFoundation } from './foundation.mjs';
+import { buildStatus, createBuildPlan, generateGithubWorkflow, inspectApplication, triggerBuild, verifyGithubWorkflow } from './delivery.mjs';
+import { applyLocalSourceDeployment, createLocalSourcePlan, initializeApplicationConfig, removeLocalSourceDeployment, stopLocalSourceDeployment, verifyLocalSourceDeployment } from './local-source.mjs';
+import { applyWorkbenchProjectsPlan, createWorkbenchProjectsPlan, initializeWorkbenchProjects, verifyWorkbenchProjects } from './workbench-projects.mjs';
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export function configRootFrom(args, { environment = process.env } = {}) {
+  const index = args.indexOf('--config-dir');
+  if (index >= 0 && (!args[index + 1] || args[index + 1].startsWith('--'))) throw new IdpError('IDP_CONFIG_ARGUMENT_MISSING', '--config-dir后必须提供绝对路径');
+  const explicit = index >= 0 ? args[index + 1] : undefined;
+  const value = explicit ?? environment.IDP_CONFIG_DIR;
+  if (!value) throw new IdpError('IDP_CONFIG_REQUIRED', '请设置IDP_CONFIG_DIR或传入--config-dir');
+  if (!path.isAbsolute(value)) throw new IdpError('IDP_CONFIG_NOT_ABSOLUTE', 'IDP_CONFIG_DIR必须使用原始绝对路径，不能依赖当前工作目录解析');
+  return path.resolve(value);
+}
+
+export function readSourceImportFile(configRoot, rawCandidate) {
+  if (!path.isAbsolute(rawCandidate ?? '')) throw new IdpError('IDP_SOURCE_FILE_NOT_ABSOLUTE', '--file必须是原始绝对路径');
+  const { root } = doctorConfig(configRoot, { requireConfigured: false, profile: 'registry' });
+  const imports = resolveContained(root, 'imports', 'Snapshot imports目录');
+  assertSafeDirectory(imports, 0o700, { role: 'Snapshot imports目录' });
+  const candidate = path.resolve(rawCandidate);
+  const relative = path.relative(imports, candidate);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) throw new IdpError('IDP_SOURCE_FILE_OUTSIDE_IMPORTS', '--file必须位于IDP_CONFIG_DIR/imports内');
+  const safeCandidate = resolveContained(imports, relative, 'Snapshot导入文件');
+  const stat = assertSafeRegularFile(safeCandidate, 0o600, { allowEmpty: false, role: 'Snapshot导入文件' });
+  if (stat.size > 16 * 1024 * 1024) throw new IdpError('IDP_SOURCE_FILE_INVALID', '导入文件必须是权限不超过0600、1 byte到16 MiB的普通非链接文件');
+  return fs.readFileSync(safeCandidate);
+}
+
+export function composeRequiresConfigured(command, args) {
+  const allowUnconfigured = args.includes('--allow-unconfigured');
+  if (allowUnconfigured && command !== 'compose') {
+    throw new IdpError('IDP_UNCONFIGURED_BYPASS_FORBIDDEN', '--allow-unconfigured只允许只读的compose配置预览，不能用于pull、up或down');
+  }
+  return command !== 'down' && !allowUnconfigured;
+}
+
+export function readContractFile(rawCandidate) {
+  if (!path.isAbsolute(rawCandidate ?? '')) throw new IdpError('IDP_CONTRACT_FILE_NOT_ABSOLUTE', 'contracts verify的--file必须是原始绝对路径');
+  const candidate = path.resolve(rawCandidate);
+  const stat = fs.lstatSync(candidate, { throwIfNoEntry: false });
+  if (!stat || !stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size < 2 || stat.size > 4 * 1024 * 1024) {
+    throw new IdpError('IDP_CONTRACT_FILE_INVALID', '合同文件必须是1 byte到4 MiB的普通非链接文件');
+  }
+  let document;
+  try { document = JSON.parse(fs.readFileSync(candidate, 'utf8')); }
+  catch (error) { throw new IdpError('IDP_CONTRACT_JSON_INVALID', '合同文件不是有效JSON', { cause: error.message }); }
+  return { candidate, document };
+}
+
+function print(value) {
+  process.stdout.write(`${typeof value === 'string' ? value : JSON.stringify(value, null, 2)}\n`);
+}
+
+export async function main(args) {
+  const [command, subcommand] = args;
+  if (!command || ['help', '--help', '-h'].includes(command)) {
+    process.stdout.write('本地项目命令：\n  app config-init --project <绝对项目目录>\n  local app plan --project <绝对目录> --compose-file <绝对文件> --output <IDP_CONFIG_DIR/plans/local-applications/...>\n  local app apply|verify|stop --plan <绝对文件>\n  local app remove --plan <绝对文件> --confirm <application-id>\n\n');
+    process.stdout.write('Docker工作台项目命令：\n  workbench projects init\n  workbench projects plan --dyyto-root <绝对目录> --file <candidate> --output <Plan>\n  workbench projects apply --plan <Plan>\n  workbench projects verify\n\n');
+    print(`idpctl：私有IDP部署与运维工具\n\n命令：\n  config init\n  config generate-secrets\n  config snapshot\n  release deploy [profile] [--version <semver>] [--oci-repository-root <host/namespace/repository>]\n  gitops app plan-create|plan-update|plan-remove --component-contract <绝对路径> --environment-binding <绝对路径> --release-candidate <绝对路径> --gitops-root <绝对路径> --output <IDP_CONFIG_DIR/plans/...>\n  gitops app apply --plan <绝对路径>\n  gitops app verify --application <名称> --environment <名称> --gitops-root <绝对路径>\n  foundation doctor|verify [--context <kube-context>]\n  foundation directory sync [--argo-url <URL>] [--rollouts-url <URL>] [--registry-url <URL>]\n  sources import dyyto|bench --stdin\n  sources import dyyto|bench --file <IDP_CONFIG_DIR/imports/...>\n  images lock\n  doctor [profile] [--require-configured]\n  compose <profile>\n  pull <profile>\n  up <profile>\n  switch <profile>\n  down <profile>\n  verify <profile>\n  bindings sync <active-profile>\n  accept mac-m4 <profile> --confirm-restart <IDP_INSTANCE_ID>\n  backup create [profile]\n  backup verify <generation-id>\n  restore test <generation-id>\n  restore apply <generation-id>\n  restore verify <candidate-id>\n  restore promote <candidate-id> --confirm <candidate-id>\n  contracts verify config-release|release-candidate|deployment-evidence --file <绝对JSON路径>\n\nProfile：registry、tech-only、foundation、flow、portal、core、full、business-smartgo、core-smartgo；release deploy默认foundation。SmartGo不会进入默认core/full，需显式选择business-smartgo或core-smartgo。\n所有命令只通过IDP_CONFIG_DIR读取仓库外配置；Secret不会打印到终端。GitOps写入必须来自不可变Plan，Apply复验输入、HEAD与Preimage并在外部配置根保存恢复证据。release deploy在同一实例Lease内完成自研镜像的amd64/arm64构建与digest绑定、已有部署备份和隔离恢复演练、镜像锁、Compose、Verifier与Binding事务。bindings sync只从已启用且verify通过的当前运行事实生成Bench ServiceBinding，并保护用户修改与历史Preimage。跨Profile必须使用switch，它会显式清理旧Profile Orphan。restore apply先生成隔离候选；promote保留物理或逻辑Preimage并在失败时自动回滚。`);
+    process.stdout.write('无集群开发者命令：\n  app inspect --component-contract <绝对路径> [--environment-binding <绝对路径>]\n  workflow generate|verify --file <绝对路径>\n  build plan --component-contract <绝对路径> --repository <Git URL> --commit <40位SHA> --image-repository <OCI仓库> --output <绝对路径>\n  build trigger --plan <绝对路径> --provider manual --output <绝对路径>\n  build status --trigger <绝对路径>\n附加只读命令：\n  lifecycle check\n  contracts verify ...\n');
+    return;
+  }
+  if (command === 'app' && subcommand === 'inspect') {
+    const values = namedArguments(args.slice(2), ['--component-contract', '--environment-binding']);
+    invariantDelivery(values, '--component-contract', 'app inspect');
+    print(inspectApplication({ componentFile: values['--component-contract'], environmentBindingFile: values['--environment-binding'] }));
+    return;
+  }
+  if (command === 'workflow' && ['generate', 'verify'].includes(subcommand)) {
+    const values = namedArguments(args.slice(2), ['--file']);
+    invariantDelivery(values, '--file', `workflow ${subcommand}`);
+    print(subcommand === 'generate' ? generateGithubWorkflow({ output: values['--file'] }) : verifyGithubWorkflow({ workflowFile: values['--file'] }));
+    return;
+  }
+  if (command === 'build' && subcommand === 'plan') {
+    const values = namedArguments(args.slice(2), ['--component-contract', '--repository', '--commit', '--image-repository', '--workflow', '--output']);
+    for (const key of ['--component-contract', '--repository', '--commit', '--image-repository', '--output']) invariantDelivery(values, key, 'build plan');
+    print(createBuildPlan({ componentFile: values['--component-contract'], repository: values['--repository'], commit: values['--commit'], imageRepository: values['--image-repository'], workflow: values['--workflow'], output: values['--output'] }));
+    return;
+  }
+  if (command === 'build' && subcommand === 'trigger') {
+    const values = namedArguments(args.slice(2), ['--plan', '--provider', '--output']);
+    for (const key of ['--plan', '--output']) invariantDelivery(values, key, 'build trigger');
+    print(triggerBuild({ planFile: values['--plan'], provider: values['--provider'] ?? 'manual', output: values['--output'] }));
+    return;
+  }
+  if (command === 'build' && subcommand === 'status') {
+    const values = namedArguments(args.slice(2), ['--trigger']);
+    invariantDelivery(values, '--trigger', 'build status');
+    print(buildStatus({ triggerFile: values['--trigger'] }));
+    return;
+  }
+  if (command === 'lifecycle' && subcommand === 'check') {
+    print(verifyAssetLifecycle(repositoryRoot));
+    return;
+  }
+  if (command === 'contracts' && subcommand === 'verify') {
+    const kind = args[2];
+    const fileIndex = args.indexOf('--file');
+    if (fileIndex < 0 || !args[fileIndex + 1] || args[fileIndex + 1].startsWith('--')) throw new IdpError('IDP_CONTRACT_FILE_REQUIRED', 'contracts verify需要--file <绝对JSON路径>');
+    const { candidate, document } = readContractFile(args[fileIndex + 1]);
+    const validated = validateFoundationContract(kind, document);
+    print({ schemaVersion: 'idp.contract-verification/v1', status: 'valid', kind, file: candidate, digest: validated.digest });
+    return;
+  }
+  if (command === 'foundation' && ['doctor', 'verify'].includes(subcommand)) {
+    const values = namedArguments(args.slice(2), ['--context']);
+    print(subcommand === 'doctor' ? doctorFoundation({ context: values['--context'] }) : verifyFoundation({ context: values['--context'] }));
+    return;
+  }
+  if (command === 'release' && subcommand === 'deploy' && args.some((value) => ['--help', '-h'].includes(value))) {
+    print(`用法：\n  ./deploy.sh [foundation|core|business-smartgo|core-smartgo] [--version <semver>] [--oci-repository-root <host/namespace/repository>] [--config-dir <绝对路径>]\n\n默认部署foundation，并自动完成配置初始化、Secret生成、自研镜像双架构构建与推送、镜像digest锁定、pull、switch、verify和Binding同步。SmartGo不会进入默认core；已有Core并行业务开发请显式选择core-smartgo。标准路径使用release/defaults.v1.json中的企业OCI仓库根；--oci-repository-root只用于显式覆盖。`);
+    return;
+  }
+  const configRoot = configRootFrom(args);
+  if (command === 'app' && subcommand === 'config-init') {
+    const values = namedArguments(args.slice(2), ['--project', '--config-dir', '--application-config-dir']);
+    invariantNamed(values, '--project', 'app config-init');
+    print(initializeApplicationConfig({ configRoot, projectRoot: values['--project'], applicationConfigRoot: values['--application-config-dir'] }));
+    return;
+  }
+  if (command === 'workbench' && subcommand === 'projects') {
+    const action = args[2];
+    const values = namedArguments(args.slice(3), ['--dyyto-root', '--file', '--output', '--plan', '--config-dir']);
+    if (action === 'init') print(initializeWorkbenchProjects({ configRoot }));
+    else if (action === 'plan') {
+      for (const key of ['--dyyto-root', '--file', '--output']) invariantNamed(values, key, 'workbench projects plan');
+      print(createWorkbenchProjectsPlan({ configRoot, dyytoRoot: values['--dyyto-root'], candidateFile: values['--file'], output: values['--output'] }));
+    } else if (action === 'apply') { invariantNamed(values, '--plan', 'workbench projects apply'); print(applyWorkbenchProjectsPlan({ configRoot, planFile: values['--plan'] })); }
+    else if (action === 'verify') print(verifyWorkbenchProjects({ configRoot }));
+    else throw new IdpError('IDP_WORKBENCH_ACTION_UNKNOWN', `未知工作台项目动作：${action ?? ''}`);
+    return;
+  }
+  if (command === 'local' && subcommand === 'app') {
+    const action = args[2];
+    const values = namedArguments(args.slice(3), ['--project', '--compose-file', '--output', '--plan', '--confirm', '--config-dir', '--application-config-dir']);
+    if (action === 'plan') {
+      for (const key of ['--project', '--compose-file', '--output']) invariantNamed(values, key, 'local app plan');
+      print(createLocalSourcePlan({ configRoot, applicationConfigRoot: values['--application-config-dir'], projectRoot: values['--project'], composeFile: values['--compose-file'], output: values['--output'] }));
+      return;
+    }
+    invariantNamed(values, '--plan', `local app ${action ?? ''}`);
+    if (action === 'apply') print(applyLocalSourceDeployment({ configRoot, applicationConfigRoot: values['--application-config-dir'], planFile: values['--plan'] }));
+    else if (action === 'verify') print(verifyLocalSourceDeployment({ configRoot, applicationConfigRoot: values['--application-config-dir'], planFile: values['--plan'] }));
+    else if (action === 'stop') print(stopLocalSourceDeployment({ configRoot, applicationConfigRoot: values['--application-config-dir'], planFile: values['--plan'] }));
+    else if (action === 'remove') print(removeLocalSourceDeployment({ configRoot, applicationConfigRoot: values['--application-config-dir'], planFile: values['--plan'], confirmation: values['--confirm'] }));
+    else throw new IdpError('IDP_LOCAL_ACTION_UNKNOWN', `未知本地应用动作：${action ?? ''}`);
+    return;
+  }
+  if (command === 'foundation' && subcommand === 'directory' && args[2] === 'sync') {
+    const values = namedArguments(args.slice(3), ['--argo-url', '--rollouts-url', '--registry-url', '--config-dir']);
+    print(syncFoundationDirectory({ configRoot, argoUrl: values['--argo-url'], rolloutsUrl: values['--rollouts-url'], registryUrl: values['--registry-url'] }));
+    return;
+  }
+  if (command === 'gitops' && subcommand === 'app') {
+    const action = args[2];
+    const values = namedArguments(args.slice(3), ['--component-contract', '--environment-binding', '--release-candidate', '--gitops-root', '--output', '--plan', '--application', '--environment', '--config-dir']);
+    if (['plan-create', 'plan-update', 'plan-remove'].includes(action)) {
+      for (const key of ['--component-contract', '--environment-binding', '--release-candidate', '--gitops-root', '--output']) invariantNamed(values, key, action);
+      print(createGitOpsPlan({ operation: action.slice(5), componentFile: values['--component-contract'], bindingFile: values['--environment-binding'], candidateFile: values['--release-candidate'], gitopsRoot: values['--gitops-root'], output: values['--output'], configRoot }));
+      return;
+    }
+    if (action === 'apply') {
+      invariantNamed(values, '--plan', action);
+      print(applyGitOpsPlan({ planFile: values['--plan'], configRoot }));
+      return;
+    }
+    if (action === 'verify') {
+      for (const key of ['--application', '--environment', '--gitops-root']) invariantNamed(values, key, action);
+      print(verifyGitOpsRepository({ gitopsRoot: values['--gitops-root'], application: values['--application'], environment: values['--environment'] }));
+      return;
+    }
+    throw new IdpError('IDP_GITOPS_ACTION_UNKNOWN', `未知GitOps应用动作：${action ?? ''}`);
+  }
+  if (command === 'release' && subcommand === 'deploy') {
+    const { profile, version, ociRepositoryRoot } = releaseDeployArguments(args);
+    print(releaseDeploy({ repositoryRoot, configRoot, profile, version, ociRepositoryRoot }));
+    return;
+  }
+  if (command === 'sources' && subcommand === 'import') {
+    const source = args[2];
+    const fileIndex = args.indexOf('--file');
+    const useStdin = args.includes('--stdin');
+    invariantSourceArguments(source, useStdin, fileIndex, args);
+    let bytes;
+    if (useStdin) bytes = await readBoundedStdin();
+    else bytes = readSourceImportFile(configRoot, args[fileIndex + 1]);
+    print(importSourceSnapshot({ configRoot, source, bytes }));
+    return;
+  }
+  if (command === 'config' && subcommand === 'init') {
+    print(initializeConfig(configRoot).report);
+    return;
+  }
+  if (command === 'config' && subcommand === 'generate-secrets') {
+    print(generateSecrets(configRoot));
+    return;
+  }
+  if (command === 'images' && subcommand === 'lock') {
+    print(lockImages(configRoot));
+    return;
+  }
+  if (command === 'doctor') {
+    const profile = subcommand && !subcommand.startsWith('-') ? subcommand : 'full';
+    print(doctorConfig(configRoot, { requireConfigured: args.includes('--require-configured'), profile }).report);
+    return;
+  }
+  if (command === 'verify') {
+    const profile = subcommand ?? 'core';
+    print(verifyDeployment({ repositoryRoot, configRoot, profile }).receipt);
+    return;
+  }
+  if (command === 'bindings' && subcommand === 'sync') {
+    const profile = args[2];
+    if (!profile || profile.startsWith('-')) throw new IdpError('IDP_BINDING_PROFILE_REQUIRED', 'bindings sync后必须提供当前活动Profile');
+    print(syncManagedBindings({ configRoot, profile }));
+    return;
+  }
+  if (command === 'accept' && subcommand === 'mac-m4') {
+    const profile = args[2] && !args[2].startsWith('-') ? args[2] : 'core';
+    const confirmIndex = args.indexOf('--confirm-restart');
+    const confirmation = confirmIndex >= 0 ? args[confirmIndex + 1] : undefined;
+    print(acceptMacM4({ repositoryRoot, configRoot, profile, confirmation }).receipt);
+    return;
+  }
+  if (['compose', 'pull', 'up', 'switch', 'down'].includes(command)) {
+    const profile = subcommand ?? 'core';
+    const composeCommand = command === 'compose' ? ['config'] : command === 'pull' ? ['pull'] : ['up', 'switch'].includes(command) ? ['up', '-d', '--wait'] : ['down'];
+    const result = composeOperation({ repositoryRoot, configRoot, profile, command: composeCommand, requireConfigured: composeRequiresConfigured(command === 'switch' ? 'up' : command, args), allowProfileSwitch: command === 'switch' });
+    print(result.receipt);
+    return;
+  }
+  if (command === 'backup' && (!subcommand || subcommand === 'create')) {
+    const profile = args[2] && !args[2].startsWith('-') ? args[2] : 'core';
+    print(createBackup({ repositoryRoot, configRoot, profile }).receipt);
+    return;
+  }
+  if (command === 'backup' && subcommand === 'verify') {
+    const generationId = args[2];
+    if (!generationId || generationId.startsWith('-')) throw new IdpError('IDP_BACKUP_ID_REQUIRED', 'backup verify需要代次ID');
+    print(verifyBackup({ configRoot, generationId }).receipt);
+    return;
+  }
+  if (command === 'restore' && subcommand === 'test') {
+    const generationId = args[2];
+    if (!generationId || generationId.startsWith('-')) throw new IdpError('IDP_BACKUP_ID_REQUIRED', 'restore test需要代次ID');
+    print(testRestore({ repositoryRoot, configRoot, generationId }).receipt);
+    return;
+  }
+  if (command === 'restore' && subcommand === 'apply') {
+    const generationId = args[2];
+    if (!generationId || generationId.startsWith('-')) throw new IdpError('IDP_BACKUP_ID_REQUIRED', 'restore apply需要代次ID');
+    print(applyRestore({ repositoryRoot, configRoot, generationId }).receipt);
+    return;
+  }
+  if (command === 'restore' && subcommand === 'verify') {
+    const candidateId = args[2];
+    if (!candidateId || candidateId.startsWith('-')) throw new IdpError('IDP_RESTORE_CANDIDATE_ID_REQUIRED', 'restore verify需要候选ID');
+    print(verifyRestoreCandidate({ configRoot, candidateId }).receipt);
+    return;
+  }
+  if (command === 'restore' && subcommand === 'promote') {
+    const candidateId = args[2];
+    const confirmIndex = args.indexOf('--confirm');
+    const confirmation = confirmIndex >= 0 ? args[confirmIndex + 1] : undefined;
+    if (!candidateId || candidateId.startsWith('-')) throw new IdpError('IDP_RESTORE_CANDIDATE_ID_REQUIRED', 'restore promote需要候选ID');
+    print(promoteRestore({ repositoryRoot, configRoot, candidateId, confirmation }).receipt);
+    return;
+  }
+  if (command === 'config' && subcommand === 'snapshot') {
+    const { report } = doctorConfig(configRoot, { requireConfigured: false });
+    const target = path.join(configRoot, 'snapshots', `${Date.now()}-${report.digest.slice(7, 19)}.json`);
+    fs.writeFileSync(target, `${JSON.stringify(report, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+    print({ target, digest: report.digest });
+    return;
+  }
+  throw new IdpError('IDP_COMMAND_UNKNOWN', `未知命令：${args.join(' ')}`);
+}
+
+export function releaseDeployArguments(args) {
+  const values = {};
+  const positionals = [];
+  const optionCodes = {
+    '--version': ['version', 'IDP_RELEASE_VERSION_REQUIRED', '--version后必须提供SemVer版本号'],
+    '--config-dir': ['configDir', 'IDP_CONFIG_ARGUMENT_MISSING', '--config-dir后必须提供绝对路径'],
+    '--oci-repository-root': ['ociRepositoryRoot', 'IDP_OCI_REPOSITORY_ROOT_REQUIRED', '--oci-repository-root后必须提供OCI仓库根'],
+  };
+  for (let index = 2; index < args.length; index += 1) {
+    const value = args[index];
+    const contract = optionCodes[value];
+    if (contract) {
+      const [key, code, message] = contract;
+      const optionValue = args[index + 1];
+      if (!optionValue || optionValue.startsWith('--')) throw new IdpError(code, message);
+      if (values[key] !== undefined) throw new IdpError('IDP_RELEASE_ARGUMENT_DUPLICATE', `release deploy参数重复：${value}`);
+      values[key] = optionValue;
+      index += 1;
+    } else if (value.startsWith('-')) {
+      throw new IdpError('IDP_RELEASE_ARGUMENT_UNKNOWN', `release deploy包含未知参数：${value}`);
+    } else positionals.push(value);
+  }
+  if (positionals.length > 1) throw new IdpError('IDP_RELEASE_ARGUMENT_UNKNOWN', `release deploy包含多余位置参数：${positionals.slice(1).join(' ')}`);
+  return { profile: positionals[0] ?? 'foundation', version: values.version, ociRepositoryRoot: values.ociRepositoryRoot };
+}
+
+function invariantSourceArguments(source, useStdin, fileIndex, args) {
+  if (!['dyyto', 'bench'].includes(source)) throw new IdpError('IDP_SOURCE_UNKNOWN', 'sources import需要dyyto或bench');
+  if (useStdin === (fileIndex >= 0)) throw new IdpError('IDP_SOURCE_INPUT_INVALID', 'sources import必须且只能选择--stdin或--file');
+  if (fileIndex >= 0 && (!args[fileIndex + 1] || args[fileIndex + 1].startsWith('--'))) throw new IdpError('IDP_SOURCE_FILE_REQUIRED', '--file后必须提供绝对路径');
+}
+
+async function readBoundedStdin() {
+  const chunks = []; let size = 0;
+  for await (const chunk of process.stdin) {
+    size += chunk.length;
+    if (size > 16 * 1024 * 1024) throw new IdpError('IDP_SOURCE_SIZE_INVALID', 'stdin Snapshot不能超过16 MiB');
+    chunks.push(chunk);
+  }
+  if (size === 0) throw new IdpError('IDP_SOURCE_SIZE_INVALID', 'stdin Snapshot不能为空');
+  return Buffer.concat(chunks);
+}
+
+export function namedArguments(args, allowed) {
+  const result = {};
+  for (let index = 0; index < args.length; index += 2) {
+    const key = args[index];
+    const value = args[index + 1];
+    if (!allowed.includes(key)) throw new IdpError('IDP_ARGUMENT_UNKNOWN', `未知参数：${key ?? ''}`);
+    if (!value || value.startsWith('--')) throw new IdpError('IDP_ARGUMENT_VALUE_REQUIRED', `${key}后必须提供值`);
+    if (result[key] !== undefined) throw new IdpError('IDP_ARGUMENT_DUPLICATE', `参数重复：${key}`);
+    result[key] = value;
+  }
+  return result;
+}
+
+function invariantNamed(values, key, action) {
+  if (!values[key]) throw new IdpError('IDP_GITOPS_ARGUMENT_REQUIRED', `${action}需要${key}`);
+}
+
+function invariantDelivery(values, key, action) {
+  if (!values[key]) throw new IdpError('IDP_DELIVERY_ARGUMENT_REQUIRED', `${action}需要${key}`);
+}

package/src/compose.mjs

@@ -0,0 +1,19 @@
+import path from 'node:path';
+import { resolveProfile } from './profiles.mjs';
+
+const FRAGMENTS = {
+  postgresql: 'postgresql.yaml',
+  registry: 'registry.yaml',
+  tech: 'tech.yaml',
+  flow: 'flow.yaml',
+  portal: 'portal.yaml',
+  smartgo: 'smartgo.yaml',
+  edge: 'edge.yaml',
+};
+
+export function composeArgs(repositoryRoot, configRoot, profile, command, { projectName = 'company-idp' } = {}) {
+  const args = ['compose', '--project-name', projectName, '--env-file', path.join(configRoot, '.env')];
+  for (const component of resolveProfile(profile)) args.push('-f', path.join(repositoryRoot, 'compose', FRAGMENTS[component]));
+  args.push(...command);
+  return args;
+}