@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 CHANGED
@@ -1,3 +1,156 @@
1
- # Temporary Holding Version
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
@@ -0,0 +1,4 @@
1
+ #!/usr/bin/env node
2
+ import { runCli } from '../src/cli.js';
3
+
4
+ runCli(process.argv.slice(2));
package/package.json CHANGED
@@ -1,6 +1,41 @@
1
1
  {
2
2
  "name": "@majinding/teampkg",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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';