@viceme-ai/cli 0.3.0 → 0.4.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.
Files changed (6) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +14 -12
  3. package/README.zh.md +14 -12
  4. package/checksums.txt +6 -6
  5. package/docs/releasing.md +12 -5
  6. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,21 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.4.0] - 2026-07-20
4
+
5
+ ### Features
6
+
7
+ - add guided human login flow (`b883736`)
8
+
9
+ ## [0.3.1] - 2026-07-20
10
+
11
+ ### Fixes
12
+
13
+ - isolate npm cache and classify failures (`b778aa1`)
14
+
15
+ ### Other Changes
16
+
17
+ - clarify workflow check names (`cf7da33`)
18
+
3
19
  ## [0.3.0] - 2026-07-20
4
20
 
5
21
  ### Features
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/@viceme-ai/cli.svg)](https://www.npmjs.com/package/@viceme-ai/cli)
4
4
  [![Go Version](https://img.shields.io/badge/go-%3E%3D1.23-blue.svg)](https://go.dev/)
5
- [![CLI quality gates](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml)
5
+ [![CLI PR checks](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml)
6
6
 
7
7
  [中文版](./README.zh.md) | [English](./README.md)
8
8
 
@@ -20,7 +20,7 @@ The official command-line client and Agent Skill for publishing external Skills
20
20
  - **Stable publishing** — later releases of the same logical Agent keep the same share URL.
21
21
  - **Multiple source types** — accepts GitHub Skills, pasted Xiaohongshu/RedSkill expressions, archives, and local Skill folders.
22
22
  - **Secure by default** — credentials use the operating-system keychain, public mutations require confirmation, and downloaded binaries are checksum-verified.
23
- - **Machine-stable output** — every data command uses the same JSON success/error envelope without an output-format flag.
23
+ - **Human and Agent login modes** — `viceme auth login` guides a person in the terminal, while Agent split-flows use explicit JSON.
24
24
 
25
25
  ## Installation & Quick Start
26
26
 
@@ -58,16 +58,15 @@ npx --yes @viceme-ai/cli@latest install --region global
58
58
 
59
59
  #### Authenticate and verify
60
60
 
61
- If the installation result says authentication is required, start device login:
61
+ If the installation result says authentication is required, start the guided device login:
62
62
 
63
63
  ```bash
64
- viceme auth login --no-wait
64
+ viceme auth login
65
65
  ```
66
66
 
67
- Open the returned `verification_url`; it normally links directly to the matching prefilled device request. Complete authorization, and then continue with the returned device code:
67
+ The CLI prints the browser URL, waits for authorization, and reports success in the same terminal. Then verify the installation:
68
68
 
69
69
  ```bash
70
- viceme auth login --device-code <device-code>
71
70
  viceme auth status
72
71
  viceme skills doctor
73
72
  ```
@@ -84,12 +83,12 @@ Use the complete bootstrap command from the bundled Skill. The explicit npm regi
84
83
  npx --yes --registry=https://registry.npmjs.org --@viceme-ai:registry=https://registry.npmjs.org --package=@viceme-ai/cli@latest -- viceme install
85
84
  ```
86
85
 
87
- Read `data.authenticated` and `data.next_step` from the result. If authentication is already valid, continue to Step 4.
86
+ Read `data.authenticated` and `data.next_step` from the result. If authentication is already valid, continue to Step 4. If login is required, do not execute the human-oriented `data.next_step` inside the Agent; use the JSON split-flow in Step 2.
88
87
 
89
88
  **Step 2 — Start device login when required**
90
89
 
91
90
  ```bash
92
- viceme auth login --no-wait
91
+ viceme auth login --no-wait --json
93
92
  ```
94
93
 
95
94
  Return the exact `data.verification_url`; the CLI normalizes it to the prefilled `verification_url_complete` browser link when available. Include `data.user_code` only as a fallback if the browser asks for it. Preserve `data.device_code` for the continuation command, then stop the current turn. Do not request, print, or place an access token in the conversation.
@@ -99,7 +98,7 @@ Return the exact `data.verification_url`; the CLI normalizes it to the prefilled
99
98
  After the user confirms browser authorization:
100
99
 
101
100
  ```bash
102
- viceme auth login --device-code <device-code>
101
+ viceme auth login --device-code <device-code> --json
103
102
  ```
104
103
 
105
104
  If authorization is still pending, reuse the same device code before it expires. Do not start a second device flow unless the original one has expired.
@@ -147,6 +146,8 @@ viceme profile remove company
147
146
 
148
147
  `VICEME_CLI_CONFIG_DIR` can override the config root. Local API development still uses the process-only `VICEME_API_BASE_URL`; it is never persisted in a profile.
149
148
 
149
+ Update checks query the npm registry directly and store only the last successful version result in `~/.viceme-cli/update-state.json`. A result is used as a fallback for at most 24 hours when the registry is temporarily unavailable. npm operations launched by `viceme install` or `viceme update` use the isolated `~/.viceme-cli/npm-cache`, so a broken user-level `~/.npm` cache does not block the CLI. Both files are non-secret and can be deleted safely; credentials never enter either cache.
150
+
150
151
  ## Agent Skills
151
152
 
152
153
  The current release deliberately ships one platform-level Agent Skill:
@@ -173,8 +174,9 @@ viceme skills doctor
173
174
  | Command | Purpose |
174
175
  |---|---|
175
176
  | `viceme auth status` | Show whether the current profile is authenticated |
176
- | `viceme auth login --no-wait` | Start device authorization and return immediately |
177
- | `viceme auth login --device-code <code>` | Complete a previously started authorization |
177
+ | `viceme auth login` | Guide a human through browser authorization and wait for completion |
178
+ | `viceme auth login --no-wait --json` | Start an Agent split-flow and return structured device authorization |
179
+ | `viceme auth login --device-code <code> --json` | Complete an Agent split-flow in a later turn |
178
180
  | `viceme auth logout` | Revoke and remove the current profile credential |
179
181
 
180
182
  Tokens are stored only in the operating-system keychain. There is no plaintext token fallback, and successful login output never contains the access or refresh token.
@@ -230,7 +232,7 @@ Use `viceme <command> --help` for the exact flags. The release-checked machine-r
230
232
 
231
233
  ## JSON Output Contract
232
234
 
233
- All data commands emit a stable JSON envelope by default.
235
+ Automation-oriented data commands emit a stable JSON envelope by default. Interactive `viceme auth login` is the deliberate human-facing exception; AI Agents and scripts must use `--no-wait --json`, then continue with `--device-code <code> --json` in a later turn.
234
236
 
235
237
  Success is written to **stdout** with exit code `0`:
236
238
 
package/README.zh.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/@viceme-ai/cli.svg)](https://www.npmjs.com/package/@viceme-ai/cli)
4
4
  [![Go Version](https://img.shields.io/badge/go-%3E%3D1.23-blue.svg)](https://go.dev/)
5
- [![CLI quality gates](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml)
5
+ [![CLI PR checks](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml/badge.svg)](https://github.com/ViceMe-AI/cli/actions/workflows/ci.yml)
6
6
 
7
7
  [中文版](./README.zh.md) | [English](./README.md)
8
8
 
@@ -20,7 +20,7 @@ Viceme 官方命令行客户端与 Agent Skill，用于将外部 Skill 发布为
20
20
  - **稳定发布** — 同一个逻辑 Agent 后续发布新版本时继续使用同一个分享链接。
21
21
  - **支持多种来源** — 支持 GitHub Skill、小红书或 RedSkill 复制口令、压缩包和本地 Skill 目录。
22
22
  - **默认安全** — 凭证保存在操作系统密钥链中，公开变更需要确认，下载的二进制文件必须通过校验和验证。
23
- - **机器稳定输出** — 所有数据命令统一使用 JSON 成功或错误信封，不需要输出格式参数。
23
+ - **人类与 Agent 双登录模式** — `viceme auth login` 在终端中引导用户，Agent 跨回合流程则显式使用 JSON。
24
24
 
25
25
  ## 安装与快速开始
26
26
 
@@ -58,16 +58,15 @@ npx --yes @viceme-ai/cli@latest install --region global
58
58
 
59
59
  #### 认证并验证
60
60
 
61
- 如果安装结果提示需要认证，启动设备登录：
61
+ 如果安装结果提示需要认证，启动引导式设备登录：
62
62
 
63
63
  ```bash
64
- viceme auth login --no-wait
64
+ viceme auth login
65
65
  ```
66
66
 
67
- 打开返回的 `verification_url`；它通常会直接进入已预填对应设备码的授权请求。完成授权，然后使用返回的 device code 继续：
67
+ CLI 会显示浏览器登录链接、等待授权，并在同一个终端中报告成功。然后验证安装：
68
68
 
69
69
  ```bash
70
- viceme auth login --device-code <device-code>
71
70
  viceme auth status
72
71
  viceme skills doctor
73
72
  ```
@@ -84,12 +83,12 @@ viceme skills doctor
84
83
  npx --yes --registry=https://registry.npmjs.org --@viceme-ai:registry=https://registry.npmjs.org --package=@viceme-ai/cli@latest -- viceme install
85
84
  ```
86
85
 
87
- 读取结果中的 `data.authenticated` 和 `data.next_step`。如果认证已经有效，直接进入第 4 步。
86
+ 读取结果中的 `data.authenticated` 和 `data.next_step`。如果认证已经有效，直接进入第 4 步。如果需要登录，Agent 不要执行面向人类的 `data.next_step`，而应使用第 2 步的 JSON 跨回合流程。
88
87
 
89
88
  **第 2 步 — 需要时启动设备登录**
90
89
 
91
90
  ```bash
92
- viceme auth login --no-wait
91
+ viceme auth login --no-wait --json
93
92
  ```
94
93
 
95
94
  向用户返回准确的 `data.verification_url`；存在 `verification_url_complete` 时，CLI 会把这个已预填设备码的浏览器直达链接规范化为 `verification_url`。只有浏览器要求输入时，才把 `data.user_code` 作为备用信息提供。保留 `data.device_code` 供后续命令使用，然后结束当前回合。不要在对话中索取、打印或传递访问令牌。
@@ -99,7 +98,7 @@ viceme auth login --no-wait
99
98
  用户确认已在浏览器完成授权后：
100
99
 
101
100
  ```bash
102
- viceme auth login --device-code <device-code>
101
+ viceme auth login --device-code <device-code> --json
103
102
  ```
104
103
 
105
104
  如果授权仍处于等待状态，应在过期前继续使用同一个 device code。只有原流程已过期时才能重新发起设备登录。
@@ -147,6 +146,8 @@ viceme profile remove company
147
146
 
148
147
  可以用 `VICEME_CLI_CONFIG_DIR` 覆盖配置根目录。本地 API 联调仍使用进程环境变量 `VICEME_API_BASE_URL`，不会写入 Profile。
149
148
 
149
+ 更新检查直接请求 npm registry，并且只把最近一次成功查询到的版本写入 `~/.viceme-cli/update-state.json`；registry 暂时不可用时，该结果最多回退使用 24 小时。`viceme install` 和 `viceme update` 启动的 npm 操作统一使用隔离的 `~/.viceme-cli/npm-cache`，不会因为用户级 `~/.npm` 缓存损坏而失败。这两个位置都不包含秘密信息，可以安全删除；凭证不会进入任何更新缓存。
150
+
150
151
  ## Agent Skills
151
152
 
152
153
  当前版本有意只提供一个平台级 Agent Skill：
@@ -173,8 +174,9 @@ viceme skills doctor
173
174
  | 命令 | 用途 |
174
175
  |---|---|
175
176
  | `viceme auth status` | 查看当前 Profile 是否已认证 |
176
- | `viceme auth login --no-wait` | 启动设备授权并立即返回 |
177
- | `viceme auth login --device-code <code>` | 完成之前启动的设备授权 |
177
+ | `viceme auth login` | 引导人类用户完成浏览器授权并等待结果 |
178
+ | `viceme auth login --no-wait --json` | 启动 Agent 跨回合流程并返回结构化设备授权信息 |
179
+ | `viceme auth login --device-code <code> --json` | 在后续回合完成 Agent 登录流程 |
178
180
  | `viceme auth logout` | 撤销并删除当前 Profile 的凭证 |
179
181
 
180
182
  令牌只保存在操作系统密钥链中，不会回退到明文存储；登录成功的输出也不会包含访问令牌或刷新令牌。
@@ -230,7 +232,7 @@ viceme skill publish --file ./poster-skill-v2.zip \
230
232
 
231
233
  ## JSON 输出契约
232
234
 
233
- 所有数据命令默认输出稳定的 JSON 信封。
235
+ 面向自动化的数据命令默认输出稳定的 JSON 信封。交互式 `viceme auth login` 是特意保留的人类友好例外；AI Agent 和脚本必须使用 `--no-wait --json`，并在后续回合使用 `--device-code <code> --json` 继续。
234
236
 
235
237
  成功结果写入 **stdout**，退出码为 `0`：
236
238
 
package/checksums.txt CHANGED
@@ -1,6 +1,6 @@
1
- 8be3c86b43e3121fde111bc195830bfb055d4a83f3aeb2516d6c232d0668831b viceme_0.3.0_darwin_amd64
2
- bb4ee6635f2a42820296827a07ccc917b470e3941e2a002ebf78eec5ad02a4e9 viceme_0.3.0_darwin_arm64
3
- ffcc623f6d14e9145b91a294c3903a121a54b23a0cd1b585f9a37cd16a50bbcf viceme_0.3.0_linux_amd64
4
- e8635cee232fa604493548e81db75664a7a0315e829bef1d357341ee377e17d3 viceme_0.3.0_linux_arm64
5
- 9e97ccd4834bd458d8334bb0ffe7cc613b1b83fa47d24ccca89a98d34316fc2a viceme_0.3.0_windows_amd64.exe
6
- 4953ef1bd354ac5885103672df9bc125c7e4410a11da0352745b687e09049e97 viceme_0.3.0_windows_arm64.exe
1
+ bd2fde9e1091a95f3d1eba69cc94177bcd7aaaf2be7aa03616a9d150bd8ba855 viceme_0.4.0_darwin_amd64
2
+ 47764d173607b67f39d87be333afffc2ede58f9de952eadd79ce1a056f7b25a8 viceme_0.4.0_darwin_arm64
3
+ 3b5e9c4b47298a442d31b4540f5b2e41af6e80b0ebb25cb09f7e93acdd998734 viceme_0.4.0_linux_amd64
4
+ 035e944ad7003045c9ae1668d8aead6a38f4e87dfb5b7daebe107ee08fd259db viceme_0.4.0_linux_arm64
5
+ 0c7d8cc7bbf406168cd04072b1f059a3d3851b73c64a1770f3d47c062db9537e viceme_0.4.0_windows_amd64.exe
6
+ 716aedae76fd167ecea536a608c2a8a320142f41553171230ccaf766603eaff1 viceme_0.4.0_windows_arm64.exe
package/docs/releasing.md CHANGED
@@ -9,7 +9,7 @@ files, create tags, write changelog entries, or run npm commands locally.
9
9
  1. Feature and fix PRs can merge into `dev` without starting release
10
10
  preparation.
11
11
  2. A maintainer explicitly opens or marks ready a repository-owned `dev` to
12
- `main` PR. That release intent starts `Prepare Release PR`.
12
+ `main` PR. That release intent starts `CLI release preparation`.
13
13
  3. `npm/scripts/prepare-release.mjs` finds the newest reachable stable tag and
14
14
  reads all unreleased non-merge commits.
15
15
  4. Conventional Commits select the next version:
@@ -26,7 +26,7 @@ files, create tags, write changelog entries, or run npm commands locally.
26
26
  checks, and is updated to `chore(release): vX.Y.Z` with exact run and commit
27
27
  evidence. No internal preparation PR is created.
28
28
  8. A maintainer reviews and merges that same Release PR.
29
- 9. `Release CLI and npm launcher` tags the exact reviewed `dev` head, reruns
29
+ 9. `CLI release publication` tags the exact reviewed `dev` head, reruns
30
30
  the quality gates, builds six platform binaries and six checksums, creates
31
31
  the GitHub Release, bundles those exact checksums into the npm launcher,
32
32
  publishes it, and then sends an
@@ -43,8 +43,9 @@ are not required. Configure:
43
43
  - repository secret `RELEASE_APP_PRIVATE_KEY`: the complete generated PEM key.
44
44
 
45
45
  Protect `dev` with an active branch ruleset that retains the normal pull request,
46
- one approving review, four CLI quality checks, deletion protection, and force
47
- push protection. Add `ViceMe CLI Release Bot` and the organization-admin role to
46
+ one approving review, the `PR quality` check, all three `PR npm installer
47
+ (<runner>)` checks, deletion protection, and force push protection. Add `ViceMe
48
+ CLI Release Bot` and the organization-admin role to
48
49
  the bypass list with `Always allow`; the latter preserves the legacy rule's
49
50
  existing `enforce_admins: false` behavior. Do not leave the legacy
50
51
  branch-protection rule active beside the ruleset because it cannot recognize the
@@ -56,12 +57,18 @@ when the job finishes. The workflow still stages an explicit allowlist of
56
57
  generated files and validates the complete release before pushing. No
57
58
  maintainer PAT or Deploy Key is used.
58
59
 
59
- The general CLI quality workflow runs for pull requests, not branch pushes. A
60
+ The general `CLI PR checks` workflow runs for pull requests, not branch pushes. A
60
61
  Release App push synchronizes the already-open `dev` to `main` PR, producing one
61
62
  set of required checks for the exact prepared commit without duplicate generic
62
63
  push and pull-request runs. The synchronize event may run release preparation a
63
64
  second time; that run is intentionally idempotent and produces no new commit.
64
65
 
66
+ Protect `main` with the same four PR checks plus `Release candidate
67
+ preparation`. The checks from `CLI release publication` are deliberately not
68
+ required for merging: that workflow starts only after the release PR has been
69
+ merged and performs the tag, binary, GitHub Release, npm, and notification
70
+ steps.
71
+
65
72
  Configure npm trusted publishing for:
66
73
 
67
74
  - npm package: `@viceme-ai/cli`;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@viceme-ai/cli",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "description": "Install and run the Viceme CLI and Viceme Agent Skill",
5
5
  "type": "module",
6
6
  "bin": {