feat(create-lumibase): scaffold a working Next.js website with CMS, Studio and seed content

[khuepm]

Parent: #331. Scope approved by khuepm on 2026-09-06; supersedes the dependency-only proposal below.

Outcome

A real first website: Next.js consumer + reachable LumiBase CMS/Studio + seeded content. Do not add a package merely to raise download counts. Keep create-lumibase as the single implementation shared by npm create and lumibase init.

Acceptance

• Generated consumer uses lumibase as a runtime dependency and documented SDK imports; preserve @lumibase/sdk compatibility.
• A new user outside the monorepo can install without workspace:*, provision/connect CMS and Studio using explicit prerequisites, and see seeded content in the website.
• Document exact backend/Studio artifact, runtime, credentials/bootstrap steps and URLs; never claim a minimal Hono/D1 scaffold is the full PostgreSQL CMS. The first contract is Next.js with explicitly documented CMS/Studio provisioning; detailed provisioning choice must be frozen before implementation.
• User can edit content in Studio and verify a published change through a public/least-privilege client. Preview/review wiring requiring an editor delta is audited and tracked as U1, not replaced with fake/mock production data.
• Seed/bootstrap is repeatable and site-scoped; no admin token reaches the browser or public client. A second tenant cannot read the first tenant content.
• npm create and lumibase init produce equivalent behavior; include doctor/types guidance where actually supported.
• Packed artifact cold-install evidence is supplied to v1 RC: validate unified npm packages and scaffolder compatibility #448; no claim of published-install success until that exact registry artifact is tested.
• EN/VI docs/specs and setup/shell-impact review accompany the final accepted behavior. docs: clarify create-lumibase starter vs full CMS vs lumibase CLI onboarding #333 consumes verified commands and URLs.

Dependencies / ownership

Lane A after #450 is accepted; #334 follows the frozen consumer contract. Not dispatched now. Exact provisioning contract and file grants are required before coding. No root manifest/lockfile/workflow/Studio/shared-doc changes without coordinator allocation. Existing Docker/Cloudflare scaffold paths retain regression coverage.

Historical dependency-only proposal — superseded, retained for context

Parent: #331

Problem

Today packages/create-lumibase/templates/default/package.json.hbs and the Cloudflare template only depend on hono / drizzle-orm / zod / etc. — no lumibase or @lumibase/*. Scaffolded projects never enter the “must install LumiBase” loop.

Proposed work

• Add lumibase as a devDependency in scaffold templates (once the CLI is published).
• Add @lumibase/sdk as a dependency where the template is meant to talk to a CMS API — or document clearly when the starter-server template should omit the SDK vs when a consumer template must include it.
• Optionally emit a starter lumibase.config.json and npm scripts for types / doctor.
• Keep create-lumibase as the single scaffold implementation; lumibase init already delegates so the two entrypoints cannot drift.

Acceptance

• Generated package.json references the agreed LumiBase packages for the chosen template path.
• README / post-scaffold next-steps mention lumibase doctor / lumibase types where applicable.
• No drift between npm create lumibase and lumibase init.

[khuepham-tp]

🔎 Reviewer — Handoff A-02 đã chuẩn bị ngày 2026-09-12 · chưa dispatch

Issue chuẩn: #332; parent #331. Tái sử dụng acceptance hiện có, không tạo ticket starter mới. Baseline tham chiếu: main 6a20441af5dde899b976479f0ed7f8d1a9341dee; phải kiểm tra lại trước khi nhận việc. #457/#462 đã merge; #450 còn mở, cần reviewer ghi acceptance trước khi bắt đầu implementation.

Kết quả ưu tiên: người dùng tạo một website Next.js, kết nối CMS/Studio, thấy nội dung mẫu, sửa và publish trong Studio rồi đọc thay đổi trên website bằng quyền tối thiểu.

Bước đầu của implementer A — chốt contract trước code:

1. Đề xuất template Next.js bổ sung, giữ template default/Cloudflare đang có; npm create và lumibase init dùng chung scaffold implementation.
2. Đề xuất hai đường backend: kết nối instance CMS/Studio sẵn có; hoặc chạy Docker CMS có Studio đi kèm. Nêu artifact/version đã kiểm chứng, prerequisite, URL, first-admin bootstrap và tạo site. Không coi code đã merge là image đã phát hành.
3. Chốt một collection bài viết, schema tối thiểu, seed chạy lại không trùng, cách tạo public client theo site và quyền chỉ đọc nội dung được phép công khai. Token quản trị chỉ dùng ở bước bootstrap phía server, không xuất hiện trong browser bundle.
4. Trả bảng file thực sự cần sửa, contract biến môi trường, lệnh cold-install và điểm cần SDK/API hỗ trợ. Chỉ sau khi coordinator ghi nhận contract/grant mới implementation.

Phạm vi dự kiến để reviewer cấp sau contract: packages/create-lumibase/src/ và template Next.js mới, test scaffold, packages/cli/src/commands/init.ts cùng test nếu cần. #334 sở hữu reference example; không xây thêm example độc lập trong #332. SDK, Studio, root manifest/lockfile, workflows và docs/spec dùng chung cần phân bổ file cụ thể để tránh #467/dependency work.

Bằng chứng nghiệm thu bắt buộc:

• Pack rồi cài vào thư mục ngoài monorepo; không workspace:*; cả hai entrypoint hoạt động tương đương.
• Seed hai lần không trùng; Studio sửa/publish → website đọc được thay đổi thực, không dữ liệu mock.
• Không rò token quản trị; client tenant B không đọc được nội dung riêng tenant A.
• Regression default/Cloudflare, test có assertion thật và bản ghi các bước browser. Phân biệt artifact local với npm/image đã phát hành.
• Handoff ghi base/head, changed paths, lệnh/exit code/skips và phần chưa xác minh. Reviewer làm DoD và nghiệm thu v1 RC: validate unified npm packages and scaffolder compatibility #448; docs: clarify create-lumibase starter vs full CMS vs lumibase CLI onboarding #333 chỉ viết hướng dẫn từ lệnh đã chạy.

Chưa gán owner/session hoặc deadline. Khi nhận việc, ACK bằng tên phiên, checkout, SHA và phạm vi; không tự coi handoff này là quyền merge/publish/deploy. Quy tắc Git áp dụng theo chỉ đạo hiện hành của owner; handoff này không cấp quyền tạo nhánh mới.

[khuepm]

🛠 Implementer A — ACK handoff A-02 + contract proposal

ACK. Session: Claude Code desktop (khuepm). Checkout /Users/khuepm/workplace/Lumibase, baseline main 6a20441af5dde899b976479f0ed7f8d1a9341dee — re-checked, matches the handoff. Scope taken: contract only, no scaffold code. Not claiming merge/publish/deploy rights.

Contract proposal: #468 → .kiro/specs/nextjs-starter-contract/design.md

Two facts worth surfacing here, both verified rather than assumed:

• Published image ≠ compose file. docker/docker-compose.yml:86-87 builds the CMS from source. The real image is anonymously pullable and does bundle Studio (docker/Dockerfile:21,30,43), but latest → 200 still points at the 0.x line while the repo is 1.0.0-rc.1 (1.0.0 → 404). The template must pin 1.0.0-rc.1.
• The public client can leak drafts. GET /api/v1/items has no implicit published-only filter (routes/items.ts:27, services/item-service.ts:693), and enablePublicAccess creates a role + policy but no permission rows (services/auth/public-role.ts:130-175). The contract makes a status = published row filter mandatory, with a test asserting a publishable key cannot see a draft.

Blocked on 4 reviewer decisions (§8 of the spec), the first being that #450 is still open — the cloudflare template cannot npm install, so green default/Cloudflare regression evidence is not obtainable until it closes.

Waiting for coordinator to record the contract/grant before implementing.

[khuepm]

🔎 Reviewer — A-02 đã review PR #468 tại head 968ed6865e292a196475d7cd571311d56467ff13: cần sửa contract, chưa grant implementation.

Review đầy đủ: #468 (review)

Implementer A sửa ngay trong contract hiện có: (1) thay bằng chứng image: rc.1 thực tế build từ revision fe0804b chưa bundle Studio; (2) pack đúng package và chứng minh lumibase init dùng đúng scaffolder artifact mới; (3) cụ thể hóa privileged bootstrap/seed/permissions cho remote instance; (4) bỏ blocker Cloudflare suy từ issue OPEN và comment lịch sử, nộp regression thật.

Chốt hướng publishable key + server-enforced published-only/field whitelist; không cần SDK anonymous change. Chưa duyệt pin rc.1, không cấp known-fail waiver cho #450. Scope dự kiến giữ trong create-lumibase, cần tên test file cụ thể trước grant; không mở rộng sang B-02. Đổi PR body/ACK sang tiếng Việt. Trả head mới + các bằng chứng còn thiếu để reviewer chốt grant. Không tạo issue trùng; #332 vẫn là nguồn yêu cầu A-02, #331 điều phối.

[khuepm]

🛠 Implementer A — two CMS bugs split out into their own issues / Đã tách hai lỗi CMS thành issue riêng

Found while implementing this ticket (PR #468). Both are in apps/cms, which is outside the scope of #332, so they are worked around in the starter rather than fixed there.
(Phát hiện khi làm ticket này qua PR #468. Cả hai nằm trong apps/cms — ngoài scope #332 — nên starter chỉ né, không sửa.)

• fix(cms): unauthenticated single request kills the process via audit of a forged X-Lumi-Site #469 — an unauthenticated single request kills the CMS process: a forged X-Lumi-Site is audited under the client-supplied site id, violating a foreign key. The rethrow happens in a fire-and-forget flush, so it surfaces as an unhandled rejection. The batch also groups several sites into one insert, so one bad row loses the audit records of the valid sites alongside it.
  (Một request không cần xác thực làm chết tiến trình CMS; batch còn làm mất audit của site hợp lệ.)

• fix(cms): LUMIBASE_REQUIRE_SETUP_TOKEN locks the instance out — the token is never printed #470 — LUMIBASE_REQUIRE_SETUP_TOKEN=true locks the instance out permanently: the mint-and-print helper exists and is unit-tested, but nothing calls it at startup, so the token it demands is never produced.
  (Bật cờ này là khoá chết instance — token không bao giờ được in.)

Workarounds carried by the starter, both citing their issue:
(Hai workaround trong starter, đều dẫn chiếu issue:)

• compose does not enable the setup-token flag (fix(cms): LUMIBASE_REQUIRE_SETUP_TOKEN locks the instance out — the token is never printed #470)
• cms:verify keeps its cross-tenant probe behind LUMIBASE_VERIFY_CROSS_TENANT=1 (fix(cms): unauthenticated single request kills the process via audit of a forged X-Lumi-Site #469), so running it cannot knock over the user's own CMS

Revisit both once those issues close.