gitea-admin/CASAN
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ff4e9d5a5338fb7d3bde684e709a7fc2d1ee6d6c
CASAN/docs/casan/CASAN_INSTALL_HYBRID.md
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

5.8 KiB
Raw Blame History

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

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
Reference in New Issue View Git Blame Copy Permalink