thanhnvandClaude Opus 4.8
ff4e9d5a53
Answers the 3 adoption questions (Plan-21 follow-up):
1) LEVEL SELECTION (4 packaging levels, packaging/levels.json):
- install.sh --level core|devkit; platform refused (preview service),
enterprise refused (future). Level recorded in .casan-level.
- casan init --level 1..4: L1=gate+Plan-20 hooks only; L2=+CI+domain-pack;
L3=L2 base+preview note; L4=refused. New `casan level show|set`.
- levels.json core now includes adapters/ + schemas/ + install scripts.
2) EXISTING SHELLS (agents/skills): init MERGES Plan-20 hooks into an existing
.claude/settings.json and .codex/{hooks.json,config.toml} idempotently
instead of clobbering — preserves the project's own hooks/agents/skills and
unrelated keys. Re-running never duplicates the CASAN hook.
3) NO RE-INDEX / NO SHELL REWRITE: init only adds config; it does not parse or
index code and does not rewrite the project shell.
Safety fixes after a test accidentally ran init in the real repo:
- launcher shim now SELF-LOCATES its install from its own path (no ambient
CASAN_HOME cross-talk).
- casan init REFUSES to adopt a CASAN source hub into itself (--force to
override), so the Plan-20 hooks can't block the developing agent.
- test always runs init inside throwaway dirs; +source-hub guard test.
hybrid-install-tests.sh: 41/41 PASS.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
130 lines
5.8 KiB
Markdown
130 lines
5.8 KiB
Markdown
# Cài CASAN kiểu tool (global install + `casan init`) — Plan-21
|
|
|
|
Mô hình **hybrid**: cài harness **một lần** vào máy (`$CASAN_HOME`), sau đó mỗi
|
|
dự án chỉ chạy `casan init` để ghi **config riêng của dự án** — harness KHÔNG bị
|
|
copy vào từng repo. Giống trải nghiệm codegraph.
|
|
|
|
## 1. Cài đặt (một lần cho mỗi máy)
|
|
|
|
```bash
|
|
# macOS / Linux
|
|
curl -fsSL https://<your-gitea>/admin/casan5/raw/branch/main/install.sh | sh
|
|
|
|
# Windows (PowerShell)
|
|
irm https://<your-gitea>/admin/casan5/raw/branch/main/install.ps1 | iex
|
|
```
|
|
|
|
Hoặc từ một checkout CASAN có sẵn:
|
|
|
|
```bash
|
|
sh install.sh # macOS/Linux
|
|
pwsh .\install.ps1 # Windows
|
|
```
|
|
|
|
Chọn **level đóng gói** để cài (theo `packaging/levels.json`):
|
|
|
|
```bash
|
|
sh install.sh --level core # L1: harness + gates + CLI (casan run/gate/verify)
|
|
sh install.sh --level devkit # L2 (mặc định): + adoption tooling (casan init, CI, domain-pack)
|
|
sh install.sh --level platform # L3 preview: từ chối — là service, deploy riêng
|
|
sh install.sh --level enterprise# L4 future: từ chối (chưa ship)
|
|
```
|
|
|
|
Levels là cumulative (devkit ⊃ core). `casan init` là tính năng của **L2 (devkit)**;
|
|
cài `--level core` sẽ không có `casan init` (báo rõ ràng).
|
|
|
|
Installer sẽ:
|
|
|
|
- Copy harness vào `$CASAN_HOME/versions/<version>` (mặc định `~/.casan`,
|
|
Windows: `%LOCALAPPDATA%\casan`) và trỏ `current` vào version đó.
|
|
- Ghi **hash toàn vẹn** của gate-code (`.harness-hash`) — mỏ neo cho pin+verify.
|
|
- Ghi level đã cài vào `.casan-level`.
|
|
- Tạo launcher `casan` (tự định vị install của chính nó) và đưa lên PATH
|
|
(`~/.local/bin` hoặc `$CASAN_HOME/bin`).
|
|
|
|
> Windows cần **Git for Windows (Git Bash)** để *chạy* harness (xem
|
|
> [CASAN_AGENTIC_CLIENTS_WINDOWS.md](CASAN_AGENTIC_CLIENTS_WINDOWS.md)) — không
|
|
> cần WSL2. Cả hai OS cần `python3`.
|
|
|
|
Biến môi trường hữu ích: `CASAN_HOME` (đổi nơi cài), `CASAN_SRC` (cài từ checkout
|
|
cục bộ), `CASAN_DIST_URL` (tải tarball), `CASAN_NO_PATH_LINK=1` (không tự thêm PATH).
|
|
|
|
## 2. Adopt vào một dự án bất kỳ
|
|
|
|
```bash
|
|
cd <dự-án-của-bạn>
|
|
casan init # project id lấy theo tên thư mục, level=devkit
|
|
# hoặc chọn level áp dụng cho project:
|
|
casan init --level 1 --project my-app # L1: chỉ gate + hook Plan-20
|
|
casan init --level 2 --project my-app # L2 (mặc định): + CI workflow + domain-pack
|
|
casan level show # xem level đã cài + level project
|
|
casan level set 2 # đổi level project (không cần init lại)
|
|
```
|
|
|
|
**Áp dụng cho dự án ĐÃ có vỏ (agents/skills/hook sẵn):** an toàn.
|
|
- `init` **KHÔNG index/parse code, KHÔNG sửa source, KHÔNG dựng lại vỏ** — chỉ thêm config.
|
|
- Hook được **MERGE** idempotent vào `.claude/settings.json` / `.codex/hooks.json`
|
|
hiện có (giữ nguyên hook/agents/skills/khóa khác của bạn), không ghi đè. Chạy
|
|
`init` nhiều lần không nhân đôi hook.
|
|
- **Guardrail:** `init` **từ chối** khi target chính là một CASAN source hub (để
|
|
không tự chặn agent đang phát triển CASAN); dùng `--force` nếu thực sự cần.
|
|
|
|
`--level 3` (platform) chỉ áp base L2 + nhắc rằng platform là service deploy riêng;
|
|
`--level 4` (enterprise) bị từ chối (chưa ship).
|
|
|
|
`casan init` chỉ ghi **config per-project** (không copy harness):
|
|
|
|
| File | Vai trò |
|
|
|---|---|
|
|
| `.casan/config.json` | project id, enforcement/integration mode, clients |
|
|
| `.casan/version.lock` | **pin** harness version + hash gate-code |
|
|
| `.casan/agentic.env` | feature flags bridge Plan-20 |
|
|
| `.specify/` | thư mục state runtime (logs/trace/admission) |
|
|
| `.claude/settings.json` | hook Claude Code (Plan-20) |
|
|
| `.codex/hooks.json`, `config.toml` | hook Codex (Plan-20) |
|
|
|
|
Tham số: `--client claude|codex|all` (mặc định `all`), `--mode observe|enforce`
|
|
(mặc định `observe`), `--integration-mode project_hook|managed_hook|casan_owned`,
|
|
`--target <dir>` (mặc định thư mục hiện tại).
|
|
|
|
Sau `init`, developer gõ prompt bình thường trong client — trace H1→H7 + H6 theo
|
|
Plan-20. Repo chỉ có mấy file config nhỏ; nâng cấp harness làm ở `$CASAN_HOME`.
|
|
|
|
## 3. Pin + Verify (giữ đảm bảo bảo mật khi harness ở ngoài repo)
|
|
|
|
Vì harness không nằm trong repo, dự án **pin** version + hash gate-code lúc
|
|
`init`. Kiểm tra bất cứ lúc nào:
|
|
|
|
```bash
|
|
casan verify-harness
|
|
```
|
|
|
|
- Khớp → `status: ok` (rc 0).
|
|
- Harness global bị đổi/tamper so với pin → `HARNESS_INTEGRITY_DRIFT` (rc 3).
|
|
|
|
`verify-harness` **luôn tính lại hash từ file thật** (không tin hash cache), nên
|
|
sửa lén một gate script sẽ bị phát hiện. Nên chạy `verify-harness` trong CI trước
|
|
khi tin bất kỳ trace nào là certified.
|
|
|
|
> Bước làm mạnh tiếp theo (chưa bật mặc định): ký `.harness-hash` bằng khóa tổ
|
|
> chức để verify cả *chữ ký* chứ không chỉ nội dung — dùng hạ tầng ký của Plan-16.
|
|
|
|
## 4. So sánh với mô hình vendored cũ
|
|
|
|
| | Vendored (`devkit/install.sh`) | Hybrid (`casan init`) |
|
|
|---|---|---|
|
|
| Repo | Nặng (copy cả harness) | Nhẹ (chỉ config) |
|
|
| Nâng cấp | Mỗi repo tự drift | 1 chỗ (`$CASAN_HOME`) |
|
|
| Bảo mật | Gate commit + ký trong repo | Gate global + **pin+verify** trong repo |
|
|
| CI/offline | Tự chứa | Cần cài harness trên runner (hoặc verify pin) |
|
|
|
|
Cả hai vẫn dùng chung lõi harness + `casan-paths.sh` (tách `CASAN_HARNESS_ROOT`
|
|
= code, `CASAN_STATE_ROOT` = state trong repo, `CASAN_DOMAIN_ROOT` = dữ liệu dự
|
|
án). Chọn mô hình theo nhu cầu triển khai.
|
|
|
|
## 5. Kiểm thử
|
|
|
|
```bash
|
|
bash packages/casan-devkit/tests/hybrid-install-tests.sh
|
|
```
|