kup-cli 0.1.4 → 0.2.0

package/README.md

@@ -44,6 +44,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.
@@ -65,6 +79,7 @@ Option | Short | Value Type | Description | Notes
 ---|---|---|---|---
 `--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
 
@@ -90,7 +105,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?
 

package/README.zh.md

@@ -44,6 +44,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。
@@ -65,6 +79,7 @@ Kup 会把 `file.md` 文件的内容更新到 `foo/bar` 仓库的编号为 `123`
 ---|---|---|---|---
 `--repo` | `-r` | 字符串 | 指定 GitHub 仓库
 `--id` | `-i` | 整数 | 指定 issue 的编号 | <ul><li>指定编号表示更新已有 issue<li>未指定编号则表示发布新 issue</ul>
+`--dump` | `-d` | - | 激活采集模式，把 GitHub issue 保存为本地 Markdown 文件
 `--version` | `-v` | - | 显示版本号
 `--help` | `-h` | - | 显示帮助信息
 
@@ -90,7 +105,7 @@ Kup 会把 `file.md` 文件的内容更新到 `foo/bar` 仓库的编号为 `123`
 1. 调用命令行时指定的 `--id` 参数。
 1. Markdown 文件内的元数据的 `id` 字段。
 
-当一个文件成功发布为 issue 后，Kup 会立即把 `id` 写入它的元数据中。
+当一个文件成功发布为 issue 后，Kup 会把 `id` 写回文件的元数据中（在写入前会向用户确认）。
 
 ### Issue 的标题是如何确定的？
 

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