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>
80 lines
4.3 KiB
Markdown
80 lines
4.3 KiB
Markdown
# CASAN Plan-21 — Hybrid Global Install + `casan init`
|
|
|
|
> Ngày lập: 2026-07-23
|
|
> Trạng thái: **IMPLEMENTED — global install + `casan init` + pin/verify + level-aware + merge-safe (41/41 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` — **41/41 PASS** |
|
|
| Adoption doc | `docs/casan/CASAN_INSTALL_HYBRID.md` |
|
|
|
|
### Level selection (4 packaging levels) & safe adoption
|
|
|
|
- `install.sh --level core|devkit` (driven by `packaging/levels.json`); `platform`
|
|
refused as a preview SERVICE, `enterprise` refused (future). Level recorded in
|
|
`.casan-level`; launcher self-locates its own install (no cross-home talk).
|
|
- `casan init --level 1..4`: L1 = gate + Plan-20 hooks only; L2 = + CI workflow +
|
|
domain-pack; L3 = L2 base + preview note; L4 = refused. `casan level show`/`set`.
|
|
- **Merge, not clobber:** `init` merges Plan-20 hooks into an existing
|
|
`.claude/settings.json` / `.codex/{hooks.json,config.toml}` idempotently,
|
|
preserving the project's own hooks/agents/skills. Never re-indexes or rewrites
|
|
the project shell.
|
|
- **Source-hub guardrail:** `init` refuses to adopt a CASAN source hub into itself
|
|
(would block the developing agent); `--force` overrides.
|
|
|
|
## 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 đủ.
|