kup-cli 0.1.3 → 0.2.0

package/README.md

@@ -1,3 +1,5 @@
+English | [中文](README.zh.md)
+
 # Kup
 
 <img src="https://user-images.githubusercontent.com/1231359/171321963-e8e73bdf-f9c8-435b-9707-318e92f1805a.png" width="150" height="80" align="right" alt="Kup logo">
@@ -6,135 +8,151 @@
 >
 > 这款命令行工具可以把本地的 Markdown 文件同步到 GitHub issue。
 
-## 谁需要它
+## Who Is It For
 
-* 利用 GitHub issue 写博客的作者们，可以方便地在本地编辑原稿，并随时发布新博文或更新已有博文。
-* 通过 GitHub issue 发布文档的开源软件作者们，可以把代码仓库中的文档更新到指定 issue。
-* 其它需要频繁更新 GitHub issue 的人。
+* 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.
+* 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:
 
 ```sh
-npm i -g kup-cli
+npm install -g kup-cli
 ```
 
-（当 Kup 发布新版时，可以再次运行这行命令升级已安装的版本。）
+(When a new version of Kup is released, run the same command again to upgrade.)
 
 
-## 使用方法
+## Usage
 
-### 发布新 issue
+### Publish a New Issue
 
 ```sh
 kup ./path/to/file.md --repo foo/bar
 ```
 
-Kup 会把 `file.md` 文件的内容发布为 `foo/bar` 仓库的一个新 issue，发布成功后会告知新 issue 的编号。
+Kup will publish the content of `file.md` as a new issue in the `foo/bar` repository, and report the new issue number after it succeeds.
 
-### 更新已有 issue
+### Update an Existing Issue
 
 ```sh
 kup ./path/to/file.md --repo foo/bar --id 123
 ```
 
-Kup 会把 `file.md` 文件的内容更新到 `foo/bar` 仓库的编号为 `123` 的 issue。
+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
 
-操作 GitHub issue 是需要权限认证的，因此你需要向 Kup 提供 GitHub token，以便 Kup 调用 GitHub API。
+Updating GitHub issues requires authentication, so you need to provide a GitHub token for Kup to call the GitHub API.
 
-1. 在 GitHub 的 “[Personal access tokens](https://github.com/settings/tokens)” 页面生成一个新 token，权限范围需要选中 “repo”。（详细说明参见 [这篇文档](https://github.com/cssmagic/kup/issues/17)。）
+1. Create a new token on GitHub's "[Personal access tokens](https://github.com/settings/tokens)" page, and make sure the `repo` scope is selected. (See [this document](https://github.com/cssmagic/kup/issues/17) for details.)
 
-2. 把获取到的 token 写入环境变量：
+2. Put the token into an environment variable:
 
-	```sh
-	export GITHUB_TOKEN=ghp_**********
-	```
+   ```sh
+   export GITHUB_TOKEN=ghp_**********
+   ```
 
-如果 Kup 未能从环境变量获取 token，会在命令行向你询问。
+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
 ---|---|---|---|---
-`--repo` | `-r` | 字符串 | 指定 GitHub 仓库
-`--id` | `-i` | 整数 | 指定 issue 的编号 | <li>指定编号表示更新已有 issue<li>未指定编号则表示发布新 issue
-`--version` | `-v` | - | 显示版本号
-`--help` | `-h` | - | 显示帮助信息
+`--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>
+`--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
 
 
-## 进阶
+## Advanced
 
-### 如何更方便地指定 `repo` 参数？
+### How can I specify the `repo` option more conveniently?
 
-有以下方式可以指定 `repo` 参数，优先级递减：
+Kup can determine the `repo` option in the following order of priority:
 
-1. 调用命令行时指定的 `--repo` 参数。
-1. Markdown 文件内的 [元数据](https://github.com/cssmagic/kup/issues/1) 的 `repo` 字段。
-1. 当前项目的 `package.json` 文件内的 `kup.repo` 字段。Kup 会以 Markdown 文件所在目录为起点逐级向上寻找 `package.json` 文件。
-1. 如果 `package.json` 文件内没有 `kup.repo` 字段，则 Kup 会尝试根据 `repository` 字段来猜测仓库名（在使用前会向用户确认）。
-1. 如果以上方式都没有成功，则 Kup 会继续查找同级或上级目录中的 `.git/config` 文件，并尝试根据其中 `remote "origin"` 的 `url` 字段来猜测仓库名（在使用前会向用户确认）。
+1. The `--repo` option passed on the command line.
+1. The `repo` field in the Markdown file's [metadata](https://github.com/cssmagic/kup/issues/1).
+1. The `kup.repo` field in the current project's `package.json`. Kup starts from the Markdown file's directory and searches upward for a `package.json` file.
+1. If `kup.repo` is not present in `package.json`, Kup will try to infer the repository name from the `repository` field and ask for confirmation before using it.
+1. If that still fails, Kup will continue searching for `.git/config` in the current or parent directories, then try to infer the repository name from the `url` field of `remote "origin"` and ask for confirmation before using it.
 
-如果整个项目的同步目标都是同一个仓库，则建议采用 `kup.repo` 字段统一指定 `repo` 参数。
+If the entire project syncs to the same repository, it is usually best to configure `kup.repo` in `package.json`.
 
-### 如何更方便地指定 `id` 参数？
+### How can I specify the `id` option more conveniently?
 
-有以下方式可以指定 `id` 参数，优先级递减：
+Kup can determine the `id` option in the following order of priority:
 
-1. 调用命令行时指定的 `--id` 参数。
-1. Markdown 文件内的元数据的 `id` 字段。
+1. The `--id` option passed on the command line.
+1. The `id` field in the Markdown file's metadata.
 
-当一个文件发布成功后，建议立即把 id 写入它的元数据。
+After a file is successfully published as an issue, Kup writes the `id` back to the file’s metadata (with user confirmation before writing).
 
-### Issue 的标题是怎么确定的？
+### How is the issue title determined?
 
-Kup 通过以下线索来确定 issue 的标题，优先级递减：
+Kup determines the issue title using the following hints, in descending priority:
 
-1. Markdown 文件内的元数据的 `title` 字段。
-1. Markdown 正文的第一个标记如果是一级标题（`# Title` 格式），则取它的内容（在这种情况下，这个一级标题在同步时会从内容中排除）。
+1. The `title` field in the Markdown file's metadata.
+1. If the first Markdown block is an H1 heading (in `# Title` form), Kup uses its text as the title. In this case, that H1 heading is excluded from the synced content.
 
-如果通过以上方式无法确定 issue 标题，Kup 会怎么处理？
+What happens if Kup still cannot determine the issue title?
 
-* 如果是在发布新 issue，则 Kup 会自己生成一个标题。
-* 如果是在更新已有 issue，则 Kup 会忽略标题（也就是说，不会修改已有标题）。
+* When publishing a new issue, Kup generates a title automatically.
+* When updating an existing issue, Kup ignores the title, which means the existing title will not be changed.
 
-### 如何为 issue 指定 label？
+### How do I assign labels to an issue?
 
-不论是在写博客，还是在发表 issue，你常常都会有打标签的需求。于是 Kup 也实现了这个功能。
+Whether you are blogging or publishing regular issues, labels are often useful, so Kup supports them as well.
 
-你需要在 Markdown 文件的元数据中添加 `tags` 字段，指定一个或多个 label。这些 label 不需要事先在 GitHub 仓库里创建好——如果你指定了不存在的 label，会在发布 issue 时自动创建。
+Add a `tags` field to the Markdown file's metadata and specify one or more labels. These labels do not need to exist in the GitHub repository beforehand. If a label does not already exist, it will be created automatically when the issue is published.
 
-如果元数据中没有 `tags` 字段，Kup 会怎么处理？
+What happens if there is no `tags` field in the metadata?
 
-* 如果是在发布新 issue，则 Kup 不会为 issue 设置任何 label。
-* 如果是在更新已有 issue 时，Kup 会忽略标签（也就是说，不会修改已有标签）。
+* When publishing a new issue, Kup will not assign any labels.
+* When updating an existing issue, Kup ignores labels, which means the existing labels will not be changed.
 
-在更新已有 issue 时，如果元数据指定的标签与 issue 现有标签不一致，则前者会完全替代后者。
+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
 
-* [Markdown 文件内的元数据示例](https://github.com/cssmagic/kup/issues/1)
-* [如何为 Kup 生成合适的 GitHub token](https://github.com/cssmagic/kup/issues/17)
+* [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
 
-请参考 [本项目的 issue](https://github.com/cssmagic/kup/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)。欢迎提出你的需求，或参与 RFC 讨论。
+* See [the issue list for this project](https://github.com/cssmagic/kup/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) for current plans.
+* Feature requests and RFC discussions are welcome.
 
-### 关于名字
+### About the Name
 
-* Kup 取自 “皮卡” 的英文词 pickup，喻意是 “轻便地运载”。
-* Kup 是变形金刚人物 “杯子” 的英文名。
+* Kup comes from the English word "pickup", suggesting lightweight transport.
+* Kup is also a character in *Transformers*.
 
-### 关于 Logo
+### About the Logo
 
-* 作者 [Fasil](https://freeicons.io/profile/722)，由 [freeicons.io](https://freeicons.io/icon/e-commerce-icons/pickup-truck-icon-26893) 免费提供。
+* The logo was created by [Fasil](https://freeicons.io/profile/722) and provided for free via [freeicons.io](https://freeicons.io/icon/e-commerce-icons/pickup-truck-icon-26893).
 
 ***
 
@@ -142,6 +160,6 @@ Kup 通过以下线索来确定 issue 的标题，优先级递减：
 
 > Any code contributed to this project is considered authorized for commercial use by the project authors and their affiliated companies and distributed under this project's license.
 >
-> 任何贡献到本项目的代码，均视为授权本项目作者及其名下公司用于商业用途、并按本项目协议分发。
+> 任何贡献到本项目的代码，均视为授权本项目作者及其关联公司用于商业用途，并可按本项目协议进行分发。
 
 MIT

package/README.zh.md

@@ -0,0 +1,165 @@
+[English](README.md) | 中文
+
+# Kup
+
+<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.
+>
+> 这款命令行工具可以把本地的 Markdown 文件同步到 GitHub issue。
+
+## 谁需要它
+
+* 利用 GitHub issue 写博客的作者们，可以方便地在本地编辑原稿，并随时发布新博文或更新已有博文。
+* 通过 GitHub issue 发布文档的开源软件作者们，可以把代码仓库中的文档更新到指定 issue。
+* 其它需要频繁更新 GitHub issue 的人。
+
+
+## 安装
+
+需要全局安装，以便随时在命令行调用：
+
+```sh
+npm install -g kup-cli
+```
+
+（当 Kup 发布新版时，可以再次运行这行命令升级已安装的版本。）
+
+
+## 使用方法
+
+### 发布新 issue
+
+```sh
+kup ./path/to/file.md --repo foo/bar
+```
+
+Kup 会把 `file.md` 文件的内容发布为 `foo/bar` 仓库的一个新 issue，发布成功后会告知新 issue 的编号。
+
+### 更新已有 issue
+
+```sh
+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。
+
+1. 在 GitHub 的 “[Personal access tokens](https://github.com/settings/tokens)” 页面生成一个新 token，权限范围需要选中 “repo”。（详细说明参见 [这篇文档](https://github.com/cssmagic/kup/issues/17)。）
+
+2. 把获取到的 token 写入环境变量：
+
+   ```sh
+   export GITHUB_TOKEN=ghp_**********
+   ```
+
+如果 Kup 未能从环境变量获取 token，会在命令行向你询问。
+
+
+## 命令行参数
+
+参数 | 短名 | 值类型 | 含义 | 备注
+---|---|---|---|---
+`--repo` | `-r` | 字符串 | 指定 GitHub 仓库
+`--id` | `-i` | 整数 | 指定 issue 的编号 | <ul><li>指定编号表示更新已有 issue<li>未指定编号则表示发布新 issue</ul>
+`--dump` | `-d` | - | 激活采集模式，把 GitHub issue 保存为本地 Markdown 文件
+`--version` | `-v` | - | 显示版本号
+`--help` | `-h` | - | 显示帮助信息
+
+
+## 进阶
+
+### 如何更方便地指定 `repo` 参数？
+
+有以下方式可以指定 `repo` 参数，优先级递减：
+
+1. 调用命令行时指定的 `--repo` 参数。
+1. Markdown 文件内的 [元数据](https://github.com/cssmagic/kup/issues/1) 的 `repo` 字段。
+1. 当前项目的 `package.json` 文件内的 `kup.repo` 字段。Kup 会以 Markdown 文件所在目录为起点逐级向上寻找 `package.json` 文件。
+1. 如果 `package.json` 文件内没有 `kup.repo` 字段，则 Kup 会尝试根据 `repository` 字段来猜测仓库名（在使用前会向用户确认）。
+1. 如果以上方式都没有成功，则 Kup 会继续查找同级或上级目录中的 `.git/config` 文件，并尝试根据其中 `remote "origin"` 的 `url` 字段来猜测仓库名（在使用前会向用户确认）。
+
+如果整个项目的同步目标都是同一个仓库，通常建议在 `package.json` 里统一配置 `kup.repo`。
+
+### 如何更方便地指定 `id` 参数？
+
+有以下方式可以指定 `id` 参数，优先级递减：
+
+1. 调用命令行时指定的 `--id` 参数。
+1. Markdown 文件内的元数据的 `id` 字段。
+
+当一个文件成功发布为 issue 后，Kup 会把 `id` 写回文件的元数据中（在写入前会向用户确认）。
+
+### Issue 的标题是如何确定的？
+
+Kup 会通过以下线索来确定 issue 的标题，优先级递减：
+
+1. Markdown 文件内的元数据的 `title` 字段。
+1. Markdown 正文的第一个标记如果是一级标题（`# Title` 格式），则取它的内容（在这种情况下，这个一级标题在同步时会从内容中排除）。
+
+如果通过以上方式无法确定 issue 标题，Kup 会怎么处理？
+
+* 如果是在发布新 issue，则 Kup 会自己生成一个标题。
+* 如果是在更新已有 issue，则 Kup 会忽略标题（也就是说，不会修改已有标题）。
+
+### 如何为 issue 指定 label？
+
+不论是在写博客，还是在发表 issue，你常常都会有打标签的需求。因此 Kup 也实现了这个功能。
+
+你需要在 Markdown 文件的元数据中添加 `tags` 字段，指定一个或多个 label。这些 label 不需要事先在 GitHub 仓库里创建好——如果你指定了不存在的 label，会在发布 issue 时自动创建。
+
+如果元数据中没有 `tags` 字段，Kup 会怎么处理？
+
+* 如果是在发布新 issue，则 Kup 不会为 issue 设置任何 label。
+* 如果是在更新已有 issue 时，Kup 会忽略标签（也就是说，不会修改已有标签）。
+
+在更新已有 issue 时，如果元数据指定的标签与 issue 现有标签不一致，则前者会完全替代后者。
+
+## 文档
+
+* [Markdown 文件内的元数据示例](https://github.com/cssmagic/kup/issues/1)
+* [如何为 Kup 生成合适的 GitHub token](https://github.com/cssmagic/kup/issues/17)
+
+
+## 其它
+
+### 开发计划
+
+* 请参考 [本项目的 issue 列表](https://github.com/cssmagic/kup/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) 来了解当前规划。
+* 欢迎提交需求，或参与 RFC 讨论。
+
+### 关于名字
+
+* Kup 取自 “皮卡” 的英文词 pickup，喻意是 “轻便地运载”。
+* Kup 是变形金刚人物 “杯子” 的英文名。
+
+### 关于 Logo
+
+* Logo 由 [Fasil](https://freeicons.io/profile/722) 创作，并通过 [freeicons.io](https://freeicons.io/icon/e-commerce-icons/pickup-truck-icon-26893) 免费提供。
+
+***
+
+## License
+
+> Any code contributed to this project is considered authorized for commercial use by the project authors and their affiliated companies and distributed under this project's license.
+>
+> 任何贡献到本项目的代码，均视为授权本项目作者及其关联公司用于商业用途，并可按本项目协议进行分发。
+
+MIT

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.3",
+	"version": "0.2.0",
 	"description": "A CLI tool to sync local Markdown files to GitHub issues.",
 	"type": "module",
 	"bin": {