@wdyy/skills 0.1.11 → 0.1.13

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

@@ -1,46 +1,46 @@
+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, stat, 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';
 
+const run = promisify(execFile);
 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.blue-green.yml');
-const nginxTemplate = join(templatesRoot, 'nginx-upstream.template.conf');
-const dockerignoreTemplate = join(templatesRoot, 'dockerignore.template');
-const frontendDockerfileTemplate = join(templatesRoot, 'frontend.Dockerfile.template');
-const backendDockerfileTemplate = join(templatesRoot, 'Dockerfile.template');
-const frontendNginxTemplate = join(templatesRoot, 'frontend-container.conf.template');
-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=
+# 部署
+PROJECT_NAME=example_project
+DOCKER_BIND_IP=0.0.0.0
+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
@@ -48,445 +48,193 @@ DB_USER=
 DB_PASSWORD=
 DB_NAME=
 DB_SCHEMA=
-
 # API
-
+API_URL=
 # 部署
-PROJECT_NAME=fixture
-PROJECT_HTTP_PORT=9099
-DOCKER_BIND_IP=127.0.0.1
-FRONTEND_BLUE_PORT=19091
-FRONTEND_GREEN_PORT=19092
-BACKEND_BLUE_PORT=19093
-BACKEND_GREEN_PORT=19094
+PROJECT_NAME=
+DOCKER_BIND_IP=
 FRONTEND_BASE_IMAGE=nginx:stable
 BACKEND_BASE_IMAGE=node:24-alpine3.24
-${extra}`;
-}
-
-async function createFixture({ agents = '# Target project\n', extraEnv = '' } = {}) {
-  const root = await temporary('wdyy-deploy-');
-  const fakeBin = join(root, 'fake-bin');
-  const serverProjectsRoot = join(root, 'servers');
-  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 }),
-    mkdir(serverProjectsRoot, { recursive: true }),
-  ]);
-  await Promise.all([
-    copyFile(deployTemplate, join(root, 'deploy.sh')),
-    copyFile(frontendDockerfileTemplate, join(root, 'src/frontend/Dockerfile')),
-    copyFile(backendDockerfileTemplate, join(root, 'src/backend/Dockerfile')),
-    copyFile(composeTemplate, join(root, 'scripts/deployment/docker-compose.blue-green.yml')),
-    copyFile(nginxTemplate, join(root, 'scripts/deployment/nginx-site.conf')),
-    copyFile(frontendNginxTemplate, join(root, 'scripts/deployment/frontend-container.conf.template')),
-    copyFile(dockerignoreTemplate, 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 '<!doctype html><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)
-    if [[ "\${2:-}" == inspect ]]; then tag="\${!#}"; printf '%s\n' "\${tag##*:}";
-    elif [[ "\${2:-}" == ls ]]; then printf '%s\n' "\${DOCKER_IMAGE_LIST:-fixture_frontend:20260808-001
-fixture_backend:20260808-001
-other_project_frontend:shared}"; fi
-    ;;
-  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 ;;
-  ps)
-    if [[ "\${2:-}" == -aq ]]; then
-      printf '%s\n' "\${DOCKER_CONTAINER_IDS:-c111
-c222}"
-    elif [[ "\${2:-}" == --format && -n "\${DOCKER_RUNNING_PORTS:-}" ]]; then
-      printf '%s\n' "$DOCKER_RUNNING_PORTS"
-    fi
-    ;;
-  network)
-    if [[ "\${2:-}" == ls ]]; then printf '%s\n' "\${DOCKER_NETWORK_IDS:-n111}"; fi
-    ;;
-  rm) 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_PUBLIC_ENDPOINT:-0}" == 1 && "$url" == *:9099/* ]]; then exit 26; fi
-if [[ "$url" == */version ]]; then printf '%s' "\${EXPECTED_VERSION:?}"; else printf 'ok'; fi
-`);
-  await writeExecutable(join(fakeBin, 'nginx'), `#!/usr/bin/env bash
-set -euo pipefail
-printf 'nginx %s\n' "$*" >> "$COMMAND_LOG"
-if [[ "\${1:-}" == -t ]]; then [[ "\${FAIL_NGINX_TEST:-0}" != 1 ]] || exit 23; exit 0; fi
-if [[ "\${1:-}" == -T ]]; then
-  [[ ! -f "$SERVER_ROOT/nginx/site.conf" ]] || cat "$SERVER_ROOT/nginx/site.conf"
-  [[ -z "\${EXTRA_NGINX_CONFIG:-}" ]] || printf '%s\n' "$EXTRA_NGINX_CONFIG"
-  exit 0
-fi
-if [[ "\${1:-}" == -s && "\${2:-}" == reload && "\${FAIL_NGINX_RELOAD_ONCE:-0}" == 1 && ! -f "$NGINX_FAIL_MARKER" ]]; then
-  : > "$NGINX_FAIL_MARKER"; exit 24
-fi
-`);
-  await writeExecutable(join(fakeBin, 'flock'), '#!/usr/bin/env bash\nexit 0\n');
-  await writeExecutable(join(fakeBin, 'install'), `#!/usr/bin/env bash
-set -euo pipefail
-target="\${!#}"
-if [[ "\${FAIL_STATE_INSTALL:-0}" == 1 && "$target" == */state/active.env ]]; then exit 25; fi
-exec /usr/bin/install "$@"
-`);
-
-  return { root, fakeBin, serverProjectsRoot, commandLog };
-}
-
-async function writeExecutable(path, content) {
-  await writeFile(path, content);
-  await chmod(path, 0o755);
+`;
+
+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] === 'image' && args[1] === 'inspect') {
+  const image = args[args.length - 1];
+  if (process.env.MISSING_IMAGE === image) process.exit(1);
+  process.exit(0);
 }
-
-function run(root, args, fixture, extraEnv = {}) {
-  return spawnSync('bash', args, {
-    cwd: root,
-    encoding: 'utf8',
-    env: {
-      ...process.env,
-      PATH: `${fixture.fakeBin}:${process.env.PATH}`,
-      COMMAND_LOG: fixture.commandLog,
-      ...extraEnv,
-    },
-  });
-}
-
-function runBuild(fixture, extraEnv = {}, ...extraArgs) {
-  return run(fixture.root, ['deploy.sh', 'build', ...extraArgs], fixture, extraEnv);
+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);
 }
-
-async function releaseVersion(root) {
-  return (await readFile(join(root, 'deploy/release.env'), 'utf8')).trim().slice('RELEASE_VERSION='.length);
+if (args[0] === 'save') {
+  const output = args[args.indexOf('-o') + 1];
+  const tag = args[args.length - 1];
+  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'), '{}\\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);
 }
-
-function runValidator(root, version) {
-  return spawnSync(process.execPath, [
-    validator,
-    join(root, 'deploy/deploy.sh'),
-    join(root, `deploy/${version}/nginx/site.conf`),
-    join(root, `deploy/${version}/docker/docker-compose.blue-green.yml`),
-    join(root, 'deploy'),
-  ], { encoding: 'utf8' });
+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') };
 }
 
-async function installOnServer(fixture) {
-  const serverRoot = join(fixture.serverProjectsRoot, 'fixture');
-  await cp(join(fixture.root, 'deploy'), serverRoot, { recursive: true, force: true });
-  await chmod(join(serverRoot, 'deploy.sh'), 0o755);
-  return serverRoot;
+async function buildProject(item, extraEnvironment = {}) {
+  return run(join(item.root, 'deploy.sh'), ['build'], { cwd: item.root, env: { ...item.environment, ...extraEnvironment } });
 }
 
-function runServer(fixture, serverRoot, command, extraEnv = {}, argument) {
-  const args = [join(serverRoot, 'deploy.sh'), command];
-  if (argument) args.push(argument);
-  return run(fixture.root, args, fixture, {
-    SERVER_ROOT: serverRoot,
-    NGINX_FAIL_MARKER: join(fixture.root, 'nginx-failed-once'),
-    ...extraEnv,
-  });
+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;
 }
 
-test('build 生成根 .env、双镜像和四服务完整包', 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 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}`));
-  assert.match(log, /--build-arg BACKEND_PORT=3000/);
-  assert.doesNotMatch(await readFile(join(fixture.root, `deploy/${version}/docker/docker-compose.blue-green.yml`), 'utf8'), /FRONTEND_CONTAINER_PORT|BACKEND_CONTAINER_PORT|_HEALTH_URL|_VERSION_URL/);
-});
-
-test('发布包不包含数据库迁移文件或迁移参数', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const version = await releaseVersion(fixture.root);
-  await assert.rejects(stat(join(fixture.root, `deploy/${version}/database`)));
-  assert.doesNotMatch(await readFile(join(fixture.root, 'deploy/deploy.sh'), 'utf8'), /apply-migrations\.sh|database\/migrations|\bpsql\b/);
-});
-
-test('连续构建的 deploy.sh、Compose 和 Nginx 配置字节一致', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const firstVersion = await releaseVersion(fixture.root);
-  const first = await configurationHashes(fixture.root, firstVersion);
-  assert.equal(runBuild(fixture).status, 0);
-  const secondVersion = await releaseVersion(fixture.root);
-  const second = await configurationHashes(fixture.root, secondVersion);
-  assert.notEqual(firstVersion, secondVersion);
-  assert.deepEqual(second, first);
-});
-
-async function configurationHashes(root, version) {
-  const paths = ['deploy/deploy.sh', `deploy/${version}/docker/docker-compose.blue-green.yml`, `deploy/${version}/nginx/site.conf`];
-  return Promise.all(paths.map(async (path) => createHash('sha256').update(await readFile(join(root, path))).digest('hex')));
-}
-
-async function rewriteManifest(versionRoot, directory = 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);
-    }
+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 walk(directory);
-  const lines = await Promise.all(files.sort().map(async (path) => {
-    const relative = path.slice(versionRoot.length + 1).split('\\').join('/');
-    const hash = createHash('sha256').update(await readFile(path)).digest('hex');
-    return `${hash}  ${relative}`;
-  }));
-  await writeFile(join(versionRoot, 'manifest.sha256'), `${lines.join('\n')}\n`);
+  await writeFile(join(root, 'manifest.sha256'), `${lines.join('\n')}\n`);
 }
 
-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('dotenv 被作为数据解析，不执行命令替换或覆盖脚本 PATH', async () => {
-  const fixture = await createFixture({ extraEnv: 'UNUSED_VALUE=$(touch should-not-exist)\nPATH=/malicious\n' });
-  const result = runBuild(fixture);
-  assert.equal(result.status, 0, result.stderr);
-  await assert.rejects(access(join(fixture.root, 'should-not-exist')));
-});
-
-test('build 接受带标签基础镜像并拒绝重复键和额外版本参数', async () => {
-  const duplicate = await createFixture({ extraEnv: 'PROJECT_NAME=duplicate\n' });
-  assert.notEqual(runBuild(duplicate).status, 0);
-  const tagged = await createFixture();
-  assert.equal(runBuild(tagged).status, 0);
-  const extra = await createFixture();
-  assert.equal(runBuild(extra, {}, '20260808-001').status, 2);
-  const logDirectory = await createFixture({ extraEnv: 'LOG_DIR=/tmp/logs\n' });
-  const rejected = runBuild(logDirectory);
-  assert.notEqual(rejected.status, 0);
-  assert.match(rejected.stderr, /must not configure log directories/);
-  const legacy = await createFixture({ extraEnv: 'FRONTEND_CONTAINER_PORT=8080\n' });
-  const legacyRejected = runBuild(legacy);
-  assert.notEqual(legacyRejected.status, 0);
-  assert.match(legacyRejected.stderr, /legacy duplicate environment key/);
-  const migration = await createFixture({ extraEnv: 'DATABASE_MIGRATION_MODE=none\n' });
-  const migrationRejected = runBuild(migration);
-  assert.notEqual(migrationRejected.status, 0);
-  assert.match(migrationRejected.stderr, /legacy duplicate environment key/);
-  const reverseInclude = await createFixture();
-  await writeFile(join(reverseInclude.root, '.dockerignore'), `${await readFile(join(reverseInclude.root, '.dockerignore'), 'utf8')}!.env\n`);
-  const reverseRejected = runBuild(reverseInclude);
-  assert.notEqual(reverseRejected.status, 0);
-  assert.match(reverseRejected.stderr, /forbidden reverse include/);
-});
-
-test('validator 拒绝缺失前端镜像、镜像 fallback 和嵌套日志', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const version = await releaseVersion(fixture.root);
-  await unlink(join(fixture.root, `deploy/${version}/frontend-image.tar`));
-  assert.notEqual(runValidator(fixture.root, version).status, 0);
-
-  assert.equal(runBuild(fixture).status, 0);
-  const next = await releaseVersion(fixture.root);
-  const composePath = join(fixture.root, `deploy/${next}/docker/docker-compose.blue-green.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'));
-  const validation = runValidator(fixture.root, next);
-  assert.notEqual(validation.status, 0);
-  assert.match(validation.stderr, /fallback|logs/);
-});
-
-test('validator 拒绝版本目录符号链接', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const version = await releaseVersion(fixture.root);
-  await symlink('../outside', join(fixture.root, `deploy/${version}/linked-file`));
-  const validation = runValidator(fixture.root, version);
-  assert.notEqual(validation.status, 0);
-  assert.match(validation.stderr, /symbolic links/);
-});
-
-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');
-  const tarResult = spawnSync('/usr/bin/tar', ['-cf', join(versionRoot, 'frontend-image.tar'), '-C', badArchiveRoot, 'manifest.json', 'config.json'], { encoding: 'utf8' });
-  assert.equal(tarResult.status, 0, tarResult.stderr);
-  await rewriteManifest(versionRoot);
-  const serverRoot = await installOnServer(fixture);
-  await writeFile(fixture.commandLog, '');
-  const started = runServer(fixture, serverRoot, 'start', { EXPECTED_VERSION: version });
-  assert.notEqual(started.status, 0);
-  assert.match(started.stderr, /exactly one expected tag/);
-  assert.doesNotMatch(await readFile(fixture.commandLog, 'utf8'), /docker load/);
-});
-
-test('start、replace 和 rollback 成对切换前后端', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const first = await releaseVersion(fixture.root);
-  const serverRoot = await installOnServer(fixture);
-  const started = runServer(fixture, serverRoot, 'start', { EXPECTED_VERSION: first });
-  assert.equal(started.status, 0, started.stderr);
-  assert.match(await readFile(join(serverRoot, 'state/active.env'), 'utf8'), new RegExp(`ACTIVE_COLOR=blue[\\s\\S]*${first}`));
-
-  assert.equal(runBuild(fixture).status, 0);
-  const second = await releaseVersion(fixture.root);
-  await cp(join(fixture.root, 'deploy'), serverRoot, { recursive: true, force: true });
-  const replaced = runServer(fixture, serverRoot, 'replace', { EXPECTED_VERSION: second });
-  assert.equal(replaced.status, 0, replaced.stderr);
-  assert.match(await readFile(join(serverRoot, 'state/active.env'), 'utf8'), /ACTIVE_COLOR=green/);
-  assert.match(await readFile(join(serverRoot, 'state/previous.env'), 'utf8'), new RegExp(first));
-  const upstream = await readFile(join(serverRoot, 'nginx/active-upstreams.conf'), 'utf8');
-  assert.match(upstream, /fixture_frontend_active/);
-  assert.match(upstream, /fixture_backend_active/);
-
-  const rolledBack = runServer(fixture, serverRoot, 'rollback', { EXPECTED_VERSION: first }, first);
-  assert.equal(rolledBack.status, 0, rolledBack.stderr);
-  assert.match(await readFile(join(serverRoot, 'state/active.env'), 'utf8'), new RegExp(first));
-});
-
-test('restart、stop、status 只操作当前颜色的一对容器', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const version = await releaseVersion(fixture.root);
-  const serverRoot = await installOnServer(fixture);
-  assert.equal(runServer(fixture, serverRoot, 'start', { EXPECTED_VERSION: version }).status, 0);
-  await writeFile(fixture.commandLog, '');
-  assert.equal(runServer(fixture, serverRoot, 'restart', { EXPECTED_VERSION: version }).status, 0);
-  assert.equal(runServer(fixture, serverRoot, 'stop', { EXPECTED_VERSION: version }).status, 0);
-  const statusResult = runServer(fixture, serverRoot, 'status', { EXPECTED_VERSION: version });
-  assert.equal(statusResult.status, 0, statusResult.stderr);
-  assert.match(statusResult.stdout, new RegExp(version));
-  const log = await readFile(fixture.commandLog, 'utf8');
-  assert.match(log, /up -d --force-recreate frontend-blue backend-blue/);
-  assert.match(log, /stop frontend-blue backend-blue/);
-});
-
-test('remove 只删除本项目容器、网络和两个镜像仓库并保留日志', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const serverRoot = await installOnServer(fixture);
-  await mkdir(join(serverRoot, 'logs'), { recursive: true });
-  await writeFile(join(serverRoot, 'logs/backend.log'), 'keep\n');
-  await writeFile(fixture.commandLog, '');
-  const removed = runServer(fixture, serverRoot, 'remove');
-  assert.equal(removed.status, 0, removed.stderr);
-  const log = await readFile(fixture.commandLog, 'utf8');
-  assert.match(log, /docker rm -f c111 c222/);
-  assert.match(log, /docker network rm n111/);
-  assert.match(log, /docker image rm -f fixture_backend:20260808-001 fixture_frontend:20260808-001|docker image rm -f fixture_frontend:20260808-001 fixture_backend:20260808-001/);
-  assert.doesNotMatch(log, /other_project_frontend:shared/);
-  assert.equal(await readFile(join(serverRoot, 'logs/backend.log'), 'utf8'), 'keep\n');
-  await access(join(serverRoot, 'release.env'));
-});
-
-test('replace 的 Nginx reload 失败时恢复旧 upstream 和状态', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const first = await releaseVersion(fixture.root);
-  const serverRoot = await installOnServer(fixture);
-  assert.equal(runServer(fixture, serverRoot, 'start', { EXPECTED_VERSION: first }).status, 0);
-  const oldUpstream = await readFile(join(serverRoot, 'nginx/active-upstreams.conf'), 'utf8');
-  const oldState = await readFile(join(serverRoot, 'state/active.env'), 'utf8');
-  assert.equal(runBuild(fixture).status, 0);
-  const second = await releaseVersion(fixture.root);
-  await cp(join(fixture.root, 'deploy'), serverRoot, { recursive: true, force: true });
-  const failed = runServer(fixture, serverRoot, 'replace', { EXPECTED_VERSION: second, FAIL_NGINX_RELOAD_ONCE: '1' });
-  assert.notEqual(failed.status, 0);
-  assert.equal(await readFile(join(serverRoot, 'nginx/active-upstreams.conf'), 'utf8'), oldUpstream);
-  assert.equal(await readFile(join(serverRoot, 'state/active.env'), 'utf8'), oldState);
-});
-
-test('首次切流后的外部端口验证失败时不提交状态并移除候选 Nginx 文件', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const version = await releaseVersion(fixture.root);
-  const serverRoot = await installOnServer(fixture);
-  const failed = runServer(fixture, serverRoot, 'start', { EXPECTED_VERSION: version, FAIL_PUBLIC_ENDPOINT: '1' });
-  assert.notEqual(failed.status, 0);
-  assert.match(failed.stderr, /public endpoint verification failed/);
-  await assert.rejects(access(join(serverRoot, 'state/active.env')));
-  await assert.rejects(access(join(serverRoot, 'nginx/site.conf')));
-  await assert.rejects(access(join(serverRoot, 'nginx/active-upstreams.conf')));
-});
-
-test('状态提交失败时恢复旧流量和旧状态', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const first = await releaseVersion(fixture.root);
-  const serverRoot = await installOnServer(fixture);
-  assert.equal(runServer(fixture, serverRoot, 'start', { EXPECTED_VERSION: first }).status, 0);
-  const oldUpstream = await readFile(join(serverRoot, 'nginx/active-upstreams.conf'), 'utf8');
-  const oldState = await readFile(join(serverRoot, 'state/active.env'), 'utf8');
-  assert.equal(runBuild(fixture).status, 0);
-  const second = await releaseVersion(fixture.root);
-  await cp(join(fixture.root, 'deploy'), serverRoot, { recursive: true, force: true });
-  const failed = runServer(fixture, serverRoot, 'replace', { EXPECTED_VERSION: second, FAIL_STATE_INSTALL: '1' });
-  assert.notEqual(failed.status, 0);
-  assert.equal(await readFile(join(serverRoot, 'nginx/active-upstreams.conf'), 'utf8'), oldUpstream);
-  assert.equal(await readFile(join(serverRoot, 'state/active.env'), 'utf8'), oldState);
-});
-
-test('服务器命令拒绝额外参数且部署根由脚本位置确定', async () => {
-  const fixture = await createFixture();
-  assert.equal(runBuild(fixture).status, 0);
-  const serverRoot = await installOnServer(fixture);
-  assert.equal(runServer(fixture, serverRoot, 'start', {}, 'unexpected').status, 2);
-  const alternateRoot = join(fixture.root, 'alternate');
-  await cp(join(fixture.root, 'deploy'), alternateRoot, { recursive: true });
-  assert.equal(runServer(fixture, alternateRoot, 'status').status, 0);
+test.after(async () => {
+  await Promise.all(created.map((path) => rm(path, { recursive: true, force: true })));
+});
+
+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 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/g) ?? []).length, 2);
+  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('缺少本地基础镜像时在 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 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 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');
+  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/);
+});
+
+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 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('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('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('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' });
 });