Files

T

thanhnvandClaude Opus 4.8 ff4e9d5a53 feat(install): level-aware casan init + merge-safe adoption + hub guardrail

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>

2026-07-23 22:00:46 +07:00

4.3 KiB

Raw Blame History

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 (adapter/hook là base phổ quát), 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 đủ.

4.3 KiB Raw Blame History

CASAN Plan-21 — Hybrid Global Install + casan init