@weotro/dx 0.1.0

package/lib/backend-artifact-deploy/artifact-builder.js

@@ -0,0 +1,267 @@
+import { execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { cp, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { basename, dirname, join, relative } from 'node:path'
+import { promisify } from 'node:util'
+import { execManager } from '../exec.js'
+import { basenameOrThrow, resolveWithinBase } from './path-utils.js'
+import { createRuntimePackage } from './runtime-package.js'
+
+const execFileAsync = promisify(execFile)
+const tarEnv = {
+  ...process.env,
+  COPYFILE_DISABLE: '1',
+  COPY_EXTENDED_ATTRIBUTES_DISABLE: '1',
+}
+
+function assertSafeNamePart(value, label) {
+  const text = String(value || '').trim()
+  if (!text || text.includes('/') || text.includes('\\') || text.includes('..')) {
+    throw new Error(`${label} 越界，已拒绝: ${text}`)
+  }
+  return text
+}
+
+function defaultNowTag() {
+  const now = new Date()
+  const pad = value => String(value).padStart(2, '0')
+  return [
+    now.getFullYear(),
+    pad(now.getMonth() + 1),
+    pad(now.getDate()),
+  ].join('') + `-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`
+}
+
+async function defaultReadVersion(versionFile) {
+  const pkg = JSON.parse(await readFile(versionFile, 'utf8'))
+  return String(pkg.version || '').trim()
+}
+
+export function buildFlagsForEnvironment(environment) {
+  switch (environment || 'development') {
+    case 'production':
+      return { prod: true }
+    case 'staging':
+      return { staging: true }
+    case 'development':
+    default:
+      return { dev: true }
+  }
+}
+
+async function defaultRunBuild(build, environment = 'development') {
+  if (!build?.command) {
+    throw new Error('缺少构建命令: build.command')
+  }
+  await execManager.executeCommand(build.command, {
+    app: build.app || undefined,
+    flags: buildFlagsForEnvironment(environment),
+  })
+}
+
+async function defaultPrepareOutputDir(outputDir) {
+  await mkdir(outputDir, { recursive: true })
+}
+
+async function copyIntoDir(source, destinationDir) {
+  if (!existsSync(source)) {
+    throw new Error(`缺少必需文件或目录: ${source}`)
+  }
+  await cp(source, destinationDir, { recursive: true })
+}
+
+async function defaultStageFiles({ config, stageDir, stagePlan }) {
+  await rm(stageDir, { recursive: true, force: true })
+  await mkdir(stageDir, { recursive: true })
+
+  for (const entry of await readdir(stagePlan.dist.source)) {
+    await copyIntoDir(join(stagePlan.dist.source, entry), join(stageDir, entry))
+  }
+
+  const appPackage = JSON.parse(await readFile(stagePlan.appPackage.source, 'utf8'))
+  const rootPackage = JSON.parse(await readFile(stagePlan.rootPackage.source, 'utf8'))
+  const runtimePackage = createRuntimePackage({ appPackage, rootPackage })
+  await writeFile(join(stageDir, stagePlan.runtimePackage.destination), `${JSON.stringify(runtimePackage, null, 2)}\n`)
+
+  await copyIntoDir(stagePlan.lockfile.source, join(stageDir, stagePlan.lockfile.destination))
+
+  if (stagePlan.prismaSchema) {
+    await mkdir(join(stageDir, dirname(stagePlan.prismaSchema.destination)), { recursive: true })
+    await copyIntoDir(stagePlan.prismaSchema.source, join(stageDir, stagePlan.prismaSchema.destination))
+  }
+  if (stagePlan.prismaConfig) {
+    await mkdir(join(stageDir, dirname(stagePlan.prismaConfig.destination)), { recursive: true })
+    await copyIntoDir(stagePlan.prismaConfig.source, join(stageDir, stagePlan.prismaConfig.destination))
+  }
+  if (stagePlan.ecosystemConfig) {
+    await copyIntoDir(stagePlan.ecosystemConfig.source, join(stageDir, stagePlan.ecosystemConfig.destination))
+  }
+}
+
+async function defaultAssertNoEnvFiles(stageDir) {
+  const envFiles = []
+  const queue = ['.']
+
+  while (queue.length > 0) {
+    const currentRelativeDir = queue.shift()
+    const currentDir = currentRelativeDir === '.' ? stageDir : join(stageDir, currentRelativeDir)
+    const entries = await readdir(currentDir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const entryRelativePath =
+        currentRelativeDir === '.' ? entry.name : join(currentRelativeDir, entry.name)
+
+      if (entry.name.startsWith('.env')) {
+        envFiles.push(entryRelativePath.replace(/\\/g, '/'))
+      }
+
+      if (entry.isDirectory()) {
+        queue.push(entryRelativePath)
+      }
+    }
+  }
+
+  if (envFiles.length > 0) {
+    throw new Error(`制品目录包含 .env* 文件: ${envFiles.join(', ')}`)
+  }
+}
+
+async function defaultCreateInnerArchive({ stageDir, innerArchivePath }) {
+  await mkdir(dirname(innerArchivePath), { recursive: true })
+  await execFileAsync('tar', ['-czf', innerArchivePath, '.'], {
+    cwd: stageDir,
+    env: tarEnv,
+  })
+}
+
+async function defaultWriteChecksum({ archivePath, checksumPath }) {
+  const archiveName = basename(archivePath)
+  try {
+    const { stdout } = await execFileAsync('sha256sum', [archiveName], {
+      cwd: dirname(archivePath),
+    })
+    await writeFile(checksumPath, stdout)
+  } catch {
+    const { stdout } = await execFileAsync('shasum', ['-a', '256', archiveName], {
+      cwd: dirname(archivePath),
+    })
+    await writeFile(checksumPath, stdout)
+  }
+}
+
+async function defaultCreateBundle({ outputDir, bundlePath, innerArchivePath, checksumPath }) {
+  await execFileAsync(
+    'tar',
+    ['-czf', bundlePath, basename(innerArchivePath), basename(checksumPath)],
+    {
+      cwd: outputDir,
+      env: tarEnv,
+    },
+  )
+}
+
+export function createArtifactNames({ version, timeTag, bundleName }) {
+  const safeVersion = assertSafeNamePart(version, 'version')
+  const safeTimeTag = assertSafeNamePart(timeTag, 'timeTag')
+  const safeBundleName = assertSafeNamePart(bundleName, 'bundleName')
+  const versionName = `backend-v${safeVersion}-${safeTimeTag}`
+  const innerArchiveName = `${versionName}.tgz`
+  return {
+    versionName,
+    innerArchiveName,
+    checksumName: `${innerArchiveName}.sha256`,
+    bundleName: `${safeBundleName}-v${safeVersion}-${safeTimeTag}.tgz`,
+  }
+}
+
+export function createStagePlan(config) {
+  const projectRoot = config.projectRoot || '/'
+  const relativeToProject = targetPath =>
+    relative(projectRoot, targetPath).replace(/\\/g, '/').replace(/^repo\//, '')
+  const plan = {
+    dist: {
+      source: config.build.distDir,
+      destination: '.',
+    },
+    runtimePackage: {
+      destination: 'package.json',
+    },
+    lockfile: {
+      source: config.runtime.lockfile,
+      destination: 'pnpm-lock.yaml',
+    },
+    appPackage: {
+      source: config.runtime.appPackage,
+    },
+    rootPackage: {
+      source: config.runtime.rootPackage,
+    },
+  }
+
+  if (config.runtime.prismaSchemaDir) {
+    plan.prismaSchema = {
+      source: config.runtime.prismaSchemaDir,
+      destination: relativeToProject(config.runtime.prismaSchemaDir),
+    }
+  }
+  if (config.runtime.prismaConfig) {
+    plan.prismaConfig = {
+      source: config.runtime.prismaConfig,
+      destination: relativeToProject(config.runtime.prismaConfig),
+    }
+  }
+  if (config.runtime.ecosystemConfig) {
+    plan.ecosystemConfig = {
+      source: config.runtime.ecosystemConfig,
+      destination: basenameOrThrow(config.runtime.ecosystemConfig, 'runtime.ecosystemConfig'),
+    }
+  }
+
+  return plan
+}
+
+export async function buildBackendArtifact(config, deps = {}) {
+  const nowTag = deps.nowTag || defaultNowTag
+  const readVersion = deps.readVersion || defaultReadVersion
+  const runBuild = deps.runBuild || defaultRunBuild
+  const prepareOutputDir = deps.prepareOutputDir || defaultPrepareOutputDir
+  const stageFiles = deps.stageFiles || defaultStageFiles
+  const assertNoEnvFiles = deps.assertNoEnvFiles || defaultAssertNoEnvFiles
+  const createInnerArchive = deps.createInnerArchive || defaultCreateInnerArchive
+  const writeChecksum = deps.writeChecksum || defaultWriteChecksum
+  const createBundle = deps.createBundle || defaultCreateBundle
+  const version = await readVersion(config.build.versionFile)
+  const timeTag = nowTag()
+  const names = createArtifactNames({
+    version,
+    timeTag,
+    bundleName: config.artifact.bundleName,
+  })
+
+  const outputDir = resolveWithinBase(config.artifact.outputDir, '.', 'artifact.outputDir')
+  const stageDir = resolveWithinBase(outputDir, names.versionName, 'stageDir')
+  const innerArchivePath = resolveWithinBase(outputDir, names.innerArchiveName, 'innerArchivePath')
+  const checksumPath = resolveWithinBase(outputDir, names.checksumName, 'checksumPath')
+  const bundlePath = resolveWithinBase(outputDir, names.bundleName, 'bundlePath')
+
+  await runBuild(config.build, config.environment)
+  await prepareOutputDir(outputDir)
+  await stageFiles({
+    config,
+    stageDir,
+    stagePlan: createStagePlan(config),
+  })
+  await assertNoEnvFiles(stageDir)
+  await createInnerArchive({ stageDir, innerArchivePath })
+  await writeChecksum({ archivePath: innerArchivePath, checksumPath })
+  await createBundle({ outputDir, bundlePath, innerArchivePath, checksumPath })
+
+  return {
+    version,
+    timeTag,
+    versionName: names.versionName,
+    bundlePath,
+    innerArchivePath,
+    checksumPath,
+  }
+}

package/lib/backend-artifact-deploy/config.js

@@ -0,0 +1,218 @@
+import { isAbsolute } from 'node:path'
+import { resolveWithinBase } from './path-utils.js'
+
+function requireString(value, fieldPath) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`缺少必填配置: ${fieldPath}`)
+  }
+  return value.trim()
+}
+
+function requirePositiveInteger(value, fieldPath) {
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`缺少必填配置: ${fieldPath}`)
+  }
+  return parsed
+}
+
+function requireEnvName(value, fieldPath) {
+  const name = requireString(value, fieldPath)
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new Error(`缺少必填配置: ${fieldPath}`)
+  }
+  return name
+}
+
+function resolveHealthCheckEndpoint(healthCheckConfig) {
+  if (healthCheckConfig.url != null) {
+    const url = requireString(healthCheckConfig.url, 'verify.healthCheck.url')
+    try {
+      new URL(url)
+    } catch {
+      throw new Error(`缺少必填配置: verify.healthCheck.url`)
+    }
+    return { url }
+  }
+
+  if (healthCheckConfig.envPort != null) {
+    const rawPath = healthCheckConfig.path == null ? '/health' : requireString(healthCheckConfig.path, 'verify.healthCheck.path')
+    return {
+      envPort: requireEnvName(healthCheckConfig.envPort, 'verify.healthCheck.envPort'),
+      path: rawPath.startsWith('/') ? rawPath : `/${rawPath}`,
+    }
+  }
+
+  throw new Error(`缺少必填配置: verify.healthCheck.url`)
+}
+
+function resolveVerifyConfig(verifyConfig = {}) {
+  const healthCheckConfig = verifyConfig?.healthCheck
+  if (healthCheckConfig == null) {
+    return {
+      healthCheck: null,
+    }
+  }
+
+  return {
+    healthCheck: {
+      ...resolveHealthCheckEndpoint(healthCheckConfig),
+      timeoutSeconds:
+        healthCheckConfig.timeoutSeconds == null
+          ? 10
+          : requirePositiveInteger(healthCheckConfig.timeoutSeconds, 'verify.healthCheck.timeoutSeconds'),
+      maxWaitSeconds:
+        healthCheckConfig.maxWaitSeconds == null
+          ? 24
+          : requirePositiveInteger(healthCheckConfig.maxWaitSeconds, 'verify.healthCheck.maxWaitSeconds'),
+      retryIntervalSeconds:
+        healthCheckConfig.retryIntervalSeconds == null
+          ? 2
+          : requirePositiveInteger(
+              healthCheckConfig.retryIntervalSeconds,
+              'verify.healthCheck.retryIntervalSeconds',
+            ),
+    },
+  }
+}
+
+function resolveBuildCommand(buildConfig, environment) {
+  if (buildConfig?.commands && typeof buildConfig.commands === 'object') {
+    const selected = buildConfig.commands[environment]
+    if (!selected || typeof selected !== 'string' || selected.trim() === '') {
+      throw new Error(`缺少必填配置: build.commands.${environment}`)
+    }
+    return selected.trim()
+  }
+
+  return requireString(buildConfig?.command, 'build.command')
+}
+
+function resolveProjectPath(projectRoot, relativePath, fieldPath) {
+  return resolveWithinBase(projectRoot, requireString(relativePath, fieldPath), fieldPath)
+}
+
+function requireRemoteBaseDir(value, fieldPath) {
+  const baseDir = requireString(value, fieldPath)
+  if (!isAbsolute(baseDir)) {
+    throw new Error(`${fieldPath} 必须是绝对路径: ${baseDir}`)
+  }
+  if (!/^\/[A-Za-z0-9._/-]*$/.test(baseDir)) {
+    throw new Error(`${fieldPath} 包含非法字符: ${baseDir}`)
+  }
+  return baseDir.replace(/\/+$/, '') || '/'
+}
+
+function resolveRemoteConfig(remoteConfig, environment) {
+  if (!remoteConfig || typeof remoteConfig !== 'object') {
+    return null
+  }
+
+  if (typeof remoteConfig.host === 'string') {
+    return remoteConfig
+  }
+
+  const selected = remoteConfig[environment]
+  if (!selected || typeof selected !== 'object') {
+    throw new Error(`缺少必填配置: remote.${environment}`)
+  }
+  return selected
+}
+
+export function resolveBackendDeployConfig({ cli, targetConfig, environment, flags = {} }) {
+  const deployConfig = targetConfig?.backendDeploy
+  if (!deployConfig || typeof deployConfig !== 'object') {
+    throw new Error('缺少必填配置: backendDeploy')
+  }
+
+  const buildConfig = deployConfig.build || {}
+  const runtimeConfig = deployConfig.runtime || {}
+  const artifactConfig = deployConfig.artifact || {}
+  const remoteConfig = resolveRemoteConfig(deployConfig.remote, environment)
+  const startupConfig = deployConfig.startup || {}
+  const runConfig = deployConfig.deploy || {}
+  const verifyConfig = deployConfig.verify || {}
+  const buildOnly = Boolean(flags.buildOnly)
+  const startupMode = String(startupConfig.mode || 'pm2').trim()
+  const prismaGenerate = runConfig.prismaGenerate !== false
+  const prismaMigrateDeploy = runConfig.prismaMigrateDeploy !== false
+  const prismaSeed = runConfig.prismaSeed === true
+
+  const normalized = {
+    projectRoot: cli.projectRoot,
+    environment,
+    build: {
+      app: typeof buildConfig.app === 'string' && buildConfig.app.trim() ? buildConfig.app.trim() : null,
+      command: resolveBuildCommand(buildConfig, environment),
+      distDir: resolveProjectPath(cli.projectRoot, buildConfig.distDir, 'build.distDir'),
+      versionFile: resolveProjectPath(cli.projectRoot, buildConfig.versionFile, 'build.versionFile'),
+    },
+    runtime: {
+      appPackage: resolveProjectPath(cli.projectRoot, runtimeConfig.appPackage, 'runtime.appPackage'),
+      rootPackage: resolveProjectPath(cli.projectRoot, runtimeConfig.rootPackage, 'runtime.rootPackage'),
+      lockfile: resolveProjectPath(cli.projectRoot, runtimeConfig.lockfile, 'runtime.lockfile'),
+      prismaSchemaDir: runtimeConfig.prismaSchemaDir
+        ? resolveProjectPath(cli.projectRoot, runtimeConfig.prismaSchemaDir, 'runtime.prismaSchemaDir')
+        : null,
+      prismaConfig: runtimeConfig.prismaConfig
+        ? resolveProjectPath(cli.projectRoot, runtimeConfig.prismaConfig, 'runtime.prismaConfig')
+        : null,
+      ecosystemConfig: runtimeConfig.ecosystemConfig
+        ? resolveProjectPath(cli.projectRoot, runtimeConfig.ecosystemConfig, 'runtime.ecosystemConfig')
+        : null,
+    },
+    artifact: {
+      outputDir: resolveProjectPath(cli.projectRoot, artifactConfig.outputDir, 'artifact.outputDir'),
+      bundleName: requireString(artifactConfig.bundleName, 'artifact.bundleName'),
+    },
+    remote: buildOnly
+      ? null
+      : {
+          host: requireString(remoteConfig?.host, 'remote.host'),
+          port: remoteConfig?.port == null ? 22 : requirePositiveInteger(remoteConfig.port, 'remote.port'),
+          user: requireString(remoteConfig?.user, 'remote.user'),
+          baseDir: requireRemoteBaseDir(remoteConfig?.baseDir, 'remote.baseDir'),
+        },
+    startup: {
+      mode: startupMode,
+      serviceName:
+        typeof startupConfig.serviceName === 'string' && startupConfig.serviceName.trim()
+          ? startupConfig.serviceName.trim()
+          : null,
+      entry:
+        typeof startupConfig.entry === 'string' && startupConfig.entry.trim()
+          ? startupConfig.entry.trim()
+          : null,
+    },
+    deploy: {
+      keepReleases:
+        runConfig.keepReleases == null ? 5 : requirePositiveInteger(runConfig.keepReleases, 'deploy.keepReleases'),
+      installCommand: requireString(
+        runConfig.installCommand || 'pnpm install --prod --no-frozen-lockfile --ignore-workspace',
+        'deploy.installCommand',
+      ),
+      prismaGenerate,
+      prismaMigrateDeploy,
+      prismaSeed,
+      skipMigration: Boolean(flags.skipMigration),
+    },
+    verify: resolveVerifyConfig(verifyConfig),
+  }
+
+  if (!['pm2', 'direct'].includes(normalized.startup.mode)) {
+    throw new Error('缺少必填配置: startup.mode')
+  }
+  if (normalized.startup.mode === 'pm2') {
+    requireString(normalized.startup.serviceName, 'startup.serviceName')
+    requireString(normalized.runtime.ecosystemConfig, 'runtime.ecosystemConfig')
+  } else {
+    requireString(normalized.startup.entry, 'startup.entry')
+  }
+
+  if (normalized.deploy.prismaGenerate || normalized.deploy.prismaMigrateDeploy || normalized.deploy.prismaSeed) {
+    requireString(normalized.runtime.prismaSchemaDir, 'runtime.prismaSchemaDir')
+    requireString(normalized.runtime.prismaConfig, 'runtime.prismaConfig')
+  }
+
+  return normalized
+}

package/lib/backend-artifact-deploy/path-utils.js

@@ -0,0 +1,18 @@
+import { basename, resolve, sep } from 'node:path'
+
+export function resolveWithinBase(baseDir, targetPath, label = 'path') {
+  const absoluteBase = resolve(baseDir)
+  const absoluteTarget = resolve(absoluteBase, targetPath)
+  if (absoluteTarget !== absoluteBase && !absoluteTarget.startsWith(`${absoluteBase}${sep}`)) {
+    throw new Error(`${label} 越界，已拒绝: ${absoluteTarget}`)
+  }
+  return absoluteTarget
+}
+
+export function basenameOrThrow(filePath, label = 'path') {
+  const name = basename(String(filePath || '').trim())
+  if (!name || name === '.' || name === '..') {
+    throw new Error(`无效的 ${label}: ${filePath}`)
+  }
+  return name
+}

package/lib/backend-artifact-deploy/remote-phases.js

@@ -0,0 +1,14 @@
+export function createRemotePhaseModel(payload) {
+  return [
+    { phase: 'lock', payload },
+    { phase: 'extract', payload },
+    { phase: 'env', payload },
+    { phase: 'install', payload },
+    { phase: 'prisma-generate', payload },
+    { phase: 'prisma-migrate', payload },
+    { phase: 'switch-current', payload },
+    { phase: 'startup', payload },
+    { phase: 'verify', payload },
+    { phase: 'cleanup', payload },
+  ]
+}

package/lib/backend-artifact-deploy/remote-result.js

@@ -0,0 +1,44 @@
+function parseResultLine(line) {
+  if (!line.startsWith('DX_REMOTE_RESULT=')) return null
+  return JSON.parse(line.slice('DX_REMOTE_RESULT='.length))
+}
+
+function getLastPhase(output = '') {
+  const lines = String(output).split('\n')
+  let phase = 'cleanup'
+  for (const line of lines) {
+    if (line.startsWith('DX_REMOTE_PHASE=')) {
+      phase = line.slice('DX_REMOTE_PHASE='.length).trim() || phase
+    }
+  }
+  return phase
+}
+
+export function parseRemoteResult({ stdout = '', stderr = '', exitCode = 0 }) {
+  const allLines = `${stdout}\n${stderr}`.trim().split('\n').filter(Boolean)
+  for (let index = allLines.length - 1; index >= 0; index -= 1) {
+    const parsed = parseResultLine(allLines[index])
+    if (parsed) return parsed
+  }
+
+  if (exitCode === 0) {
+    return {
+      ok: true,
+      phase: getLastPhase(stdout),
+      message: 'ok',
+      rollbackAttempted: false,
+      rollbackSucceeded: null,
+      summary: null,
+    }
+  }
+
+  const message = [stderr, stdout].filter(Boolean).join('\n').trim() || 'remote execution failed'
+  return {
+    ok: false,
+    phase: getLastPhase(`${stdout}\n${stderr}`),
+    message,
+    rollbackAttempted: false,
+    rollbackSucceeded: null,
+    summary: null,
+  }
+}