feat: add production init wizard UX
This commit is contained in:
thanhnv
@@ -1,24 +1,45 @@
|
||||
# CASAN
|
||||
|
||||
CASAN là governance harness cho agentic coding. CASAN được cài một lần trên máy
|
||||
developer, sau đó được liên kết vào từng repository bằng project hooks. CASAN
|
||||
không thay thế IDE, coding agent hoặc workflow phát triển của project.
|
||||
CASAN là governance harness cho agentic coding. CASAN bổ sung policy gates,
|
||||
audit trail, evidence và kiểm tra integrity vào lifecycle của coding agent,
|
||||
nhưng không thay thế IDE, model, agent, skill, slash command hay workflow hiện
|
||||
có của repository.
|
||||
|
||||
Project có thể tiếp tục dùng nguyên trạng slash commands, agents, skills, review
|
||||
loops và cấu trúc source hiện hữu. CASAN không áp đặt một pipeline hoặc số bước
|
||||
cố định.
|
||||
Mô hình production mặc định:
|
||||
|
||||
- Cài **DevKit một lần trên máy** để có launcher và lệnh quản trị.
|
||||
- Chạy `casan init` trong từng repository.
|
||||
- Project mới dùng **Core level + Managed runtime + Enforce mode** nếu người
|
||||
dùng không chọn khác.
|
||||
- Project offline, air-gapped hoặc cần tự chứa runtime có thể chọn
|
||||
**Vendored runtime**.
|
||||
|
||||
`casan init` chỉ thêm lớp tích hợp cần thiết. Runtime phát hành không chứa test
|
||||
suite, test scripts, internal CI runners, `level5`, dashboard lab, source docs
|
||||
hay release tooling.
|
||||
|
||||
## Trạng thái sản phẩm
|
||||
|
||||
| Thành phần | Trạng thái | Phạm vi |
|
||||
|---|---|---|
|
||||
| Core — Level 1 | Implemented | H1–H7 harness, hooks, policy gates, audit, evidence và CLI |
|
||||
| DevKit — Level 2 | Implemented | Core + `casan init`, domain-pack và CI template |
|
||||
| Platform — Level 3 | Preview | Control Panel được deploy riêng, không được cài vào project bằng `casan init` |
|
||||
| Enterprise — Level 4 | Chưa phát hành | Installer chủ động từ chối |
|
||||
| DevKit — Level 2 | Implemented | Core + adoption tooling, domain-pack và CI template |
|
||||
| Platform — Level 3 | Preview | Control Panel deploy riêng; `casan init` chỉ áp dụng nền Level 2 |
|
||||
| Enterprise — Level 4 | Chưa phát hành | CLI chủ động từ chối, không giả lập tính năng |
|
||||
|
||||
Đối với repository đã có sẵn vỏ dự án, nên dùng **Level 1 cho project**. Chỉ
|
||||
chọn Level 2 khi project thực sự cần domain-pack và CI template của CASAN.
|
||||
## Bốn quyết định cần phân biệt
|
||||
|
||||
CASAN tách riêng bốn khái niệm để cấu hình rõ ràng:
|
||||
|
||||
| Quyết định | Lựa chọn | Mặc định production |
|
||||
|---|---|---|
|
||||
| Gói cài trên máy | `core`, `devkit`, `platform` | `devkit`, vì `casan init` thuộc DevKit |
|
||||
| Capability của project | `--level core`, `devkit`, `platform` | `core` |
|
||||
| Vị trí Core runtime | `--runtime managed`, `vendored` | `managed` |
|
||||
| Cách thực thi policy | `--mode enforce`, `observe` | `enforce` |
|
||||
|
||||
`--level core` không có nghĩa Core phải nằm trong repository. Level mô tả
|
||||
capability; runtime mô tả vị trí. Đây là hai quyết định độc lập.
|
||||
|
||||
## Quick start
|
||||
|
||||
@@ -28,15 +49,15 @@ chọn Level 2 khi project thực sự cần domain-pack và CI template của C
|
||||
- Windows: PowerShell 5.1+, Python 3 và Git for Windows/Git Bash.
|
||||
- Client tương ứng nếu cần: Claude Code, Codex hoặc VS Code.
|
||||
|
||||
### 1. Cài CASAN một lần trên máy
|
||||
### 1. Cài DevKit một lần trên máy
|
||||
|
||||
Từ checkout hoặc release bundle của CASAN:
|
||||
Từ checkout hoặc release bundle đã được duyệt:
|
||||
|
||||
```bash
|
||||
# macOS/Linux
|
||||
sh install.sh --level devkit
|
||||
|
||||
# Nếu launcher chưa nằm trên PATH
|
||||
# Chỉ cần nếu terminal hiện tại chưa nhận launcher
|
||||
export PATH="${CASAN_HOME:-$HOME/.casan}/bin:$PATH"
|
||||
|
||||
casan version
|
||||
@@ -50,74 +71,195 @@ pwsh .\install.ps1
|
||||
casan version
|
||||
```
|
||||
|
||||
Gói global `devkit` được dùng vì nó chứa lệnh adoption `casan init`. Harness
|
||||
được cài mặc định tại:
|
||||
Vị trí mặc định:
|
||||
|
||||
- macOS/Linux: `~/.casan`
|
||||
- Windows: `%LOCALAPPDATA%\casan`
|
||||
|
||||
Bản cài là runtime allowlist tối giản: không mang theo test suites, internal CI
|
||||
runners, thư mục legacy `level5`, Platform dashboard/local lab, source docs hay
|
||||
release tooling. Source repository vẫn giữ tests để kiểm chứng chính CASAN.
|
||||
Có thể đặt `CASAN_HOME` trước khi cài nếu tổ chức dùng một vị trí quản lý khác.
|
||||
`casan init` không hỏi một đường dẫn runtime tùy ý: Managed luôn dùng
|
||||
installation đã resolve từ `CASAN_HOME`; Vendored luôn dùng
|
||||
`.casan/runtime/casan-core` trong project.
|
||||
|
||||
### 2. Adopt vào repository hiện hữu
|
||||
|
||||
CASAN tách rõ hai quyết định:
|
||||
|
||||
| Phạm vi | Ý nghĩa |
|
||||
|---|---|
|
||||
| `--level core` (mặc định) | Capability áp dụng cho project: governance Core, không thêm domain-pack/CI |
|
||||
| `--runtime managed` (mặc định project mới) | Dùng Core global đã pin version/hash; repo nhẹ, nâng cấp tập trung |
|
||||
| `--runtime vendored` | Copy Core production-only vào `.casan/runtime/casan-core`; phù hợp offline/air-gapped/self-contained |
|
||||
### 2. Khởi tạo CASAN trong repository
|
||||
|
||||
```bash
|
||||
cd <project-root>
|
||||
|
||||
# Production mặc định: managed Core
|
||||
casan init --client claude,codex --mode enforce
|
||||
|
||||
casan doctor
|
||||
casan verify-harness
|
||||
casan init
|
||||
```
|
||||
|
||||
`casan init` có menu chọn client khi chạy tương tác. Trong automation nên chỉ
|
||||
định rõ `--client`. Project hiện hữu mặc định dùng Level 1 (`core`); chỉ truyền
|
||||
`--level devkit` khi muốn CASAN bổ sung CI template và domain-pack:
|
||||
Với project mới và terminal tương tác, wizard hỏi hai lựa chọn:
|
||||
|
||||
```text
|
||||
Core runtime placement
|
||||
|
||||
1) Managed (Recommended)
|
||||
Use the shared CASAN installation, pinned by version and hash.
|
||||
Best for developer workstations and managed CI.
|
||||
|
||||
2) Vendored
|
||||
Copy production-only Core into .casan/runtime/casan-core.
|
||||
Best for offline, air-gapped, or self-contained repositories.
|
||||
|
||||
Select runtime [1]:
|
||||
|
||||
Client integrations
|
||||
|
||||
1) Claude Code
|
||||
2) Codex
|
||||
3) GitHub Copilot in VS Code via explicit @casan route
|
||||
|
||||
Select clients (comma-separated) [1,2]:
|
||||
```
|
||||
|
||||
Nhấn Enter để dùng Managed và Claude Code + Codex. Nhập sai sẽ được hướng dẫn
|
||||
chọn lại. Sau khi hoàn tất, output terminal là bản tóm tắt dễ đọc gồm project,
|
||||
level, runtime, mode, client, file thay đổi và next steps.
|
||||
|
||||
Project đã init không bị hỏi lại runtime: CASAN giữ nguyên mode hiện tại. Muốn
|
||||
đổi, truyền rõ `--runtime managed` hoặc `--runtime vendored`.
|
||||
|
||||
### 3. Kiểm tra readiness
|
||||
|
||||
```bash
|
||||
casan init --level core --client claude
|
||||
casan init --level core --client codex
|
||||
casan init --level core --client claude,codex
|
||||
casan init --level core --client vscode-copilot --vscode-install yes
|
||||
casan init --level core --client all
|
||||
casan init --level devkit --client claude,codex
|
||||
|
||||
# Project phải tự chứa Core (offline/air-gapped)
|
||||
casan init --runtime vendored --client claude,codex
|
||||
casan doctor
|
||||
casan verify-harness
|
||||
casan level show
|
||||
```
|
||||
|
||||
Output `init` và `casan level show` luôn hiển thị runtime mode cùng đường dẫn
|
||||
thực tế. Chạy lại `init` giữ mode hiện tại; chỉ đổi khi truyền rõ
|
||||
`--runtime managed` hoặc `--runtime vendored`.
|
||||
Với Codex, mở `/hooks`, review và trust đúng project hook sau lần init hoặc khi
|
||||
bootstrap hash thay đổi.
|
||||
|
||||
Với Codex, sau init phải mở `/hooks`, kiểm tra và trust đúng project hook hash.
|
||||
### 4. Dùng workflow hiện có
|
||||
|
||||
### 3. Dùng project bình thường
|
||||
Tiếp tục dùng chat, agents, skills và slash commands của project như bình
|
||||
thường. Không cần gọi một “CASAN agent” hoặc chạy một pipeline CASAN riêng.
|
||||
|
||||
Không cần gọi CASAN agent hoặc CASAN pipeline. Tiếp tục dùng workflow hiện hữu,
|
||||
ví dụ `/bd:boss`, `/bd:generation`, `/bd:review`, hoặc chat bình thường không
|
||||
chỉ định agent.
|
||||
|
||||
CASAN tự tham gia vào lifecycle của client đã enable:
|
||||
CASAN tham gia tại lifecycle của client đã enable:
|
||||
|
||||
1. `UserPromptSubmit`: admission và quét prompt.
|
||||
2. `PreToolUse`: kiểm tra tool input và chặn side effect không hợp lệ.
|
||||
2. `PreToolUse`: kiểm tra tool input, chặn side effect không hợp lệ.
|
||||
3. `PostToolUse`: ghi evidence của tool result.
|
||||
4. `Stop`: finalize trace, telemetry và trạng thái certification.
|
||||
|
||||
CASAN bridge không gọi model lần thứ hai. Claude Code/Codex vẫn là model
|
||||
CASAN bridge không gọi model lần thứ hai. Claude Code hoặc Codex vẫn là model
|
||||
executor duy nhất.
|
||||
|
||||
## Dùng trong script và CI
|
||||
|
||||
Automation phải khai báo quyết định rõ ràng:
|
||||
|
||||
```bash
|
||||
casan init \
|
||||
--non-interactive \
|
||||
--level core \
|
||||
--runtime managed \
|
||||
--mode enforce \
|
||||
--client claude,codex
|
||||
```
|
||||
|
||||
`--non-interactive` và `--json` không bao giờ chờ input. Nếu không truyền
|
||||
`--runtime`, project mới mặc định Managed; nếu không truyền `--client`, mặc
|
||||
định Claude Code + Codex để tương thích các bản trước.
|
||||
|
||||
Output mặc định dành cho người đọc. Chỉ dùng JSON khi một chương trình cần xử
|
||||
lý dữ liệu:
|
||||
|
||||
```bash
|
||||
casan init --non-interactive --client codex --json
|
||||
casan doctor --json
|
||||
casan verify-harness --json
|
||||
casan level show --json
|
||||
```
|
||||
|
||||
## Chọn runtime
|
||||
|
||||
### Managed — khuyến nghị cho đa số tổ chức
|
||||
|
||||
Managed dùng Core trong global installation và pin version/hash theo từng
|
||||
project.
|
||||
|
||||
Ưu điểm:
|
||||
|
||||
- Repository nhẹ, không nhân bản runtime.
|
||||
- Nâng cấp và rollback tập trung.
|
||||
- Phù hợp workstation và CI runner được quản lý.
|
||||
- Nhiều project có thể dùng chung một CASAN installation.
|
||||
|
||||
Yêu cầu:
|
||||
|
||||
- Máy developer/runner phải cài release CASAN mà project đã pin.
|
||||
- Không thay runtime global tùy tiện; luôn chạy `casan verify-harness`.
|
||||
|
||||
```bash
|
||||
casan init --runtime managed
|
||||
```
|
||||
|
||||
### Vendored — cho môi trường tự chứa
|
||||
|
||||
Vendored copy Core production-only vào
|
||||
`.casan/runtime/casan-core`. Bootstrap và launcher trong project resolve runtime
|
||||
này trước, không âm thầm fallback sang global nếu runtime bị thiếu.
|
||||
|
||||
Ưu điểm:
|
||||
|
||||
- Có thể hoạt động offline hoặc air-gapped.
|
||||
- Runtime đi cùng đúng project.
|
||||
- Phù hợp repository được đóng gói thành một deliverable độc lập.
|
||||
|
||||
Đánh đổi:
|
||||
|
||||
- Repository/artifact lớn hơn.
|
||||
- Mỗi project phải chủ động nhận bản vá và upgrade.
|
||||
- Tổ chức phải quản lý quyền phân phối runtime theo license.
|
||||
|
||||
```bash
|
||||
casan init --runtime vendored
|
||||
```
|
||||
|
||||
### Bảng quyết định
|
||||
|
||||
| Tình huống | Runtime nên dùng |
|
||||
|---|---|
|
||||
| Máy developer và CI do công ty quản lý | Managed |
|
||||
| Nhiều repository dùng chung CASAN | Managed |
|
||||
| Cần rollout/rollback tập trung | Managed |
|
||||
| Offline hoặc air-gapped | Vendored |
|
||||
| Deliverable phải tự chứa toàn bộ Core | Vendored |
|
||||
| Không thể đảm bảo CASAN đã cài trên runner | Vendored |
|
||||
|
||||
## Chọn project level
|
||||
|
||||
| Level | Dùng khi | Nội dung thêm vào project |
|
||||
|---|---|---|
|
||||
| `core` | Mặc định cho repository đã có cấu trúc | Governance Core, bootstrap, hooks và config |
|
||||
| `devkit` | Cần CASAN domain-pack và CI template | Core + `.gitea/workflows/casan-ci.yml` + domain scaffold |
|
||||
| `platform` | Đánh giá Platform preview | Áp dụng nền Level 2; Control Panel vẫn deploy riêng |
|
||||
| `enterprise` | Chưa khả dụng | CLI từ chối |
|
||||
|
||||
```bash
|
||||
casan init --level core
|
||||
casan init --level devkit
|
||||
```
|
||||
|
||||
Level 1 Core không đưa test folders, test scripts, `level5` hoặc source-only
|
||||
components vào project. Chỉ chọn DevKit khi thực sự cần scaffold bổ sung.
|
||||
|
||||
## Enforcement mode
|
||||
|
||||
| Mode | Dùng cho | Hành vi |
|
||||
|---|---|---|
|
||||
| `enforce` | Production | Side effect fail-closed; turn đủ evidence có thể certified |
|
||||
| `observe` | Pilot và thu telemetry | Ghi nhận nhưng không chặn như production; luôn `observed_only` |
|
||||
|
||||
```bash
|
||||
casan init --mode enforce
|
||||
casan init --mode observe
|
||||
```
|
||||
|
||||
Không gọi một turn là CASAN-certified nếu không có trace tương ứng hoặc trace bị
|
||||
đánh dấu `observed_only`/`non_certified`.
|
||||
|
||||
## Client support
|
||||
|
||||
| Client | Chat bình thường tự qua CASAN | Bước bắt buộc |
|
||||
@@ -126,224 +268,300 @@ executor duy nhất.
|
||||
| Codex CLI/extension | Có | Mở `/hooks`, review và trust hook hash |
|
||||
| GitHub Copilot Chat | Không | Cài CASAN VSIX và gửi `@casan <prompt>` |
|
||||
|
||||
Các cách chọn client:
|
||||
|
||||
```bash
|
||||
casan init --client claude
|
||||
casan init --client codex
|
||||
casan init --client claude,codex
|
||||
casan init --client vscode-copilot --vscode-install yes
|
||||
casan init --client all
|
||||
casan init --client none
|
||||
```
|
||||
|
||||
GitHub Copilot không cung cấp public API để extension intercept toàn bộ built-in
|
||||
chat. Chỉ route explicit `@casan` mới là CASAN-owned. Một backend tự gọi LLM API
|
||||
chat. Chỉ route explicit `@casan` mới là CASAN-owned. Backend tự gọi LLM API
|
||||
cũng không đi qua IDE hooks và cần adapter riêng.
|
||||
|
||||
## Kiến trúc runtime
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
U["Developer"] --> C1["Claude Code"]
|
||||
U --> C2["Codex"]
|
||||
U --> C3["VS Code: @casan"]
|
||||
|
||||
C1 --> E1["Project hook events"]
|
||||
C2 --> E1
|
||||
C3 --> E2["CASAN-owned VSIX route"]
|
||||
|
||||
E1 --> B[".casan/casan-hook.py"]
|
||||
E2 --> B
|
||||
B --> V{"Global harness<br/>matches version.lock?"}
|
||||
V -- "No" --> D["Deny or degrade<br/>according to mode"]
|
||||
U["Developer"] --> C["Claude Code / Codex / @casan"]
|
||||
C --> B["Project bootstrap<br/>.casan/casan-hook.py"]
|
||||
B --> R{"Runtime mode"}
|
||||
R -- "Managed" --> GM["CASAN_HOME/current"]
|
||||
R -- "Vendored" --> GV[".casan/runtime/casan-core"]
|
||||
GM --> V{"Version + hash<br/>match version.lock?"}
|
||||
GV --> V
|
||||
V -- "No" --> D["Deny or degrade<br/>according to enforcement mode"]
|
||||
V -- "Yes" --> A["Client adapter"]
|
||||
A --> G["Agentic bridge"]
|
||||
|
||||
subgraph TURN["Per-turn lifecycle"]
|
||||
direction LR
|
||||
L1["Admission<br/>H1 + H4"] --> L2["Pre-tool gate<br/>H2 + H4"]
|
||||
L2 --> L3["Post-tool evidence<br/>H5"]
|
||||
L3 --> L4["Finalize<br/>H3 + H5 + H6 + H7"]
|
||||
end
|
||||
|
||||
G --> L1
|
||||
L4 --> S["Project runtime state<br/>.specify/logs + state"]
|
||||
L4 --> R["Native client result"]
|
||||
G --> L1["Admission"]
|
||||
L1 --> L2["Pre-tool gate"]
|
||||
L2 --> L3["Post-tool evidence"]
|
||||
L3 --> L4["Finalize trace"]
|
||||
L4 --> S[".specify/logs + state"]
|
||||
L4 --> O["Native client result"]
|
||||
```
|
||||
|
||||
## Cấu trúc cài đặt thực tế
|
||||
Runtime resolution fail-closed: một project pin Vendored nhưng thiếu
|
||||
`.casan/runtime/casan-core` sẽ báo lỗi và yêu cầu restore bằng release DevKit đã
|
||||
duyệt, không tự chuyển sang Managed.
|
||||
|
||||
CASAN mặc định dùng managed runtime: policy code nằm ở global installation,
|
||||
project giữ bootstrap, pin và state riêng. Với `--runtime vendored`, cùng Core
|
||||
production-only được đặt tại `.casan/runtime/casan-core`.
|
||||
## Cấu trúc cài đặt
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph M["Developer machine"]
|
||||
H["CASAN_HOME"]
|
||||
CUR["current<br/>symlink hoặc junction"]
|
||||
VER["versions/<version>"]
|
||||
CLI["bin/casan"]
|
||||
HAR["packages/casan-harness"]
|
||||
DEV["packages/casan-devkit"]
|
||||
### Global installation
|
||||
|
||||
H --> CUR --> VER
|
||||
H --> CLI
|
||||
VER --> HAR
|
||||
VER --> DEV
|
||||
end
|
||||
```text
|
||||
CASAN_HOME/
|
||||
├── bin/casan
|
||||
├── current -> versions/<version>
|
||||
└── versions/<version>/
|
||||
├── VERSION
|
||||
├── bin/casan
|
||||
├── packages/casan-harness/
|
||||
└── packages/casan-devkit/
|
||||
```
|
||||
|
||||
INIT["casan init"] --> CFG
|
||||
CLI --> INIT
|
||||
DEV --> INIT
|
||||
Release runtime là allowlist production-only. Tests và release tooling vẫn nằm
|
||||
trong source repository để kiểm chứng CASAN, nhưng không được copy vào
|
||||
installation hoặc project runtime.
|
||||
|
||||
subgraph P["Existing project"]
|
||||
CFG[".casan/<br/>config.json<br/>version.lock<br/>agentic.env<br/>init-manifest.json"]
|
||||
BOOT[".casan/casan-hook.py"]
|
||||
STATE[".specify/<br/>logs/<br/>state/<br/>.gitignore"]
|
||||
CLIENTS["Client config khi được chọn<br/>.claude/settings.json<br/>.codex/hooks.json<br/>.vscode/extensions.json"]
|
||||
L2["Level 2 only<br/>.gitea/workflows/casan-ci.yml<br/>apps/<project-id>/domain/"]
|
||||
OWNED["Project-owned<br/>source, agents, skills,<br/>commands, hooks và CI khác"]
|
||||
end
|
||||
### Project sau `casan init`
|
||||
|
||||
INIT --> BOOT
|
||||
INIT --> STATE
|
||||
INIT --> CLIENTS
|
||||
INIT -. "chỉ khi --level devkit" .-> L2
|
||||
INIT -. "không thay đổi" .-> OWNED
|
||||
CFG --> BOOT
|
||||
HAR -. "runtime policy" .-> BOOT
|
||||
```text
|
||||
<project>/
|
||||
├── .casan/
|
||||
│ ├── config.json
|
||||
│ ├── version.lock
|
||||
│ ├── casan-hook.py
|
||||
│ ├── agentic.env
|
||||
│ ├── init-manifest.json
|
||||
│ └── runtime/casan-core/ # chỉ khi --runtime vendored
|
||||
├── .specify/
|
||||
│ ├── .gitignore
|
||||
│ ├── logs/ # runtime, không commit
|
||||
│ └── state/ # runtime, không commit
|
||||
├── .claude/settings.json # khi enable Claude
|
||||
├── .codex/hooks.json # khi enable Codex
|
||||
├── .vscode/extensions.json # merge theo client
|
||||
└── .gitea/workflows/casan-ci.yml # chỉ Level 2, nếu chưa có
|
||||
```
|
||||
|
||||
### File nào được thay đổi
|
||||
|
||||
| Path | Hành vi |
|
||||
|---|---|
|
||||
| `.casan/config.json` | Lưu project id, mode và danh sách client |
|
||||
| `.casan/version.lock` | Pin version và SHA-256 của global harness |
|
||||
| `.casan/casan-hook.py` | Bootstrap stdlib, verify pin rồi dispatch adapter |
|
||||
| `.casan/config.json` | Project id, level, runtime mode, enforcement mode và clients |
|
||||
| `.casan/version.lock` | Pin version và SHA-256 của Core runtime đã resolve |
|
||||
| `.casan/casan-hook.py` | Stdlib bootstrap, verify pin rồi dispatch adapter |
|
||||
| `.casan/agentic.env` | Compatibility/reference flags; runtime đọc `config.json` |
|
||||
| `.casan/init-manifest.json` | Ghi file đã tạo và backup |
|
||||
| `.specify/logs`, `.specify/state` | Runtime trace, audit và state; không commit |
|
||||
| `.casan/init-manifest.json` | Danh sách file CASAN quản lý, checksum và backup |
|
||||
| `.casan/runtime/casan-core/` | Core production-only; chỉ có ở Vendored |
|
||||
| `.specify/logs`, `.specify/state` | Trace, audit và state runtime; không commit |
|
||||
| `.claude/settings.json` | Merge CASAN handlers khi enable Claude |
|
||||
| `.codex/hooks.json` | Merge CASAN handlers khi enable Codex |
|
||||
| `.vscode/extensions.json` | Merge extension recommendations theo client |
|
||||
| `.gitea/workflows/casan-ci.yml` | Chỉ Level 2, chỉ tạo khi chưa có |
|
||||
| `apps/<project-id>/domain/` | Chỉ Level 2, chỉ bổ sung file còn thiếu |
|
||||
| `.gitea/workflows/casan-ci.yml` | Chỉ Level 2; chỉ tạo khi chưa có |
|
||||
| `apps/<project-id>/domain/` | Chỉ Level 2; chỉ bổ sung file còn thiếu |
|
||||
|
||||
Trước lần thay đổi đầu tiên, init tạo backup `<file>.casan-bak` cho file hiện
|
||||
hữu. `init-manifest.json` ghi lại các file và backup liên quan.
|
||||
Trước lần thay đổi đầu tiên, init tạo `<file>.casan-bak` cho file hiện hữu.
|
||||
`init-manifest.json` giúp re-init và uninstall chỉ quản lý đúng tài sản CASAN.
|
||||
|
||||
### Nội dung luôn được giữ nguyên
|
||||
### Nội dung luôn được bảo toàn
|
||||
|
||||
- Source code và cấu trúc ứng dụng.
|
||||
- `.claude/agents`, `.claude/skills`, `.claude/commands`.
|
||||
- Agents, skills, prompts và instructions trong `.github/`.
|
||||
- Hook và JSON key không thuộc CASAN.
|
||||
- Hook, JSON key và VS Code recommendation không thuộc CASAN.
|
||||
- CI/workflow hiện hữu.
|
||||
- Vendored `packages/casan-harness` của project cũ; chỉ xóa sau khi đã migration
|
||||
toàn bộ CI và scripts sang global harness.
|
||||
- Scaffold file đã được người dùng chỉnh sửa.
|
||||
- Backup `.casan-bak`.
|
||||
|
||||
Nếu target chính là CASAN source hub, init từ chối để tránh self-adoption. Không
|
||||
dùng `--force` trừ khi chủ động muốn kiểm thử trường hợp này.
|
||||
CASAN source hub tự từ chối self-adoption. Không dùng `--force` trừ khi chủ động
|
||||
kiểm thử trường hợp này.
|
||||
|
||||
## Chọn mode
|
||||
## Nên commit gì
|
||||
|
||||
| Mode | Dùng cho | Certification |
|
||||
|---|---|---|
|
||||
| `enforce` | Mặc định production | Side effect fail-closed; turn đủ evidence có thể certified |
|
||||
| `observe` | Pilot và thu telemetry | Không chặn như production; luôn `observed_only` |
|
||||
Thông thường nên commit:
|
||||
|
||||
- `.casan/config.json`
|
||||
- `.casan/version.lock`
|
||||
- `.casan/casan-hook.py`
|
||||
- `.casan/agentic.env`
|
||||
- `.casan/init-manifest.json`
|
||||
- các client config đã merge
|
||||
- Level 2 workflow/domain files sau khi review
|
||||
|
||||
Không commit:
|
||||
|
||||
- `.specify/logs/`
|
||||
- `.specify/state/`
|
||||
- file `.casan-bak`
|
||||
|
||||
Với Managed, không có runtime để commit. Với Vendored, tổ chức phải đưa
|
||||
`.casan/runtime/casan-core` vào cùng deliverable bằng Git hoặc artifact channel
|
||||
đã duyệt; nếu bỏ runtime này, project sẽ fail-closed. Quyết định phân phối phải
|
||||
tuân theo license và policy nội bộ.
|
||||
|
||||
## Cấu hình lại
|
||||
|
||||
Chạy lại init với **toàn bộ danh sách client mong muốn**:
|
||||
|
||||
```bash
|
||||
casan init --level core --client claude,codex --mode enforce
|
||||
# Chỉ giữ Claude
|
||||
casan init --client claude
|
||||
|
||||
# Tắt CASAN IDE integrations nhưng giữ config và evidence
|
||||
casan init --client none
|
||||
|
||||
# Chuyển runtime có chủ đích
|
||||
casan init --runtime vendored
|
||||
casan init --runtime managed
|
||||
```
|
||||
|
||||
Không gọi một turn là CASAN-certified nếu không có trace tương ứng hoặc trace bị
|
||||
đánh dấu `observed_only`/`non_certified`.
|
||||
Client bị bỏ khỏi danh sách sẽ được gỡ CASAN handler; hook và config không thuộc
|
||||
CASAN vẫn được giữ. `--client none` không tự gỡ VS Code extension dùng chung.
|
||||
|
||||
## Kiểm tra, cấu hình lại và nâng cấp
|
||||
## Nâng cấp và rollback
|
||||
|
||||
Kiểm tra project:
|
||||
### Managed
|
||||
|
||||
```bash
|
||||
casan doctor
|
||||
casan verify-harness
|
||||
casan level show
|
||||
```
|
||||
|
||||
- Output mặc định được tối ưu để đọc trực tiếp trong terminal. Thêm `--json`
|
||||
sau command khi cần payload đầy đủ cho CI hoặc script, ví dụ
|
||||
`casan doctor --json`.
|
||||
- `doctor`: kiểm tra config, bootstrap, hook schema, adapter smoke test, VSIX và
|
||||
cảnh báo trust.
|
||||
- `verify-harness`: tính lại live hash và so với project pin; drift trả exit
|
||||
code `3`.
|
||||
- `level show`: hiển thị package level đã cài và target level của project.
|
||||
|
||||
Đổi danh sách client bằng cách chạy lại init với **toàn bộ danh sách mong muốn**.
|
||||
CASAN handler của client bị bỏ khỏi danh sách sẽ được gỡ, còn hook khác được giữ:
|
||||
|
||||
```bash
|
||||
casan init --level core --client claude
|
||||
|
||||
# Tắt toàn bộ IDE integration của CASAN nhưng giữ config/state
|
||||
casan init --level core --client none
|
||||
```
|
||||
|
||||
`--client none` không uninstall VSIX đã cài trên máy; nếu không còn dùng route
|
||||
`@casan`, gỡ extension `fpt-casan.casan-governed-chat` trong VS Code.
|
||||
|
||||
Gỡ CASAN khỏi project:
|
||||
|
||||
```bash
|
||||
# Gỡ project hooks và config CASAN; giữ hook người dùng và runtime evidence
|
||||
casan uninstall
|
||||
|
||||
# Đồng thời xóa .specify/logs và .specify/state
|
||||
casan uninstall --purge
|
||||
|
||||
# Chỉ dùng khi extension dùng chung không còn cần trên máy
|
||||
casan uninstall --remove-vscode-extension
|
||||
```
|
||||
|
||||
`uninstall` xóa workflow CASAN trong `.gitea`, xóa các scaffold file CASAN còn
|
||||
nguyên checksum và tự dọn thư mục cha khi đã rỗng. Workflow/file của project,
|
||||
scaffold file đã chỉnh sửa và `.casan-bak` được giữ lại để tránh mất dữ liệu.
|
||||
Vendored Core trong `.casan/runtime/casan-core` cũng được xóa. Lệnh không mặc
|
||||
định gỡ VS Code extension dùng chung cho các project khác.
|
||||
|
||||
Khi nâng cấp CASAN:
|
||||
|
||||
1. Chạy lại installer từ release đã duyệt.
|
||||
2. Chạy lại `casan init` trong từng project để cập nhật bootstrap và pin.
|
||||
1. Cài release CASAN đã duyệt trên workstation/runner.
|
||||
2. Chạy lại `casan init --runtime managed` trong từng project để cập nhật
|
||||
bootstrap và pin.
|
||||
3. Chạy `casan doctor` và `casan verify-harness`.
|
||||
4. Với Codex, review/trust lại hook nếu hash thay đổi.
|
||||
|
||||
Trong production, không bỏ qua `HARNESS_INTEGRITY_DRIFT`.
|
||||
### Vendored
|
||||
|
||||
## CI
|
||||
1. Cài hoặc giải nén DevKit release đã duyệt trên máy thực hiện upgrade.
|
||||
2. Chạy `casan init --runtime vendored`; CASAN refresh Core production-only
|
||||
trong project.
|
||||
3. Review thay đổi runtime, chạy `doctor` và `verify-harness`.
|
||||
4. Phát hành lại deliverable Vendored.
|
||||
|
||||
Runner phải cài cùng release CASAN mà project đã pin. Gate tối thiểu:
|
||||
Rollback dùng đúng release đã duyệt trước đó, chạy lại init và verify. Không bỏ
|
||||
qua `HARNESS_INTEGRITY_DRIFT` trong production.
|
||||
|
||||
## Uninstall
|
||||
|
||||
```bash
|
||||
# Gỡ hooks, config, CASAN workflow/scaffold còn nguyên checksum và Vendored Core
|
||||
casan uninstall
|
||||
|
||||
# Đồng thời xóa runtime evidence
|
||||
casan uninstall --purge
|
||||
|
||||
# Chỉ khi VSIX dùng chung không còn cần trên máy
|
||||
casan uninstall --remove-vscode-extension
|
||||
```
|
||||
|
||||
`casan uninstall`:
|
||||
|
||||
- gỡ CASAN handlers nhưng giữ handlers của project;
|
||||
- xóa CASAN-owned `.gitea` workflow và dọn thư mục cha nếu đã rỗng;
|
||||
- xóa `.casan/runtime/casan-core` nếu dùng Vendored;
|
||||
- chỉ xóa scaffold file còn đúng checksum;
|
||||
- giữ file người dùng đã sửa và `.casan-bak`;
|
||||
- giữ `.specify/logs` và `.specify/state` trừ khi có `--purge`;
|
||||
- không mặc định gỡ VSIX vì extension có thể được project khác dùng chung.
|
||||
|
||||
Sau uninstall, output liệt kê rõ mục đã xóa và mục được giữ lại.
|
||||
|
||||
## CI production
|
||||
|
||||
Gate tối thiểu:
|
||||
|
||||
```bash
|
||||
casan verify-harness
|
||||
casan gate
|
||||
```
|
||||
|
||||
Managed runner phải cài đúng approved release trước khi chạy gate. Vendored
|
||||
runner phải nhận `.casan/runtime/casan-core` cùng checkout/artifact; global
|
||||
launcher vẫn có thể được dùng, nhưng runtime policy được resolve từ project.
|
||||
|
||||
Level 2 tạo `.gitea/workflows/casan-ci.yml` như một template nếu file chưa tồn
|
||||
tại. Template phải được review theo runner và mô hình cài đặt của tổ chức trước
|
||||
khi enable; CASAN không ghi đè workflow hiện hữu.
|
||||
tại. Luôn review template theo runner, secret model và runtime mode của tổ chức
|
||||
trước khi enable. CASAN không ghi đè workflow hiện hữu.
|
||||
|
||||
Đảm bảo `.specify/logs/` và `.specify/state/` không được commit. Init chỉ tạo
|
||||
`.specify/.gitignore` khi file đó chưa tồn tại.
|
||||
|
||||
## CLI tham khảo
|
||||
|
||||
| Lệnh | Mục đích |
|
||||
|---|---|
|
||||
| `casan init` | Adopt hoặc cấu hình lại CASAN trong project |
|
||||
| `casan uninstall` | Gỡ CASAN-owned project integration an toàn |
|
||||
| `casan doctor` | Kiểm tra config, bootstrap, pin, adapters và client readiness |
|
||||
| `casan verify-harness` | So live Core hash với project pin |
|
||||
| `casan level show` | Hiển thị installed level, project level và runtime |
|
||||
| `casan gate` | Chạy production checks từ project manifest |
|
||||
| `casan verify` | Verify audit chain, tool audit và policy bundle |
|
||||
| `casan prompt verify` | Verify prompt-enforcement contract |
|
||||
| `casan prompt trace <trace-id>` | Verify H1–H7 certification của một turn |
|
||||
| `casan version` | Hiển thị phiên bản |
|
||||
| `casan help` | Hiển thị toàn bộ command |
|
||||
|
||||
Các trạng thái quan trọng:
|
||||
|
||||
- `doctor` trả non-zero khi project chưa sẵn sàng.
|
||||
- `verify-harness` trả exit code `3` khi phát hiện drift.
|
||||
- Cú pháp/giá trị CLI không hợp lệ trả exit code `64`.
|
||||
- JSON là opt-in qua `--json`; lỗi vận hành vẫn được viết ngắn gọn ra stderr.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `casan` không có trên PATH
|
||||
|
||||
Mở terminal mới hoặc thêm `${CASAN_HOME:-$HOME/.casan}/bin` vào `PATH`.
|
||||
|
||||
### Managed báo integrity drift
|
||||
|
||||
Cài đúng release đã pin, chạy lại `casan init --runtime managed`, sau đó
|
||||
`casan verify-harness`. Không sửa `version.lock` thủ công để né kiểm tra.
|
||||
|
||||
### Vendored báo runtime missing
|
||||
|
||||
Từ một approved DevKit installation, chạy:
|
||||
|
||||
```bash
|
||||
casan init --runtime vendored
|
||||
casan verify-harness
|
||||
```
|
||||
|
||||
### Codex chưa chạy hook
|
||||
|
||||
Mở `/hooks`, review project hook và trust hash hiện tại.
|
||||
|
||||
### GitHub Copilot chat không tự qua CASAN
|
||||
|
||||
Dùng explicit route `@casan <prompt>` và kiểm tra
|
||||
`fpt-casan.casan-governed-chat` đã được cài.
|
||||
|
||||
## Cấu trúc source repository CASAN
|
||||
|
||||
| Path | Trách nhiệm |
|
||||
|---|---|
|
||||
| `bin/casan` | CLI entrypoint |
|
||||
| `install.sh`, `install.ps1` | Global installers |
|
||||
| `packages/casan-harness/` | Runtime controls, adapters, policies, evidence và tests |
|
||||
| `packages/casan-devkit/` | Hybrid adoption, project bootstrap và templates |
|
||||
| `packages/casan-harness/` | Runtime controls, adapters, policies, evidence và source tests |
|
||||
| `packages/casan-devkit/` | Project adoption tooling và templates |
|
||||
| `packages/casan-control-panel/` | Platform UI/API preview, deploy riêng |
|
||||
| `packaging/levels.json` | Nguồn sự thật cho package level và maturity |
|
||||
| `infra/` | Local/production deployment references |
|
||||
| `docs/` | Security, operations, packaging và design records |
|
||||
| `apps/` | Demo/validation applications; không phải runtime dependency của `casan init` |
|
||||
|
||||
Source tree có tests để phát triển sản phẩm. Release packaging dùng allowlist để
|
||||
chỉ đưa production runtime cần thiết vào global install hoặc Vendored Core.
|
||||
|
||||
## Tài liệu chi tiết
|
||||
|
||||
- [Hybrid installation và migration](docs/casan/CASAN_INSTALL_HYBRID.md)
|
||||
- [Production installation và migration](docs/casan/CASAN_INSTALL_HYBRID.md)
|
||||
- [Agentic client security boundary](docs/casan/CASAN_AGENTIC_CLIENT_SECURITY.md)
|
||||
- [Windows client setup](docs/casan/CASAN_AGENTIC_CLIENTS_WINDOWS.md)
|
||||
- [Packaging levels](docs/packaging/CASAN_PACKAGING_PLAN.md)
|
||||
|
||||
Reference in New Issue
Block a user