@majinding/teampkg 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +155 -2
- package/bin/teampkg.js +4 -0
- package/package.json +39 -4
- package/src/cli.js +89 -0
- package/src/index.js +1 -0
package/README.md
CHANGED
|
@@ -1,3 +1,156 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @majinding/teampkg
|
|
2
|
+
|
|
3
|
+
npm 包演示项目:执行 `teampkg install` 进行交互式安装。
|
|
4
|
+
|
|
5
|
+
## 安装
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install -g @majinding/teampkg # 全局安装,获得 teampkg 命令
|
|
9
|
+
|
|
10
|
+
# 本地开发
|
|
11
|
+
npm install # 安装本地依赖(仅 devDependencies)
|
|
12
|
+
npm link # 将 teampkg 命令链接到全局 PATH
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## 使用
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
teampkg help # 查看帮助
|
|
19
|
+
teampkg install # 交互式安装向导
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
`teampkg install` 会依次询问:
|
|
23
|
+
|
|
24
|
+
1. **安装模式** `standard` / `minimal`(默认 standard)
|
|
25
|
+
2. **是否安装全局资源**(默认 Y)
|
|
26
|
+
3. **是否生成示例文件**(默认 Y)
|
|
27
|
+
|
|
28
|
+
完成后在当前目录写入:
|
|
29
|
+
|
|
30
|
+
- `teampkg.config.json` — 安装摘要(模式、全局、示例、时间戳)
|
|
31
|
+
- `sample.md` — 仅在"生成示例文件"为 yes 时写入
|
|
32
|
+
|
|
33
|
+
## 发布到 npm
|
|
34
|
+
|
|
35
|
+
scoped 包名占用检查(以 `@majinding` 用户/组织名下的 `teampkg` 为例):
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
npm view @majinding/teampkg --registry https://registry.npmjs.org
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
发布步骤:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
npm login
|
|
45
|
+
npm publish
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
> 说明:
|
|
49
|
+
> - `@majinding` 是 scope,需要先在 npm 注册同名的用户或组织(用户名需为 `majinding`)。
|
|
50
|
+
> - scoped 包发布为 public 时,需 `publishConfig.access: public`(本仓库已配置)。
|
|
51
|
+
> - 包名 `@majinding/teampkg` 若不可用,请改 `package.json` 的 `name` 字段,
|
|
52
|
+
> 同步修改 `bin` 键名(命令名,本例为 `teampkg`)与 `files` 目录引用。
|
|
53
|
+
|
|
54
|
+
## 目录结构
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
bin/teampkg.js CLI 入口(shebang + 转发 src/cli.js)
|
|
58
|
+
src/cli.js 交互式 install 逻辑与 runCli 入口
|
|
59
|
+
src/index.js 包导出面(可被 require/import)
|
|
60
|
+
test/install.test.js node:test 单元测试
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## 测试
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
npm test
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
详细调试、本地链接、发布前检查见 [`docs/debugging.md`](docs/debugging.md)。
|
|
70
|
+
|
|
71
|
+
## 发布到 GitHub 仓库
|
|
72
|
+
|
|
73
|
+
本项目源码托管在 GitHub(`github.com/majinding/npm-package-demo`),
|
|
74
|
+
发布 npm 包与同步 GitHub 仓库是两条独立的路径:
|
|
75
|
+
|
|
76
|
+
### 1. 源码推送到 GitHub
|
|
77
|
+
|
|
78
|
+
首次初始化:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
git init
|
|
82
|
+
git add .
|
|
83
|
+
git commit -m "feat: @majinding/teampkg v0.1.0"
|
|
84
|
+
git remote add origin https://github.com/majinding/npm-package-demo.git
|
|
85
|
+
git push -u origin main
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
后续每次发版:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
npm version patch # 自动 bump 版本号 + 打 git tag v0.1.1 + 提交
|
|
92
|
+
git push origin main --tags
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
> `npm version` 会同时修改 `package.json`/`package-lock.json`、创建 git commit
|
|
96
|
+
> 和 tag,确保 git 历史与 npm 版本一一对应。
|
|
97
|
+
|
|
98
|
+
### 2. 发布 npm 包(可选:自动随 git tag 触发)
|
|
99
|
+
|
|
100
|
+
手动发布:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
npm login
|
|
104
|
+
npm publish
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
如果用 GitHub Actions 自动发布(推荐),在 `.github/workflows/publish.yml`
|
|
108
|
+
添加:
|
|
109
|
+
|
|
110
|
+
```yaml
|
|
111
|
+
name: Publish to npm
|
|
112
|
+
on:
|
|
113
|
+
push:
|
|
114
|
+
tags:
|
|
115
|
+
- 'v*'
|
|
116
|
+
jobs:
|
|
117
|
+
publish:
|
|
118
|
+
runs-on: ubuntu-latest
|
|
119
|
+
permissions:
|
|
120
|
+
contents: read
|
|
121
|
+
id-token: write
|
|
122
|
+
steps:
|
|
123
|
+
- uses: actions/checkout@v4
|
|
124
|
+
- uses: actions/setup-node@v4
|
|
125
|
+
with:
|
|
126
|
+
node-version: 22
|
|
127
|
+
registry: npm
|
|
128
|
+
- run: npm ci
|
|
129
|
+
- run: npm test
|
|
130
|
+
# 使用 npm_token 直接认证(简单)
|
|
131
|
+
- run: npm publish
|
|
132
|
+
env:
|
|
133
|
+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
并在 GitHub 仓库 `Settings → Secrets and variables → Actions` 中
|
|
137
|
+
添加 `NPM_TOKEN`(在 [npmjs.com → Access Tokens](https://www.npmjs.com/settings/tokens)
|
|
138
|
+
生成 Classic Token,勾选 `Read and write`)。
|
|
139
|
+
|
|
140
|
+
之后打 tag 即自动发版:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
npm version patch # 生成 v0.1.1
|
|
144
|
+
git push origin main --tags
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
### 3. 验证
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
npm view @majinding/teampkg --registry https://registry.npmjs.org
|
|
151
|
+
git tag -l # 查看已打版本
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
> 注意:`npm version` 默认按 `patch` 递增(0.1.0 → 0.1.1),
|
|
155
|
+
> 也可以用 `npm version minor` / `npm version major`。
|
|
2
156
|
|
|
3
|
-
This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
|
package/bin/teampkg.js
ADDED
package/package.json
CHANGED
|
@@ -1,6 +1,41 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@majinding/teampkg",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "npm 包演示:执行 teampkg install 进行交互式安装",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"teampkg": "./bin/teampkg.js"
|
|
8
|
+
},
|
|
9
|
+
"files": [
|
|
10
|
+
"bin",
|
|
11
|
+
"src"
|
|
12
|
+
],
|
|
13
|
+
"main": "src/index.js",
|
|
14
|
+
"exports": {
|
|
15
|
+
".": "./src/index.js"
|
|
16
|
+
},
|
|
17
|
+
"scripts": {
|
|
18
|
+
"test": "node --test test/install.test.js",
|
|
19
|
+
"prepublishOnly": "node --test test/install.test.js"
|
|
20
|
+
},
|
|
21
|
+
"publishConfig": {
|
|
22
|
+
"access": "public"
|
|
23
|
+
},
|
|
24
|
+
"keywords": [
|
|
25
|
+
"cli",
|
|
26
|
+
"install",
|
|
27
|
+
"demo"
|
|
28
|
+
],
|
|
29
|
+
"author": "majinding",
|
|
30
|
+
"license": "MIT",
|
|
31
|
+
"repository": {
|
|
32
|
+
"type": "git",
|
|
33
|
+
"url": "git+https://github.com/majinding/npm-package-demo.git"
|
|
34
|
+
},
|
|
35
|
+
"devDependencies": {
|
|
36
|
+
"@types/node": "^24.0.0"
|
|
37
|
+
},
|
|
38
|
+
"engines": {
|
|
39
|
+
"node": ">=18"
|
|
40
|
+
}
|
|
41
|
+
}
|
package/src/cli.js
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import fs from 'node:fs';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import process from 'node:process';
|
|
4
|
+
import readline from 'node:readline';
|
|
5
|
+
|
|
6
|
+
const CONFIG_NAME = 'teampkg.config.json';
|
|
7
|
+
const SAMPLE_NAME = 'sample.md';
|
|
8
|
+
|
|
9
|
+
const BANNER = `
|
|
10
|
+
teampkg install
|
|
11
|
+
---------------
|
|
12
|
+
交互式安装向导:依次询问安装模式、全局资源、示例文件,
|
|
13
|
+
然后在目标目录写入 teampkg.config.json 并打印安装摘要。
|
|
14
|
+
`;
|
|
15
|
+
|
|
16
|
+
function writeFiles(targetDir, summary) {
|
|
17
|
+
fs.mkdirSync(targetDir, { recursive: true });
|
|
18
|
+
const configPath = path.join(targetDir, CONFIG_NAME);
|
|
19
|
+
fs.writeFileSync(configPath, `${JSON.stringify({ installedBy: 'teampkg', version: 1, ...summary, installedAt: new Date().toISOString() }, null, 2)}\n`);
|
|
20
|
+
const written = [configPath];
|
|
21
|
+
if (summary.sample) {
|
|
22
|
+
const samplePath = path.join(targetDir, SAMPLE_NAME);
|
|
23
|
+
fs.writeFileSync(samplePath, `# teampkg 示例文件\n\n这是 teampkg install 生成的示例文件(mode=${summary.mode},global=${summary.global})。\n`);
|
|
24
|
+
written.push(samplePath);
|
|
25
|
+
}
|
|
26
|
+
return written;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
function ask(rl, question, defaultValue) {
|
|
30
|
+
const suffix = defaultValue ? ` (${defaultValue})` : '';
|
|
31
|
+
return new Promise((resolve) => {
|
|
32
|
+
rl.question(`${question}${suffix} `, (answer) => {
|
|
33
|
+
if (answer && answer.trim()) resolve(answer.trim());
|
|
34
|
+
else resolve(defaultValue);
|
|
35
|
+
});
|
|
36
|
+
});
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
function askYesNo(rl, question, defaultYes = true) {
|
|
40
|
+
const hint = defaultYes ? '[Y/n]' : '[y/N]';
|
|
41
|
+
return new Promise((resolve) => {
|
|
42
|
+
rl.question(`${question} ${hint} `, (answer) => {
|
|
43
|
+
const a = answer.trim().toLowerCase();
|
|
44
|
+
if (!a) resolve(defaultYes);
|
|
45
|
+
else resolve(a === 'y' || a === 'yes');
|
|
46
|
+
});
|
|
47
|
+
});
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* 交互式安装流程。
|
|
52
|
+
* @param {string} targetDir 安装资源写入的目录
|
|
53
|
+
* @returns {Promise<{mode:string,global:boolean,sample:boolean,target:string,written:string[]}>}
|
|
54
|
+
*/
|
|
55
|
+
export async function install(targetDir = process.cwd()) {
|
|
56
|
+
const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
|
|
57
|
+
process.stderr.write(BANNER);
|
|
58
|
+
|
|
59
|
+
const mode = await ask(rl, '安装模式 [standard|minimal] (standard):', 'standard');
|
|
60
|
+
const useGlobal = await askYesNo(rl, '是否安装全局资源?', true);
|
|
61
|
+
const sample = await askYesNo(rl, '是否生成示例文件?', true);
|
|
62
|
+
rl.close();
|
|
63
|
+
|
|
64
|
+
const normalizedMode = mode === 'minimal' ? 'minimal' : 'standard';
|
|
65
|
+
const summary = { mode: normalizedMode, global: useGlobal, sample, target: targetDir };
|
|
66
|
+
summary.written = writeFiles(targetDir, summary);
|
|
67
|
+
return summary;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* CLI 入口:支持 `teampkg install` 子命令。
|
|
72
|
+
* @param {string[]} argv 已去掉 node 与脚本路径的 argv
|
|
73
|
+
*/
|
|
74
|
+
export function runCli(argv) {
|
|
75
|
+
const command = argv[0];
|
|
76
|
+
if (!command || command === 'help' || command === '--help' || command === '-h') {
|
|
77
|
+
process.stderr.write('用法: teampkg <command>\n\n命令:\n install 交互式安装向导(在当前目录生成配置与示例)\n help 显示帮助\n');
|
|
78
|
+
return;
|
|
79
|
+
}
|
|
80
|
+
if (command === 'install') {
|
|
81
|
+
install().then((summary) => {
|
|
82
|
+
process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
|
|
83
|
+
process.stderr.write('\n安装完成 ✔\n');
|
|
84
|
+
});
|
|
85
|
+
return;
|
|
86
|
+
}
|
|
87
|
+
console.error(`未知命令: ${command}\n运行 teampkg help 查看可用命令。`);
|
|
88
|
+
process.exitCode = 1;
|
|
89
|
+
}
|
package/src/index.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { runCli, install } from './cli.js';
|