@gemboss/gem-framework 0.4.0

package/README.md

@@ -0,0 +1,42 @@
+# @gemboss/gem-framework
+
+gem-framework của GemTheme đóng thành package, cho các repo **ngoài** monorepo gemtheme (đầu tiên:
+`gemlabs-gemfactory`, tên cũ `gemtheme-designlab`). Build từ mã nguồn trong repo này; đừng sửa gì ở `dist/`.
+
+| Cổng vào | Là gì | Nguồn |
+|---|---|---|
+| `@gemboss/gem-framework` | token, `createGemThemeCss`, runtime, manifest, bộ kiểm framework. Từ 0.3.4 manifest khai họ `gem-cart-line-item` (khối, `__media`, `__details`, `__title`, `__variant`, `__plan`, `__meta`, `__remove`, `__quantity`, `__price`): framework vốn style và adapter Shopify vốn render nó, nên section dùng markup dòng giỏ của framework không còn bị `unknown_gem_class` | `packages/gem-framework/src` |
+| `…/sections` | 4 hàm `headless.tsx` được import (`elementOverrides`, `imageSrcSet`, `subscriptionPlans`, `defaultPlan`) | `packages/gem-sections/src` |
+| `…/section-gate` | `validateSectionArtifacts`: ĐÚNG bộ kiểm section gemtheme dùng khi duyệt. Từ 0.3.0 thêm ba cổng của thư viện cho MỘT section: `layoutKnobCheck` (+ `LAYOUT_ATTRS`), `slotContractDrift` (+ `slotsReadBy`, `slotSourceFromElementTree`), `cssPairingOrphans` (+ `classesStyledBy`, truyền CSS từ `createGemThemeCss`). Từ 0.3.2 thêm hai cổng pháp lý: `fabricatedProofInSource` / `fabricatedProofInSchema` (điểm, số lượt, người, lời hứa bịa) và `inventedTestimonyIn` (hằng DEMO_*_QUOTE/REVIEW… làm giá trị khi thiếu dữ liệu). Từ 0.3.3 hai cổng này đọc được tiếng Việt ("4,8/5", "đã bán", "miễn phí vận chuyển", "199k", cả chữ NFD), tra giá trị của `DEMO.<key>` ở mọi chỗ đọc nó (`??`, `\|\|`, toán tử ba ngôi, dòng bị Prettier ngắt), và bỏ qua số lượng hiển thị (`reviews_to_show`…). Nâng từ 0.3.2 lên có thể làm đỏ section trước đó xanh: đó là lời khẳng định nằm trong DEMO. Từ 0.3.5 bắt thêm chữ ký người Việt (tên kèm nơi chốn như "Chị Lan, Hà Nội", hoặc họ + Thị/Văn như "Nguyễn Thị Hoa"; tiêu đề viết hoa từng chữ thì không), điểm sao ("4,9 ★"), `rating: 4.9` / `reviewCount: "1.284"` trong mảng sản phẩm mẫu, và hằng demo ở nhánh else của toán tử ba ngôi (`bound ? [] : DEMO_REVIEWS`). Mỗi thứ bịa chỉ báo MỘT lần: tại dòng DEMO nếu dòng đó tự lộ, không thì tại chỗ đọc. "đồng hồ" không còn bị đọc là giá. Từ 0.3.6 bắt lời hứa có thời hạn đứng sau từ khoá ("Dùng thử 30 ngày", "Bảo hành 12 tháng", "Nhận trong 2–4 ngày", "Giao 2 giờ") và "hoàn tiền" không kèm số; "Chính sách hoàn tiền" vẫn là nhãn. Từ 0.3.7 câu hỏi (kết thúc bằng "?") không bao giờ là lời hứa, "không hợp lệ"/số bước/nhịp giao không bị báo, và bắt thêm "trong vòng N ngày", "Giao hàng 2–4 ngày", "Bảo hành 1 đổi 1…", "Try it free for 30 days", "Ships in 24h". Từ 0.3.8 xuất thêm `claimIn` (câu hỏi "một chuỗi này có phải lời khẳng định, người bịa, hay lời hứa?"). Từ 0.3.9 bắt "cancel anytime", "guaranteed delivery", "huỷ bất cứ lúc nào" (chính sách huỷ gói và giao hàng). Từ 0.3.10 lời từ chối ("cannot be canceled", "Không thể hủy") không bị báo, "giao dịch/giao diện" không phải giao hàng, "Delivery not guaranteed" là lời miễn trừ, một chuỗi chỉ gồm con số viết tắt ("199k", "12k+") mang nhãn trung tính "hardcoded figure" (không phân biệt được giá với số đếm), và `stringLiteralsIn(line)` thay cho hằng `STRING_LITERAL` (đã gỡ: một regex `/g` dùng chung rò `lastIndex`; 0 chỗ dùng ở gemboss/gemfactory/gemsite). Từ 0.3.11 "Huỷ bỏ lọc…" và "Hủy đơn, gọi chúng tôi bất cứ lúc nào" không bị đọc là chính sách huỷ; "huỷ đăng ký" là bỏ nhận tin (như "Unsubscribe anytime"); `SOURCE.json` ghi `gemtheme_dirty`, và `npm pack` từ chối khi ĐẦU VÀO của gói (`packages/`, gói này trừ `package.json`, `scripts/lib/`) có thay đổi chưa commit hoặc git không trả lời được. Từ 0.3.12 bắt lời hứa hoàn tiền không có chữ "hoàn tiền" liền nhau ("nhận lại toàn bộ tiền", "Hoàn lại 100% tiền", "Trả lại tiền nếu không hài lòng"); lời từ chối ("Không được hoàn lại tiền") và tiền thừa/thối khi thanh toán không bị bắt Từ 0.4.0: `demoOutsidePreview(tsx)` (chữ mẫu DEMO chỉ hiện trong bản xem trước, tức khi `section.demo === true`; plan xuất bản không bao giờ mang cờ đó) và schema `SectionSpec` khai trường `demo` | `packages/gem-sections/src/section-artifacts.ts`, `section-contract.ts` |
+| `…/settings-schema` | `validateSettingsSchema` | `scripts/lib/settings-schema-contract.mjs` |
+| `…/gem-framework.css`, `…/gem-runtime.js` | CSS token mặc định + runtime mọi plugin, dựng sẵn | build |
+
+## Cài
+
+```bash
+npm i @gemboss/gem-framework   # npmjs công khai, cùng scope với @gemboss/ui; không cần token
+```
+
+Tới 29/09/2026 gói tên `@chriskoh26/gem-framework` và chỉ nằm ở GitHub Packages. Registry đó đòi token kể cả
+khi CÀI, nên build trên Railway không kéo được, và GemFactory phải chép tay file `.tgz` vào `vendor/`: nó đứng
+ở 0.3.2 trong khi gói đã lên 0.4.0 mà không gì báo. Chuyển sang npmjs công khai (Chris chốt scope `@gemboss`)
+thì mọi repo cài theo version, và bị tụt thì thấy ngay ở số version. Mã trong gói là CSS và runtime vốn đã tới
+trình duyệt của người mua, cộng bộ kiểm; `license: UNLICENSED` giữ nguyên (xem được, không có quyền dùng lại).
+
+## Phát hành
+
+Một lệnh, chạy trên máy, không dùng GitHub Actions (Chris chốt 30/09/2026: không trả tiền runner):
+
+```bash
+# 1. nâng version trong dist-packages/gem-framework/package.json qua một PR, merge vào main
+# 2. rồi, ở bất kỳ đâu trong checkout gemtheme:
+bash scripts/publish-gem-framework.sh
+DRY_RUN=1 bash scripts/publish-gem-framework.sh   # chạy mọi phép kiểm + npm publish --dry-run, không gửi gì
+```
+
+Script build từ một worktree tạm ở `origin/main` (không bao giờ từ cây đang sửa), từ chối nếu version đã có trên
+npm, từ chối nếu `dist/SOURCE.json` không ghi đúng sha `origin/main` và `gemtheme_dirty: false`, tự `npm login` khi
+phiên hết hạn, rồi `npm publish`. npm hỏi mã từ app xác thực của tài khoản `gemboss`: đó là bước duy nhất phải có
+người. Đổi luật kiểm (manifest, validation,
+section-artifacts) là đổi **minor**: repo dùng package sẽ thấy cảnh báo mới sau khi lên version. Trước khi đổi
+version, xem `npm view @gemboss/gem-framework versions`: phiên khác có thể đã lấy số đó.

package/dist/SOURCE.json

@@ -0,0 +1,7 @@
+{
+  "package": "@gemboss/gem-framework",
+  "version": "0.4.0",
+  "gemtheme_sha": "6c4690cdfe8c48e980cb55d8455370bb39a60701",
+  "gemtheme_dirty": false,
+  "framework_version": "0.1.0"
+}