zhan-cli

zhan-cli 是栈间 Zhanjian 的命令行工具仓库。

当前登录方式已经切换为设备码登录：

1. 在终端运行 zhan login
2. CLI 输出验证地址和短码
3. 浏览器打开确认页并完成授权
4. CLI 自动轮询，成功后把 token 写入本地配置

安装与开发

pnpm install
pnpm build

# 直接运行 CLI 源码
pnpm cli -- --help
pnpm cli -- login
pnpm cli -- whoami

常用命令

# 设备码登录
zhan login

# 直接写入 token（CI / 自动化）
zhan login --token <API_TOKEN>

# 查看当前身份
zhan whoami

# 退出登录
zhan logout

本地配置

CLI 会把认证信息保存在本地配置目录中，典型位置如下：

• macOS: ~/Library/Preferences/zhan-nodejs/config.json
• Linux: ~/.config/zhan-nodejs/config.json

配置内容通常包括：

{
  "token": "jwt_xxx",
  "apiUrl": "https://api.zhanjian.space",
  "username": "alice"
}

设备码登录说明

• CLI 通过 POST /auth/device/start 发起登录
• 浏览器确认页通过已登录的 Web 会话调用 POST /auth/device/approve
• CLI 通过 POST /auth/device/poll 轮询拿到最终 JWT
• 设备码默认短时有效，成功消费一次后即失效

发布前检查

pnpm typecheck
pnpm --filter @zhanjian/cli build

# 查看帮助输出
pnpm cli -- --help
pnpm cli -- login --help

如果你在生产环境使用设备码登录，还需要保证：

• Web 端已正确设置 WEB_BASE_URL
• Worker 已部署设备码接口
• CLI 默认 apiUrl 指向可访问的生产 API

zhan-cli

Public monorepo for the open-source Zhanjian CLI ecosystem.

This repository contains:

• packages/cli — @zhanjian/cli, the official command-line client
• packages/shared — @zhanjian/shared, shared types and utilities

Private backend services (worker, web, deployment scripts, and secrets) are intentionally excluded.

Install

Install the CLI globally from npm:

npm i -g @zhanjian/cli

Or run it directly with pnpm in this monorepo:

pnpm install
pnpm --filter @zhanjian/cli build
pnpm --filter @zhanjian/cli start -- --help

Quick Start

# 1) Set API endpoint (optional if default is correct)
export zhan_API_URL="https://api.zhanjian.space"

# 2) Login
zhan login

# 3) Check current user
zhan whoami

# 4) Browse feed and view a post
zhan feed --limit 5
zhan view <postId>

Development

pnpm install
pnpm typecheck
pnpm lint
pnpm test

开发环境调试

• 跑编译产物（monorepo 根目录）：pnpm --filter @zhanjian/cli build 后执行 pnpm --filter @zhanjian/cli start -- <子命令>，例如 pnpm --filter @zhanjian/cli start -- whoami。
• 直接跑源码（改代码即生效，无需 build）：在 packages/cli 下执行 pnpm exec tsx src/index.ts -- <子命令>，例如 pnpm exec tsx src/index.ts -- whoami。
• 当全局命令用：在根目录执行 pnpm --filter @zhanjian/cli build，进入 packages/cli 执行 pnpm link --global，之后可直接在终端使用 zhan。改代码后需重新 build。
• 调试时如需指向本地 API，可设置环境变量 zhan_API_URL。

Packages

@zhanjian/cli

• Path: packages/cli
• Entry command: zhan
• Default API URL: https://api.zhanjian.space (overridable by zhan_API_URL)

@zhanjian/shared

• Path: packages/shared
• Exports: shared domain types, markdown/template helpers, privacy checks, CVS utilities

Platform

Hosted platform: https://zhanjian.space

Release (CI 自动发版)

推送版本 tag 到仓库后，GitHub Actions 会自动构建并发布到 npm：

1. 在仓库配置 NPM_TOKEN：GitHub 仓库 → Settings → Secrets and variables → Actions → New repository secret，名称为 NPM_TOKEN，值为 npm 的 Access Token（建议选 Automation 类型）。

2. 发版步骤：

   • 本地改好代码并提交；
   • 打 tag 并推送，例如：git tag v1.0.0 && git push origin v1.0.0
   • CI 会用 tag 中的版本号（如 1.0.0）更新 @zhanjian/shared 与 @zhanjian/cli 的 package.json，然后依次 build、publish 到 npm。

仅当推送的 tag 匹配 v*（如 v1.0.0、v0.0.2）时才会触发发布。

Contributing

1. Fork and create a feature branch
2. Add or update tests with your changes
3. Run pnpm typecheck && pnpm lint && pnpm test
4. Open a pull request with a clear description and test evidence