CASAN/docs/casan/CASAN_INSTALL_HYBRID.md

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)

# 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:

sh install.sh                 # macOS/Linux
pwsh .\install.ps1            # Windows

Chọn level đóng gói để cài (theo packaging/levels.json):

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) — 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ỳ

cd <dự-án-của-bạn>
casan init                       # interactive: chọn Claude, Codex, VS Code/Copilot
# hoặc chọn level áp dụng cho project:
casan init --level 1 --project my-app --client claude
casan init --level 2 --project my-app --client claude,codex
casan init --project my-app --client vscode-copilot --vscode-install yes
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
.casan/casan-hook.py	bootstrap stdlib: load config, resolve + verify harness global, dispatch adapter
.specify/	thư mục state runtime (logs/trace/admission)
.claude/settings.json	hook Claude Code (Plan-20)
.codex/hooks.json	hook Codex theo schema hiện hành; cần review/trust bằng /hooks
.vscode/extensions.json	recommendations cho IDE đã chọn

Tham số --client có thể lặp hoặc comma-separated: claude, codex, vscode-copilot, all, none. Khi chạy casan init trực tiếp trong terminal, CLI hiển thị menu chọn. Trong automation không có TTY, mặc định tương thích ngược là claude,codex.

--mode observe|enforce mặc định enforce; dùng observe chỉ cho pilot telemetry-only. --integration-mode nhận project_hook|managed_hook|casan_owned; --target <dir> mặc định là thư mục hiện tại.

Bootstrap .casan/casan-hook.py tự đọc config.json; developer không còn phải source .casan/agentic.env trước khi mở IDE. Mỗi invocation kiểm tra live hash của harness global so với version.lock trước khi chạy adapter.

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.

Capability theo client

Lựa chọn	Trải nghiệm	Bước trust/cài đặt bắt buộc
claude	Claude Code CLI và extension chính thức dùng project hooks	Mở trusted project; hook chạy tự động
codex	Codex CLI và IDE extension dùng .codex/hooks.json	Mở /hooks, review và trust đúng hook hash
vscode-copilot	GitHub Copilot Chat qua route explicit @casan	Cài VSIX do init tạo/cài; dùng @casan <prompt>

GitHub Copilot Chat mặc định không có public API để CASAN intercept mọi prompt. Chỉ route @casan là casan_owned; participant detection/built-in Copilot không được quảng bá là certified.

Kiểm tra sau init:

casan doctor
casan doctor --client claude
casan doctor --client codex
casan doctor --client vscode-copilot

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:

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 packages/casan-devkit/tests/hybrid-install-tests.sh