kup-cli 0.1.2 → 0.1.4

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,134 +8,136 @@
 >
 > 这款命令行工具可以把本地的 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`.
 
-### 准备工作
+### 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>
+`--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 会从当前目录向上逐级寻找 `package.json` 文件。
-1. 如果没有 `kup.repo` 字段，则 Kup 会尝试根据 `repository` 字段来猜测仓库名（在使用前会向用户确认）。
+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 immediately writes the `id` back into its metadata.
 
-### 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).
 
 ***
 
@@ -141,6 +145,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,150 @@
+[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。
+
+### 准备工作
+
+操作 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>
+`--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/lib/main.js

@@ -56,7 +56,7 @@ async function main(argv) {
 				{
 					name: 'useGuessedRepo',
 					type: 'confirm',
-					message: `Kup guessed the GitHub repo "${ repoResult.repo }" from package.json#repository, use it?`,
+					message: `Kup guessed the GitHub repo "${ repoResult.repo }" from ${ getRepoSourceLabel(repoResult.source) }, use it?`,
 					default: true,
 				},
 			])
@@ -91,6 +91,17 @@ async function main(argv) {
 	}
 }
 
+function getRepoSourceLabel(source = '') {
+	switch (source) {
+		case 'package.repository':
+			return 'package.json#repository'
+		case 'git.origin':
+			return '.git/config remote "origin"'
+		default:
+			return 'an inferred source'
+	}
+}
+
 export {
 	main,
 }

package/lib/repo.js

@@ -1,3 +1,4 @@
+import fs from 'fs/promises'
 import { findUp } from 'find-up'
 import path from 'path'
 
@@ -6,38 +7,44 @@ import { validateRepo } from './validate.js'
 
 async function getRepo(sourceFile = '') {
 	const json = await _getPkg(sourceFile)
-	if (!json) {
-		return {
-			repo: '',
-			source: '',
-			needsConfirm: false,
+
+	if (json) {
+		const packageRepo = _getRepoFromPkgKup(json)
+		if (packageRepo.repo) {
+			return {
+				repo: packageRepo.repo,
+				source: 'package',
+				needsConfirm: false,
+			}
 		}
-	}
 
-	const packageRepo = _getRepoFromPkgKup(json)
-	if (packageRepo.hasRepoField) {
-		return {
-			repo: packageRepo.repo,
-			source: packageRepo.repo ? 'package' : '',
-			needsConfirm: false,
+		if (!packageRepo.hasKupRepoField) {
+			const guessedRepo = _getRepoFromPkgRepo(json)
+			if (guessedRepo) {
+				return {
+					repo: guessedRepo,
+					source: 'package.repository',
+					needsConfirm: true,
+				}
+			}
 		}
 	}
 
-	const guessedRepo = _getRepoFromPkgRepo(json)
+	const guessedRepo = await _getRepoFromGit(sourceFile)
 	return {
 		repo: guessedRepo,
-		source: guessedRepo ? 'package.repository' : '',
+		source: guessedRepo ? 'git.origin' : '',
 		needsConfirm: !!guessedRepo,
 	}
 }
 
 function _getRepoFromPkgKup(json) {
-	const hasRepoField = !!json?.kup && Object.prototype.hasOwnProperty.call(json.kup, 'repo')
+	const hasKupRepoField = !!json?.kup && Object.prototype.hasOwnProperty.call(json.kup, 'repo')
 	const repo = json?.kup?.repo
 	const result = validateRepo(repo)
 	return {
 		repo: result.status ? repo : '',
-		hasRepoField,
+		hasKupRepoField,
 	}
 }
 function _getRepoFromPkgRepo(json) {
@@ -54,8 +61,18 @@ function _getRepoFromPkgRepo(json) {
 
 	return ''
 }
-async function _getRepoFromGit() {
-	// TODO
+async function _getRepoFromGit(sourceFile = '') {
+	const configFile = await _getGitConfigFile(sourceFile)
+	if (!configFile) return ''
+
+	let config = ''
+	try {
+		config = await readTextFile(configFile)
+	} catch {
+		return ''
+	}
+
+	return _getRepoFromGitConfig(config)
 }
 
 async function _getPkg(sourceFile = '') {
@@ -81,6 +98,58 @@ async function _getPkg(sourceFile = '') {
 	return json
 }
 
+async function _getGitConfigFile(sourceFile = '') {
+	let cwd = sourceFile ? path.resolve(path.dirname(sourceFile)) : process.cwd()
+	while (true) {
+		const gitPath = path.join(cwd, '.git')
+
+		try {
+			const stats = await fs.stat(gitPath)
+			if (stats.isDirectory()) {
+				const configFile = path.join(gitPath, 'config')
+				try {
+					await fs.access(configFile)
+					return configFile
+				} catch {
+					return ''
+				}
+			}
+			return ''
+		} catch {
+			const parent = path.dirname(cwd)
+			if (parent === cwd) return ''
+			cwd = parent
+		}
+	}
+}
+
+function _getRepoFromGitConfig(config) {
+	if (typeof config !== 'string' || !config.trim()) return ''
+
+	const lines = config.split(/\r?\n/)
+	let inOriginRemote = false
+	for (const line of lines) {
+		const trimmed = line.trim()
+		if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith(';')) continue
+
+		const sectionMatched = /^\[\s*(.*?)\s*\]$/.exec(trimmed)
+		if (sectionMatched) {
+			inOriginRemote = /^remote\s+"origin"$/i.test(sectionMatched[1])
+			continue
+		}
+		if (!inOriginRemote) continue
+
+		const entryMatched = /^([A-Za-z][\w-]*)\s*=\s*(.*?)\s*$/.exec(trimmed)
+		if (!entryMatched) continue
+
+		const key = entryMatched[1].toLowerCase()
+		const value = entryMatched[2]
+		if (key === 'url') return normalizeRepositoryToRepo(value)
+	}
+
+	return ''
+}
+
 function normalizeRepositoryToRepo(repository) {
 	if (typeof repository !== 'string') return ''
 
@@ -111,6 +180,7 @@ export {
 	getRepo,
 	_getRepoFromPkgKup as __getRepoFromPkgKup,
 	_getRepoFromPkgRepo as __getRepoFromPkgRepo,
-	// __getRepoFromGit: _getRepoFromGit,
+	_getRepoFromGit as __getRepoFromGit,
+	_getRepoFromGitConfig as __getRepoFromGitConfig,
 	normalizeRepositoryToRepo as __normalizeRepositoryToRepo,
 }

package/package.json

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