vcs-patch-deploy 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,103 @@
1
+ /**
2
+ * PHP 后端(ThinkPHP / 通用 PHP API)增量部署配置
3
+ *
4
+ * 当前 v1 仅内置 php 后端;后续可扩展 node、java 等。
5
+ */
6
+
7
+ const fs = require('fs')
8
+ const path = require('path')
9
+
10
+ /** PHP 项目默认排除路径(与 Build-BackendPatch.ps1 对齐) */
11
+ const PHP_EXCLUDE_PATTERNS = [
12
+ /(^|\/)vendor\//,
13
+ /(^|\/)runtime\//,
14
+ /(^|\/)public\/uploads\//,
15
+ /(^|\/)public\/runtime\//,
16
+ /(^|\/)public\/cache\//,
17
+ /(^|\/)deploy\/out\//,
18
+ /(^|\/)tests\/coverage\//,
19
+ /(^|\/)build\//,
20
+ /(^|\/)dist\//,
21
+ /(^|\/)node_modules\//,
22
+ /(^|\/)\\.git\//,
23
+ /(^|\/)\\.svn\//,
24
+ /(^|\/)\\.env$/,
25
+ /(^|\/)\\.env\./,
26
+ /Thumbs\.db$/,
27
+ /\.DS_Store$/,
28
+ /\.log$/
29
+ ]
30
+
31
+ const COMPOSER_PATTERN = /(^|\/)composer\.(json|lock)$/
32
+
33
+ /** ThinkPHP 典型目录标记 */
34
+ const PHP_BACKEND_MARKERS = ['app', 'config', 'route']
35
+
36
+ /**
37
+ * @param {string} pkgRoot npm 包根目录
38
+ * @returns {string}
39
+ */
40
+ function getApplyScriptPath (pkgRoot) {
41
+ return path.join(pkgRoot, 'assets', 'php', 'apply-update.php')
42
+ }
43
+
44
+ /**
45
+ * 校验源码目录是否像 PHP 后端项目
46
+ * @param {string} sourceDir
47
+ * @returns {{ valid: boolean, framework: 'thinkphp'|'php-generic'|null, hints: string[] }}
48
+ */
49
+ function validatePhpBackend (sourceDir) {
50
+ const hints = []
51
+ const hasApp = fs.existsSync(path.join(sourceDir, 'app'))
52
+ const hasConfig = fs.existsSync(path.join(sourceDir, 'config'))
53
+ const hasThink = fs.existsSync(path.join(sourceDir, 'think'))
54
+ const hasComposer = fs.existsSync(path.join(sourceDir, 'composer.json'))
55
+
56
+ if (hasApp && (hasConfig || hasThink)) {
57
+ return { valid: true, framework: 'thinkphp', hints }
58
+ }
59
+
60
+ if (hasApp) {
61
+ hints.push('检测到 app/ 目录,按 ThinkPHP 结构处理')
62
+ return { valid: true, framework: 'thinkphp', hints }
63
+ }
64
+
65
+ if (hasComposer) {
66
+ hints.push('未检测到 app/,但存在 composer.json,按通用 PHP 项目处理')
67
+ return { valid: true, framework: 'php-generic', hints }
68
+ }
69
+
70
+ const missing = PHP_BACKEND_MARKERS.filter(m => !fs.existsSync(path.join(sourceDir, m)))
71
+ hints.push(`缺少典型 PHP 后端目录:${missing.join(', ')}`)
72
+ hints.push('若确为 PHP 后端,请确认 --source 指向含 app/ 的项目根(如 trunk)')
73
+
74
+ return { valid: false, framework: null, hints }
75
+ }
76
+
77
+ /**
78
+ * @param {string} relativePath
79
+ * @param {RegExp[]} [extraPatterns]
80
+ */
81
+ function shouldExcludePath (relativePath, extraPatterns = []) {
82
+ const p = relativePath.replace(/\\/g, '/')
83
+ const patterns = [...PHP_EXCLUDE_PATTERNS, ...extraPatterns]
84
+
85
+ for (const pat of patterns) {
86
+ if (pat.test(p)) {
87
+ return { excluded: true, isComposer: COMPOSER_PATTERN.test(p) }
88
+ }
89
+ }
90
+
91
+ return { excluded: false, isComposer: false }
92
+ }
93
+
94
+ module.exports = {
95
+ id: 'php',
96
+ label: 'PHP 后端(ThinkPHP)',
97
+ PHP_EXCLUDE_PATTERNS,
98
+ COMPOSER_PATTERN,
99
+ getApplyScriptPath,
100
+ validatePhpBackend,
101
+ shouldExcludePath,
102
+ defaultZipPrefix: 'backend-update'
103
+ }
@@ -0,0 +1,323 @@
1
+ /**
2
+ * 增量 patch 包构建核心(SVN / Git 统一入口)
3
+ */
4
+
5
+ const fs = require('fs')
6
+ const path = require('path')
7
+ const os = require('os')
8
+ const fse = require('fs-extra')
9
+ const { shouldExcludePath } = require('./exclude')
10
+ const { getBackend } = require('./backends')
11
+ const { readDeployMarker, writeDeployMarker } = require('./marker')
12
+ const { getSvnInfo, getSvnDiffSummary } = require('./svn')
13
+ const { getGitInfo, getGitDiffSummary, resolveGitRef } = require('./git')
14
+ const { createZipFromDirectory } = require('./zip')
15
+
16
+ /**
17
+ * @typedef {object} BuildResult
18
+ * @property {boolean} success
19
+ * @property {boolean} skipped
20
+ * @property {string} message
21
+ * @property {string} [patchDir]
22
+ * @property {string} [zipPath]
23
+ * @property {number} [fileCount]
24
+ * @property {number} [deletedCount]
25
+ * @property {string[]} [warnings]
26
+ * @property {'svn'|'git'} vcs
27
+ * @property {string} fromLabel
28
+ * @property {string} toLabel
29
+ */
30
+
31
+ /**
32
+ * 将 diff 条目分类为增改/删除,并应用排除规则
33
+ * @param {Array<{ action: string, relativePath: string, parseError?: string }>} entries
34
+ * @param {string} sourceDir
35
+ */
36
+ function classifyDiffEntries (entries, sourceDir, backendId = 'php') {
37
+ /** @type {string[]} */
38
+ const addedOrModified = []
39
+ /** @type {string[]} */
40
+ const deleted = []
41
+ /** @type {string[]} */
42
+ const warnings = []
43
+
44
+ for (const entry of entries) {
45
+ if (entry.parseError) {
46
+ warnings.push(entry.parseError)
47
+ }
48
+
49
+ const rel = entry.relativePath.replace(/\\/g, '/')
50
+ const { excluded, isComposer } = shouldExcludePath(rel, [], backendId)
51
+
52
+ if (excluded) {
53
+ if (isComposer) {
54
+ warnings.push(`composer 依赖变更:${rel} — 上线后可能需在服务器执行 composer install --no-dev`)
55
+ }
56
+ continue
57
+ }
58
+
59
+ if (entry.action === 'D') {
60
+ deleted.push(rel)
61
+ continue
62
+ }
63
+
64
+ const src = path.join(sourceDir, rel)
65
+ if (!fs.existsSync(src)) {
66
+ warnings.push(`跳过(工作副本不存在):${rel}`)
67
+ continue
68
+ }
69
+
70
+ addedOrModified.push(rel)
71
+ }
72
+
73
+ return {
74
+ addedOrModified: [...new Set(addedOrModified)].sort(),
75
+ deleted: [...new Set(deleted)].sort(),
76
+ warnings
77
+ }
78
+ }
79
+
80
+ /**
81
+ * 生成 patch 目录名与 zip 名后缀
82
+ * @param {'svn'|'git'} vcs
83
+ * @param {string} toLabel
84
+ */
85
+ function buildArtifactNames (vcs, toLabel, zipPrefix) {
86
+ if (vcs === 'svn') {
87
+ return {
88
+ patchName: `patch-r${toLabel}`,
89
+ zipName: `${zipPrefix}-r${toLabel}.zip`
90
+ }
91
+ }
92
+
93
+ const short = toLabel.slice(0, 12)
94
+ return {
95
+ patchName: `patch-${short}`,
96
+ zipName: `${zipPrefix}-${short}.zip`
97
+ }
98
+ }
99
+
100
+ /**
101
+ * @param {import('./config').BuildConfig} config
102
+ * @returns {Promise<BuildResult>}
103
+ */
104
+ async function buildPatch (config) {
105
+ const {
106
+ backend,
107
+ vcs,
108
+ sourceDir,
109
+ deployDir,
110
+ outDir,
111
+ applyScriptPath,
112
+ noZip,
113
+ markDeployed,
114
+ skipValidation,
115
+ zipPrefix
116
+ } = config
117
+
118
+ const backendModule = getBackend(backend)
119
+
120
+ if (!skipValidation && backend === 'php') {
121
+ const check = backendModule.validatePhpBackend(sourceDir)
122
+ if (!check.valid) {
123
+ throw new Error(check.hints.join('\n'))
124
+ }
125
+ }
126
+
127
+ if (!fs.existsSync(applyScriptPath)) {
128
+ throw new Error(`缺少 apply-update.php 模板:${applyScriptPath}`)
129
+ }
130
+
131
+ /** @type {string} */
132
+ let fromLabel
133
+ /** @type {string} */
134
+ let toLabel
135
+ /** @type {Array<{ action: string, relativePath: string, parseError?: string }>} */
136
+ let diffEntries
137
+
138
+ const marker = readDeployMarker(deployDir)
139
+
140
+ if (vcs === 'svn') {
141
+ const svnInfo = getSvnInfo(sourceDir)
142
+ const toRev = config.toRef != null ? Number(config.toRef) : svnInfo.revision
143
+ let fromRev = config.fromRef != null ? Number(config.fromRef) : null
144
+
145
+ if (fromRev == null) {
146
+ if (marker && marker.vcs === 'svn') {
147
+ fromRev = parseInt(marker.value, 10)
148
+ } else {
149
+ throw new Error(
150
+ `未找到 deploy/.last-deploy-marker 或 .last-deploy-rev,请指定 --from=<revision>`
151
+ )
152
+ }
153
+ }
154
+
155
+ if (fromRev >= toRev) {
156
+ if (markDeployed && fromRev === toRev) {
157
+ writeDeployMarker(deployDir, 'svn', String(toRev))
158
+ return {
159
+ success: true,
160
+ skipped: true,
161
+ message: `已更新 deploy 基准 = r${toRev}(无新文件需打包)`,
162
+ vcs,
163
+ fromLabel: String(fromRev),
164
+ toLabel: String(toRev)
165
+ }
166
+ }
167
+ return {
168
+ success: true,
169
+ skipped: true,
170
+ message: `FromRev (${fromRev}) >= ToRev (${toRev}),无增量可打包`,
171
+ vcs,
172
+ fromLabel: String(fromRev),
173
+ toLabel: String(toRev)
174
+ }
175
+ }
176
+
177
+ fromLabel = String(fromRev)
178
+ toLabel = String(toRev)
179
+ diffEntries = getSvnDiffSummary({ sourceDir, fromRev, toRev })
180
+ } else {
181
+ const gitInfo = getGitInfo(sourceDir)
182
+ const toCommit = config.toRef != null
183
+ ? resolveGitRef(sourceDir, String(config.toRef))
184
+ : gitInfo.commit
185
+
186
+ let fromCommit = config.fromRef != null
187
+ ? resolveGitRef(sourceDir, String(config.fromRef))
188
+ : null
189
+
190
+ if (!fromCommit) {
191
+ if (marker && marker.vcs === 'git') {
192
+ fromCommit = resolveGitRef(sourceDir, marker.value)
193
+ } else {
194
+ throw new Error(
195
+ `未找到 deploy/.last-deploy-marker(git:...),请指定 --from=<commit|tag>`
196
+ )
197
+ }
198
+ }
199
+
200
+ if (fromCommit === toCommit) {
201
+ if (markDeployed) {
202
+ writeDeployMarker(deployDir, 'git', toCommit)
203
+ return {
204
+ success: true,
205
+ skipped: true,
206
+ message: `已更新 deploy 基准 = ${toCommit.slice(0, 12)}(无新文件需打包)`,
207
+ vcs,
208
+ fromLabel: fromCommit,
209
+ toLabel: toCommit
210
+ }
211
+ }
212
+ return {
213
+ success: true,
214
+ skipped: true,
215
+ message: 'from 与 to 为同一 commit,无增量可打包',
216
+ vcs,
217
+ fromLabel: fromCommit,
218
+ toLabel: toCommit
219
+ }
220
+ }
221
+
222
+ fromLabel = fromCommit
223
+ toLabel = toCommit
224
+ diffEntries = getGitDiffSummary({ sourceDir, fromRef: fromCommit, toRef: toCommit })
225
+ }
226
+
227
+ const { addedOrModified, deleted, warnings } = classifyDiffEntries(diffEntries, sourceDir, backend)
228
+
229
+ if (addedOrModified.length === 0 && deleted.length === 0) {
230
+ return {
231
+ success: true,
232
+ skipped: true,
233
+ message: '无需要部署的文件(可能全部被排除规则过滤)',
234
+ warnings,
235
+ vcs,
236
+ fromLabel,
237
+ toLabel
238
+ }
239
+ }
240
+
241
+ const { patchName, zipName } = buildArtifactNames(vcs, toLabel, zipPrefix)
242
+ const patchDir = path.join(outDir, patchName)
243
+ const zipPath = path.join(outDir, zipName)
244
+
245
+ await fse.emptyDir(patchDir)
246
+
247
+ for (const rel of addedOrModified) {
248
+ const src = path.join(sourceDir, rel)
249
+ const dst = path.join(patchDir, rel)
250
+ await fse.ensureDir(path.dirname(dst))
251
+ await fse.copy(src, dst)
252
+ }
253
+
254
+ await fse.copy(applyScriptPath, path.join(patchDir, 'apply-update.php'))
255
+
256
+ const manifestLines = [
257
+ '# PHP 后端增量部署清单',
258
+ `backend=${backend}`,
259
+ `vcs=${vcs}`,
260
+ vcs === 'svn'
261
+ ? `from_revision=${fromLabel}`
262
+ : `from_commit=${fromLabel}`,
263
+ vcs === 'svn'
264
+ ? `to_revision=${toLabel}`
265
+ : `to_commit=${toLabel}`,
266
+ `generated_at=${new Date().toISOString().replace('T', ' ').slice(0, 19)}`,
267
+ `generated_by=${os.userInfo().username}`,
268
+ '',
269
+ '# files',
270
+ ...addedOrModified,
271
+ '',
272
+ '# deleted (需人工确认是否删除线上文件)',
273
+ ...(deleted.length > 0 ? deleted : ['# (none)'])
274
+ ]
275
+
276
+ if (warnings.length > 0) {
277
+ manifestLines.push('', '# warnings', ...warnings)
278
+ }
279
+
280
+ fs.writeFileSync(path.join(patchDir, 'MANIFEST.txt'), manifestLines.join('\n'), 'utf8')
281
+
282
+ if (deleted.length > 0) {
283
+ fs.writeFileSync(
284
+ path.join(patchDir, 'MANIFEST-deleted.txt'),
285
+ deleted.join('\n'),
286
+ 'utf8'
287
+ )
288
+ }
289
+
290
+ let zipSize = 0
291
+ if (!noZip) {
292
+ const zipResult = await createZipFromDirectory(patchDir, zipPath)
293
+ zipSize = zipResult.size
294
+ }
295
+
296
+ if (markDeployed) {
297
+ writeDeployMarker(deployDir, vcs, toLabel)
298
+ }
299
+
300
+ return {
301
+ success: true,
302
+ skipped: false,
303
+ message: `打包完成:${vcs === 'svn' ? `r${fromLabel} -> r${toLabel}` : `${fromLabel.slice(0, 8)}..${toLabel.slice(0, 8)}`}`,
304
+ patchDir,
305
+ zipPath: noZip ? undefined : zipPath,
306
+ zipSize,
307
+ fileCount: addedOrModified.length,
308
+ deletedCount: deleted.length,
309
+ warnings,
310
+ vcs,
311
+ fromLabel,
312
+ toLabel,
313
+ markDeployedHint: markDeployed
314
+ ? undefined
315
+ : `上线成功后执行:patch-build --vcs=${vcs} --mark-deployed --from=${toLabel} --to=${toLabel}`
316
+ }
317
+ }
318
+
319
+ module.exports = {
320
+ buildPatch,
321
+ classifyDiffEntries,
322
+ buildArtifactNames
323
+ }
package/lib/config.js ADDED
@@ -0,0 +1,159 @@
1
+ /**
2
+ * 路径与 CLI 配置解析
3
+ */
4
+
5
+ const fs = require('fs')
6
+ const path = require('path')
7
+ const { isGitRepository } = require('./git')
8
+ const { findSvnExe, runSvn } = require('./svn')
9
+ const { getBackend } = require('./backends')
10
+
11
+ /**
12
+ * @param {string} dir
13
+ * @returns {boolean}
14
+ */
15
+ function isSvnWorkingCopy (dir) {
16
+ try {
17
+ const svnExe = findSvnExe()
18
+ runSvn(svnExe, ['info', dir], dir)
19
+ return true
20
+ } catch {
21
+ return false
22
+ }
23
+ }
24
+
25
+ /**
26
+ * 自动检测 VCS 类型(PHP 后端常见:BackendSVN/trunk 可能 Git+SVN 并存)
27
+ * @param {string} sourceDir
28
+ * @returns {'svn'|'git'|null}
29
+ */
30
+ function detectVcs (sourceDir) {
31
+ const { readDeployMarker } = require('./marker')
32
+ const deployDir = path.join(sourceDir, 'deploy')
33
+ const marker = readDeployMarker(deployDir)
34
+
35
+ if (marker?.vcs === 'svn' && isSvnWorkingCopy(sourceDir)) return 'svn'
36
+ if (marker?.vcs === 'git' && isGitRepository(sourceDir)) return 'git'
37
+
38
+ const hasSvn = isSvnWorkingCopy(sourceDir)
39
+ const hasGit = isGitRepository(sourceDir)
40
+
41
+ // 双仓库并存时:有 SVN marker / 旧版 rev 文件则优先 SVN(KJCG Backend 场景)
42
+ if (hasSvn && hasGit) {
43
+ if (marker?.vcs === 'svn') return 'svn'
44
+ const legacyRev = path.join(deployDir, '.last-deploy-rev')
45
+ if (fs.existsSync(legacyRev)) return 'svn'
46
+ return 'git'
47
+ }
48
+
49
+ if (hasGit) return 'git'
50
+ if (hasSvn) return 'svn'
51
+ return null
52
+ }
53
+
54
+ /**
55
+ * @typedef {object} BuildConfig
56
+ * @property {'php'} backend 后端类型(v1 仅 php)
57
+ * @property {'svn'|'git'} vcs
58
+ * @property {string} sourceDir
59
+ * @property {string} deployDir
60
+ * @property {string} outDir
61
+ * @property {string} applyScriptPath
62
+ * @property {string|number|null} fromRef
63
+ * @property {string|number|null} toRef
64
+ * @property {boolean} noZip
65
+ * @property {boolean} markDeployed
66
+ * @property {boolean} skipValidation
67
+ * @property {string} zipPrefix
68
+ */
69
+
70
+ /**
71
+ * @param {Partial<BuildConfig> & { cwd?: string, pkgRoot?: string }} input
72
+ * @returns {BuildConfig}
73
+ */
74
+ function resolveConfig (input = {}) {
75
+ const cwd = input.cwd ? path.resolve(input.cwd) : process.cwd()
76
+ const sourceDir = path.resolve(input.sourceDir || process.env.PATCH_SOURCE_DIR || cwd)
77
+ const deployDir = path.resolve(
78
+ input.deployDir || process.env.PATCH_DEPLOY_DIR || path.join(sourceDir, 'deploy')
79
+ )
80
+ const outDir = path.join(deployDir, 'out')
81
+ const pkgRoot = input.pkgRoot || path.join(__dirname, '..')
82
+
83
+ const backendId = (input.backend || process.env.PATCH_BACKEND || 'php').toLowerCase()
84
+ const backend = getBackend(backendId)
85
+
86
+ let vcs = input.vcs || process.env.PATCH_VCS
87
+ if (vcs !== 'svn' && vcs !== 'git') {
88
+ const detected = detectVcs(sourceDir)
89
+ if (!detected) {
90
+ throw new Error(
91
+ `无法自动检测 VCS 类型:${sourceDir}\n请指定 --vcs=svn 或 --vcs=git`
92
+ )
93
+ }
94
+ vcs = detected
95
+ }
96
+
97
+ return {
98
+ backend: /** @type {'php'} */ (backendId),
99
+ vcs,
100
+ sourceDir,
101
+ deployDir,
102
+ outDir,
103
+ applyScriptPath: backend.getApplyScriptPath(pkgRoot),
104
+ fromRef: input.fromRef ?? null,
105
+ toRef: input.toRef ?? null,
106
+ noZip: Boolean(input.noZip),
107
+ markDeployed: Boolean(input.markDeployed),
108
+ skipValidation: Boolean(input.skipValidation || process.env.PATCH_SKIP_VALIDATION === 'true'),
109
+ zipPrefix: input.zipPrefix || process.env.PATCH_ZIP_PREFIX || backend.defaultZipPrefix
110
+ }
111
+ }
112
+
113
+ /**
114
+ * 初始化 PHP 后端 deploy 目录结构
115
+ * @param {string} deployDir
116
+ * @param {'svn'|'git'} [vcs]
117
+ */
118
+ function initDeployDir (deployDir, vcs = 'svn') {
119
+ fs.mkdirSync(path.join(deployDir, 'out'), { recursive: true })
120
+
121
+ const exampleMarker = vcs === 'git' ? 'git:请替换为上次成功上线的commit' : 'svn:请替换为上次成功上线的revision'
122
+ const markerPath = path.join(deployDir, '.last-deploy-marker.example')
123
+ if (!fs.existsSync(markerPath)) {
124
+ fs.writeFileSync(markerPath, exampleMarker, 'utf8')
125
+ }
126
+
127
+ const readmePath = path.join(deployDir, 'README.md')
128
+ if (!fs.existsSync(readmePath)) {
129
+ fs.writeFileSync(readmePath, `# PHP 后端增量部署
130
+
131
+ ## 基准文件
132
+
133
+ - \`.last-deploy-marker\`:上次成功上线标记,格式 \`svn:467\` 或 \`git:abc123...\`
134
+ - 兼容旧版 SVN:\`.last-deploy-rev\`(仅数字)
135
+
136
+ ## 本机打包
137
+
138
+ \`\`\`bash
139
+ npx patch-build --vcs=${vcs}
140
+ \`\`\`
141
+
142
+ ## 服务器应用
143
+
144
+ \`\`\`bash
145
+ unzip -o backend-update-*.zip -d patch-dir
146
+ cd patch-dir
147
+ php apply-update.php --check /path/to/backend
148
+ php apply-update.php /path/to/backend
149
+ \`\`\`
150
+ `, 'utf8')
151
+ }
152
+ }
153
+
154
+ module.exports = {
155
+ detectVcs,
156
+ resolveConfig,
157
+ initDeployDir,
158
+ isSvnWorkingCopy
159
+ }
package/lib/exclude.js ADDED
@@ -0,0 +1,18 @@
1
+ /**
2
+ * 路径排除 — 委托给当前后端配置(默认 PHP)
3
+ */
4
+
5
+ const { getBackend } = require('./backends')
6
+
7
+ /**
8
+ * @param {string} relativePath
9
+ * @param {RegExp[]} [extraPatterns]
10
+ * @param {string} [backendId]
11
+ */
12
+ function shouldExcludePath (relativePath, extraPatterns = [], backendId = 'php') {
13
+ return getBackend(backendId).shouldExcludePath(relativePath, extraPatterns)
14
+ }
15
+
16
+ module.exports = {
17
+ shouldExcludePath
18
+ }