@wdyy/skills 0.1.12 → 0.1.14

package/.well-known/skills/wdyy-deployment-standard/scripts/validate-deployment-package.test.mjs

@@ -1,39 +1,51 @@
+import test from 'node:test';
 import assert from 'node:assert/strict';
 import { createHash } from 'node:crypto';
-import { access, chmod, cp, copyFile, mkdir, mkdtemp, readFile, readdir, rm, symlink, unlink, writeFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { chmod, mkdtemp, mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { afterEach, test } from 'node:test';
-import { spawnSync } from 'node:child_process';
+import { promisify } from 'node:util';
+import { gunzip } from 'node:zlib';
 
+const run = promisify(execFile);
+const unzip = promisify(gunzip);
 const scriptsRoot = dirname(fileURLToPath(import.meta.url));
-const skillRoot = resolve(scriptsRoot, '..');
-const templatesRoot = join(skillRoot, 'templates');
+const generator = join(scriptsRoot, 'generate-deployment-files.mjs');
 const validator = join(scriptsRoot, 'validate-deployment-package.mjs');
-const deployTemplate = join(templatesRoot, 'deploy.sh.template');
-const composeTemplate = join(templatesRoot, 'docker-compose.yml');
-const temporaryDirectories = [];
+const created = [];
 
-afterEach(async () => {
-  await Promise.all(temporaryDirectories.splice(0).map((path) => rm(path, { recursive: true, force: true })));
-});
-
-async function temporary(prefix) {
-  const path = await mkdtemp(join(tmpdir(), prefix));
-  temporaryDirectories.push(path);
-  return path;
-}
-
-function envText(extra = '') {
-  return `# 前端
+const envText = `# 前端
+FRONTEND_URL=0.0.0.0
+FRONTEND_PORT=5173
+# 后端
+BACKEND_URL=0.0.0.0
+BACKEND_PORT=3000
+# 数据库
+DB_URL=db.internal
+DB_PORT=5432
+DB_USER=app
+DB_PASSWORD=secret
+DB_NAME=app
+DB_SCHEMA=public
+# API
+API_URL=
+API_PREFIX=api
+VITE_API_BASE_URL=/api
+# 部署
+PROJECT_NAME=example_project
+DOCKER_BIND_IP=0.0.0.0
+DOCKER_PLATFORM=linux/amd64
+FRONTEND_BASE_IMAGE=nginx:stable
+BACKEND_BASE_IMAGE=node:24-alpine3.24
+`;
+const exampleText = `# 前端
 FRONTEND_URL=0.0.0.0
 FRONTEND_PORT=5173
-
 # 后端
 BACKEND_URL=0.0.0.0
 BACKEND_PORT=3000
-
 # 数据库
 DB_URL=
 DB_PORT=5432
@@ -41,326 +53,325 @@ DB_USER=
 DB_PASSWORD=
 DB_NAME=
 DB_SCHEMA=
-
 # API
-
+API_URL=
+API_PREFIX=api
+VITE_API_BASE_URL=/api
 # 部署
-PROJECT_NAME=fixture
-DOCKER_BIND_IP=127.0.0.1
+PROJECT_NAME=
+DOCKER_BIND_IP=
+DOCKER_PLATFORM=linux/amd64
 FRONTEND_BASE_IMAGE=nginx:stable
 BACKEND_BASE_IMAGE=node:24-alpine3.24
-${extra}`;
+`;
+
+const fakeDocker = `#!/usr/bin/env node
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const cp = require('child_process');
+const args = process.argv.slice(2);
+if (process.env.DOCKER_LOG) fs.appendFileSync(process.env.DOCKER_LOG, args.join(' ') + '\\n');
+if (args[0] === 'version') {
+  if (process.env.FAIL_SERVER_PLATFORM_READ === '1') process.exit(1);
+  process.stdout.write((process.env.SERVER_PLATFORM || 'linux/amd64') + '\\n');
+  process.exit(0);
 }
-
-async function writeExecutable(path, content) {
-  await writeFile(path, content);
-  await chmod(path, 0o755);
+if (args[0] === 'image' && args[1] === 'inspect') {
+  const image = args[args.length - 1];
+  if (process.env.MISSING_IMAGE === image) process.exit(1);
+  if (args.includes('--format')) process.stdout.write((process.env.IMAGE_PLATFORM || 'linux/amd64') + '\\n');
+  process.exit(0);
 }
-
-async function createFixture({ agents = '# Target project\n', extraEnv = '' } = {}) {
-  const root = await temporary('wdyy-direct-deploy-');
-  const fakeBin = join(root, 'fake-bin');
-  const commandLog = join(root, 'commands.log');
-  await Promise.all([
-    mkdir(fakeBin, { recursive: true }),
-    mkdir(join(root, 'src/frontend'), { recursive: true }),
-    mkdir(join(root, 'src/backend'), { recursive: true }),
-    mkdir(join(root, 'scripts/deployment'), { recursive: true }),
-  ]);
-  await Promise.all([
-    copyFile(deployTemplate, join(root, 'deploy.sh')),
-    copyFile(join(templatesRoot, 'frontend.Dockerfile.template'), join(root, 'src/frontend/Dockerfile')),
-    copyFile(join(templatesRoot, 'Dockerfile.template'), join(root, 'src/backend/Dockerfile')),
-    copyFile(composeTemplate, join(root, 'scripts/deployment/docker-compose.yml')),
-    copyFile(join(templatesRoot, 'frontend-container.conf.template'), join(root, 'scripts/deployment/frontend-container.conf.template')),
-    copyFile(join(templatesRoot, 'dockerignore.template'), join(root, '.dockerignore')),
-    writeFile(join(root, 'AGENTS.md'), agents),
-    writeFile(join(root, '.env'), envText(extraEnv)),
-    writeFile(commandLog, ''),
-  ]);
-  await chmod(join(root, 'deploy.sh'), 0o755);
-  await chmod(join(root, '.env'), 0o600);
-
-  await writeExecutable(join(fakeBin, 'pnpm'), `#!/usr/bin/env bash
-set -euo pipefail
-printf 'pnpm %s\n' "$*" >> "$COMMAND_LOG"
-[[ "\${FAIL_GATE:-}" != "\${1:-}" ]] || exit 9
-if [[ "\${1:-}" == build ]]; then mkdir -p src/frontend/dist; printf '<div id="app"></div>\n' > src/frontend/dist/index.html; fi
-`);
-  await writeExecutable(join(fakeBin, 'docker'), `#!/usr/bin/env bash
-set -euo pipefail
-printf 'docker %s\n' "$*" >> "$COMMAND_LOG"
-case "\${1:-}" in
-  build) exit 0 ;;
-  image)
-    [[ "\${2:-}" == inspect ]] || exit 10
-    tag="\${!#}"; printf '%s\n' "\${tag##*:}"
-    ;;
-  save)
-    shift; output=; tag=
-    while [[ "$#" -gt 0 ]]; do if [[ "$1" == -o ]]; then output="$2"; shift 2; else tag="$1"; shift; fi; done
-    work="$(mktemp -d)"; printf '[{"Config":"config.json","RepoTags":["%s"],"Layers":[]}]\n' "$tag" > "$work/manifest.json"; printf '{}\n' > "$work/config.json"
-    /usr/bin/tar -cf "$output" -C "$work" manifest.json config.json; /bin/rm -rf "$work"
-    ;;
-  load) exit 0 ;;
-  compose) exit 0 ;;
-  *) echo "unexpected docker command: $*" >&2; exit 10 ;;
-esac
-`);
-  await writeExecutable(join(fakeBin, 'curl'), `#!/usr/bin/env bash
-set -euo pipefail
-url="\${!#}"
-if [[ "\${FAIL_HEALTH:-}" == frontend && "$url" == *:5173/* ]]; then exit 26; fi
-if [[ "\${FAIL_HEALTH:-}" == backend && "$url" == *:3000/* ]]; then exit 27; fi
-if [[ "$url" == */version ]]; then printf '%s' "\${EXPECTED_VERSION:?}"; else printf 'ok'; fi
-`);
-  return { root, fakeBin, commandLog };
+if (args[0] === 'build') {
+  const tagIndex = args.indexOf('--tag');
+  const tag = tagIndex >= 0 ? args[tagIndex + 1] : '';
+  if (process.env.FAIL_BUILD && tag.includes(process.env.FAIL_BUILD)) process.exit(1);
+  process.exit(0);
 }
-
-function run(fixture, args, { input, extraEnv = {}, cwd = fixture.root } = {}) {
-  return spawnSync('bash', args, {
-    cwd,
-    encoding: 'utf8',
-    input,
-    env: { ...process.env, PATH: `${fixture.fakeBin}:${process.env.PATH}`, COMMAND_LOG: fixture.commandLog, ...extraEnv },
-  });
+if (args[0] === 'save') {
+  const output = args[args.indexOf('-o') + 1];
+  const tag = args[args.length - 1];
+  const [imageOs, imageArchitecture] = (process.env.IMAGE_PLATFORM || 'linux/amd64').split('/');
+  const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'fake-image-'));
+  fs.writeFileSync(path.join(temporary, 'manifest.json'), JSON.stringify([{Config:'config.json',RepoTags:[tag],Layers:[]}]) + '\\n');
+  fs.writeFileSync(path.join(temporary, 'config.json'), JSON.stringify({architecture:imageArchitecture,os:imageOs}) + '\\n');
+  const result = cp.spawnSync('tar', ['-cf', output, '-C', temporary, 'manifest.json', 'config.json']);
+  fs.rmSync(temporary, {recursive:true, force:true});
+  process.exit(result.status || 0);
+}
+if (args[0] === 'compose' && args.includes('up') && process.env.FAIL_COMPOSE_UP === '1') process.exit(1);
+process.exit(0);
+`;
+
+async function fixture() {
+  const root = await mkdtemp(join(tmpdir(), 'wdyy-unified-delivery-'));
+  created.push(root);
+  await mkdir(join(root, 'src/frontend'), { recursive: true });
+  await mkdir(join(root, 'src/backend'), { recursive: true });
+  await mkdir(join(root, 'deploy'), { recursive: true });
+  await writeFile(join(root, '.env'), envText, { mode: 0o600 });
+  await writeFile(join(root, '.env.example'), exampleText, { mode: 0o644 });
+  await writeFile(join(root, 'package.json'), '{}\n');
+  await writeFile(join(root, 'pnpm-lock.yaml'), 'lockfileVersion: 9\n');
+  await writeFile(join(root, 'pnpm-workspace.yaml'), 'packages:\n  - src/*\n');
+  await run(process.execPath, [generator, '--target', root, '--write']);
+  const bin = join(root, 'fake-bin');
+  await mkdir(bin);
+  await writeFile(join(bin, 'docker'), fakeDocker, { mode: 0o755 });
+  await chmod(join(bin, 'docker'), 0o755);
+  const log = join(root, 'docker.log');
+  const environment = { ...process.env, PATH: `${bin}:${process.env.PATH}`, DOCKER_LOG: log };
+  return { root, log, environment, archive: join(root, 'deploy/example_project-docker.tar.gz') };
 }
 
-function runBuild(fixture, extraEnv = {}, ...extraArgs) {
-  return run(fixture, ['deploy.sh', 'build', ...extraArgs], { extraEnv });
+async function buildProject(item, extraEnvironment = {}) {
+  return run(join(item.root, 'deploy.sh'), ['build'], { cwd: item.root, env: { ...item.environment, ...extraEnvironment } });
 }
 
-async function releaseVersion(root) {
-  return (await readFile(join(root, 'deploy/release.env'), 'utf8')).trim().slice('RELEASE_VERSION='.length);
+async function extractArchive(item) {
+  const extracted = await mkdtemp(join(tmpdir(), 'wdyy-unified-package-'));
+  created.push(extracted);
+  await run('tar', ['-xzf', item.archive, '-C', extracted]);
+  return extracted;
 }
 
-function runValidator(root, version) {
-  return spawnSync(process.execPath, [
-    validator,
-    join(root, 'deploy/deploy.sh'),
-    join(root, `deploy/${version}/docker/docker-compose.yml`),
-    join(root, 'deploy'),
-  ], { encoding: 'utf8' });
+async function rewriteManifest(root) {
+  const names = ['.env', 'backend-image.tar', 'deploy.sh', 'docker-compose.yml', 'frontend-image.tar'];
+  const lines = [];
+  for (const name of names) {
+    const hash = createHash('sha256').update(await readFile(join(root, name))).digest('hex');
+    lines.push(`${hash}  ${name}`);
+  }
+  await writeFile(join(root, 'manifest.sha256'), `${lines.join('\n')}\n`);
 }
 
-async function installOnServer(fixture) {
-  const serverRoot = await temporary('wdyy-server-root-');
-  await cp(join(fixture.root, 'deploy'), serverRoot, { recursive: true, force: true });
-  await chmod(join(serverRoot, 'deploy.sh'), 0o755);
-  return serverRoot;
+async function setTargetPlatform(root, platform) {
+  const environmentPath = join(root, '.env');
+  const environment = await readFile(environmentPath, 'utf8');
+  await writeFile(environmentPath, environment.replace(/^DOCKER_PLATFORM=.*$/m, `DOCKER_PLATFORM=${platform}`), { mode: 0o600 });
 }
 
-function runServer(fixture, serverRoot, choice, extraEnv = {}, args = []) {
-  return run(fixture, [join(serverRoot, 'deploy.sh'), ...args], {
-    cwd: fixture.root,
-    input: `${choice}\n`,
-    extraEnv,
-  });
+async function readImageArchivePlatform(archive) {
+  const { stdout: manifestText } = await run('tar', ['-xOf', archive, 'manifest.json']);
+  const [{ Config: configName }] = JSON.parse(manifestText);
+  const { stdout: configText } = await run('tar', ['-xOf', archive, configName]);
+  const config = JSON.parse(configText);
+  return `${config.os}/${config.architecture}`;
 }
 
-async function rewriteManifest(versionRoot) {
-  const files = [];
-  async function walk(current) {
-    for (const entry of await readdir(current, { withFileTypes: true })) {
-      const path = join(current, entry.name);
-      if (entry.isDirectory()) await walk(path);
-      else if (entry.isFile() && entry.name !== 'manifest.sha256') files.push(path);
-    }
-  }
-  await walk(versionRoot);
-  const lines = await Promise.all(files.sort().map(async (path) => {
-    const relativePath = path.slice(versionRoot.length + 1).split('\\').join('/');
-    return `${createHash('sha256').update(await readFile(path)).digest('hex')}  ${relativePath}`;
-  }));
-  await writeFile(join(versionRoot, 'manifest.sha256'), `${lines.join('\n')}\n`);
+async function rewriteImageArchivePlatform(archive, platform) {
+  const temporary = await mkdtemp(join(tmpdir(), 'wdyy-image-platform-'));
+  created.push(temporary);
+  await run('tar', ['-xf', archive, '-C', temporary]);
+  const manifest = JSON.parse(await readFile(join(temporary, 'manifest.json'), 'utf8'));
+  const configName = manifest[0].Config;
+  const config = JSON.parse(await readFile(join(temporary, configName), 'utf8'));
+  const [os, architecture] = platform.split('/');
+  config.os = os;
+  config.architecture = architecture;
+  await writeFile(join(temporary, configName), `${JSON.stringify(config)}\n`);
+  await run('tar', ['-cf', archive, '-C', temporary, 'manifest.json', configName]);
 }
 
-test('build 导出带版本号双镜像和双服务完整包', async () => {
-  const fixture = await createFixture();
-  const result = runBuild(fixture);
-  assert.equal(result.status, 0, `stdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
-  const version = await releaseVersion(fixture.root);
-  assert.deepEqual((await readdir(join(fixture.root, 'deploy'))).sort(), ['.env', version, 'deploy.sh', 'release.env'].sort());
-  await Promise.all([
-    access(join(fixture.root, `deploy/${version}/frontend-image.tar`)),
-    access(join(fixture.root, `deploy/${version}/backend-image.tar`)),
-  ]);
-  const validation = runValidator(fixture.root, version);
-  assert.equal(validation.status, 0, validation.stderr);
-  assert.match(validation.stdout, /valid direct dual-image deployment package/);
-  const log = await readFile(fixture.commandLog, 'utf8');
-  assert.match(log, new RegExp(`--tag fixture_frontend:${version}`));
-  assert.match(log, new RegExp(`--tag fixture_backend:${version}`));
-  const compose = await readFile(join(fixture.root, `deploy/${version}/docker/docker-compose.yml`), 'utf8');
-  assert.deepEqual([...compose.matchAll(/^  ([a-z-]+):$/gm)].map((match) => match[1]), ['frontend', 'backend']);
-  assert.doesNotMatch(compose, /blue|green|PROJECT_HTTP_PORT|nginx\/site/);
+test.after(async () => {
+  await Promise.all(created.map((path) => rm(path, { recursive: true, force: true })));
 });
 
-test('连续构建保持 deploy.sh 与 Compose 字节一致', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const first = await releaseVersion(fixture.root);
-  const hashes = await Promise.all(['deploy/deploy.sh', `deploy/${first}/docker/docker-compose.yml`].map(async (path) => createHash('sha256').update(await readFile(join(fixture.root, path))).digest('hex')));
-  assert.equal(runBuild(fixture).status, 0);
-  const second = await releaseVersion(fixture.root);
-  assert.notEqual(second, first);
-  const nextHashes = await Promise.all(['deploy/deploy.sh', `deploy/${second}/docker/docker-compose.yml`].map(async (path) => createHash('sha256').update(await readFile(join(fixture.root, path))).digest('hex')));
-  assert.deepEqual(nextHashes, hashes);
+test('build 使用本地基础镜像并生成一个含双镜像归档的压缩包', async () => {
+  const item = await fixture();
+  const result = await buildProject(item);
+  assert.match(result.stdout, /delivery archive created/);
+  assert.deepEqual(await readdir(join(item.root, 'deploy')), ['example_project-docker.tar.gz']);
+  const uncompressed = await unzip(await readFile(item.archive));
+  assert.equal(uncompressed.includes(Buffer.from('./._.env')), false);
+  const listing = await run('tar', ['-tzf', item.archive]);
+  assert.doesNotMatch(listing.stdout, /(^|\/)\._[^/]*(?:\n|$)/m);
+  assert.doesNotMatch(listing.stderr, /LIBARCHIVE\.xattr|unknown extended header/i);
+  const extracted = await extractArchive(item);
+  assert.deepEqual((await readdir(extracted)).sort(), ['.env', 'backend-image.tar', 'deploy.sh', 'docker-compose.yml', 'frontend-image.tar', 'manifest.sha256'].sort());
+  const validation = await run(process.execPath, [validator, extracted]);
+  assert.match(validation.stdout, /valid unified Docker delivery package/);
+  const log = await readFile(item.log, 'utf8');
+  assert.match(log, /image inspect nginx:stable/);
+  assert.match(log, /image inspect node:24-alpine3\.24/);
+  assert.equal((log.match(/build --pull=false --platform linux\/amd64/g) ?? []).length, 2);
+  assert.match(log, /build --pull=false --platform linux\/amd64 .*--build-arg VITE_API_BASE_URL=\/api .*example_project_frontend:latest/);
+  assert.doesNotMatch(log, /(^|\s)pull(\s|$)/m);
+  assert.match(log, /save -o .*frontend-image\.tar example_project_frontend:latest/);
+  assert.match(log, /save -o .*backend-image\.tar example_project_backend:latest/);
 });
 
-test('失败构建保留上一发布包和发布账本', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const version = await releaseVersion(fixture.root);
-  const agents = await readFile(join(fixture.root, 'AGENTS.md'), 'utf8');
-  const failed = runBuild(fixture, { FAIL_GATE: 'lint' });
-  assert.equal(failed.status, 9);
-  assert.equal(await releaseVersion(fixture.root), version);
-  assert.equal(await readFile(join(fixture.root, 'AGENTS.md'), 'utf8'), agents);
+test('基础镜像平台不匹配时在 build 前失败', async () => {
+  const item = await fixture();
+  await assert.rejects(buildProject(item, { IMAGE_PLATFORM: 'linux/arm64' }), /image platform mismatch for nginx:stable: expected linux\/amd64, got linux\/arm64/);
+  const log = await readFile(item.log, 'utf8');
+  assert.doesNotMatch(log, /^build /m);
+  assert.equal((await readdir(join(item.root, 'deploy'))).length, 0);
 });
 
-test('build 拒绝额外参数、旧部署键和日志目录配置', async () => {
-  const extra = await createFixture();
-  assert.equal(runBuild(extra, {}, '20260808-001').status, 2);
-  for (const setting of ['PROJECT_HTTP_PORT=9099\n', 'FRONTEND_BLUE_PORT=19091\n', 'LOG_DIR=/tmp/logs\n', 'DATABASE_MIGRATION_MODE=none\n']) {
-    const fixture = await createFixture({ extraEnv: setting });
-    const result = runBuild(fixture);
-    assert.notEqual(result.status, 0);
-    assert.match(result.stderr, /removed deployment configuration/);
-  }
+test('linux/arm64 目标在不同构建机平台上生成并部署单架构交付包', async () => {
+  const item = await fixture();
+  await setTargetPlatform(item.root, 'linux/arm64');
+  await buildProject(item, { IMAGE_PLATFORM: 'linux/arm64' });
+  const buildLog = await readFile(item.log, 'utf8');
+  assert.equal((buildLog.match(/build --pull=false --platform linux\/arm64/g) ?? []).length, 2);
+  const extracted = await extractArchive(item);
+  assert.equal(await readImageArchivePlatform(join(extracted, 'frontend-image.tar')), 'linux/arm64');
+  assert.equal(await readImageArchivePlatform(join(extracted, 'backend-image.tar')), 'linux/arm64');
+  const validation = await run(process.execPath, [validator, extracted]);
+  assert.match(validation.stdout, /valid unified Docker delivery package/);
+  await writeFile(item.log, '');
+  await run(join(extracted, 'deploy.sh'), [], { env: { ...item.environment, IMAGE_PLATFORM: 'linux/arm64', SERVER_PLATFORM: 'linux/arm64' } });
+  const deployLog = await readFile(item.log, 'utf8');
+  assert.match(deployLog, /^version --format \{\{\.Server\.Os\}\}\/\{\{\.Server\.Arch\}\}$/m);
+  assert.equal((deployLog.match(/^load -i /gm) ?? []).length, 2);
 });
 
-test('validator 拒绝镜像 fallback、嵌套日志和符号链接', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  let version = await releaseVersion(fixture.root);
-  let composePath = join(fixture.root, `deploy/${version}/docker/docker-compose.yml`);
-  await writeFile(composePath, (await readFile(composePath, 'utf8')).replace('${FRONTEND_IMAGE:?FRONTEND_IMAGE is required}', '${FRONTEND_IMAGE:-fallback}').replace('../../logs:/app/logs', '../../logs/frontend:/app/logs'));
-  let validation = runValidator(fixture.root, version);
-  assert.notEqual(validation.status, 0);
-  assert.match(validation.stderr, /fallback|logs/);
-
-  assert.equal(runBuild(fixture).status, 0);
-  version = await releaseVersion(fixture.root);
-  await symlink('../outside', join(fixture.root, `deploy/${version}/linked-file`));
-  validation = runValidator(fixture.root, version);
-  assert.notEqual(validation.status, 0);
-  assert.match(validation.stderr, /symbolic links/);
+test('缺少本地基础镜像时在 build 前失败', async () => {
+  const item = await fixture();
+  await assert.rejects(buildProject(item, { MISSING_IMAGE: 'nginx:stable' }), /required local frontend base image is missing/);
+  const log = await readFile(item.log, 'utf8');
+  assert.match(log, /^image inspect nginx:stable$/m);
+  assert.doesNotMatch(log, /^build /m);
+  assert.equal((await readdir(join(item.root, 'deploy'))).length, 0);
 });
 
-test('菜单可独立运行或替换前端且记录成功日志', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const version = await releaseVersion(fixture.root);
-  const serverRoot = await installOnServer(fixture);
-  await writeFile(fixture.commandLog, '');
-  const result = runServer(fixture, serverRoot, '1', { EXPECTED_VERSION: version });
-  assert.equal(result.status, 0, result.stderr);
-  const commands = await readFile(fixture.commandLog, 'utf8');
-  assert.match(commands, /docker load -i .*frontend-image\.tar/);
-  assert.doesNotMatch(commands, /docker load -i .*backend-image\.tar/);
-  assert.match(commands, /compose .* up -d --force-recreate --no-deps frontend/);
-  assert.doesNotMatch(commands, /--no-deps backend/);
-  assert.match(await readFile(join(serverRoot, 'logs/deploy.log'), 'utf8'), new RegExp(`version=${version} operation=run-or-replace-frontend result=success`));
+test('构建失败保留上一份成功交付包且不暴露半成品', async () => {
+  const item = await fixture();
+  await buildProject(item);
+  const before = createHash('sha256').update(await readFile(item.archive)).digest('hex');
+  await assert.rejects(buildProject(item, { FAIL_BUILD: 'backend' }));
+  const after = createHash('sha256').update(await readFile(item.archive)).digest('hex');
+  assert.equal(after, before);
+  assert.deepEqual(await readdir(join(item.root, 'deploy')), ['example_project-docker.tar.gz']);
 });
 
-test('菜单可独立运行后端、同时运行前后端并同时停止', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const version = await releaseVersion(fixture.root);
-  const serverRoot = await installOnServer(fixture);
+test('服务器无参数执行时从脚本目录整体加载并部署前后端', async () => {
+  const item = await fixture();
+  await buildProject(item);
+  const extracted = await extractArchive(item);
+  await writeFile(item.log, '');
+  await run(join(extracted, 'deploy.sh'), [], { cwd: tmpdir(), env: item.environment });
+  const log = await readFile(item.log, 'utf8');
+  const versionIndex = log.indexOf('version --format {{.Server.Os}}/{{.Server.Arch}}');
+  const firstLoadIndex = log.indexOf('load -i ');
+  assert(versionIndex >= 0 && firstLoadIndex > versionIndex);
+  assert.equal((log.match(/^load -i /gm) ?? []).length, 2);
+  assert.match(log, /compose --env-file .* --project-name example_project -f .* up -d --force-recreate --no-build --pull never --wait frontend backend/);
+  assert.match(await readFile(join(extracted, 'logs/deploy.log'), 'utf8'), /operation=deploy result=success/);
+});
 
-  await writeFile(fixture.commandLog, '');
-  assert.equal(runServer(fixture, serverRoot, '2', { EXPECTED_VERSION: version }).status, 0);
-  let commands = await readFile(fixture.commandLog, 'utf8');
-  assert.match(commands, /docker load -i .*backend-image\.tar/);
-  assert.doesNotMatch(commands, /docker load -i .*frontend-image\.tar/);
-  assert.match(commands, /--no-deps backend/);
+test('服务器平台无法读取、不受支持或不匹配时在加载镜像前失败', async () => {
+  const item = await fixture();
+  await buildProject(item);
+  const cases = [
+    [{ FAIL_SERVER_PLATFORM_READ: '1' }, /Docker Server platform is unavailable/],
+    [{ SERVER_PLATFORM: 'windows/amd64' }, /unsupported Docker Server platform: windows\/amd64/],
+    [{ SERVER_PLATFORM: 'linux/arm64' }, /Docker Server platform mismatch: expected linux\/amd64, got linux\/arm64/],
+  ];
+  for (const [extraEnvironment, expectedError] of cases) {
+    const extracted = await extractArchive(item);
+    await writeFile(item.log, '');
+    await assert.rejects(run(join(extracted, 'deploy.sh'), [], { env: { ...item.environment, ...extraEnvironment } }), expectedError);
+    const log = await readFile(item.log, 'utf8');
+    assert.match(log, /^version --format \{\{\.Server\.Os\}\}\/\{\{\.Server\.Arch\}\}$/m);
+    assert.doesNotMatch(log, /^load -i /m);
+    assert.doesNotMatch(log, /^compose .* (?:up|stop) /m);
+    assert.match(await readFile(join(extracted, 'logs/deploy.log'), 'utf8'), /operation=deploy result=failure/);
+  }
+});
 
-  await writeFile(fixture.commandLog, '');
-  assert.equal(runServer(fixture, serverRoot, '3', { EXPECTED_VERSION: version }).status, 0);
-  commands = await readFile(fixture.commandLog, 'utf8');
-  assert.match(commands, /up -d --force-recreate frontend backend/);
+test('服务器在 Docker 操作前拒绝 AppleDouble 和上传压缩包残留', async () => {
+  const item = await fixture();
+  await buildProject(item);
+  const extracted = await extractArchive(item);
+  await writeFile(item.log, '');
+  await writeFile(join(extracted, '._deploy.sh'), 'AppleDouble\n');
+  await assert.rejects(run(join(extracted, 'deploy.sh'), [], { env: item.environment }), /unexpected package entry: \._deploy\.sh/);
+  assert.equal(await readFile(item.log, 'utf8'), '');
+  await rm(join(extracted, '._deploy.sh'));
+  await writeFile(join(extracted, 'example_project-docker.tar.gz'), 'uploaded archive\n');
+  await assert.rejects(run(join(extracted, 'deploy.sh'), [], { env: item.environment }), /unexpected package entry: example_project-docker\.tar\.gz/);
+  assert.equal(await readFile(item.log, 'utf8'), '');
+});
 
-  await writeFile(fixture.commandLog, '');
-  assert.equal(runServer(fixture, serverRoot, '4').status, 0);
-  commands = await readFile(fixture.commandLog, 'utf8');
-  assert.match(commands, /stop frontend backend/);
-  const operationLog = await readFile(join(serverRoot, 'logs/deploy.log'), 'utf8');
-  assert.match(operationLog, /operation=run-or-replace-backend result=success/);
-  assert.match(operationLog, /operation=run-or-replace-both result=success/);
-  assert.match(operationLog, /operation=stop-both result=success/);
+test('stop 与 status 始终作用于完整项目栈，非法参数不触发 Docker', async () => {
+  const item = await fixture();
+  await buildProject(item);
+  const extracted = await extractArchive(item);
+  await writeFile(item.log, '');
+  await run(join(extracted, 'deploy.sh'), ['stop'], { env: item.environment });
+  await run(join(extracted, 'deploy.sh'), ['status'], { env: item.environment });
+  const beforeInvalid = await readFile(item.log, 'utf8');
+  assert.match(beforeInvalid, /stop frontend backend/);
+  assert.match(beforeInvalid, /ps frontend backend/);
+  await assert.rejects(run(join(extracted, 'deploy.sh'), ['frontend'], { env: item.environment }), /usage:/);
+  assert.equal(await readFile(item.log, 'utf8'), beforeInvalid);
+  assert.match(await readFile(join(extracted, 'logs/deploy.log'), 'utf8'), /operation=stop result=success/);
 });
 
-test('健康检查失败返回非零并记录失败，不自动回滚', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const version = await releaseVersion(fixture.root);
-  const serverRoot = await installOnServer(fixture);
-  const result = runServer(fixture, serverRoot, '2', { EXPECTED_VERSION: version, FAIL_HEALTH: 'backend' });
-  assert.notEqual(result.status, 0);
-  const commands = await readFile(fixture.commandLog, 'utf8');
-  assert.match(commands, /up -d --force-recreate --no-deps backend/);
-  assert.doesNotMatch(commands, /docker .*rollback|nginx -(?:t|s)/);
-  assert.match(await readFile(join(serverRoot, 'logs/deploy.log'), 'utf8'), /operation=run-or-replace-backend result=failure/);
+test('整栈健康等待失败返回非零并记录失败', async () => {
+  const item = await fixture();
+  await buildProject(item);
+  const extracted = await extractArchive(item);
+  await assert.rejects(run(join(extracted, 'deploy.sh'), [], { env: { ...item.environment, FAIL_COMPOSE_UP: '1' } }));
+  assert.match(await readFile(join(extracted, 'logs/deploy.log'), 'utf8'), /operation=deploy result=failure/);
 });
 
-test('非法菜单输入和额外命令参数不执行 Docker 状态变更', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const serverRoot = await installOnServer(fixture);
-  await writeFile(fixture.commandLog, '');
-  const invalid = runServer(fixture, serverRoot, '9');
-  assert.notEqual(invalid.status, 0);
-  assert.doesNotMatch(await readFile(fixture.commandLog, 'utf8'), /docker (?:load|compose)/);
-  const extra = runServer(fixture, serverRoot, '1', {}, ['start']);
-  assert.equal(extra.status, 2);
+test('validator 拒绝数据库容器和不完整远程数据库配置', async () => {
+  const item = await fixture();
+  await buildProject(item);
+  const databasePackage = await extractArchive(item);
+  await writeFile(join(databasePackage, 'docker-compose.yml'), `${await readFile(join(databasePackage, 'docker-compose.yml'), 'utf8')}\n  database:\n    image: postgres:18\n`);
+  await rewriteManifest(databasePackage);
+  await assert.rejects(run(process.execPath, [validator, databasePackage]), /Compose must define only frontend and backend|contains a database/);
+
+  const envPackage = await extractArchive(item);
+  await writeFile(join(envPackage, '.env'), envText.replace('DB_URL=db.internal', 'DB_URL='), { mode: 0o600 });
+  await rewriteManifest(envPackage);
+  await assert.rejects(run(process.execPath, [validator, envPackage]), /Root \.env is missing DB_URL/);
 });
 
-test('服务器拒绝标签不匹配的镜像归档且不执行 docker load', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const version = await releaseVersion(fixture.root);
-  const versionRoot = join(fixture.root, `deploy/${version}`);
-  const badArchiveRoot = await temporary('bad-image-');
-  await writeFile(join(badArchiveRoot, 'manifest.json'), `[{"Config":"config.json","RepoTags":["fixture_frontend:${version}","other_frontend:bad"],"Layers":[]}]\n`);
-  await writeFile(join(badArchiveRoot, 'config.json'), '{}\n');
-  assert.equal(spawnSync('/usr/bin/tar', ['-cf', join(versionRoot, 'frontend-image.tar'), '-C', badArchiveRoot, 'manifest.json', 'config.json']).status, 0);
-  await rewriteManifest(versionRoot);
-  const serverRoot = await installOnServer(fixture);
-  await writeFile(fixture.commandLog, '');
-  const result = runServer(fixture, serverRoot, '1', { EXPECTED_VERSION: version });
-  assert.notEqual(result.status, 0);
-  assert.match(result.stderr, /exactly one expected tag/);
-  assert.doesNotMatch(await readFile(fixture.commandLog, 'utf8'), /docker load/);
+test('validator 拒绝冲突的 API 路径和缺失的代理注入', async () => {
+  const item = await fixture();
+  await buildProject(item);
+
+  const envPackage = await extractArchive(item);
+  await writeFile(join(envPackage, '.env'), envText.replace('VITE_API_BASE_URL=/api', 'VITE_API_BASE_URL=/service'), { mode: 0o600 });
+  await rewriteManifest(envPackage);
+  await assert.rejects(run(process.execPath, [validator, envPackage]), /VITE_API_BASE_URL must equal \/API_PREFIX/);
+
+  const composePackage = await extractArchive(item);
+  const compose = await readFile(join(composePackage, 'docker-compose.yml'), 'utf8');
+  await writeFile(join(composePackage, 'docker-compose.yml'), compose.replace('      VITE_API_BASE_URL: "${VITE_API_BASE_URL:?VITE_API_BASE_URL is required}"\n', ''));
+  await rewriteManifest(composePackage);
+  await assert.rejects(run(process.execPath, [validator, composePackage]), /Frontend API path is not passed to Nginx/);
 });
 
-test('服务器部署根由脚本物理路径确定', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const version = await releaseVersion(fixture.root);
-  const serverRoot = await installOnServer(fixture);
-  const unrelated = await temporary('unrelated-cwd-');
-  const result = run(fixture, [join(serverRoot, 'deploy.sh')], { cwd: unrelated, input: '1\n', extraEnv: { EXPECTED_VERSION: version } });
-  assert.equal(result.status, 0, result.stderr);
-  await access(join(serverRoot, 'logs/deploy.log'));
-  await assert.rejects(access(join(unrelated, 'logs/deploy.log')));
+test('validator 拒绝清单篡改和额外包内容', async () => {
+  const item = await fixture();
+  await buildProject(item);
+  const extracted = await extractArchive(item);
+  await writeFile(join(extracted, 'unexpected.txt'), 'unexpected\n');
+  await assert.rejects(run(process.execPath, [validator, extracted]), /Unexpected package entry/);
+  await rm(join(extracted, 'unexpected.txt'));
+  await writeFile(join(extracted, 'docker-compose.yml'), 'tampered\n');
+  await assert.rejects(run(process.execPath, [validator, extracted]), /Compose must define only frontend and backend|Checksum mismatch/);
 });
 
-test('validator 拒绝缺失镜像和宿主机 Nginx 文件', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  let version = await releaseVersion(fixture.root);
-  await unlink(join(fixture.root, `deploy/${version}/frontend-image.tar`));
-  assert.notEqual(runValidator(fixture.root, version).status, 0);
+test('validator 拒绝镜像归档平台与 DOCKER_PLATFORM 不一致', async () => {
+  const item = await fixture();
+  await buildProject(item);
+  const extracted = await extractArchive(item);
+  await rewriteImageArchivePlatform(join(extracted, 'backend-image.tar'), 'linux/arm64');
+  await rewriteManifest(extracted);
+  await assert.rejects(run(process.execPath, [validator, extracted]), /backend-image\.tar platform must equal DOCKER_PLATFORM/);
+});
 
-  assert.equal(runBuild(fixture).status, 0);
-  version = await releaseVersion(fixture.root);
-  const nginxDir = join(fixture.root, `deploy/${version}/nginx`);
-  await mkdir(nginxDir);
-  await writeFile(join(nginxDir, 'site.conf'), 'server {}\n');
-  await rewriteManifest(join(fixture.root, `deploy/${version}`));
-  const validation = runValidator(fixture.root, version);
-  assert.notEqual(validation.status, 0);
-  assert.match(validation.stderr, /must not contain host Nginx/);
+test('build 在任何 Docker 操作前拒绝环境文件命令语法', async () => {
+  const item = await fixture();
+  await writeFile(join(item.root, '.env'), envText.replace('DB_PASSWORD=secret', 'DB_PASSWORD=$(id)'), { mode: 0o600 });
+  await assert.rejects(buildProject(item), /executable syntax is forbidden in \.env: DB_PASSWORD/);
+  await assert.rejects(stat(item.log), { code: 'ENOENT' });
 });