feat(install): Plan-21 hybrid global install + casan init (pin+verify)
Adopt CASAN like a normal tool (codegraph-style): install the harness ONCE
per machine, then `casan init` per project writes CONFIG ONLY — the harness
is no longer copied into every repo.
- install.sh / install.ps1: global bootstrap (curl|sh / irm|iex or local
source). Installs harness to $CASAN_HOME/versions/<ver>, writes a `casan`
launcher that resolves the shared harness + the current project's .specify,
and records a gate-code integrity hash. CASAN_NO_PATH_LINK for tests.
- harness_hash.py: deterministic content hash over gate code (scripts/bash,
scripts/python, security, level5) — the pin+verify anchor.
- casan-init.py: `casan init` writes .casan/{config,version.lock,agentic.env},
.specify/ marker, and the Plan-20 client hooks — no harness copy. `verify`
recomputes the harness hash LIVE and compares to the project pin (drift/
tamper -> rc 3), preserving the Plan-16 trusted-gates guarantee off-repo.
- bin/casan: new `init` and `verify-harness` commands.
- hybrid-install-tests.sh: 21/21 (install, config-only init, no-copy, pin,
verify ok, tamper drift, bridge runs against project state via global harness).
- docs: CASAN_INSTALL_HYBRID.md + Plan-21.
The path model (casan-paths.sh) already separated harness/state/domain roots,
so this is installer + init, not a core rewrite. Remote dist tarball, real
Windows run, and signed .harness-hash are the documented next steps.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
thanhnv
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
f6d28a3163
commit
8450f8ca1a
@@ -0,0 +1,101 @@
|
||||
# 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
|
||||
```
|
||||
|
||||
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.
|
||||
- Tạo launcher `casan` 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
|
||||
# hoặc:
|
||||
casan init --project my-app --client all --mode observe
|
||||
```
|
||||
|
||||
`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
|
||||
```
|
||||
@@ -0,0 +1,65 @@
|
||||
# CASAN Plan-21 — Hybrid Global Install + `casan init`
|
||||
|
||||
> Ngày lập: 2026-07-23
|
||||
> Trạng thái: **IMPLEMENTED (MVP) — global install + `casan init` + pin/verify xanh (21/21 test)**
|
||||
> Liên quan: [Plan-20](CASAN_PLAN_20_AGENTIC_CLIENT_INTEGRATION.md) (adapter/hook là base phổ quát), [CASAN_INSTALL_HYBRID.md](../casan/CASAN_INSTALL_HYBRID.md)
|
||||
|
||||
## 1. Mục tiêu
|
||||
|
||||
Cài CASAN như một tool bình thường (giống codegraph): cài **một lần** lên máy,
|
||||
rồi trong dự án chỉ chạy `casan init`. Không còn copy toàn bộ harness vào từng
|
||||
repo. Đây là câu trả lời cho "làm sao dựng 1 base chung nhất cho dự án muôn hình
|
||||
vạn trạng": **harness = phần chung (agnostic), config per-project = phần biến
|
||||
thể**, và entry phổ quát nhất là agentic bridge Plan-20 (chỉ cần Python + bash).
|
||||
|
||||
## 2. Kiến trúc
|
||||
|
||||
Tận dụng sẵn `casan-paths.sh` đã tách 3 root độc lập:
|
||||
|
||||
- `CASAN_HARNESS_ROOT` = **code** → cài global (`$CASAN_HOME/versions/<ver>`).
|
||||
- `CASAN_STATE_ROOT` (`.specify/`) = **state runtime** → trong repo.
|
||||
- `CASAN_DOMAIN_ROOT` = **dữ liệu dự án** → trong repo (optional).
|
||||
|
||||
Launcher global set `CASAN_HARNESS_ROOT`/`CASAN_DEVKIT_ROOT` về bản cài, và tìm
|
||||
`CASAN_APP_ROOT` bằng cách đi lên từ CWD tới marker `.casan`/`.specify`. Nhờ vậy
|
||||
harness global thao tác đúng trên state của dự án hiện tại.
|
||||
|
||||
## 3. Pin + Verify (giữ đảm bảo Plan-16 khi harness ở ngoài repo)
|
||||
|
||||
- Installer tính **hash toàn vẹn gate-code** (`scripts/bash`, `scripts/python`,
|
||||
`security`, `level5`) và ghi `.harness-hash`.
|
||||
- `casan init` **pin** version + hash vào `.casan/version.lock`.
|
||||
- `casan verify-harness` **tính lại live** từ file thật và so với pin → phát hiện
|
||||
drift/tamper (rc 3). Không tin hash cache.
|
||||
- Làm mạnh sau: ký `.harness-hash` bằng khóa tổ chức (tái dùng hạ tầng ký Plan-16).
|
||||
|
||||
## 4. Deliverable đã ship
|
||||
|
||||
| Deliverable | File |
|
||||
|---|---|
|
||||
| Global installer (macOS/Linux) | `install.sh` |
|
||||
| Global installer (Windows) | `install.ps1` |
|
||||
| Integrity hash primitive | `packages/casan-harness/scripts/python/harness_hash.py` |
|
||||
| `casan init` / `verify` | `packages/casan-devkit/casan-init.py` |
|
||||
| CLI wiring | `bin/casan` (`init`, `verify-harness`) |
|
||||
| Acceptance suite | `packages/casan-devkit/tests/hybrid-install-tests.sh` — **21/21 PASS** |
|
||||
| Adoption doc | `docs/casan/CASAN_INSTALL_HYBRID.md` |
|
||||
|
||||
## 5. Definition of Done
|
||||
|
||||
- ✅ `install.sh` cài harness + launcher + integrity hash từ checkout cục bộ.
|
||||
- ✅ `casan init` ghi CHỈ config per-project; **không** copy harness.
|
||||
- ✅ `version.lock` pin đúng hash; `verify-harness` ok khi sạch, drift (rc 3) khi tamper.
|
||||
- ✅ Bridge Plan-20 chạy qua harness global, state ghi vào `.specify` của dự án.
|
||||
- ✅ Project id mặc định theo tên thư mục, được sanitize.
|
||||
|
||||
## 6. Còn lại / bước tiếp
|
||||
|
||||
- **Remote bootstrap**: `install.sh`/`install.ps1` đã hỗ trợ `CASAN_DIST_URL`
|
||||
nhưng chưa có release tarball + URL Gitea công bố; cần publish artifact.
|
||||
- **Windows thực**: `install.ps1` viết path-safe nhưng chưa chạy trên máy Windows
|
||||
thật (host dev không có `pwsh`).
|
||||
- **Ký `.harness-hash`**: verify hiện theo nội dung; thêm chữ ký để chống thay cả
|
||||
hash lẫn code.
|
||||
- **`casan init` domain pack**: hiện init tối giản (config + hook Plan-20); có thể
|
||||
thêm `--with-domain` để scaffold domain-pack khi dự án cần traceability đầy đủ.
|
||||
Reference in New Issue
Block a user