@wwkit/opm 1.0.1 → 1.0.2

package/src/tools/ftp/client.js

@@ -0,0 +1,214 @@
+/**
+ * FTP 客户端封装 — 基于 basic-ftp
+ *
+ * 提供连接、上传、下载、列表、删除、建目录等操作。
+ * 自动重试 + 超时 + 被动模式由配置驱动。
+ */
+
+import ftp from 'basic-ftp'
+import { Readable } from 'node:stream'
+import { getConfig } from '../../config.js'
+
+const { Client } = ftp
+
+/**
+ * 从 opm config 读取 FTP 配置
+ * @returns {{ host: string, port: number, user: string, password: string, remote_root: string, base_url: string, timeout: number, max_retries: number, pasv: boolean }}
+ */
+export function getFtpConfig() {
+  const cfg = getConfig().ftp || {}
+  return {
+    host: cfg.host || '',
+    port: parseInt(cfg.port, 10) || 21,
+    user: cfg.user || '',
+    password: cfg.password || '',
+    remote_root: (cfg.remote_root || '/htdocs/webwork').replace(/\/+$/, ''),
+    base_url: (cfg.base_url || '').replace(/\/+$/, ''),
+    timeout: parseInt(cfg.timeout, 10) || 120,
+    max_retries: parseInt(cfg.max_retries, 10) || 2,
+    pasv: cfg.pasv !== undefined ? cfg.pasv : false,
+  }
+}
+
+/**
+ * 创建并连接 FTP 客户端
+ * @returns {Promise<import('basic-ftp').Client>}
+ */
+export async function connect() {
+  const cfg = getFtpConfig()
+  const client = new Client(cfg.timeout * 1000)
+  await client.access({
+    host: cfg.host,
+    port: cfg.port,
+    user: cfg.user,
+    password: cfg.password,
+    secure: false,
+  })
+  return client
+}
+
+/**
+ * 测试连接
+ * @returns {Promise<boolean>}
+ */
+export async function checkConnection() {
+  let client
+  try {
+    client = await connect()
+    return true
+  } catch {
+    return false
+  } finally {
+    if (client) client.close()
+  }
+}
+
+/**
+ * 确保远程目录存在（递归创建）
+ * @param {import('basic-ftp').FTPClient} client
+ * @param {string} dirPath - 绝对路径
+ */
+export async function ensureDir(client, dirPath) {
+  const parts = dirPath.split('/').filter(Boolean)
+  let current = ''
+  for (const part of parts) {
+    current += '/' + part
+    try {
+      await client.cd(current)
+    } catch {
+      await client.send('MKD ' + current)
+    }
+  }
+}
+
+/**
+ * 上传 Buffer 到远程路径
+ * @param {Buffer} data
+ * @param {string} remotePath - 绝对路径
+ * @param {number} [maxRetries]
+ * @returns {Promise<boolean>}
+ */
+export async function uploadBuffer(data, remotePath, maxRetries) {
+  const cfg = getFtpConfig()
+  const retries = maxRetries !== undefined ? maxRetries : cfg.max_retries
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    let client
+    try {
+      client = await connect()
+      const dir = remotePath.substring(0, remotePath.lastIndexOf('/'))
+      if (dir) await ensureDir(client, dir)
+      await client.uploadFrom(Readable.from(data), remotePath)
+      return true
+    } catch (err) {
+      if (attempt === retries) throw err
+    } finally {
+      if (client) client.close()
+    }
+  }
+  return false
+}
+
+/**
+ * 上传本地文件到远程路径
+ * @param {string} localPath
+ * @param {string} remotePath - 绝对路径
+ * @param {number} [maxRetries]
+ * @returns {Promise<boolean>}
+ */
+export async function uploadFile(localPath, remotePath, maxRetries) {
+  const cfg = getFtpConfig()
+  const retries = maxRetries !== undefined ? maxRetries : cfg.max_retries
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    let client
+    try {
+      client = await connect()
+      const dir = remotePath.substring(0, remotePath.lastIndexOf('/'))
+      if (dir) await ensureDir(client, dir)
+      await client.uploadFrom(localPath, remotePath)
+      return true
+    } catch (err) {
+      if (attempt === retries) throw err
+    } finally {
+      if (client) client.close()
+    }
+  }
+  return false
+}
+
+/**
+ * 下载远程文件到本地
+ * @param {string} remotePath - 绝对路径
+ * @param {string} localPath
+ * @returns {Promise<boolean>}
+ */
+export async function downloadFile(remotePath, localPath) {
+  let client
+  try {
+    client = await connect()
+    const dir = localPath.substring(0, localPath.lastIndexOf('/'))
+    if (dir) {
+      const fs = await import('node:fs')
+      fs.mkdirSync(dir, { recursive: true })
+    }
+    await client.downloadTo(localPath, remotePath)
+    return true
+  } catch {
+    return false
+  } finally {
+    if (client) client.close()
+  }
+}
+
+/**
+ * 列出远程目录下的文件（递归），返回相对路径 + size
+ * @param {string} remoteDir - 绝对路径
+ * @returns {Promise<Map<string, number>>} Map<relPath, size>
+ */
+export async function listRemoteFiles(remoteDir) {
+  let client
+  try {
+    client = await connect()
+    const result = new Map()
+    await walkRemote(client, remoteDir, '', result)
+    return result
+  } finally {
+    if (client) client.close()
+  }
+}
+
+async function walkRemote(client, baseDir, relDir, result) {
+  let entries
+  try {
+    entries = await client.list(baseDir + '/' + relDir)
+  } catch {
+    return
+  }
+  for (const entry of entries) {
+    const name = entry.name
+    if (name === '.' || name === '..') continue
+    const rel = relDir ? `${relDir}/${name}` : name
+    if (entry.isDirectory) {
+      await walkRemote(client, baseDir, rel, result)
+    } else if (entry.isFile) {
+      result.set(rel, entry.size)
+    }
+  }
+}
+
+/**
+ * 删除远程文件
+ * @param {string} remotePath - 绝对路径
+ * @returns {Promise<boolean>}
+ */
+export async function removeFile(remotePath) {
+  let client
+  try {
+    client = await connect()
+    await client.remove(remotePath)
+    return true
+  } catch {
+    return false
+  } finally {
+    if (client) client.close()
+  }
+}

package/src/tools/ftp/index.js

@@ -0,0 +1,271 @@
+/**
+ * opm ftp 命令组 — FTP 文件管理
+ *
+ * 命令：connect / upload / rsync / download / root / config
+ * 各命令接口独立，不强制统一结构。
+ */
+
+import path from 'node:path'
+import fs from 'node:fs'
+import { parseFlags } from '../../cli/helpers/args.js'
+import { getConfig } from '../../config.js'
+import { output } from '../../formatter.js'
+import {
+  getFtpConfig, checkConnection, uploadBuffer, uploadFile,
+  downloadFile, listRemoteFiles, removeFile, ensureDir, connect,
+} from './client.js'
+import {
+  isExcluded, md5File, detectImageExt, extFromName, makeFilename,
+  todayStr, readData, collectFiles,
+} from './util.js'
+
+export class FtpGroup {
+  constructor() {
+    this.name = 'ftp'
+    this.desc = 'FTP file management (upload/rsync/download)'
+  }
+
+  async run(argv) {
+    const [action, ...rest] = argv
+
+    if (!action || action === '-h' || action === '--help' || action === 'help') {
+      this.printHelp()
+      return
+    }
+
+    switch (action) {
+      case 'connect':
+        return this._connect()
+      case 'upload':
+        return this._upload(parseFlags(rest))
+      case 'rsync':
+        return this._rsync(parseFlags(rest))
+      case 'download':
+        return this._download(parseFlags(rest))
+      case 'root':
+        return this._root()
+      case 'config':
+        return this._config()
+      default:
+        console.error(`Unknown action: ${action}`)
+        this.printHelp()
+        process.exit(1)
+    }
+  }
+
+  async _connect() {
+    const ok = await checkConnection()
+    output({ connected: ok })
+  }
+
+  async _upload(parsed) {
+    const file = parsed.positional[0]
+    if (!file) {
+      console.error('Usage: opm ftp upload <file> [-n name] [-s subdir]')
+      process.exit(1)
+    }
+    const name = parsed.flags.name || parsed.flags.n || ''
+    const subdir = parsed.flags.subdir || parsed.flags.s || ''
+    const cfg = getFtpConfig()
+
+    const data = await readData(file, cfg.timeout * 1000)
+    if (!data || data.length === 0) {
+      console.error('Failed to read data (empty or not found)')
+      process.exit(1)
+    }
+
+    let ext = detectImageExt(data) || extFromName(name || file) || ''
+    if (!ext) {
+      const fromPath = path.extname(file).slice(1).toLowerCase()
+      ext = fromPath || 'bin'
+    }
+
+    let filename
+    if (name) {
+      const nameExt = path.extname(name).slice(1).toLowerCase()
+      if (nameExt && nameExt !== ext) ext = nameExt
+      filename = name.endsWith(`.${ext}`) ? name : `${name}.${ext}`
+    } else {
+      filename = makeFilename(ext)
+    }
+
+    const date = todayStr()
+    const parts = [cfg.remote_root, date]
+    if (subdir) parts.push(subdir.replace(/^\/+/, ''))
+    parts.push(filename)
+    const remotePath = parts.join('/')
+
+    const ok = await uploadBuffer(data, remotePath)
+    if (!ok) {
+      console.error('Upload failed')
+      process.exit(1)
+    }
+
+    const urlParts = [cfg.base_url, date]
+    if (subdir) urlParts.push(subdir.replace(/^\/+/, ''))
+    urlParts.push(filename)
+    output({ uploaded: true, remote: remotePath, url: urlParts.join('/') })
+  }
+
+  async _rsync(parsed) {
+    const local = parsed.positional[0]
+    if (!local) {
+      console.error('Usage: opm ftp rsync <local> [-s subdir] [-x pattern] [--dry-run] [--prune]')
+      process.exit(1)
+    }
+    const subdir = parsed.flags.subdir || parsed.flags.s || ''
+    const excludes = parsed.flags.exclude || parsed.flags.x || []
+    const excludeList = Array.isArray(excludes) ? excludes : [excludes]
+    const dryRun = parsed.flags['dry-run'] === 'true'
+    const prune = parsed.flags.prune === 'true'
+
+    const cfg = getFtpConfig()
+    const localDir = path.resolve(local)
+    if (!fs.existsSync(localDir) || !fs.statSync(localDir).isDirectory()) {
+      console.error(`Local directory not found: ${localDir}`)
+      process.exit(1)
+    }
+
+    const remoteBase = subdir
+      ? `${cfg.remote_root}/${subdir.replace(/^\/+/, '')}`
+      : cfg.remote_root
+
+    const allFiles = collectFiles(localDir)
+    const toUpload = allFiles.filter((rel) => !isExcluded(rel, excludeList))
+    const skippedExcluded = allFiles.filter((rel) => isExcluded(rel, excludeList))
+
+    const remoteFiles = await listRemoteFiles(remoteBase)
+
+    const uploadPlan = []
+    const skippedSame = []
+    for (const rel of toUpload) {
+      const localPath = path.join(localDir, ...rel.split('/'))
+      const stat = fs.statSync(localPath)
+      const remoteSize = remoteFiles.get(rel)
+      if (remoteSize !== undefined && remoteSize === stat.size) {
+        skippedSame.push(rel)
+      } else {
+        uploadPlan.push(rel)
+      }
+    }
+
+    const deletePlan = []
+    if (prune) {
+      for (const [rel] of remoteFiles) {
+        if (!toUpload.includes(rel)) {
+          deletePlan.push(rel)
+        }
+      }
+    }
+
+    if (dryRun) {
+      output({
+        dryRun: true,
+        remote: remoteBase,
+        upload: uploadPlan,
+        skipSame: skippedSame.length,
+        skipExcluded: skippedExcluded,
+        delete: deletePlan,
+      })
+      return
+    }
+
+    const uploaded = []
+    const failed = []
+    const total = uploadPlan.length
+    for (let i = 0; i < uploadPlan.length; i++) {
+      const rel = uploadPlan[i]
+      const localPath = path.join(localDir, ...rel.split('/'))
+      const remotePath = `${remoteBase}/${rel}`
+      try {
+        await uploadFile(localPath, remotePath)
+        uploaded.push(rel)
+      } catch (err) {
+        failed.push({ path: rel, error: err.message })
+      }
+      process.stderr.write(`\r[${i + 1}/${total}] ${rel}`)
+    }
+    if (total > 0) process.stderr.write('\n')
+
+    const deleted = []
+    const deleteFailed = []
+    for (const rel of deletePlan) {
+      const remotePath = `${remoteBase}/${rel}`
+      const ok = await removeFile(remotePath)
+      if (ok) deleted.push(rel)
+      else deleteFailed.push(rel)
+    }
+
+    output({
+      remote: remoteBase,
+      uploaded: uploaded.length,
+      uploadedFiles: uploaded,
+      skippedSame: skippedSame.length,
+      skippedExcluded,
+      failed,
+      pruned: deleted.length,
+      prunedFiles: deleted,
+      pruneFailed: deleteFailed,
+    })
+  }
+
+  async _download(parsed) {
+    const remote = parsed.positional[0]
+    const local = parsed.positional[1]
+    if (!remote || !local) {
+      console.error('Usage: opm ftp download <remote> <local>')
+      process.exit(1)
+    }
+    const cfg = getFtpConfig()
+    const remotePath = remote.startsWith('/') ? remote : `${cfg.remote_root}/${remote}`
+    const ok = await downloadFile(remotePath, local)
+    output({ downloaded: ok, remote: remotePath, local })
+  }
+
+  _root() {
+    const cfg = getFtpConfig()
+    output({ remote_root: cfg.remote_root })
+  }
+
+  _config() {
+    const cfg = getFtpConfig()
+    output(cfg)
+  }
+
+  printHelp() {
+    console.log(`
+Usage: opm ftp <action> [args] [options]
+
+Actions:
+  connect                              Test FTP connection
+  upload <file> [-n name] [-s subdir]  Upload file (local path or HTTP URL)
+  rsync <local> [options]              Recursive upload directory (FTP-side dedup)
+  download <remote> <local>            Download file from FTP
+  root                                 Show configured remote root directory
+  config                               Show FTP config
+  help                                 Show this help
+
+rsync options:
+  -s, --subdir <dir>                   Remote subdirectory (under remote_root)
+  -x, --exclude <pattern>              Exclude glob pattern (repeatable)
+  --dry-run                            Preview without uploading
+  --prune                              Delete remote files not in local
+
+Options:
+  -h, --help                           Show this help
+
+Examples:
+  opm ftp connect
+  opm ftp upload ./img.png
+  opm ftp upload ./img.png -n cover -s banner
+  opm ftp upload https://example.com/a.jpg -n cover.jpg
+  opm ftp rsync ./webwork/
+  opm ftp rsync ./webwork/ -s deploy -x "vendor/*" -x "*.log"
+  opm ftp rsync ./webwork/ --dry-run
+  opm ftp rsync ./webwork/ --prune
+  opm ftp download 20260913/cover.jpg ./cover.jpg
+  opm ftp root
+  opm ftp config
+`)
+  }
+}

package/src/tools/ftp/util.js

@@ -0,0 +1,174 @@
+/**
+ * FTP 工具函数 — exclude 匹配、MD5、图片检测、自动命名、HTTP 源下载
+ */
+
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const IMAGE_MAGIC = {
+  jpg: Buffer.from([0xff, 0xd8, 0xff]),
+  png: Buffer.from([0x89, 0x50, 0x4e, 0x47]),
+  gif: Buffer.from([0x47, 0x49, 0x46, 0x38]),
+  webp: Buffer.from([0x52, 0x49, 0x46, 0x46]),
+}
+
+/**
+ * glob 通配符匹配（支持 * 和 **）
+ * @param {string} relPath - 相对路径（posix 风格）
+ * @param {string} pattern - glob 模式
+ * @returns {boolean}
+ */
+export function matchGlob(relPath, pattern) {
+  const regex = globToRegex(pattern)
+  return regex.test(relPath)
+}
+
+function globToRegex(pattern) {
+  let re = ''
+  let i = 0
+  while (i < pattern.length) {
+    if (pattern[i] === '*' && pattern[i + 1] === '*') {
+      re += '.*'
+      i += 2
+    } else if (pattern[i] === '*') {
+      re += '[^/]*'
+      i++
+    } else if (pattern[i] === '?') {
+      re += '[^/]'
+      i++
+    } else if ('.+^$(){}|[]\\'.includes(pattern[i])) {
+      re += '\\' + pattern[i]
+      i++
+    } else {
+      re += pattern[i]
+      i++
+    }
+  }
+  return new RegExp('^' + re + '$')
+}
+
+/**
+ * 判断路径是否被排除
+ * @param {string} relPath - 相对路径（posix）
+ * @param {string[]} excludes - 排除模式列表
+ * @returns {boolean}
+ */
+export function isExcluded(relPath, excludes) {
+  for (const pattern of excludes) {
+    const p = pattern.trim()
+    if (!p) continue
+    if (matchGlob(relPath, p) || matchGlob(relPath, `${p}/**`)) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * 计算文件 MD5（流式，避免大文件占内存）
+ * @param {string} filePath
+ * @returns {Promise<string>}
+ */
+export async function md5File(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('md5')
+    const stream = fs.createReadStream(filePath)
+    stream.on('data', (chunk) => hash.update(chunk))
+    stream.on('end', () => resolve(hash.digest('hex')))
+    stream.on('error', reject)
+  })
+}
+
+/**
+ * 计算 Buffer MD5
+ * @param {Buffer} data
+ * @returns {string}
+ */
+export function md5Buffer(data) {
+  return crypto.createHash('md5').update(data).digest('hex')
+}
+
+/**
+ * 从 magic bytes 检测图片扩展名
+ * @param {Buffer} data
+ * @returns {string|null}
+ */
+export function detectImageExt(data) {
+  for (const [ext, magic] of Object.entries(IMAGE_MAGIC)) {
+    if (data.subarray(0, magic.length).equals(magic)) {
+      return ext
+    }
+  }
+  return null
+}
+
+/**
+ * 从文件名提取扩展名（仅限图片类型）
+ * @param {string} name
+ * @returns {string|null}
+ */
+export function extFromName(name) {
+  const clean = name.split('?')[0]
+  const ext = path.extname(clean).slice(1).toLowerCase()
+  return ext in IMAGE_MAGIC ? ext : null
+}
+
+/**
+ * 生成随机文件名
+ * @param {string} ext
+ * @returns {string}
+ */
+export function makeFilename(ext) {
+  const id = crypto.randomUUID().replace(/-/g, '').slice(0, 8)
+  return `${id}.${ext}`
+}
+
+/**
+ * 今天的日期字符串 YYYYMMDD
+ * @returns {string}
+ */
+export function todayStr() {
+  const d = new Date()
+  const y = d.getFullYear()
+  const m = String(d.getMonth() + 1).padStart(2, '0')
+  const day = String(d.getDate()).padStart(2, '0')
+  return `${y}${m}${day}`
+}
+
+/**
+ * 读取本地文件或下载 HTTP URL 为 Buffer
+ * @param {string} urlOrPath
+ * @param {number} [timeout=120000]
+ * @returns {Promise<Buffer>}
+ */
+export async function readData(urlOrPath, timeout = 120000) {
+  if (urlOrPath.startsWith('http://') || urlOrPath.startsWith('https://')) {
+    const resp = await fetch(urlOrPath, { signal: AbortSignal.timeout(timeout) })
+    if (!resp.ok) throw new Error(`HTTP ${resp.status}: ${urlOrPath}`)
+    return Buffer.from(await resp.arrayBuffer())
+  }
+  if (!fs.existsSync(urlOrPath)) throw new Error(`File not found: ${urlOrPath}`)
+  return fs.readFileSync(urlOrPath)
+}
+
+/**
+ * 递归收集目录下所有文件（posix 相对路径）
+ * @param {string} dir
+ * @returns {string[]}
+ */
+export function collectFiles(dir) {
+  const result = []
+  function walk(base) {
+    for (const entry of fs.readdirSync(base, { withFileTypes: true })) {
+      const full = path.join(base, entry.name)
+      if (entry.isDirectory()) {
+        walk(full)
+      } else if (entry.isFile()) {
+        result.push(path.relative(dir, full).split(path.sep).join('/'))
+      }
+    }
+  }
+  walk(dir)
+  return result.sort()
+}