@qzhuli/qzhuli-cli 0.1.0-alpha.1

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.
Files changed (3) hide show
  1. package/README.md +182 -0
  2. package/dist/cmd.js +13672 -0
  3. package/package.json +59 -0
package/README.md ADDED
@@ -0,0 +1,182 @@
1
+ # QZhuli CLI
2
+
3
+ A command-line tool for managing QZhuli authentication, friends, relations, users, conversations, and messages.
4
+
5
+ ## Installation
6
+
7
+ ### Global Install
8
+
9
+ ```bash
10
+ npm install -g qzhuli-cli
11
+
12
+ # or
13
+ pnpm add -g qzhuli-cli
14
+
15
+ qz --version
16
+ qz auth login
17
+ ```
18
+
19
+ ### Local Install
20
+
21
+ ```bash
22
+ npm install qzhuli-cli
23
+ npx qz --version
24
+ ```
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
+ ## Commands
45
+
46
+ ```bash
47
+ # Authentication
48
+ qz auth login [--method qr-code] # QR code login
49
+ qz auth status # Check local auth status
50
+ qz auth logout # Clear local credentials
51
+
52
+ # Configuration
53
+ qz config # Show current preferences
54
+ qz config --locale en|zh # Update output language
55
+ qz config --debug # Enable debug logging
56
+ qz config --no-debug # Disable debug logging
57
+
58
+ # User
59
+ qz user search <query> # Search user/profile data by query
60
+
61
+ # Friends
62
+ qz friend list # List friends, contacts, classes, and teams
63
+ qz friend profile <uid/nickname/remark>
64
+
65
+ # Relations
66
+ qz relation get <uid> # Get friend relation
67
+ qz relation set <uid> --remark <name> # Update friend remark
68
+ qz relation set <uid> --type <type> # Update relation type: 0 stranger, 1 friend, 2 family, 3 colleague
69
+
70
+ # Conversations
71
+ qz conversation list [--limit <n>] # List conversations, default limit 50
72
+
73
+ # Messages
74
+ qz message send <conversation-id> <target-cid> <content>
75
+ qz message history <conversation-id> [--from <id>] [--direction newer|older] [--limit <n>]
76
+ ```
77
+
78
+ ## Global Options
79
+
80
+ | Option | Description |
81
+ |-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
82
+ | `-v, --version` | Print the CLI version. |
83
+ | `-q, --jq <expr>` | Apply a simple dot-path filter to JSON output, such as `.data.uid` or `.data.links`. |
84
+ | `--dry-run` | Print/prepare requests without executing side effects. It skips HTTP API calls, IM WebSocket actions, credential writes/deletes, and preference writes. |
85
+ | `-h, --help` | Show help. |
86
+
87
+ ## Environments
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
+ ```
181
+
182
+ GitHub Actions detects the tag pattern: plain versions (`v0.1.0`) publish to `latest`, prerelease versions (`v0.1.0-alpha.1`) publish to `test`.