sdk: use lumibase as the default client in standalone examples and Next.js tutorial

[khuepm]

Execution hiện hành — A03 Ready

🔎 Reviewer — Handoff exact-file và acceptance: #334 (comment). #332 đã Completed sau PR #468; lane A chờ session ACK, được bắt đầu scope A03. B02 độc lập. Quy tắc Git hiện tại: không tạo nhánh, tích hợp main tuần tự. Phần dependency/grant cũ bên dưới được thay bằng handoff này.

Parent: #331. Approved scope — 2026-09-06.

Outcome / acceptance

• New consumer/example/tutorial default is SDK imports from lumibase, installed as a runtime dependency; keep @lumibase/sdk compatibility and its explicit typegen override.
• examples/nextjs-blog runs independently of the monorepo, without workspace:* or undocumented setup. Audit apps/consumer before changing it; do not invent a second starter.
• Use existing SDK commands/createLumiClient; raw fetch is an optional alternative, not the primary onboarding path.
• Document backend/Studio prerequisite, site selection and safe public/least-privilege credentials; no admin token in browser bundles.
• At least one verified example demonstrates lumibase types --check in CI where typegen applies.
• Real install and published-content read evidence, plus compatible @lumibase/sdk coverage, feed v1 RC: validate unified npm packages and scaffolder compatibility #448. EN/VI Next.js tutorial changes land together after the contract is fixed, coordinated with docs: clarify create-lumibase starter vs full CMS vs lumibase CLI onboarding #333.

Dependencies: #450 then accepted #332 consumer contract. Lane A, not dispatched; exact file grants later. SDK changes only when needed for acceptance. Shared docs/manifests/workflows are coordinator-reserved.

Previous @lumibase/sdk-default proposal — superseded

Parent: #331

Problem

Tutorials still present raw fetch as an equal alternative to @lumibase/sdk. That weakens the “every consumer project installs the SDK” install surface and skips typegen / typed commands.

Proposed work

• Make @lumibase/sdk the default client path in docs/en/tutorials/nextjs-quickstart.md (and VI).
• Keep raw fetch only as a short “without the SDK” footnote if needed.
• Ensure examples (examples/nextjs-blog, apps/consumer) document install of @lumibase/sdk and show a CI snippet for lumibase types --check where typegen applies.

Acceptance

• Primary code samples use createLumiClient / SDK commands.
• Examples’ README (or docs) tell readers to install @lumibase/sdk.
• At least one example or tutorial shows lumibase types --check in CI.

[khuepm]

🔎 Reviewer — Handoff A-03 / 2026-09-13 — Ready, chờ session ACK

Canonical #334; parent #331. A02 #332 đã đóng Completed, PR #468 merge vào main tại d280771. Có thể bắt đầu A03 song song với B02; không phụ thuộc implementation MCP.

Mục tiêu

Copy example ra ngoài monorepo → cài dependency thật → chạy Next.js → đọc bài published từ CMS/Studio theo contract A02. lumibase là runtime dependency và client mặc định; giữ đường dùng @lumibase/sdk tương thích.

Đã kiểm source main: examples/nextjs-blog/package.json còn @lumibase/sdk: workspace:*; src/lib/lumi.ts dùng plugin GraphQL; quickstart vẫn dạy fetch trước SDK. Không thay import rồi coi là hoàn tất.

Exact-file grant của A03

• examples/nextjs-blog/package.json
• examples/nextjs-blog/.env.example
• examples/nextjs-blog/README.md
• examples/nextjs-blog/src/lib/lumi.ts
• examples/nextjs-blog/src/app/page.tsx
• examples/nextjs-blog/src/app/posts/[id]/page.tsx
• examples/nextjs-blog/tsconfig.json
• examples/nextjs-blog/next.config.mjs
• examples/nextjs-blog/lumibase.config.ts (mới, chỉ nếu typegen cần)
• examples/nextjs-blog/src/lumibase.generated.ts (mới, output typegen nếu áp dụng)
• docs/en/tutorials/nextjs-quickstart.md + docs/vi/tutorials/nextjs-quickstart.md, stamp bằng script hiện có.

Audit apps/consumer read-only trước; không mặc định biến harness dev đó thành starter thứ hai. Không sửa CMS/MCP/harness, SDK/CLI/scaffolder, root lock/manifests/workflows hoặc docs getting-started trong lượt này. Nếu cần lockfile, dependency hay provenance phụ ngoài danh sách, trả exact diff để coordinator tích hợp tuần tự; PR #467 đang giữ phần dependency chung.

Chốt hướng kỹ thuật

Dùng SDK REST theo contract A02 làm luồng mặc định nếu public GraphQL chưa hỗ trợ (#356); không kéo #356 vào scope. Token đặc quyền chỉ phía server, không vào NEXT_PUBLIC/bundle. Contract posts/seed bám starter đã nghiệm thu; không tạo backend provisioner mới.

Nghiệm thu

1. Cài và build/typecheck ở thư mục tạm ngoài workspace, không workspace:* hoặc link node_modules monorepo; ghi phiên bản npm artifact thực đã dùng. Pack local và registry install báo riêng; chưa publish thì không ghi đã ship.
2. CMS/Studio thật với DB riêng: published hiện ở list/detail, draft không lộ; cập nhật/publish được phản ánh đúng cơ chế cache đã ghi. Site sai/quyền thiếu không trả nội dung site khác. HTTP 500 không được tính là pass cho negative test.
3. Có lệnh typegen và lumibase types --check chạy thật: schema đúng exit 0; drift có chủ đích làm check fail. CI snippet được chạy trong môi trường kiểm chứng; không cần sửa root workflow chỉ để thêm snippet.
4. Compatibility smoke import từ @lumibase/sdk; EN/VI đồng bộ và stamp; đầy đủ env/setup/cache prerequisites. Bằng chứng chuyển sang v1 RC: validate unified npm packages and scaffolder compatibility #448, không tự đóng release gate.

Nhận việc / bàn giao

Owner dự kiến lane A; chưa gán session hay tuyên bố đang chạy. ACK session/checkout/base SHA/phạm vi, rồi triển khai. Không tạo nhánh mới theo chỉ thị chủ repo; dùng checkout cô lập không chồng working tree B02, coordinator tích hợp tuần tự lên main. Không tự checkout/reset/stash cây làm việc hiện tại. Bàn giao commit/diff, lệnh + exit code, artifact versions, môi trường và phần chưa kiểm; verifier kiểm DoD trên đúng revision. Không nhận đồng thời #333.

[khuepm]

🛠 A03 — bàn giao, chờ verifier

Nhánh: feature/334-lumibase-default-example (base 6a20441a, main)
Commits: 221ab4c4 (example) · d417b617 (docs EN+VI)

⚠️ Handoff ghi "không tạo nhánh, tích hợp tuần tự lên main". Chủ repo chỉ thị trực tiếp trong phiên này là tạo nhánh mới, nên tôi làm theo chỉ thị đó. Coordinator quyết định cách tích hợp.

Môi trường kiểm chứng

CMS 1.0.0-rc.1 chạy thật (apps/cms/src/serve.ts, docker mode), DB riêng lumibase_a03 trên postgres 16 (đã drop sau khi xong). Node v26.0.0. search/storage unhealthy (không chạy Meili/MinIO) — không ảnh hưởng luồng đọc item.

Seed: collection posts (title/body/author), 2 item published + 1 draft.
Credential: API key lbk_… gắn role → policy read trên posts với rule {"status":{"_eq":"published"}}.

1. Cài đặt & build ngoài workspace ✅

Artifact pnpm pack (không phải npm pack — chỉ pnpm rewrite workspace:* → 1.0.0-rc.1, khớp pnpm publish của release.yml):
lumibase-1.0.0-rc.1.tgz, lumibase-sdk-1.0.0-rc.1.tgz.

Copy example ra thư mục tạm ngoài repo → npm install <2 tarball>:

• không còn workspace:*; không symlink nào trỏ vào monorepo (chỉ .bin/lumibase cục bộ)
• tsc --noEmit → exit 0
• next build → thành công, prerender đúng 2 id published, draft không có

Đây là local pack, CHƯA publish lên registry — không ghi nhận là đã ship. Registry install cần báo riêng sau khi publish.

2. CMS/Studio thật ✅

• List/detail hiển thị bài published; meta.total đúng
• Draft không lộ: grep toàn bộ output build → 0 kết quả; request trực tiếp id draft → 404
• Token không vào bundle client: grep key trong .next/static → 0 kết quả
• Negative (không có 500 nào): draft by id 404 · ghi 403 · sai site 401 · không token 401
• Cache: publish → API thấy ngay, trang vẫn phục vụ bản cache; revalidate đúng ở ~56s với revalidate = 60

3. Typegen & types --check ✅

• lumibase types → exit 0, sinh src/lumibase-types.d.ts (import từ lumibase), đã commit
• --check schema khớp → exit 0
• Thêm field subtitle (drift có chủ đích) → exit 1; xoá field → exit 0 trở lại
• CI snippet nằm trong README + tutorial; không sửa root workflow

🔴 Phát hiện quan trọng: GET /api/v1/typegen/schema nằm sau STUDIO_ACCESS_PATH_PREFIXES (middleware/studio-access.ts) vốn đòi user principal. API key bị 403 kể cả khi policy đã cấp schema:read. Typegen phải dùng token của staff user; API key chỉ-đọc dành cho lượt đọc runtime. Đã ghi rõ trong README + tutorial EN/VI.

4. Compatibility & docs ✅

Smoke test: createLumiClient/legacyRest/LumiError import từ @lumibase/sdk và lumibase là cùng object (=== true), cùng trả 2 bài published.

Docs EN+VI: parity 0 problems · verify 26 claims, 0 stale · stamp-pair --verified → cả hai v3, contentHash/sourceHash/codeVerifiedHash = 8517ebf6d2842ff5 · detect 148/148 up-to-date, 0 conflicts · artifacts đã revert.

Đã sửa một claim sai có sẵn trong tutorial: createClient(...).items(c).readMany(...) không tồn tại trong SDK. Cũng bỏ status khỏi danh sách field tự khai (nó là cột dựng sẵn), và thêm chuỗi policy/role least-privilege đã chạy verbatim thành công.

Có waiver check-parity: allow code-fences (kèm lý do, ở cả hai locale): các block giống hệt nhau từng byte trừ comment cuối dòng đã dịch; check-parity strip comment cả dòng chứ không strip comment cuối dòng.

Ngoài phạm vi / cần người khác xử lý

1. Bug CMS (DoS): request với X-Lumi-Site không tồn tại trả 401 đúng, nhưng ghi audit log sau đó vi phạm FK lumibase_audit_log_site_id_lumibase_sites_id_fk (23503) và làm chết cả process. Remotely triggerable bằng 1 header sai. Không thuộc grant A03.
2. next@^15.5.19: npm audit báo 2 lỗi (1 high) — đều là postcss transitive, chỉ hết khi lên Next 16 (major, ngoài grant). Không tự nâng.
3. Phải thêm src/app/layout.tsx (thiếu root layout ⇒ example không build được độc lập) và dùng lumibase.config.json (grant ghi .ts, nhưng CLI chỉ đọc .json).

Bằng chứng chuyển sang #448; không tự đóng release gate. Chưa nhận #333.