Skip to content

RFC 0004: Publish lên npmjs với scope @tasco-fe ​

  • Trạng thái: Accepted
  • Người đề xuất: Core team
  • Ngày: 2026-11-10

Bối cảnh & vấn đề ​

Các package @tasco/* hiện chỉ publish lên GitLab Package Registry (access: restricted). Muốn phát hành lên npmjs thì gặp hai trở ngại:

  • Scope @tasco trên npmjs đã có chủ. Kiểm tra ngày 2026-11-10 bằng npm org ls: tasco trả 200 (đã đăng ký), còn tên bịa trả 404 Scope not found. Không dùng được, chưa biết ai giữ.
  • Code còn gắn hạ tầng nội bộ: nuxt-layer-base (server/utils/iam.ts, routes/auth/login.post.ts), data của @tasco/mcp (docs.json, primitives.json chứa link web.docs.vtii.vn), template của @tasco/cli (.gitlab-ci.yml, _npmrc, docker-compose.*, .mcp.json).

@tasco-fe còn trống (cùng ngày, kiểm tra cùng cách, kèm đối chứng).

Đề xuất ​

  1. Đăng ký org npm @tasco-fe (bước thủ công trên npmjs.com, người có quyền của công ty thực hiện).
  2. Đổi tên 10 package @tasco/* → @tasco-fe/*, phát hành thành major 3.0.0 (breaking: đổi mọi import và extends).
  3. Tên nội bộ không đổi: tasco:<khu>:<tên>, $tasco<Tên>, --tasco-*, tiền tố Tasco/C*.
  4. Tách mọi host nội bộ ra cấu hình (runtimeConfig, biến môi trường), không để giá trị mặc định trỏ hạ tầng nội bộ.
  5. Release qua GitLab CI như hiện tại, đổi .npmrc sang registry.npmjs.org với granular token chỉ có quyền publish scope @tasco-fe, đặt Protected và Masked.

Kết quả rà soát tham chiếu nội bộ (2026-11-10) ​

Quét packages/ (bỏ test, story, CHANGELOG, node_modules, dist):

NơiTham chiếuCách xử lý
nuxt-layer-basebaseURL mặc định đã rỗng (cấu hình qua env). Còn ví dụ host IAM nội bộ trong comment (nuxt.config.ts, iam.ts), README; mock dev dùng email miền nội bộ; đường dẫn endpoint mặc định (/auth/auth/login-v1, /iam/user/userInfo…) khớp IAM nội bộThay bằng ví dụ trung lập; cân nhắc để endpoint mặc định rỗng hoặc chuyển sang preset
@tasco/cli templates_npmrc, .gitlab-ci.yml (host GitLab, registry), docker-compose.*, _env.example, .mcp.json, scripts/deploy-prod.shBiến hoá bằng placeholder/prompt khi scaffold, hoặc tách sang template nội bộ
@tasco/mcp codeDOCS_ORIGIN = https://web.docs.vtii.vn (links.ts, server.ts)Đổi theo domain docs công khai hoặc cấu hình qua env
@tasco/mcp datadocs.json: ~1.486 link web.docs.vtii.vn + 18 chỗ host GitLab nội bộ (từ trang docs hướng dẫn cài registry và clone repo); components.json: 17, primitives.json: 52 linkĐã làm: scripts/generate.ts thay host nội bộ bằng <host-noi-bo> khi ghi data (src/redact.ts), email ví dụ trong docs đổi sang example.com. Hướng dẫn cài qua GitLab sẽ viết lại khi đổi sang registry npm
README các packageLink docs, URL AI gateway và API gateway nội bộĐổi sang ví dụ trung lập

Chưa xác định: docs web.docs.vtii.vn đã công khai chưa, và host GitLab nội bộ có lộ ra ngoài ý muốn không.

Endpoint và mapping IAM mặc định (đã đánh giá) ​

runtimeConfig.auth mặc định khớp IAM Tasco: đường dẫn (/auth/auth/login-v1, /iam/user/userInfo…), field response (body.tokenData.access_token, listRole, authorization) và mã authenMethod. Host để trống (baseURL: ''), nên bản công khai không tự gọi tới hạ tầng nào; lộ ra chỉ là hình dạng API, và hình dạng đó đã nằm trong docs công khai.

  • Làm ngay (không breaking): thay ví dụ mang định danh nghiệp vụ nội bộ (mã role và permission URI thật) bằng ví dụ trung lập ORDER_ADMIN, /orders/* trong comment, JSDoc và docs.
  • Giữ nguyên mặc định ở 3.0: đổi sang rỗng làm mọi team đang dùng mặc định phải đặt thêm ~12 biến NUXT_AUTH_*, lợi ích bảo mật thấp. Nếu về sau muốn layer trung lập, thêm auth.preset: 'tasco' ở bản minor, rồi mới đổi mặc định ở major sau.

Câu hỏi mở (cần chốt trước khi Accepted) ​

  • Công khai hay private? Đã chốt (2026-11-10): công khai. Org @tasco-fe đã đăng ký, dùng gói Free (chỉ publish được package công khai) → access: public. Phải xử lý hết mục "Kết quả rà soát" dưới đây trước khi publish.
  • License Đã chốt (2026-11-10): MIT, thêm file LICENSE ở gốc và trong từng package.
  • Có giữ publish song song lên GitLab (scope cũ @tasco) cho các team còn ở major 2 không.

Tác động ​

  • Team sản phẩm: đổi import, extends, .npmrc, lockfile; có hướng dẫn migration 2.x → 3.0 trong docs.
  • Docs, CLAUDE.md, template CLI, data MCP, rule ESLint noDirectAntdv đều nhắc tên scope.
  • @tasco/miniapp-sdk (project khác cùng group GitLab) không thuộc phạm vi RFC này.

Việc cần làm ​

  1. Tách cấu hình nội bộ khỏi code và template; quét bí mật (gitleaks) trước khi công khai.
  2. Đổi tên package, import, template, data MCP, docs; thêm repository, homepage, bugs, engines, sideEffects, LICENSE.
  3. CI: pnpm pack --dry-run kiểm tra danh sách file; smoke test cài nuxt-layer-base vào app sạch trước publish.
  4. Publish thử tag beta (3.0.0-beta.0), một team cài thử, rồi mới latest.
  5. Cập nhật docs/core/npmrc.md, docs/core/releasing.md.

Rủi ro & rollback ​

  • Bản đã publish lên npm không gỡ được sau 72 giờ và không dùng lại được số version: bắt buộc qua beta.
  • Lộ code/kiến trúc BFF–IAM nếu chọn công khai mà chưa tách cấu hình.
  • Rollback: ngừng publish lên npm, deprecate các bản 3.x đã đẩy, team sản phẩm ở lại major 2 trên GitLab.