@nalvietnam/avatar-cli 3.3.1 → 3.5.0-beta.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/README.md +48 -48
  2. package/dist/index.js +64 -62
  3. package/dist/index.js.map +1 -1
  4. package/dist/templates/CLAUDE.md.tpl +6 -0
  5. package/package.json +1 -1
  6. package/src/templates/CLAUDE.md.tpl +6 -0
package/README.md CHANGED
@@ -2,27 +2,20 @@
2
2
 
3
3
  AI harness CLI for NAL Vietnam engineering. Implements the Avatar architecture defined in [`avatar-cli-implementation_4.html`](../init-doc/avatar-cli-implementation_4.html).
4
4
 
5
- ## ⚠️ v2.0 BREAKING CHANGE — Terminology rename
5
+ ## v3 — Trạng thái hiện tại
6
6
 
7
- v2.0 đổi tên command + state file:
7
+ avatar-cli v3 mang 3 thay đổi lớn:
8
8
 
9
- | Cũ (v1.x) | Mới (v2.0) |
10
- |---|---|
11
- | `avatar feature enable <name>` | `avatar tools enable <name>` |
12
- | `avatar feature disable <name>` | `avatar tools disable <name>` |
13
- | `avatar feature list` | `avatar tools list` |
14
- | `avatar feature add` | `avatar tools add` |
15
- | `avatar feature remove` | `avatar tools remove` |
16
- | `.claude/avatar-features.json` (state file) | `.claude/avatar-tools.json` |
17
-
18
- Cần dùng cùng **team-ai-pack v1.0+** (folder `tools/` thay vì `features/`). Hard
19
- break — không auto-migrate state cũ. User phải `avatar tools enable <name>` lại
20
- cho từng tool muốn giữ (chỉ vài tool nên rất nhanh). File `avatar-features.json`
21
- cũ có thể xóa tay.
22
-
23
- Vì sao đổi: gộp "feature toggle" (NAL custom) + "tools stub" (system deps, MCP
24
- roadmap) thành 1 concept thống nhất.
9
+ - **Pack distribution qua Supabase tarball** — pack tải dưới dạng tarball ký số từ
10
+ edge function `get-pack` (signed URL, xác thực `id_token` Google NAL), giải nén
11
+ vào `.claude/pack/`. Không còn git submodule.
12
+ - **Multi-repo workspace** — 1 workspace chứa nhiều repo code trong `src/<name>`
13
+ (thêm bằng `avatar add repo`).
14
+ - **Google SSO login** — `avatar login` (workspace `@nal.vn` / `nal-software.com`).
25
15
 
16
+ > Lịch sử: v2.0 từng đổi tên `avatar feature` → `avatar tools` và state file
17
+ > `avatar-features.json` → `avatar-tools.json` (đi cùng team-ai-pack v1.0 folder
18
+ > `tools/`). Đây là history; mô hình hiện tại dùng tarball + login như trên.
26
19
 
27
20
  ## Cài đặt
28
21
 
@@ -40,18 +33,20 @@ npm install -g @nalvietnam/avatar-cli
40
33
  ## Sử dụng
41
34
 
42
35
  ```bash
43
- avatar --help # liệt kê toàn bộ 13 commands
44
- avatar --version # 1.0.0
36
+ avatar --help # liệt kê toàn bộ 16 commands
37
+ avatar --version # 3.4.1
45
38
 
46
- # Lần đầu — đăng nhập Google SSO (workspace @nal.vn)
39
+ # Lần đầu — đăng nhập Google SSO (workspace @nal.vn / nal-software.com)
47
40
  avatar login
48
41
 
49
- # Khởi tạo Avatar trong dự án
50
- avatar init # interactive wizard
51
- avatar init --mode=internal # NAL nội bộ — files commit cùng code
52
- avatar init --mode=client \
53
- --client-repo=git@github.com:org/client-repo.git \
54
- --workspace-name=avatar-client-workspace
42
+ # Khởi tạo workspace Avatar (tạo workspace + tải pack tarball)
43
+ avatar init # interactive wizard
44
+ avatar init my-workspace --yes # auto-confirm tất cả prompt
45
+ avatar init --pack-version v1.0.2 # pin pack vào tag cụ thể
46
+
47
+ # Thêm repo code vào workspace (multi-repo)
48
+ avatar add repo # clone repo vào src/<name>
49
+ avatar list repo # liệt kê repo trong workspace
55
50
 
56
51
  # Snapshot
57
52
  avatar status
@@ -63,20 +58,25 @@ avatar doctor --fix
63
58
 
64
59
  ## Trạng thái implement
65
60
 
66
- | Command | Trạng thái | Milestone |
67
- |---|---|---|
68
- | `login` | ✅ implement thật (Google OAuth Device Flow) | 03 |
69
- | `init` (3 mode) | ✅ implement thật | 05 + 07 |
70
- | `status` | ✅ implement thật | 08 |
71
- | `doctor` | ✅ implement thật | 08 |
72
- | `sync` | ⏳ stub | 08 |
73
- | `scan` | ⏳ stub (5 scanner cũng stub) | 06 |
74
- | `review` | ⏳ stub | 08 |
75
- | `restore` | ⏳ stub | 08 |
76
- | `commit` | ⏳ stub | 07 |
77
- | `tools list/install/remove` | ⏳ stub | 09 |
78
- | `secrets list/set/get/rm/check` | ⏳ stub | 09 |
79
- | `mcp-run` (hidden) | ⏳ stub | 09 |
61
+ 16 commands (đăng ký trong `src/index.ts`):
62
+
63
+ | Command | Trạng thái |
64
+ |---|---|
65
+ | `login` / `logout` | ✅ implement thật (Google OAuth Device Flow) |
66
+ | `init` | ✅ implement thật (tạo workspace + tải pack) |
67
+ | `sync` | ✅ implement thật (tải pack tarball Supabase) |
68
+ | `status` | ✅ implement thật |
69
+ | `doctor` | ✅ implement thật |
70
+ | `tools` (enable/disable/list/add/remove) | ✅ implement thật |
71
+ | `add` / `list` / `remove` (repo) | ✅ implement thật (multi-repo workspace) |
72
+ | `pack` | ✅ implement thật (status + version check) |
73
+ | `ai` | ✅ implement thật (setup AI provider) |
74
+ | `gitnexus` | ✅ implement thật (setup + analyze) |
75
+ | `uninstall` | ✅ implement thật |
76
+ | `scan` | ⏳ stub (5 scanner cũng stub) |
77
+ | `review` | ⏳ stub |
78
+ | `restore` | ⏳ stub |
79
+ | `mcp-run` (hidden) | ⏳ stub |
80
80
 
81
81
  ## Cấu trúc thư mục
82
82
 
@@ -84,14 +84,14 @@ avatar doctor --fix
84
84
  avatar-cli/
85
85
  ├── bin/avatar.js # Shebang entry, loads dist/index.js
86
86
  ├── src/
87
- │ ├── index.ts # Bootstrap commander + register 13 commands
88
- │ ├── commands/ # 1 file per CLI subcommand
87
+ │ ├── index.ts # Bootstrap commander + register 16 commands
88
+ │ ├── commands/ # 1 file per CLI subcommand (login, init, sync, add-repo, ...)
89
89
  │ ├── scanners/ # 5 project scanners (stub)
90
- │ ├── lib/ # Utilities: oauth, git, fs, templates, ...
90
+ │ ├── lib/ # Utilities: oauth, git, supabase-pack-downloader, symlink farm, ...
91
91
  │ ├── hooks/ # post-merge + pre-push shell templates
92
- │ ├── templates/ # CLAUDE.md, settings.json, project knowledge
92
+ │ ├── templates/ # CLAUDE.md.tpl, settings.json.tpl, gitignore, project knowledge
93
93
  │ └── types/ # Zod schemas
94
- ├── test/ # vitest suites (TBD)
94
+ ├── test/ # vitest suites
95
95
  ├── package.json
96
96
  ├── tsconfig.json
97
97
  ├── tsup.config.ts
@@ -106,7 +106,7 @@ Client ID và Client Secret được hardcode trong `src/lib/google-oauth-device
106
106
  OAuth Client tạo trong Google Cloud Console:
107
107
  - Project: `avatar-cli`
108
108
  - Application type: **TV and Limited Input devices**
109
- - Hosted domain: `nal.vn`
109
+ - 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`)
110
110
 
111
111
  Rotate secret: Console → APIs & Services → Credentials → OAuth client → Reset Secret → cập nhật `GOOGLE_CLIENT_SECRET` trong source.
112
112
 
@@ -123,4 +123,4 @@ npm run build # production bundle vào dist/
123
123
 
124
124
  - Blueprint kiến trúc: [`../init-doc/avatar-blueprint-v1_10.html`](../init-doc/avatar-blueprint-v1_10.html)
125
125
  - Implementation spec: [`../init-doc/avatar-cli-implementation_4.html`](../init-doc/avatar-cli-implementation_4.html)
126
- - Knowledge pack: [`../team-ai-pack/`](../team-ai-pack/) (sẽ là `github.com:LukeNALS/team-ai-pack.git` submodule khi `avatar init`)
126
+ - Knowledge pack: [`../team-ai-pack/`](../team-ai-pack/) — tải dưới dạng tarball ký số từ Supabase edge function `get-pack` (signed URL, xác thực `id_token` Google NAL) khi `avatar init` / `avatar sync`, giải nén vào `.claude/pack/`