kup-cli 0.1.4 → 0.2.1

package/README.md

@@ -4,26 +4,28 @@ English | [中文](README.zh.md)
 
 <img src="https://user-images.githubusercontent.com/1231359/171321963-e8e73bdf-f9c8-435b-9707-318e92f1805a.png" width="150" height="80" align="right" alt="Kup logo">
 
-> A CLI tool to sync local Markdown files to GitHub issues.
+> A CLI tool to sync local Markdown files and GitHub issues bidirectionally.
 >
-> 这款命令行工具可以把本地的 Markdown 文件同步到 GitHub issue。
+> 一款命令行工具，实现本地 Markdown 文件与 GitHub Issues 的双向同步。
+
+
 
 ## Who Is It For
 
-* Bloggers who publish with GitHub issues and want to edit drafts locally, then publish new posts or update existing ones at any time.
-* Open-source authors who publish documentation through GitHub issues and want to sync docs from the repository to specific issues.
+* Bloggers who publish with GitHub issues and want to edit drafts locally.
+* Open-source authors who publish documentation through GitHub issues.
 * Anyone else who needs to update GitHub issues frequently.
 
 
-## Installation
 
-Install it globally so you can call it from the command line at any time:
+## Installation
 
 ```sh
 npm install -g kup-cli
 ```
 
-(When a new version of Kup is released, run the same command again to upgrade.)
+Install it globally so you can use it anytime, anywhere from the command line. (When a new version of Kup is released, run the same command again to upgrade.)
+
 
 
 ## Usage
@@ -44,6 +46,20 @@ kup ./path/to/file.md --repo foo/bar --id 123
 
 Kup will update issue `123` in the `foo/bar` repository with the content of `file.md`.
 
+### Dump an Existing Issue
+
+```sh
+kup --dump --repo foo/bar --id 123
+```
+
+Kup will dump issue `123` from the `foo/bar` repository to `123.md` in the current directory.
+
+If you want to specify the output file, you can also use:
+
+```sh
+kup ./path/to/file.md --dump --repo foo/bar --id 123
+```
+
 ### Preparation
 
 Updating GitHub issues requires authentication, so you need to provide a GitHub token for Kup to call the GitHub API.
@@ -59,16 +75,35 @@ Updating GitHub issues requires authentication, so you need to provide a GitHub
 If Kup cannot read a token from the environment, it will prompt you for one in the terminal.
 
 
+
 ## Command-Line Options
 
-Option | Short | Value Type | Description | Notes
----|---|---|---|---
+Option | Short | Value Type | Description
+---|---|---|---
 `--repo` | `-r` | string | Specify the GitHub repository
-`--id` | `-i` | integer | Specify the issue number | <ul><li>Providing a number means updating an existing issue<li>Omitting it means publishing a new issue</ul>
+`--id` | `-i` | integer | Specify the issue number: <ul><li>Providing a number means updating an existing issue<li>Omitting it means publishing a new issue</ul>
+`--dump` | `-d` | - | Enable dump mode, save a GitHub issue as a local Markdown file
 `--version` | `-v` | - | Show the version number
 `--help` | `-h` | - | Show help information
 
 
+
+&nbsp;
+
+> ***
+>
+> ### **🙋‍♂️ Open to Work (Remote, Global)**
+>
+> * Senior Fullstack Engineer · Node.js, React, Vue, TS · 10+ years
+> * Published author on “AI Coding” · GitHub 3k+ followers
+> * → Resume / Contact: https://github.com/cssmagic/cssmagic
+>
+> ***
+
+&nbsp;
+
+
+
 ## Advanced
 
 ### How can I specify the `repo` option more conveniently?
@@ -90,7 +125,7 @@ Kup can determine the `id` option in the following order of priority:
 1. The `--id` option passed on the command line.
 1. The `id` field in the Markdown file's metadata.
 
-After a file is successfully published as an issue, Kup immediately writes the `id` back into its metadata.
+After a file is successfully published as an issue, Kup writes the `id` back to the file’s metadata (with user confirmation before writing).
 
 ### How is the issue title determined?
 
@@ -117,12 +152,15 @@ What happens if there is no `tags` field in the metadata?
 
 When updating an existing issue, if the labels specified in the metadata differ from the issue's current labels, the new set completely replaces the old one.
 
+
+
 ## Documentation
 
 * [Metadata examples for Markdown files](https://github.com/cssmagic/kup/issues/1)
 * [How to generate an appropriate GitHub token for Kup](https://github.com/cssmagic/kup/issues/17)
 
 
+
 ## Other
 
 ### Roadmap

package/README.zh.md

@@ -4,9 +4,11 @@
 
 <img src="https://user-images.githubusercontent.com/1231359/171321963-e8e73bdf-f9c8-435b-9707-318e92f1805a.png" width="150" height="80" align="right" alt="Kup logo">
 
-> A CLI tool to sync local Markdown files to GitHub issues.
+> A CLI tool to sync local Markdown files and GitHub issues bidirectionally.
 >
-> 这款命令行工具可以把本地的 Markdown 文件同步到 GitHub issue。
+> 一款命令行工具，实现本地 Markdown 文件与 GitHub Issues 的双向同步。
+
+
 
 ## 谁需要它
 
@@ -15,15 +17,15 @@
 * 其它需要频繁更新 GitHub issue 的人。
 
 
-## 安装
 
-需要全局安装，以便随时在命令行调用：
+## 安装
 
 ```sh
 npm install -g kup-cli
 ```
 
-（当 Kup 发布新版时，可以再次运行这行命令升级已安装的版本。）
+需要全局安装，以便随时在命令行调用。（当 Kup 发布新版时，可以再次运行这行命令升级已安装的版本。）
+
 
 
 ## 使用方法
@@ -44,6 +46,20 @@ kup ./path/to/file.md --repo foo/bar --id 123
 
 Kup 会把 `file.md` 文件的内容更新到 `foo/bar` 仓库的编号为 `123` 的 issue。
 
+### 采集已有 issue
+
+```sh
+kup --dump --repo foo/bar --id 123
+```
+
+Kup 会把 `foo/bar` 仓库的编号为 `123` 的 issue 采集为当前目录下的 `123.md` 文件。
+
+如果你想指定输出文件，也可以这样使用：
+
+```sh
+kup ./path/to/file.md --dump --repo foo/bar --id 123
+```
+
 ### 准备工作
 
 操作 GitHub issue 是需要权限认证的，因此你需要向 Kup 提供 GitHub token，以便 Kup 调用 GitHub API。
@@ -59,16 +75,19 @@ Kup 会把 `file.md` 文件的内容更新到 `foo/bar` 仓库的编号为 `123`
 如果 Kup 未能从环境变量获取 token，会在命令行向你询问。
 
 
+
 ## 命令行参数
 
-参数 | 短名 | 值类型 | 含义 | 备注
----|---|---|---|---
+参数 | 短名 | 值类型 | 含义
+---|---|---|---
 `--repo` | `-r` | 字符串 | 指定 GitHub 仓库
-`--id` | `-i` | 整数 | 指定 issue 的编号 | <ul><li>指定编号表示更新已有 issue<li>未指定编号则表示发布新 issue</ul>
+`--id` | `-i` | 整数 | 指定 issue 的编号： <ul><li>指定编号表示更新已有 issue<li>未指定编号则表示发布新 issue</ul>
+`--dump` | `-d` | - | 激活采集模式，把 GitHub issue 保存为本地 Markdown 文件
 `--version` | `-v` | - | 显示版本号
 `--help` | `-h` | - | 显示帮助信息
 
 
+
 ## 进阶
 
 ### 如何更方便地指定 `repo` 参数？
@@ -90,7 +109,7 @@ Kup 会把 `file.md` 文件的内容更新到 `foo/bar` 仓库的编号为 `123`
 1. 调用命令行时指定的 `--id` 参数。
 1. Markdown 文件内的元数据的 `id` 字段。
 
-当一个文件成功发布为 issue 后，Kup 会立即把 `id` 写入它的元数据中。
+当一个文件成功发布为 issue 后，Kup 会把 `id` 写回文件的元数据中（在写入前会向用户确认）。
 
 ### Issue 的标题是如何确定的？
 
@@ -117,12 +136,15 @@ Kup 会通过以下线索来确定 issue 的标题，优先级递减：
 
 在更新已有 issue 时，如果元数据指定的标签与 issue 现有标签不一致，则前者会完全替代后者。
 
+
+
 ## 文档
 
 * [Markdown 文件内的元数据示例](https://github.com/cssmagic/kup/issues/1)
 * [如何为 Kup 生成合适的 GitHub token](https://github.com/cssmagic/kup/issues/17)
 
 
+
 ## 其它
 
 ### 开发计划

package/bin/cli.js

@@ -14,8 +14,10 @@ if (isDebugging()) {
 const argv = yargs(hideBin(process.argv))
 	.scriptName('kup')
 	.usage('Kup -- A CLI tool to sync local Markdown files to GitHub issues.')
-	.usage('Usage: $0 <file> [options]')
+	.usage('Usage (publish to GitHub):  $0 <file> [options]')
+	.usage('Usage (dump to local file): $0 [file] --dump [options]')
 	.example('kup foo.md --repo aaa/bbb --id 123', '// sync foo.md to GitHub issue aaa/bbb#123')
+	.example('kup 123.md --dump --repo aaa/bbb --id 123', '// dump GitHub issue aaa/bbb#123 to 123.md')
 	.option('repo', {
 		alias: 'r',
 		type: 'string',
@@ -26,6 +28,11 @@ const argv = yargs(hideBin(process.argv))
 		type: 'number',
 		description: 'Specify GitHub issue ID',
 	})
+	.option('dump', {
+		alias: 'd',
+		type: 'boolean',
+		description: 'Dump a GitHub issue to a local Markdown file',
+	})
 	.option('parse-only', {
 		alias: 'p',
 		type: 'boolean',

package/lib/file.js

@@ -1,5 +1,14 @@
 import fsPromises from 'fs/promises'
 
+async function fileExists(pathname) {
+	try {
+		await fsPromises.access(pathname)
+		return true
+	} catch {
+		return false
+	}
+}
+
 function readTextFile(pathname) {
 	return fsPromises.readFile(pathname)
 		.then((bin) => {
@@ -16,6 +25,7 @@ function writeTextFile(pathname, content) {
 }
 
 export {
+	fileExists,
 	readTextFile,
 	writeTextFile,
 }

package/lib/main.js

@@ -1,38 +1,35 @@
+import path from 'path'
 import inquirer from 'inquirer'
 
 import { isDebugging } from './util.js'
 import { KupError, errorLine } from './error.js'
-import { readTextFile } from './file.js'
+import { fileExists, readTextFile } from './file.js'
 import { parse } from './parse.js'
 import { getRepo } from './repo.js'
-import { updateIssue, postIssue } from './sync.js'
+import { dumpIssue, updateIssue, postIssue } from './sync.js'
 import { getToken } from './token.js'
 
 async function main(argv) {
 	const {
+		dump = false,
 		id = 0,
+		parseOnly = false,
 		repo = '',
 		_: files,
 	} = argv
 
 	// 目前只处理第一个文件
-	const file = files[0]
-	let content = ''
-	try {
-		content = await readTextFile(file)
-	} catch (e) {
-		throw new KupError([
-			errorLine(`[Kup] [Error] Cannot read file "${ file }"!`),
-			errorLine(e.message),
-		])
-	}
+	const file = files[0] || ''
+	const fileInfo = await getFileInfoForMode(file, {
+		dump,
+		parseOnly,
+		needsFileMeta: !repo || !id,
+	})
 
-	const fileInfo = parse(content)
-
-	if (argv.parseOnly || isDebugging()) {
+	if (parseOnly || isDebugging()) {
 		console.log('[Kup] [Debug] fileInfo =', fileInfo)
 		// 如果有 p 参数，则提前退出，不需要走后面的步骤
-		if (argv.parseOnly) return
+		if (parseOnly) return
 	}
 
 	// 通过各种方式获取 repo
@@ -77,9 +74,19 @@ async function main(argv) {
 
 	// 检查 TOKEN
 	if (await getToken()) {
-		// 调用 GitHub API
 		const idReal = id || fileInfo.meta.id
-		if (idReal) {
+		if (dump) {
+			if (!idReal) {
+				throw new KupError([
+					errorLine('[Kup] [Error] Cannot get `id` to dump!'),
+				])
+			}
+			const outputFile = file || path.resolve(`${ idReal }.md`)
+			await dumpIssue(repoReal, idReal, {
+				file: outputFile,
+				repoSource,
+			})
+		} else if (idReal) {
 			await updateIssue(fileInfo, repoReal, idReal)
 		} else {
 			await postIssue(fileInfo, repoReal, {
@@ -91,6 +98,39 @@ async function main(argv) {
 	}
 }
 
+async function getFileInfoForMode(file, {
+	dump = false,
+	parseOnly = false,
+	needsFileMeta = false,
+} = {}) {
+	if (!dump || parseOnly) {
+		const content = await readMarkdownFile(file)
+		return parse(content)
+	}
+
+	if (!needsFileMeta || !file || !await fileExists(file)) {
+		return {
+			meta: {},
+			title: '',
+			content: '',
+		}
+	}
+
+	const content = await readMarkdownFile(file)
+	return parse(content)
+}
+
+async function readMarkdownFile(file) {
+	try {
+		return await readTextFile(file)
+	} catch (e) {
+		throw new KupError([
+			errorLine(`[Kup] [Error] Cannot read file "${ file }"!`),
+			errorLine(e.message),
+		])
+	}
+}
+
 function getRepoSourceLabel(source = '') {
 	switch (source) {
 		case 'package.repository':

package/lib/meta.js

@@ -1,3 +1,5 @@
+import YAML from 'yaml'
+
 const SEPARATOR = '---'
 const SEPARATOR_END_ALT = '...'
 
@@ -5,6 +7,8 @@ function updateIssueMeta(content, {
 	id,
 	repo = '',
 	shouldWriteRepo = false,
+	tags,
+	title,
 } = {}) {
 	const eol = detectEol(content)
 	const lines = content.split(eol)
@@ -16,12 +20,16 @@ function updateIssueMeta(content, {
 			id,
 			repo,
 			shouldWriteRepo,
+			tags,
+			title,
 		})
 	}
 
 	const metaLines = lines.slice(metaSection.start + 1, metaSection.end)
 	upsertMetaLine(metaLines, 'repo', repo, shouldWriteRepo, ['id', 'tags', 'title'])
-	upsertMetaLine(metaLines, 'id', String(id), true, ['tags', 'title'], ['repo'])
+	upsertMetaLine(metaLines, 'id', id, typeof id !== 'undefined', ['tags', 'title'], ['repo'])
+	upsertMetaLine(metaLines, 'tags', tags, Array.isArray(tags) && tags.length > 0, ['title'], ['id', 'repo'])
+	upsertMetaLine(metaLines, 'title', title, typeof title === 'string' && !!title, [], ['tags', 'id', 'repo'])
 
 	return [
 		...lines.slice(0, metaSection.start + 1),
@@ -62,16 +70,30 @@ function detectMetaSection(lines) {
 	return null
 }
 
-function insertNewMetaSection(lines, { eol, id, repo, shouldWriteRepo }) {
+function insertNewMetaSection(lines, {
+	eol,
+	id,
+	repo,
+	tags,
+	title,
+	shouldWriteRepo,
+}) {
 	let insertAt = 0
 	while (insertAt < lines.length && !lines[insertAt].trim()) {
 		insertAt++
 	}
 
-	const metaLines = [SEPARATOR]
-	if (shouldWriteRepo) metaLines.push(`repo: ${ repo }`)
-	metaLines.push(`id: ${ id }`)
-	metaLines.push(SEPARATOR)
+	const metaLines = [
+		SEPARATOR,
+		...buildMetaFields({
+			id,
+			repo,
+			tags,
+			title,
+			shouldWriteRepo,
+		}),
+		SEPARATOR,
+	]
 
 	const bodyLines = lines.slice(insertAt)
 	const result = [...metaLines]
@@ -93,7 +115,7 @@ function upsertMetaLine(metaLines, key, value, shouldWrite, beforeKeys = [], aft
 	}
 
 	const insertIndex = findInsertIndex(metaLines, beforeKeys, afterKeys)
-	metaLines.splice(insertIndex, 0, `${ key }: ${ value }`)
+	metaLines.splice(insertIndex, 0, stringifyMetaField(key, value))
 }
 
 function findMetaLineIndex(metaLines, key) {
@@ -105,10 +127,10 @@ function findMetaLineIndex(metaLines, key) {
 
 function replaceMetaLineValue(line, key, value) {
 	const match = new RegExp(`^(\\s*${ key }\\s*:)(\\s*)(.*?)(\\s+#.*)?$`).exec(line)
-	if (!match) return `${ key }: ${ value }`
+	if (!match) return stringifyMetaField(key, value)
 
 	const [, prefix, , , comment = ''] = match
-	return `${ prefix } ${ value }${ comment }`
+	return `${ prefix } ${ stringifyMetaValue(value, { flow: Array.isArray(value) }) }${ comment }`
 }
 
 function findInsertIndex(metaLines, beforeKeys, afterKeys) {
@@ -126,6 +148,61 @@ function findInsertIndex(metaLines, beforeKeys, afterKeys) {
 	return afterIndex >= 0 ? afterIndex + 1 : metaLines.length
 }
 
+function buildIssueMarkdown({
+	body = '',
+	id,
+	repo = '',
+	tags,
+	title,
+	shouldWriteRepo = false,
+} = {}) {
+	const metaLines = [
+		SEPARATOR,
+		...buildMetaFields({
+			id,
+			repo,
+			tags,
+			title,
+			shouldWriteRepo,
+		}),
+		SEPARATOR,
+	]
+
+	return `${ metaLines.join('\n') }\n\n${ body || '' }`
+}
+
+function buildMetaFields({
+	id,
+	repo = '',
+	tags,
+	title,
+	shouldWriteRepo = false,
+} = {}) {
+	const fields = []
+	if (shouldWriteRepo) fields.push(stringifyMetaField('repo', repo))
+	if (typeof id !== 'undefined') fields.push(stringifyMetaField('id', id))
+	if (Array.isArray(tags) && tags.length > 0) fields.push(stringifyMetaField('tags', tags))
+	if (typeof title === 'string' && title) fields.push(stringifyMetaField('title', title))
+	return fields
+}
+
+function stringifyMetaField(key, value) {
+	return `${ key }: ${ stringifyMetaValue(value, { flow: Array.isArray(value) }) }`
+}
+
+function stringifyMetaValue(value, { flow = false } = {}) {
+	const doc = new YAML.Document()
+	doc.contents = doc.createNode({ value })
+	const node = doc.get('value', true)
+	if (flow && node) node.flow = true
+	const output = doc.toString({
+		directives: false,
+		flowCollectionPadding: false,
+	}).trim()
+	return output.replace(/^value:\s*/, '')
+}
+
 export {
+	buildIssueMarkdown,
 	updateIssueMeta,
 }

package/lib/parse.js

@@ -39,9 +39,11 @@ function parse(text) {
 }
 
 function _detectMetaSectionLineQty(lines) {
-	const hasSeparatorStart = lines[0].trimEnd() === SEPARATOR
-	const noEmptyLineAfterSeparatorStart = !!lines[1].trimEnd()
-	const hasYamlKey = /^#?\s*[\w\-]+:/.test(lines[1].trim())
+	const firstLine = lines[0] || ''
+	const secondLine = lines[1] || ''
+	const hasSeparatorStart = firstLine.trimEnd() === SEPARATOR
+	const noEmptyLineAfterSeparatorStart = !!secondLine.trimEnd()
+	const hasYamlKey = /^#?\s*[\w\-]+:/.test(secondLine.trim())
 
 	let metaLineQty = 0
 	if (hasSeparatorStart && noEmptyLineAfterSeparatorStart && hasYamlKey) {
@@ -111,7 +113,7 @@ function _stripMetaSection(lines, metaLineQty) {
 	if (emptyLineQty) lines.splice(0, emptyLineQty)
 }
 
-function _getTitleFromMainBody(firstLine) {
+function _getTitleFromMainBody(firstLine = '') {
 	const re = /^#([^#].*)/
 	const result = re.exec(firstLine.trim())
 	const title = result ? result[1].trim() : ''

package/lib/sync.js

@@ -2,9 +2,9 @@ import ghGot from 'gh-got'
 import inquirer from 'inquirer'
 
 import { KupError, errorLine, logLine } from './error.js'
-import { readTextFile, writeTextFile } from './file.js'
-import { updateIssueMeta } from './meta.js'
-import { isDebugging } from '../lib/util.js'
+import { fileExists, readTextFile, writeTextFile } from './file.js'
+import { buildIssueMarkdown, updateIssueMeta } from './meta.js'
+import { isDebugging } from './util.js'
 
 let proxyOptionsForGot = {}
 if (isDebugging()) {
@@ -100,16 +100,101 @@ async function postIssue(fileInfo, repo, options = {}) {
 		console.log(`[Kup] [Success] URL: ${ url }`)
 
 		if (options.file) {
-			await writeIssueMeta(options.file, {
-				id,
-				repo,
-				shouldWriteRepo: options.repoSource === 'cli' && !options.hasRepoInMeta,
-			})
-			console.log(`[Kup] [Notice] Updated metadata in Markdown file: ${ options.file }`)
+			const shouldWriteMeta = await confirmWriteIssueMeta(options.file)
+			if (shouldWriteMeta) {
+				await writeIssueMeta(options.file, {
+					id,
+					repo,
+					shouldWriteRepo: options.repoSource === 'cli' && !options.hasRepoInMeta,
+				})
+				console.log(`[Kup] [Notice] Updated metadata in Markdown file: ${ options.file }`)
+			}
 		}
 	}
 }
 
+async function dumpIssue(repo, id, options = {}) {
+	const api = `/repos/${ repo }/issues/${ id }`
+	const url = `https://github.com/${ repo }/issues/${ id }`
+	let response = null
+	console.log(`[Kup] Dumping "${ repo }#${ id }"...`)
+	console.log(`[Kup] Dumping URL: ${ url }`)
+	try {
+		response = await ghGot(api, {
+			token: process.env.GITHUB_TOKEN,
+			...proxyOptionsForGot,
+		})
+	} catch (e) {
+		throw new KupError([
+			errorLine('[Kup] [Error] Request error: ' + e.message),
+		])
+	}
+
+	if (!response) return
+
+	const outputFile = options.file
+	if (outputFile && await fileExists(outputFile)) {
+		const shouldOverwrite = await confirmOverwriteDumpFile(outputFile)
+		if (!shouldOverwrite) {
+			throw new KupError([
+				logLine('[Kup] Aborted!'),
+			])
+		}
+	}
+
+	const issue = response.body || {}
+	const title = issue.title || ''
+	const body = issue.body || ''
+	const tags = Array.isArray(issue.labels)
+		? issue.labels
+			.map((label) => String(label?.name || '').trim())
+			.filter(Boolean)
+		: []
+	const content = buildIssueMarkdown({
+		body,
+		id,
+		repo,
+		shouldWriteRepo: options.repoSource === 'cli',
+		tags,
+		title,
+	})
+
+	try {
+		await writeTextFile(outputFile, content)
+	} catch (e) {
+		throw new KupError([
+			errorLine(`[Kup] [Error] Cannot write file "${ outputFile }"!`),
+			errorLine(e.message),
+		])
+	}
+
+	console.log(`[Kup] [Success] Dumped "${ repo }#${ id }" to "${ outputFile }"!`)
+}
+
+async function confirmWriteIssueMeta(file) {
+	const answer = await inquirer.prompt([
+		{
+			name: 'writeIssueMeta',
+			type: 'confirm',
+			message: `Kup is going to write the new issue metadata back to "${ file }", OK?`,
+			default: true,
+		},
+	])
+	return answer.writeIssueMeta
+}
+
+async function confirmOverwriteDumpFile(file) {
+	const answer = await inquirer.prompt([
+		{
+			name: 'overwriteDumpFile',
+			type: 'confirm',
+			message: `Kup is going to overwrite the local file "${ file }", OK?`,
+			default: true,
+		},
+	])
+	return answer.overwriteDumpFile
+}
+
 async function writeIssueMeta(file, { id, repo, shouldWriteRepo }) {
 	let content = ''
 	try {
@@ -159,6 +244,9 @@ function buildPostIssuePayload(fileInfo) {
 export {
 	buildPostIssuePayload,
 	buildUpdateIssuePayload,
+	confirmOverwriteDumpFile,
+	confirmWriteIssueMeta,
+	dumpIssue,
 	updateIssue,
 	postIssue,
 	writeIssueMeta,

package/lib/validate.js

@@ -1,5 +1,6 @@
 function validate(argv) {
 	const {
+		dump = false,
 		id,
 		repo,
 		_: files,
@@ -8,7 +9,8 @@ function validate(argv) {
 	let results = []
 	if ('id' in argv) results.push(validateId(id))
 	if ('repo' in argv) results.push(validateRepo(repo))
-	results.push(validateFiles(files))
+	results.push(validateFiles(files, { required: !dump }))
+	if (dump) results.push(validateDumpArgs(argv))
 	// 筛选出有错误的结果
 	const errorResults = results.filter((result) => result.status === false)
 
@@ -48,9 +50,9 @@ function validateRepo(repo) {
 		errorMsg,
 	}
 }
-function validateFiles(files) {
+function validateFiles(files, { required = true } = {}) {
 	let errorMsg = ''
-	if (!files.length) {
+	if (required && !files.length) {
 		errorMsg = 'Must specify a local file!'
 	} else if (files.some((item) => !item)) {
 		errorMsg = 'File name must not be empty!'
@@ -61,8 +63,25 @@ function validateFiles(files) {
 	}
 }
 
+function validateDumpArgs(argv) {
+	const {
+		_: files,
+	} = argv
+
+	let errorMsg = ''
+	if (!files.length && !('id' in argv)) {
+		errorMsg = 'Must specify a local file or `--id` in dump mode!'
+	}
+
+	return {
+		status: !errorMsg,
+		errorMsg,
+	}
+}
+
 export {
 	validate,
+	validateDumpArgs,
 	validateId,
 	validateRepo,
 	validateFiles,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kup-cli",
-	"version": "0.1.4",
+	"version": "0.2.1",
 	"description": "A CLI tool to sync local Markdown files to GitHub issues.",
 	"type": "module",
 	"bin": {