@nalvietnam/avatar-cli

AI harness CLI for NAL Vietnam engineering. Kiến trúc v3 (multi-repo workspace + pack tarball qua Supabase) mô tả trong docs/avatar-v3-multi-repo-architecture-and-pack-distribution.html.

v3 — Trạng thái hiện tại

avatar-cli v3 mang 3 thay đổi lớn:

• Pack distribution qua Supabase tarball — pack tải dưới dạng tarball từ edge function get-pack (signed URL, xác thực id_token Google NAL), giải nén vào .claude/pack/. Toàn vẹn kiểm bằng SHA-256 soft-verify: CLI so digest tarball tải về với digest backend trả — backend chưa trả digest thì CLI cảnh báo rồi bỏ qua verify, pack vẫn cài (không phải chữ ký số, không chặn cài). Không còn git submodule.
• Multi-repo workspace — 1 workspace chứa nhiều repo code trong src/<name> (thêm bằng avatar add repo).
• Google SSO login — avatar login mở cho mọi Google account (để telemetry ghi nhận được). Tải pack (avatar sync) vẫn chỉ workspace NAL (nal.vn / nal-software.com) — chặn ở server get-pack, không phải ở CLI.

Lịch sử: v2.0 từng đổi tên avatar feature → avatar tools và state file avatar-features.json → avatar-tools.json (đi cùng team-ai-pack v1.0 folder tools/). Đây là history; mô hình hiện tại dùng tarball + login như trên.

Cài đặt

# Local development (clone repo)
cd avatar-cli
npm install
npm run build
npm link              # makes `avatar` available globally pointing at this checkout

# Sau này khi đã publish:
npm install -g @nalvietnam/avatar-cli

Sử dụng

avatar --help                    # liệt kê toàn bộ 20 commands
avatar --version                 # ví dụ output — nguồn sự thật là package.json

# Lần đầu — đăng nhập Google SSO (mọi account; sync pack cần workspace NAL)
avatar login

# Khởi tạo workspace Avatar (tạo workspace + tải pack tarball)
avatar init                              # interactive wizard
avatar init my-workspace --yes           # auto-confirm tất cả prompt
avatar init --pack-version v1.0.2        # pin pack vào tag cụ thể

# Thêm repo code vào workspace (multi-repo)
avatar add repo                          # clone repo vào src/<name>
avatar list repo                         # liệt kê repo trong workspace

# Snapshot
avatar status

# Chẩn đoán
avatar doctor
avatar doctor --fix

Trạng thái implement

20 commands (đăng ký trong src/index.ts):

| Command | Trạng thái | |---|---| | login / logout | ✅ implement thật (Google OAuth Device Flow) | | init | ✅ implement thật (tạo workspace + tải pack) | | sync | ✅ implement thật (tải pack tarball Supabase; tự prune orphan tool hooks khi pack bỏ tool) | | status | ✅ implement thật | | doctor | ✅ implement thật | | tools (enable/disable/list/add/remove) | ✅ implement thật | | add / list / remove (repo) | ✅ implement thật (multi-repo workspace) | | pack | ✅ implement thật (status + version check) | | ai | ✅ implement thật (setup AI provider) | | comm-connect | ✅ implement thật | | gitnexus | ✅ implement thật (setup + analyze) | | update | ✅ implement thật (self-update CLI qua npm i -g, hỗ trợ dist-tag) | | uninstall | ✅ implement thật | | print-id-token | ✅ implement thật | | scan | ⏳ stub (5 scanner cũng stub) | | review | ⏳ stub | | restore | ⏳ stub | | debate | ⏳ stub | | mcp-run (hidden) | ⏳ stub |

Cấu trúc thư mục

avatar-cli/
├── bin/avatar.js               # Shebang entry, loads dist/index.js
├── src/
│   ├── index.ts                # Bootstrap commander + register 20 commands
│   ├── commands/               # 1 file per CLI subcommand (login, init, sync, add-repo, ...)
│   ├── scanners/               # 5 project scanners (stub)
│   ├── lib/                    # Utilities: oauth, git, supabase-pack-downloader, symlink farm, ...
│   ├── hooks/                  # post-merge + pre-push shell templates
│   ├── templates/              # CLAUDE.md.tpl, settings.json.tpl, gitignore, project knowledge
│   └── types/                  # Zod schemas
├── test/                       # vitest suites
├── package.json
├── tsconfig.json
├── tsup.config.ts
├── biome.json
└── vitest.config.ts

Google OAuth setup

Client Secret KHÔNG nằm trong CLI. Từ v3.16.0, mọi call OAuth (device code / poll / refresh / revoke) đi qua Edge Function auth-device trên avatar-supabase; secret lưu ở Supabase secrets NAL_GOOGLE_CLIENT_SECRET, CLI không bao giờ thấy nó.

Thứ có trong src/lib/google-oauth-device-flow.ts là Client ID — đây là public identifier, không phải secret. CLI giữ nó để verify claim aud của id_token.

OAuth Client tạo trong Google Cloud Console:

• Project: avatar-cli
• Application type: TV and Limited Input devices
• Hosted domain: nal.vn và nal-software.com (2 Google Workspace riêng biệt, đều được chấp nhận — xem ALLOWED_HOSTED_DOMAINS)

Rotate secret = việc server-side, KHÔNG cần release CLI:

# Console → APIs & Services → Credentials → OAuth client → Reset Secret
supabase secrets set NAL_GOOGLE_CLIENT_SECRET=<secret-mới>

Nếu đổi hẳn OAuth client trên Console: cập nhật Client ID trong src/lib/google-oauth-device-flow.ts và cả 2 secrets NAL_GOOGLE_CLIENT_ID / NAL_GOOGLE_CLIENT_SECRET phía Supabase.

Dev workflow

npm run dev                      # tsup --watch
npm run test                     # vitest
npm run lint                     # biome check
npm run build                    # production bundle vào dist/

Liên quan

• Kiến trúc v3 (multi-repo + pack distribution): docs/avatar-v3-multi-repo-architecture-and-pack-distribution.html
• Tham chiếu lệnh: docs/avatar-cli-commands-reference.html
• Knowledge pack: ../team-ai-pack/ — tải dưới dạng tarball từ Supabase edge function get-pack (signed URL, xác thực id_token Google NAL, SHA-256 soft-verify) khi avatar init / avatar sync, giải nén vào .claude/pack/