Quy Trình Phát Hành & Đóng Gói Bảo Mật (Release Pipeline)

Tài liệu này hướng dẫn chi tiết quy trình phát hành phiên bản mới của Antigravity SEO Kit và giải thích mô hình đóng gói bảo mật thương mại (Commercial Packaging & Security).

🔒 1. Mô Hình Phân Phối Bảo Mật Thương Mại

Để bảo vệ các tài nguyên độc quyền (Agents, Skills, Workflows, Rules, Scripts) không bị lộ ra công cộng thông qua registry NPM, dự án SEO Kit được phân tách thành 2 phần độc lập:

                  ┌───────────────────────────────┐
                  │      Thư mục nguồn SEO Kit    │
                  └───────────────┬───────────────┘
                                  │
         ┌────────────────────────┴────────────────────────┐
         ▼ (NPM Publish)                                   ▼ (pack-assets)
┌─────────────────────────────────┐               ┌─────────────────────────────────┐
│     NPM Package (Public)        │               │   Assets Tarball (Private)      │
│  - Chỉ chứa CLI Wrapper         │               │  - Chứa toàn bộ .agents/        │
│  - Không chứa mã nguồn độc quyền│               │  - Bảo vệ trên License Server   │
│  - Cài qua `npx`                │               │  - Tải về qua License Key       │
└─────────────────────────────────┘               └─────────────────────────────────┘

1. NPM Package Công Khai (antigravity-seo-kit trên npmjs.com):
   • Chỉ đóng gói các tệp điều hướng CLI thuộc thư mục bin/ và lib/.
   • Trường "files" trong package.json quy định chặt chẽ chỉ công khai bin/ và lib/, tuyệt đối không chứa thư mục mã nguồn .agents/.
2. Assets Tarball Độc Quyền (seo-kit-assets-{version}.tar.gz trên License Server):
   • Lưu trữ toàn bộ thư mục tài nguyên .agents/.
   • Yêu cầu xác thực qua header X-License-Key tại endpoint API server trước khi cho phép tải về.

📋 2. Quy Trình 7 Bước Phát Hành Không Rủi Ro (Zero-Risk Release Pipeline)

Khi phát hành một phiên bản mới, nhà phát triển bắt buộc phải tuân thủ nghiêm ngặt 7 bước sau:

Bước 1: Cập nhật số phiên bản

• Cập nhật trường "version" trong package.json (ví dụ: "version": "4.1.4").
• Thêm tiêu đề phiên bản và tóm tắt nội dung thay đổi vào CHANGELOG.md.

Bước 2: Đóng gói tài nguyên Assets (.agents/)

Chạy kịch bản nén thư mục tài nguyên thành tệp .tar.gz:

npm run pack-assets

Lệnh này tạo ra file dist/seo-kit-assets-{version}.tar.gz. Quá trình này tự động loại bỏ các file .env cá nhân và chỉ giữ lại .env.example.

Bước 3: Chạy bộ kiểm thử tích hợp (MANDATORY VERIFICATION)

Tuyệt đối không được bỏ qua bước kiểm thử tự động:

npm test

Bộ kiểm thử sẽ chạy song song 3 kịch bản:

• installer.test.js: Kiểm tra logic installer và tương thích ngược.
• test_live_install.js: Chạy mock server cục bộ kiểm thử cài đặt thực tế cả 2 phương pháp.
• test_verify_agents.py: Kiểm tra định dạng frontmatter của 25 Specialist Agents.

Bước 4: Đóng gói package NPM

npm run pack-npm

Tạo ra tệp package CLI dist/antigravity-seo-kit-{version}.tgz.

Bước 5: Upload Assets Tarball lên Server

Upload file dist/seo-kit-assets-{version}.tar.gz lên License Server của Solann để cung cấp cho API endpoint tải tài nguyên bản quyền.

Bước 6: Publish lên NPM Registry

cd e:\SynologyDrive\SEOKit\seo-kit
npm publish

Nhập mã xác thực OTP từ thiết bị của bạn để hoàn tất xuất bản package lên registry NPM.

Bước 7: Gửi thông báo Telegram tự động

Chạy script gửi thông báo phát hành chính thức tới kênh Telegram:

node scripts/notify-telegram.js

Script tự động đọc TELEGRAM_BOT_TOKEN và TELEGRAM_CHAT_ID từ file .env cục bộ để phát tin thông báo.

⚡ 3. Chuỗi Lệnh Tóm Tắt (Quick Command Reference)

# 1. Đóng gói assets và npm package, sau đó chạy toàn bộ test suite
npm run pack-all && npm test

# 2. Upload file assets-*.tar.gz trong dist/ lên License Server

# 3. Publish package CLI lên NPM
npm publish

# 4. Gửi thông báo Telegram phát hành
node scripts/notify-telegram.js