kup-cli 0.1.0 → 0.1.2

package/README.md

@@ -76,8 +76,9 @@ Kup 会把 `file.md` 文件的内容更新到 `foo/bar` 仓库的编号为 `123`
 1. 调用命令行时指定的 `--repo` 参数。
 1. Markdown 文件内的 [元数据](https://github.com/cssmagic/kup/issues/1) 的 `repo` 字段。
 1. 当前项目的 `package.json` 文件内的 `kup.repo` 字段。Kup 会从当前目录向上逐级寻找 `package.json` 文件。
+1. 如果没有 `kup.repo` 字段，则 Kup 会尝试根据 `repository` 字段来猜测仓库名（在使用前会向用户确认）。
 
-如果整个项目的同步目标都是同一个仓库，则可以采用最后一种方式统一指定 `repo` 参数。
+如果整个项目的同步目标都是同一个仓库，则建议采用 `kup.repo` 字段统一指定 `repo` 参数。
 
 ### 如何更方便地指定 `id` 参数？
 

package/bin/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import yargs from 'yargs'
 import { hideBin } from 'yargs/helpers'
+import { printKupError } from '../lib/error.js'
 import { isDebugging } from '../lib/util.js'
 import { main } from '../lib/main.js'
 import { validate } from '../lib/validate.js'
@@ -48,3 +49,9 @@ main(argv)
 	.then(() => {
 		console.log('[Kup] Done!')
 	})
+	.catch((error) => {
+		if (!printKupError(error)) {
+			console.error(error)
+		}
+		process.exit(error.exitCode || 1)
+	})

package/lib/error.js

@@ -0,0 +1,39 @@
+class KupError extends Error {
+	constructor(outputLines, exitCode = 1) {
+		const firstLine = outputLines[0]
+		super(firstLine?.text || 'Kup command failed.')
+		this.name = 'KupError'
+		this.outputLines = outputLines
+		this.exitCode = exitCode
+	}
+}
+
+function errorLine(text) {
+	return {
+		method: 'error',
+		text,
+	}
+}
+
+function logLine(text) {
+	return {
+		method: 'log',
+		text,
+	}
+}
+
+function printKupError(error) {
+	if (!(error instanceof KupError)) return false
+
+	error.outputLines.forEach(({ method, text }) => {
+		console[method](text)
+	})
+	return true
+}
+
+export {
+	KupError,
+	errorLine,
+	logLine,
+	printKupError,
+}

package/lib/file.js

@@ -12,7 +12,7 @@ function readTextFile(pathname) {
 }
 
 function writeTextFile(pathname, content) {
-	fsPromises.writeFile(pathname, content)
+	return fsPromises.writeFile(pathname, content)
 }
 
 export {

package/lib/main.js

@@ -1,4 +1,7 @@
+import inquirer from 'inquirer'
+
 import { isDebugging } from './util.js'
+import { KupError, errorLine } from './error.js'
 import { readTextFile } from './file.js'
 import { parse } from './parse.js'
 import { getRepo } from './repo.js'
@@ -18,9 +21,10 @@ async function main(argv) {
 	try {
 		content = await readTextFile(file)
 	} catch (e) {
-		console.error(`[Kup] [Error] Cannot read file "${ file }"!`)
-		console.error(e.message)
-		process.exit(1)
+		throw new KupError([
+			errorLine(`[Kup] [Error] Cannot read file "${ file }"!`),
+			errorLine(e.message),
+		])
 	}
 
 	const fileInfo = parse(content)
@@ -32,12 +36,43 @@ async function main(argv) {
 	}
 
 	// 通过各种方式获取 repo
-	// 优先级： 命令行参数 > 文件元数据 > 文件所在项目的 package.json 中的 `kup.repo` 字段
-	let repoReal = repo || fileInfo.meta.repo
-	if (!repoReal) repoReal = await getRepo(file)
+	// 优先级：
+	//   P1 命令行参数
+	//   P2 文件元数据
+	//   P3 package.json 中的 `kup.repo` 字段
+	//   P4 package.json 中的 `repository` 字段（需确认）
+	let repoReal = ''
+	let repoSource = ''
+	if (repo) {
+		repoReal = repo
+		repoSource = 'cli'
+	} else if (fileInfo.meta.repo) {
+		repoReal = fileInfo.meta.repo
+		repoSource = 'meta'
+	} else {
+		const repoResult = await getRepo(file)
+		if (repoResult.needsConfirm) {
+			const answer = await inquirer.prompt([
+				{
+					name: 'useGuessedRepo',
+					type: 'confirm',
+					message: `Kup guessed the GitHub repo "${ repoResult.repo }" from package.json#repository, use it?`,
+					default: true,
+				},
+			])
+			if (answer.useGuessedRepo) {
+				repoReal = repoResult.repo
+				repoSource = repoResult.source
+			}
+		} else if (repoResult.repo) {
+			repoReal = repoResult.repo
+			repoSource = repoResult.source
+		}
+	}
 	if (!repoReal) {
-		console.error('[Kup] [Error] Cannot get `repo` to sync to!')
-		process.exit(1)
+		throw new KupError([
+			errorLine('[Kup] [Error] Cannot get `repo` to sync to!'),
+		])
 	}
 
 	// 检查 TOKEN
@@ -47,7 +82,11 @@ async function main(argv) {
 		if (idReal) {
 			await updateIssue(fileInfo, repoReal, idReal)
 		} else {
-			await postIssue(fileInfo, repoReal)
+			await postIssue(fileInfo, repoReal, {
+				file,
+				repoSource,
+				hasRepoInMeta: !!fileInfo.meta.repo,
+			})
 		}
 	}
 }

package/lib/meta.js

@@ -0,0 +1,131 @@
+const SEPARATOR = '---'
+const SEPARATOR_END_ALT = '...'
+
+function updateIssueMeta(content, {
+	id,
+	repo = '',
+	shouldWriteRepo = false,
+} = {}) {
+	const eol = detectEol(content)
+	const lines = content.split(eol)
+	const metaSection = detectMetaSection(lines)
+
+	if (!metaSection) {
+		return insertNewMetaSection(lines, {
+			eol,
+			id,
+			repo,
+			shouldWriteRepo,
+		})
+	}
+
+	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'])
+
+	return [
+		...lines.slice(0, metaSection.start + 1),
+		...metaLines,
+		...lines.slice(metaSection.end),
+	].join(eol)
+}
+
+function detectEol(content) {
+	return content.includes('\r\n') ? '\r\n' : '\n'
+}
+
+function detectMetaSection(lines) {
+	let start = 0
+	while (start < lines.length && !lines[start].trim()) {
+		start++
+	}
+
+	const firstLine = lines[start]
+	const secondLine = lines[start + 1]
+	if (!firstLine || !secondLine) return null
+
+	const hasSeparatorStart = firstLine.trimEnd() === SEPARATOR
+	const noEmptyLineAfterSeparatorStart = !!secondLine.trimEnd()
+	const hasYamlKey = /^#?\s*[\w\-]+:/.test(secondLine.trim())
+	if (!(hasSeparatorStart && noEmptyLineAfterSeparatorStart && hasYamlKey)) {
+		return null
+	}
+
+	for (let i = start + 1; i < lines.length; i++) {
+		const line = lines[i].trimEnd()
+		if (line === SEPARATOR || line === SEPARATOR_END_ALT) {
+			return { start, end: i }
+		}
+		if (!line) break
+	}
+
+	return null
+}
+
+function insertNewMetaSection(lines, { eol, id, repo, 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 bodyLines = lines.slice(insertAt)
+	const result = [...metaLines]
+	if (bodyLines.length) {
+		result.push('')
+		result.push(...bodyLines)
+	}
+
+	return result.join(eol)
+}
+
+function upsertMetaLine(metaLines, key, value, shouldWrite, beforeKeys = [], afterKeys = []) {
+	if (!shouldWrite) return
+
+	const existingIndex = findMetaLineIndex(metaLines, key)
+	if (existingIndex >= 0) {
+		metaLines[existingIndex] = replaceMetaLineValue(metaLines[existingIndex], key, value)
+		return
+	}
+
+	const insertIndex = findInsertIndex(metaLines, beforeKeys, afterKeys)
+	metaLines.splice(insertIndex, 0, `${ key }: ${ value }`)
+}
+
+function findMetaLineIndex(metaLines, key) {
+	return metaLines.findIndex((line) => {
+		const match = /^(\s*)([\w\-]+)(\s*:.*)$/.exec(line)
+		return match?.[2] === key
+	})
+}
+
+function replaceMetaLineValue(line, key, value) {
+	const match = new RegExp(`^(\\s*${ key }\\s*:)(\\s*)(.*?)(\\s+#.*)?$`).exec(line)
+	if (!match) return `${ key }: ${ value }`
+
+	const [, prefix, , , comment = ''] = match
+	return `${ prefix } ${ value }${ comment }`
+}
+
+function findInsertIndex(metaLines, beforeKeys, afterKeys) {
+	for (const key of beforeKeys) {
+		const index = findMetaLineIndex(metaLines, key)
+		if (index >= 0) return index
+	}
+
+	let afterIndex = -1
+	for (const key of afterKeys) {
+		const index = findMetaLineIndex(metaLines, key)
+		if (index > afterIndex) afterIndex = index
+	}
+
+	return afterIndex >= 0 ? afterIndex + 1 : metaLines.length
+}
+
+export {
+	updateIssueMeta,
+}

package/lib/parse.js

@@ -1,5 +1,6 @@
 import YAML from 'yaml'
 
+import { KupError, errorLine } from './error.js'
 import { isPlainObject } from './util.js'
 
 // parse markdown file:
@@ -67,17 +68,19 @@ function _parseMetaSection(lines, metaLineQty) {
 	try {
 		result = YAML.parse(yaml)
 	} catch (e) {
-		console.error(`[Kup] [Error] Cannot parse YAML meta section:`)
-		console.error(SEPARATOR)
-		console.error(yaml)
-		console.error(SEPARATOR)
-		console.error(e.message)
-		process.exit(1)
+		throw new KupError([
+			errorLine('[Kup] [Error] Cannot parse YAML meta section:'),
+			errorLine(SEPARATOR),
+			errorLine(yaml),
+			errorLine(SEPARATOR),
+			errorLine(e.message),
+		])
 	}
 	// console.log(result)
 	if (!isPlainObject(result)) {
-		console.error(`[Kup] [Error] YAML data must be an Object!`)
-		process.exit(1)
+		throw new KupError([
+			errorLine('[Kup] [Error] YAML data must be an Object!'),
+		])
 	}
 
 	// format

package/lib/repo.js

@@ -5,18 +5,54 @@ import { readTextFile } from './file.js'
 import { validateRepo } from './validate.js'
 
 async function getRepo(sourceFile = '') {
-	// 目前只实现这一种方式
-	return await _getRepoFromPkgKup(sourceFile)
+	const json = await _getPkg(sourceFile)
+	if (!json) {
+		return {
+			repo: '',
+			source: '',
+			needsConfirm: false,
+		}
+	}
+
+	const packageRepo = _getRepoFromPkgKup(json)
+	if (packageRepo.hasRepoField) {
+		return {
+			repo: packageRepo.repo,
+			source: packageRepo.repo ? 'package' : '',
+			needsConfirm: false,
+		}
+	}
+
+	const guessedRepo = _getRepoFromPkgRepo(json)
+	return {
+		repo: guessedRepo,
+		source: guessedRepo ? 'package.repository' : '',
+		needsConfirm: !!guessedRepo,
+	}
 }
 
-async function _getRepoFromPkgKup(sourceFile = '') {
-	const json = await _getPkg(sourceFile)
+function _getRepoFromPkgKup(json) {
+	const hasRepoField = !!json?.kup && Object.prototype.hasOwnProperty.call(json.kup, 'repo')
 	const repo = json?.kup?.repo
 	const result = validateRepo(repo)
-	return result.status ? repo : ''
+	return {
+		repo: result.status ? repo : '',
+		hasRepoField,
+	}
 }
-async function _getRepoFromPkgRepo() {
-	// TODO
+function _getRepoFromPkgRepo(json) {
+	const repository = json?.repository
+	if (!repository) return ''
+
+	if (typeof repository === 'string') {
+		return normalizeRepositoryToRepo(repository)
+	}
+
+	if (typeof repository === 'object' && repository.url) {
+		return normalizeRepositoryToRepo(repository.url)
+	}
+
+	return ''
 }
 async function _getRepoFromGit() {
 	// TODO
@@ -25,6 +61,7 @@ async function _getRepoFromGit() {
 async function _getPkg(sourceFile = '') {
 	const cwd = sourceFile ? path.resolve(path.dirname(sourceFile)) : process.cwd()
 	const file = await findUp('package.json', { cwd })
+	if (!file) return null
 
 	let pkg = ''
 	try {
@@ -44,9 +81,36 @@ async function _getPkg(sourceFile = '') {
 	return json
 }
 
+function normalizeRepositoryToRepo(repository) {
+	if (typeof repository !== 'string') return ''
+
+	const value = repository.trim()
+	if (!value) return ''
+
+	const candidates = [
+		/^github:([\w.-]+\/[\w.-]+)$/i,
+		/^(?:git\+)?https?:\/\/github\.com\/([\w.-]+\/[\w.-]+?)(?:\.git)?(?:\/)?$/i,
+		/^git@github\.com:([\w.-]+\/[\w.-]+?)(?:\.git)?$/i,
+		/^ssh:\/\/git@github\.com\/([\w.-]+\/[\w.-]+?)(?:\.git)?(?:\/)?$/i,
+		/^([\w.-]+\/[\w.-]+)$/,
+	]
+
+	for (const pattern of candidates) {
+		const matched = pattern.exec(value)
+		if (!matched) continue
+
+		const repo = matched[1]
+		const result = validateRepo(repo)
+		if (result.status) return repo
+	}
+
+	return ''
+}
+
 export {
 	getRepo,
-	// __getRepoFromPkgKup: _getRepoFromPkgKup,
-	// __getRepoFromPkgRepo: _getRepoFromPkgRepo,
+	_getRepoFromPkgKup as __getRepoFromPkgKup,
+	_getRepoFromPkgRepo as __getRepoFromPkgRepo,
 	// __getRepoFromGit: _getRepoFromGit,
+	normalizeRepositoryToRepo as __normalizeRepositoryToRepo,
 }

package/lib/sync.js

@@ -1,6 +1,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'
 
 let proxyOptionsForGot = {}
@@ -18,14 +21,7 @@ if (isDebugging()) {
 }
 
 async function updateIssue(fileInfo, repo, id) {
-	// prepare fields
-	// 因为接口是 PATCH 方法，只需要提供需要更新的字段
-	// Markdown 文件未提供的字段就不提交了，而不是提交空值，以免清空已有值
-	const title = fileInfo.meta.title || fileInfo.title
-	const body = fileInfo.content
-	const data = { body }
-	if (title) data.title = title
-	if (fileInfo.meta.tags) data.labels = fileInfo.meta.tags
+	const data = buildUpdateIssuePayload(fileInfo)
 	if (isDebugging()) {
 		console.log('[Kup] [Debug] requestBody =', data)
 	}
@@ -43,8 +39,9 @@ async function updateIssue(fileInfo, repo, id) {
 			...proxyOptionsForGot,
 		})
 	} catch (e) {
-		console.error('[Kup] [Error] Request error:', e.message)
-		process.exit(1)
+		throw new KupError([
+			errorLine('[Kup] [Error] Request error: ' + e.message),
+		])
 	}
 
 	// handle response
@@ -55,12 +52,8 @@ async function updateIssue(fileInfo, repo, id) {
 	}
 }
 
-async function postIssue(fileInfo, repo) {
-	// prepare fields
-	const title = fileInfo.meta.title || fileInfo.title || 'Issue posted by Kup @' + new Date().toISOString()
-	const body = fileInfo.content
-	const data = { title, body }
-	if (fileInfo.meta.tags) data.labels = fileInfo.meta.tags
+async function postIssue(fileInfo, repo, options = {}) {
+	const data = buildPostIssuePayload(fileInfo)
 	if (isDebugging()) {
 		console.log('[Kup] [Debug] requestBody =', data)
 	}
@@ -89,12 +82,14 @@ async function postIssue(fileInfo, repo) {
 				...proxyOptionsForGot,
 			})
 		} catch (e) {
-			console.error('[Kup] [Error] Request error:', e.message)
-			process.exit(1)
+			throw new KupError([
+				errorLine('[Kup] [Error] Request error: ' + e.message),
+			])
 		}
 	} else {
-		console.log('[Kup] Aborted!')
-		process.exit(1)
+		throw new KupError([
+			logLine('[Kup] Aborted!'),
+		])
 	}
 
 	// handle response
@@ -104,12 +99,67 @@ async function postIssue(fileInfo, repo) {
 		console.log(`[Kup] [Success] Posted to "${ repo }#${ id }"!`)
 		console.log(`[Kup] [Success] URL: ${ url }`)
 
-		// write back meta data
-		// TODO
+		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 }`)
+		}
+	}
+}
+
+async function writeIssueMeta(file, { id, repo, shouldWriteRepo }) {
+	let content = ''
+	try {
+		content = await readTextFile(file)
+	} catch (e) {
+		throw new KupError([
+			errorLine(`[Kup] [Error] Cannot read file "${ file }"!`),
+			errorLine(e.message),
+		])
+	}
+
+	const nextContent = updateIssueMeta(content, {
+		id,
+		repo,
+		shouldWriteRepo,
+	})
+
+	try {
+		await writeTextFile(file, nextContent)
+	} catch (e) {
+		throw new KupError([
+			errorLine(`[Kup] [Error] Cannot write file "${ file }"!`),
+			errorLine(e.message),
+		])
 	}
 }
 
+function buildUpdateIssuePayload(fileInfo) {
+	// 因为接口是 PATCH 方法，只需要提供需要更新的字段
+	// Markdown 文件未提供的字段就不提交了，而不是提交空值，以免清空已有值
+	const title = fileInfo.meta.title || fileInfo.title
+	const body = fileInfo.content
+	const data = { body }
+	if (title) data.title = title
+	if (fileInfo.meta.tags) data.labels = fileInfo.meta.tags
+	return data
+}
+
+function buildPostIssuePayload(fileInfo) {
+	const title = fileInfo.meta.title || fileInfo.title || 'Issue posted by Kup @' + new Date().toISOString()
+	const body = fileInfo.content
+	const data = { title, body }
+	if (fileInfo.meta.tags) data.labels = fileInfo.meta.tags
+	return data
+}
+
 export {
+	buildPostIssuePayload,
+	buildUpdateIssuePayload,
 	updateIssue,
 	postIssue,
+	writeIssueMeta,
 }

package/lib/token.js

@@ -1,5 +1,7 @@
 import inquirer from 'inquirer'
 
+import { KupError, errorLine, logLine } from './error.js'
+
 async function getToken() {
 	let token = process.env.GITHUB_TOKEN
 	if (!token) {
@@ -7,10 +9,11 @@ async function getToken() {
 		token = await _askToken()
 		// 把用户提供的 token 写入环境变量，不过只对当前进程有效
 		process.env.GITHUB_TOKEN = token
-	} else if (!_validateToken(token)) {
-		console.error('[Kup] [Error] The GitHub token you provide is invalid!')
-		console.error('[Kup] [Error] It must be a classic (ghp_...) or fine-grained (github_pat_...) PAT.')
-		process.exit(1)
+	} else if (!validateToken(token)) {
+		throw new KupError([
+			errorLine('[Kup] [Error] The GitHub token you provide is invalid!'),
+			errorLine('[Kup] [Error] It must be a classic (ghp_...) or fine-grained (github_pat_...) PAT.'),
+		])
 	}
 	return token
 }
@@ -25,17 +28,19 @@ async function _askToken() {
 	])
 	const token = answer.token
 	if (!token) {
-		console.log('[Kup] Aborted!')
-		process.exit(1)
-	} else if (!_validateToken(token)) {
-		console.error('[Kup] [Error] The GitHub token you provide is invalid!')
-		console.error('[Kup] [Error] It must be a classic (ghp_...) or fine-grained (github_pat_...) PAT.')
-		process.exit(1)
+		throw new KupError([
+			logLine('[Kup] Aborted!'),
+		])
+	} else if (!validateToken(token)) {
+		throw new KupError([
+			errorLine('[Kup] [Error] The GitHub token you provide is invalid!'),
+			errorLine('[Kup] [Error] It must be a classic (ghp_...) or fine-grained (github_pat_...) PAT.'),
+		])
 	}
 	return token
 }
 
-function _validateToken(token) {
+function validateToken(token) {
 	if (typeof token !== 'string' || token.length < 20) return false
 	// classic PAT：ghp_...
 	// fine-grained PAT：github_pat_...
@@ -46,4 +51,5 @@ function _validateToken(token) {
 
 export {
 	getToken,
+	validateToken,
 }

package/lib/validate.js

@@ -36,7 +36,7 @@ function validateId(id) {
 	}
 }
 function validateRepo(repo) {
-	const REPO_PATTERN = /^[\w\-]+\/[\w\-]+$/
+	const REPO_PATTERN = /^[\w.-]+\/[\w.-]+$/
 	let errorMsg = ''
 	if (!repo) {
 		errorMsg = '`repo` must be a string!'

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kup-cli",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"description": "A CLI tool to sync local Markdown files to GitHub issues.",
 	"type": "module",
 	"bin": {
@@ -9,7 +9,10 @@
 	"scripts": {
 		"debug": "export KUP_DEBUG_MODE=1",
 		"postpublish": "npx npm-mirror-sync",
-		"test": "echo \"Error: no test specified\" && exit 1"
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"test:unit": "vitest run tests/unit",
+		"test:integration": "vitest run tests/integration"
 	},
 	"repository": {
 		"type": "git",
@@ -34,7 +37,10 @@
 		"yargs": "^18.0.0"
 	},
 	"devDependencies": {
-		"https-proxy-agent": "^9.0.0"
+		"execa": "^9.6.1",
+		"https-proxy-agent": "^9.0.0",
+		"nock": "^14.0.12",
+		"vitest": "^4.1.4"
 	},
 	"files": [
 		"*.js",