@qzhuli/qzhuli-cli 0.1.0-alpha.1 → 0.1.0-beta.2
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/CONTRIBUTING.md +116 -0
- package/README.md +5 -116
- package/dist/cmd.js +1 -1
- package/package.json +5 -4
package/CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
## Local Development
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
git clone <repo-url>
|
|
7
|
+
cd qzhuli-cli
|
|
8
|
+
pnpm install
|
|
9
|
+
pnpm build # Production build into dist/
|
|
10
|
+
pnpm dev # Watch build with QZ_BUILD_ENV=test
|
|
11
|
+
pnpm qz -- --version # Run the built CLI from dist/cmd.js
|
|
12
|
+
pnpm typecheck
|
|
13
|
+
pnpm lint
|
|
14
|
+
pnpm lint:fix
|
|
15
|
+
pnpm format
|
|
16
|
+
pnpm test
|
|
17
|
+
pnpm test:watch
|
|
18
|
+
pnpm tag:create
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
### Local Global Install
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
pnpm install:local:test # Build and install a test-environment CLI
|
|
25
|
+
pnpm install:local:prod # Build and install a production CLI
|
|
26
|
+
pnpm uninstall:local # Uninstall the global @qzhuli/qzhuli-cli package
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### Environments
|
|
30
|
+
|
|
31
|
+
The runtime environment is injected at build time by `tsup`.
|
|
32
|
+
|
|
33
|
+
| Build command | Environment | Config directory |
|
|
34
|
+
|---------------------------|-------------|-----------------------------------------------------|
|
|
35
|
+
| `pnpm build` | production | `~/.qzhuli-cli/` |
|
|
36
|
+
| `pnpm dev` | test | `./.qzhuli-cli/` |
|
|
37
|
+
| `pnpm install:local:test` | test | `./.qzhuli-cli/` from the command working directory |
|
|
38
|
+
| `pnpm install:local:prod` | production | `~/.qzhuli-cli/` |
|
|
39
|
+
|
|
40
|
+
### Protobuf
|
|
41
|
+
|
|
42
|
+
When `protos/*.proto` changes, regenerate generated protobuf files:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
npx pbjs --target static-module --wrap commonjs --out generated/protos.js protos/*.proto
|
|
46
|
+
npx pbts -o generated/protos.d.ts generated/protos.js
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Architecture
|
|
50
|
+
|
|
51
|
+
```text
|
|
52
|
+
CLI (Commander) -> Internal (Gateways) -> Backend
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Each command group lives under `src/commands/`. Its `index.ts` file wires Commander subcommands, and each subcommand
|
|
56
|
+
implementation exposes a pure `fooRun(factory, opts)` function that can be tested without simulating Commander.
|
|
57
|
+
|
|
58
|
+
```text
|
|
59
|
+
src/
|
|
60
|
+
+-- cmd.ts # Entry point, global options, command registration
|
|
61
|
+
+-- factory.ts # AppFactory DI container
|
|
62
|
+
+-- iostreams.ts # JSON output, dry-run, simple jq filtering
|
|
63
|
+
+-- types.ts # Shared Result/StatusResponse/CliStatusCode types
|
|
64
|
+
+-- commands/
|
|
65
|
+
| +-- auth/ # login/logout/status + QR login flow
|
|
66
|
+
| +-- config/ # show/update preferences
|
|
67
|
+
| +-- conversation/ # list
|
|
68
|
+
| +-- friend/ # list/profile
|
|
69
|
+
| +-- message/ # send/history
|
|
70
|
+
| +-- relation/ # get/set
|
|
71
|
+
| +-- user/ # search
|
|
72
|
+
+-- internal/
|
|
73
|
+
| +-- api/ # HTTP API gateway
|
|
74
|
+
| +-- im/ # WebSocket IM client + protobuf support
|
|
75
|
+
| +-- config/ # credentials, preferences, environment, directories
|
|
76
|
+
+-- i18n/ # t()/tf(), en.ts, zh.ts
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
See `AGENTS.md` for detailed development conventions.
|
|
80
|
+
|
|
81
|
+
## Publishing
|
|
82
|
+
|
|
83
|
+
This project uses GitHub Actions to automate npm publishing. Both **production** and **prerelease** builds are
|
|
84
|
+
supported.
|
|
85
|
+
|
|
86
|
+
### How it works
|
|
87
|
+
|
|
88
|
+
When a version tag matching `v*` is pushed, CI detects the tag pattern and publishes accordingly:
|
|
89
|
+
|
|
90
|
+
| Tag pattern | Build env | npm dist-tag | Install command |
|
|
91
|
+
|------------------|------------|--------------|-------------------------------------------|
|
|
92
|
+
| `v0.1.0` (plain) | production | `latest` | `npm install -g @qzhuli/qzhuli-cli` |
|
|
93
|
+
| `v0.1.0-alpha.1` | test | `alpha` | `npm install -g @qzhuli/qzhuli-cli@alpha` |
|
|
94
|
+
| `v0.1.0-beta.1` | test | `beta` | `npm install -g @qzhuli/qzhuli-cli@beta` |
|
|
95
|
+
| `v0.1.0-rc.1` | production | `rc` | `npm install -g @qzhuli/qzhuli-cli@rc` |
|
|
96
|
+
|
|
97
|
+
### Release a version
|
|
98
|
+
|
|
99
|
+
1. Update the version (this updates package.json, commits, and creates the tag automatically):
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
npm version 0.1.0-beta.1 # prerelease
|
|
103
|
+
npm version 0.1.0 # production release
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
2. Push the commit and tag:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
git push origin main --tags
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
GitHub Actions detects the tag pattern: plain versions (`v0.1.0`) publish to `latest`, alpha/beta versions publish to
|
|
113
|
+
their own channels (`alpha`/`beta`), rc versions publish to `rc`.
|
|
114
|
+
|
|
115
|
+
> **Important**: The git tag (e.g., `v0.1.0-beta.1`) must match the `package.json` version (e.g., `0.1.0-beta.1`).
|
|
116
|
+
> CI reads `package.json` for the actual version number — the tag only determines the npm dist-tag.
|
package/README.md
CHANGED
|
@@ -7,10 +7,10 @@ A command-line tool for managing QZhuli authentication, friends, relations, user
|
|
|
7
7
|
### Global Install
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
|
-
npm install -g qzhuli-cli
|
|
10
|
+
npm install -g @qzhuli/qzhuli-cli
|
|
11
11
|
|
|
12
12
|
# or
|
|
13
|
-
pnpm add -g qzhuli-cli
|
|
13
|
+
pnpm add -g @qzhuli/qzhuli-cli
|
|
14
14
|
|
|
15
15
|
qz --version
|
|
16
16
|
qz auth login
|
|
@@ -19,28 +19,10 @@ qz auth login
|
|
|
19
19
|
### Local Install
|
|
20
20
|
|
|
21
21
|
```bash
|
|
22
|
-
npm install qzhuli-cli
|
|
22
|
+
npm install @qzhuli/qzhuli-cli
|
|
23
23
|
npx qz --version
|
|
24
24
|
```
|
|
25
25
|
|
|
26
|
-
### From Source
|
|
27
|
-
|
|
28
|
-
```bash
|
|
29
|
-
git clone <repo-url>
|
|
30
|
-
cd qzhuli-cli
|
|
31
|
-
pnpm install
|
|
32
|
-
pnpm build
|
|
33
|
-
pnpm qz -- --version
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
### Local Global Install
|
|
37
|
-
|
|
38
|
-
```bash
|
|
39
|
-
pnpm install:local:test # Build and install a test-environment CLI
|
|
40
|
-
pnpm install:local:prod # Build and install a production CLI
|
|
41
|
-
pnpm uninstall:local # Uninstall the global qzhuli-cli package
|
|
42
|
-
```
|
|
43
|
-
|
|
44
26
|
## Commands
|
|
45
27
|
|
|
46
28
|
```bash
|
|
@@ -84,99 +66,6 @@ qz message history <conversation-id> [--from <id>] [--direction newer|older] [--
|
|
|
84
66
|
| `--dry-run` | Print/prepare requests without executing side effects. It skips HTTP API calls, IM WebSocket actions, credential writes/deletes, and preference writes. |
|
|
85
67
|
| `-h, --help` | Show help. |
|
|
86
68
|
|
|
87
|
-
##
|
|
88
|
-
|
|
89
|
-
The runtime environment is injected at build time by `tsup`.
|
|
90
|
-
|
|
91
|
-
| Build command | Environment | Config directory |
|
|
92
|
-
|---------------------------|-----------------|-----------------------------------------------------|
|
|
93
|
-
| `pnpm build` | production | `~/.qzhuli-cli/` |
|
|
94
|
-
| `pnpm dev` | test watch mode | `./.qzhuli-cli/` |
|
|
95
|
-
| `pnpm install:local:test` | test | `./.qzhuli-cli/` from the command working directory |
|
|
96
|
-
| `pnpm install:local:prod` | production | `~/.qzhuli-cli/` |
|
|
97
|
-
|
|
98
|
-
## Local Development
|
|
99
|
-
|
|
100
|
-
```bash
|
|
101
|
-
pnpm install
|
|
102
|
-
pnpm build # Production build into dist/
|
|
103
|
-
pnpm dev # Watch build with QZ_BUILD_ENV=test
|
|
104
|
-
pnpm qz --help # Run the built CLI from dist/cmd.js
|
|
105
|
-
pnpm typecheck
|
|
106
|
-
pnpm lint
|
|
107
|
-
pnpm lint:fix
|
|
108
|
-
pnpm test
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
When `protos/*.proto` changes, regenerate generated protobuf files:
|
|
112
|
-
|
|
113
|
-
```bash
|
|
114
|
-
npx pbjs --target static-module --wrap commonjs --out generated/protos.js protos/*.proto
|
|
115
|
-
npx pbts -o generated/protos.d.ts generated/protos.js
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
## Architecture
|
|
119
|
-
|
|
120
|
-
```text
|
|
121
|
-
CLI (Commander) -> Internal (Gateways) -> Backend
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
Each command group lives under `src/commands/`. Its `index.ts` file wires Commander subcommands, and each subcommand
|
|
125
|
-
implementation exposes a pure `fooRun(factory, opts)` function that can be tested without simulating Commander.
|
|
126
|
-
|
|
127
|
-
```text
|
|
128
|
-
src/
|
|
129
|
-
+-- cmd.ts # Entry point, global options, command registration
|
|
130
|
-
+-- factory.ts # AppFactory DI container
|
|
131
|
-
+-- iostreams.ts # JSON output, dry-run, simple jq filtering
|
|
132
|
-
+-- types.ts # Shared Result/StatusResponse/CliStatusCode types
|
|
133
|
-
+-- commands/
|
|
134
|
-
| +-- auth/ # login/logout/status + QR login flow
|
|
135
|
-
| +-- config/ # show/update preferences
|
|
136
|
-
| +-- conversation/ # list
|
|
137
|
-
| +-- friend/ # list/profile
|
|
138
|
-
| +-- message/ # send/history
|
|
139
|
-
| +-- relation/ # get/set
|
|
140
|
-
| +-- user/ # search
|
|
141
|
-
+-- internal/
|
|
142
|
-
| +-- api/ # HTTP API gateway
|
|
143
|
-
| +-- im/ # WebSocket IM client + protobuf support
|
|
144
|
-
| +-- config/ # credentials, preferences, environment, directories
|
|
145
|
-
+-- i18n/ # t()/tf(), en.ts, zh.ts
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
See `AGENTS.md` for detailed development conventions.
|
|
149
|
-
|
|
150
|
-
## Publishing
|
|
151
|
-
|
|
152
|
-
This project uses GitHub Actions to automate npm publishing. Both **production** and **prerelease** builds are
|
|
153
|
-
supported.
|
|
154
|
-
|
|
155
|
-
### Prerequisites
|
|
156
|
-
|
|
157
|
-
1. Generate an npm **Automation** token at https://www.npmjs.com/settings/tokens
|
|
158
|
-
2. Add it as a repository secret: Settings → Secrets and variables → Actions → `NPM_TOKEN`
|
|
159
|
-
|
|
160
|
-
### How it works
|
|
161
|
-
|
|
162
|
-
When a version tag matching `v*` is pushed, CI detects the tag pattern and publishes accordingly:
|
|
163
|
-
|
|
164
|
-
| Tag pattern | Build env | npm dist-tag | Install command |
|
|
165
|
-
|-------------------------------------------------------------------|------------|--------------|----------------------------------|
|
|
166
|
-
| `v0.1.0` (plain) | production | `latest` | `npm install -g qzhuli-cli` |
|
|
167
|
-
| `v0.1.0-alpha.1`, `v0.1.0-beta.1`, `v0.1.0-rc.1`, `v0.1.0-test.1` | test | `test` | `npm install -g qzhuli-cli@test` |
|
|
168
|
-
|
|
169
|
-
### Release a version
|
|
170
|
-
|
|
171
|
-
1. Update `package.json` version:
|
|
172
|
-
- Production: `"0.1.0"`
|
|
173
|
-
- Prerelease: `"0.1.0-alpha.1"`, `"0.1.0-beta.1"`, etc.
|
|
174
|
-
|
|
175
|
-
2. Create and push the tag:
|
|
176
|
-
|
|
177
|
-
```bash
|
|
178
|
-
pnpm tag:create
|
|
179
|
-
git push origin --tags
|
|
180
|
-
```
|
|
69
|
+
## Contributing
|
|
181
70
|
|
|
182
|
-
|
|
71
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for local development setup, architecture, and release process.
|
package/dist/cmd.js
CHANGED
|
@@ -13641,7 +13641,7 @@ async function main() {
|
|
|
13641
13641
|
${t("cli.banner")}` : t("cli.banner");
|
|
13642
13642
|
program.addHelpText("beforeAll", `${banner}
|
|
13643
13643
|
`);
|
|
13644
|
-
program.name("qz").version(`v${"0.1.0-
|
|
13644
|
+
program.name("qz").version(`v${"0.1.0-beta.2"}`, "-v, --version", t("options.version")).helpOption("-h, --help", t("options.help")).option("-q, --jq <expr>", t("options.jq")).option("--dry-run", t("options.dryRun"));
|
|
13645
13645
|
program.usage("<command> [subcommand] [options]");
|
|
13646
13646
|
program.hook("preAction", () => {
|
|
13647
13647
|
const opts = program.opts();
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@qzhuli/qzhuli-cli",
|
|
3
|
-
"version": "0.1.0-
|
|
3
|
+
"version": "0.1.0-beta.2",
|
|
4
4
|
"description": "CLI tool for Q助理 (QZhuli)",
|
|
5
5
|
"main": "dist/cmd.js",
|
|
6
6
|
"bin": {
|
|
@@ -8,7 +8,8 @@
|
|
|
8
8
|
},
|
|
9
9
|
"files": [
|
|
10
10
|
"dist",
|
|
11
|
-
"README.md"
|
|
11
|
+
"README.md",
|
|
12
|
+
"CONTRIBUTING.md"
|
|
12
13
|
],
|
|
13
14
|
"repository": {
|
|
14
15
|
"type": "git",
|
|
@@ -27,8 +28,7 @@
|
|
|
27
28
|
"qz": "node dist/cmd.js",
|
|
28
29
|
"install:local:test": "cross-env QZ_BUILD_ENV=test pnpm build && npm install -g .",
|
|
29
30
|
"install:local:prod": "pnpm build && npm install -g .",
|
|
30
|
-
"uninstall:local": "npm uninstall -g qzhuli-cli"
|
|
31
|
-
"tag:create": "node -e \"const v=require('./package.json').version; require('child_process').execSync('git tag -a v'+v+' -m \\\"Release v'+v+'\\\"', {stdio:'inherit'}); console.log('Tag v'+v+' created. Run git push origin v'+v+' to trigger CI.')\""
|
|
31
|
+
"uninstall:local": "npm uninstall -g @qzhuli/qzhuli-cli"
|
|
32
32
|
},
|
|
33
33
|
"keywords": [
|
|
34
34
|
"cli",
|
|
@@ -50,6 +50,7 @@
|
|
|
50
50
|
"@types/node": "^25.6.0",
|
|
51
51
|
"@types/qrcode-terminal": "^0.12.2",
|
|
52
52
|
"@types/ws": "^8.18.1",
|
|
53
|
+
"@vitest/coverage-v8": "^4.1.4",
|
|
53
54
|
"cross-env": "^10.1.0",
|
|
54
55
|
"protobufjs-cli": "2.0.1",
|
|
55
56
|
"tsup": "^8.5.1",
|