@ecomcx/create-nexus 0.0.0-stage → 1.24.0

package/README.md

@@ -1,3 +1,14 @@
-# Temporary Holding Version
+# @ecomcx/create-nexus
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+CLI for Ecomcx Nexus CMS themes and plugins: create, validate, pack, test and deploy.
+
+```bash
+npm create @ecomcx/nexus theme "My theme"      # new theme (code; --blocks for a block theme)
+npm create @ecomcx/nexus plugin "My plugin"    # new plugin (plugin.json + one C# file)
+npx @ecomcx/create-nexus validate              # check the package
+npx @ecomcx/create-nexus pack                  # zip for upload / the Store
+npx @ecomcx/create-nexus env up && npx @ecomcx/create-nexus dev   # local CMS, reinstall on save
+```
+
+Themes and plugins import `@ecomcx/nexus-theme-sdk` / `@ecomcx/nexus-admin-sdk`; the scaffold installs them as npm aliases
+(`"@ecomcx/nexus-theme-sdk": "npm:@ecomcx/nexus-theme-sdk@^x.y.z"`). Guides: theme-guide.md and plugin-guide.md in the CMS repository.

package/bin/cms.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// create-cms — tạo, kiểm tra, đóng gói và triển khai theme/plugin cho CMS.
+//   create-cms theme "Tên" [--parent default] [--blocks] [--dir x]
+//   create-cms plugin "Tên" [--admin] [--frontend] [--project] [--no-backend] [--tests] [--dir x]
+//   create-cms validate [thư-mục]
+//   create-cms upgrade [thư-mục]
+//   create-cms pack [thư-mục] [--out dist]
+//   create-cms deploy [thư-mục] [--url …] [--user …] [--password …] [--activate]
+//   create-cms dev [thư-mục] [--url …] [--user …] [--password …]   (tự đóng gói + cài lại khi sửa file)
+//   create-cms env up | status | down [--purge]
+import { CLI } from "../lib/npm.mjs";
+import fs from "node:fs";
+import path from "node:path";
+import { c, parseArgs } from "../lib/util.mjs";
+import { scaffoldPlugin, scaffoldTheme } from "../lib/scaffold.mjs";
+import { validate } from "../lib/validate.mjs";
+import { upgrade } from "../lib/upgrade.mjs";
+import { pack } from "../lib/pack.mjs";
+import { check, deploy } from "../lib/deploy.mjs";
+import { env, findEnv } from "../lib/env.mjs";
+
+const HELP = `${c.bold("create-cms")} — công cụ viết theme/plugin cho CMS
+
+  ${c.cyan('theme "Tên"')} [--parent default]      tạo theme (child theme với --parent; --blocks: dựng bằng khối, sửa trong Trình dựng)
+  ${c.cyan('plugin "Tên"')} [--admin] [--frontend] [--tests]   tạo plugin: plugin.json + một file C# (CMS tự biên dịch)
+                                      --admin / --frontend: thêm giao diện React riêng · --project: dự án csproj · --no-backend
+  ${c.cyan("validate")} [thư-mục]                  kiểm tra theme.json / plugin.json
+  ${c.cyan("upgrade")} [thư-mục]                   đưa project theme/plugin lên SDK mới nhất (@ecomcx/nexus-theme-sdk, @ecomcx/nexus-admin-sdk) rồi kiểm tra lại
+  ${c.cyan("test")} [thư-mục]                      đóng gói + chạy test xUnit trong tests/ trên CMS thử (Cms.Plugin.Testing)
+  ${c.cyan("check")} [thư-mục]                     chạy thử trên CMS: manifest, biên dịch, quét bảo mật (như khi cài / nộp Store)
+  ${c.cyan("pack")} [thư-mục] [--out dist]         đóng gói → dist/<slug>-<version>.zip
+  ${c.cyan("deploy")} [thư-mục] [--activate]       đóng gói + cài lên CMS (--url, --user, --password)
+  ${c.cyan("dev")} [thư-mục]                       tự đóng gói + cài lại mỗi khi sửa file
+  ${c.cyan("env")} up [--dev] [--build DIR] | status | logs [api|builder] [-f] | down [--purge]
+                                      CMS chạy bằng Docker để thử theme/plugin (--dev: sửa là thấy, không build lại)
+
+Mặc định CMS ở http://localhost:5100 (hoặc môi trường của \`env up\`, biến CMS_URL / CMS_USER / CMS_PASSWORD).`;
+
+const args = parseArgs(process.argv.slice(2));
+const [cmd, ...rest] = args._;
+
+/** Thông tin đăng nhập: tham số dòng lệnh → môi trường của `env up` (.cms-env) → biến môi trường (deploy tự đọc). */
+function connection() {
+  const saved = findEnv();
+  return {
+    url: args.url ?? (process.env.CMS_URL ? undefined : saved?.url),
+    user: args.user ?? (process.env.CMS_USER ? undefined : saved?.user),
+    password: args.password ?? (process.env.CMS_PASSWORD ? undefined : saved?.password),
+    activate: !!args.activate,
+  };
+}
+
+function report({ kind, errors, warnings }, dir) {
+  warnings.forEach((w) => console.log(c.yellow("  ! " + w)));
+  errors.forEach((e) => console.log(c.red("  ✗ " + e)));
+  if (errors.length) return false;
+  console.log(c.green(`✓ ${kind === "theme" ? "Theme" : "Plugin"} hợp lệ`) + c.dim(` (${path.relative(process.cwd(), dir) || "."})`));
+  return true;
+}
+
+async function packAndReport(dir) {
+  const r = await pack(dir, { out: args.out });
+  console.log(c.green(`✓ ${path.relative(process.cwd(), r.zipPath)}`) + c.dim(` (${(r.size / 1024).toFixed(0)} KB)`));
+  return r;
+}
+
+/** Theo dõi thay đổi (bỏ dist, node_modules, bin, obj) rồi đóng gói + cài lại; gộp các lần lưu liên tiếp. */
+async function dev(dir) {
+  const conn = connection();
+  let running = false, again = false, timer;
+  const cycle = async () => {
+    if (running) { again = true; return; }
+    running = true;
+    try { await deploy(await packAndReport(dir), { ...conn, activate: true }); }
+    catch (e) { console.log(c.red("✗ " + e.message)); }
+    running = false;
+    if (again) { again = false; cycle(); }
+  };
+  await cycle();
+  // Môi trường `env up --dev` đã gắn thẳng thư mục này vào website: phần website (theme, frontend/ của plugin) tự nạp lại,
+  // chỉ cài lại khi đổi phần cần máy chủ (backend, admin, plugin.json, locales)
+  const mounted = (findEnv()?.dev && (findEnv().mounts ?? []).some((m) => path.resolve(m.dir) === path.resolve(dir)));
+  const live = (file) => mounted && (fs.existsSync(path.join(dir, "theme.json")) || /^frontend[\\/]/.test(file));
+  console.log(c.dim(`• Đang theo dõi thay đổi…${mounted ? " (website tự nạp lại, không cần build)" : ""} (Ctrl+C để dừng)`));
+  const ignored = /(^|[\\/])(dist|node_modules|bin|obj|\.git|\.next)([\\/]|$)/;
+  fs.watch(dir, { recursive: true }, (_e, file) => {
+    if (!file || ignored.test(file)) return;
+    if (live(file)) { console.log(c.dim(`• ${file} — website tự nạp lại`)); return; }
+    clearTimeout(timer);
+    timer = setTimeout(() => { console.log(c.cyan(`\n• ${file} thay đổi`)); cycle(); }, 400);
+  });
+}
+
+try {
+  const dir = path.resolve(rest[0] && !["theme", "plugin", "env"].includes(cmd) ? rest[0] : ".");
+  switch (cmd) {
+    case "theme":
+    case "plugin": {
+      const name = rest[0];
+      if (!name) throw new Error(`Thiếu tên: create-cms ${cmd} "Tên ${cmd}"`);
+      const { root } = cmd === "theme"
+        ? scaffoldTheme(name, { parent: args.parent, dir: args.dir, blocks: !!args.blocks })
+        : scaffoldPlugin(name, { backend: args["no-backend"] ? false : args.project ? "project" : "source", admin: !!args.admin, frontend: !!args.frontend, tests: !!args.tests, dir: args.dir });
+      console.log(c.green(`✓ Đã tạo ${cmd} ở ${path.relative(process.cwd(), root)}`));
+      console.log(c.dim(`  cd ${path.relative(process.cwd(), root)} && npx ${CLI} dev`));
+      break;
+    }
+    case "validate":
+      if (!report(validate(dir), dir)) process.exit(1);
+      break;
+    case "upgrade":
+      // Project tạo từ trước: lên SDK mới nhất rồi kiểm tra lại (validate báo API cũ / khai báo cần CMS mới hơn)
+      await upgrade(dir);
+      if (fs.existsSync(path.join(dir, "theme.json")) || fs.existsSync(path.join(dir, "plugin.json"))) report(validate(dir), dir);
+      break;
+    case "pack":
+      await packAndReport(dir);
+      break;
+    case "deploy":
+      await deploy(await packAndReport(dir), connection());
+      break;
+    case "test": {
+      // Đóng gói → chạy dotnet test cho tests/*.csproj (Cms.Plugin.Testing cài gói lên CMS thử một lần rồi chạy test)
+      const testsDir = path.join(dir, "tests");
+      if (!fs.existsSync(testsDir) || !fs.readdirSync(testsDir).some((f) => f.endsWith(".csproj")))
+        throw new Error("Không thấy tests/*.csproj — tạo bằng: create-cms plugin \"Tên\" --tests (hoặc xem tài liệu Cms.Plugin.Testing)");
+      const pkg = await packAndReport(dir);
+      const conn = connection();
+      const env = { ...process.env, CMS_TEST_PACKAGE: path.resolve(pkg.zipPath), CMS_TEST_SLUG: pkg.manifest.slug,
+        ...(conn.url ? { CMS_URL: conn.url } : {}), ...(conn.user ? { CMS_USER: conn.user } : {}), ...(conn.password ? { CMS_PASSWORD: conn.password } : {}) };
+      const { spawnSync } = await import("node:child_process");
+      const r = spawnSync("dotnet", ["test", testsDir, "--nologo"], { stdio: "inherit", env });
+      if (r.status !== 0) process.exitCode = r.status ?? 1;
+      break;
+    }
+    case "check":
+      if (!(await check(await packAndReport(dir), connection()))) process.exitCode = 1;
+      break;
+    case "dev":
+      await dev(dir);
+      break;
+    case "env":
+      await env(rest[0], args);
+      break;
+    case undefined:
+    case "help":
+    case "--help":
+      console.log(HELP);
+      break;
+    default:
+      console.log(HELP);
+      process.exit(1);
+  }
+} catch (e) {
+  console.error(c.red("✗ " + (e?.message ?? e)));
+  process.exit(1);
+}

package/lib/deploy.mjs

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import { c } from "./util.mjs";
+
+/** Đăng nhập CMS và upload gói zip (dùng cho `cms deploy` / `cms dev`). */
+export async function deploy({ zipPath, kind, manifest }, { url, user, password, activate }) {
+  const base = (url ?? process.env.CMS_URL ?? "http://localhost:5100").replace(/\/$/, "");
+  user ??= process.env.CMS_USER ?? "admin";
+  password ??= process.env.CMS_PASSWORD;
+  if (!password) throw new Error("Thiếu mật khẩu: dùng --password hoặc biến môi trường CMS_PASSWORD");
+
+  const login = await fetch(`${base}/api/auth/login`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ login: user, password }) });
+  if (!login.ok) throw new Error(`Đăng nhập thất bại (${login.status})`);
+  const { accessToken } = await login.json();
+  const auth = { authorization: `Bearer ${accessToken}` };
+
+  const form = new FormData();
+  form.append("file", new Blob([fs.readFileSync(zipPath)], { type: "application/zip" }), zipPath.split("/").pop());
+  const res = await fetch(`${base}/api/admin/${kind === "theme" ? "themes" : "plugins"}/upload`, { method: "POST", headers: auth, body: form });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const details = body.errors ? "\n" + Object.values(body.errors).flat().map((e) => "  - " + e).join("\n") : "";
+    throw new Error(`${body.title ?? "Upload thất bại"} (${res.status})${details}`);
+  }
+  console.log(c.green(`  ✓ ${body.message}`));
+  if (body.restartRequired) await waitHealthy(base);
+
+  if (body.buildId) {
+    process.stdout.write(c.dim(`  • Đang build #${body.buildId}`));
+    for (let i = 0; i < 600; i++) {
+      await new Promise((r) => setTimeout(r, 1000));
+      let b;
+      try { b = await (await fetch(`${base}/api/admin/builds/${body.buildId}`, { headers: auth })).json(); }
+      catch { process.stdout.write("?"); continue; } // CMS đang khởi động lại
+
+      if (b.status === "succeeded") { console.log(c.green(" ✓ build thành công")); break; }
+      if (b.status === "failed") { console.log(c.red(" ✗ build lỗi\n") + (b.log ?? "").split("\n").slice(-25).join("\n")); throw new Error("Build thất bại"); }
+      process.stdout.write(".");
+    }
+  }
+
+  if (kind === "plugin" && activate) {
+    const r = await fetch(`${base}/api/admin/plugins/${manifest.slug}/activate`, { method: "POST", headers: auth });
+    const b = await r.json().catch(() => ({}));
+    if (!r.ok) throw new Error(b.title ?? "Kích hoạt thất bại");
+    console.log(c.green(`  ✓ ${b.message}`));
+    if (b.restartRequired) await waitHealthy(base);
+  }
+  if (kind === "theme" && activate) {
+    const r = await fetch(`${base}/api/admin/themes/${manifest.slug}/activate`, { method: "POST", headers: auth });
+    if (!r.ok) throw new Error(((await r.json().catch(() => ({}))).title) ?? "Kích hoạt theme thất bại");
+    console.log(c.green("  ✓ Đã kích hoạt theme"));
+  }
+}
+
+async function waitHealthy(base) {
+  process.stdout.write(c.dim("  • Chờ CMS khởi động lại"));
+  await new Promise((r) => setTimeout(r, 1500));
+  for (let i = 0; i < 90; i++) {
+    try {
+      const r = await fetch(`${base}/api/health`);
+      if (r.ok && (await r.json()).status === "ok") { console.log(c.green(" ✓")); return; }
+    } catch { /* đang khởi động */ }
+    process.stdout.write(".");
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  throw new Error("CMS chưa khởi động lại sau 90 giây");
+}
+
+/**
+ * Chạy thử quy trình cài trên CMS (manifest, biên dịch mã nguồn, quét bảo mật — giống hệt khi cài và khi nộp Store) mà không cài.
+ * Trả true nếu gói cài được không cần xác nhận rủi ro.
+ */
+export async function check({ zipPath, kind }, { url, user, password }) {
+  if (kind === "theme") throw new Error("check hiện dành cho plugin — theme: dùng validate + deploy");
+  const base = (url ?? process.env.CMS_URL ?? "http://localhost:5100").replace(/\/$/, "");
+  user ??= process.env.CMS_USER ?? "admin";
+  password ??= process.env.CMS_PASSWORD;
+  if (!password) throw new Error("Thiếu mật khẩu: dùng --password, CMS_PASSWORD hoặc `create-cms env up`");
+  const login = await fetch(`${base}/api/auth/login`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ login: user, password }) });
+  if (!login.ok) throw new Error(`Đăng nhập thất bại (${login.status})`);
+  const { accessToken } = await login.json();
+  const form = new FormData();
+  form.append("file", new Blob([fs.readFileSync(zipPath)], { type: "application/zip" }), zipPath.split("/").pop());
+  const res = await fetch(`${base}/api/admin/plugins/check`, { method: "POST", headers: { authorization: `Bearer ${accessToken}` }, body: form });
+  const r = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(r.title ?? `CMS trả ${res.status}`);
+  for (const e of r.errors ?? []) console.log(c.red(`  ✗ ${e}`));
+  for (const e of r.compileErrors ?? []) console.log(c.red(`  ✗ ${e}`));
+  for (const w of r.compileWarnings ?? []) console.log(c.yellow(`  ! ${w}`));
+  if (r.scan) {
+    const tone = { safe: c.green, warning: c.yellow, dangerous: c.red, blocked: c.red }[r.scan.verdict] ?? ((s) => s);
+    console.log(`  • Quét bảo mật: ${tone(r.scan.verdict)} (${r.scan.filesScanned} file)`);
+    for (const f of r.scan.findings ?? []) console.log(`    ${f.severity === "critical" || f.severity === "high" ? c.red("✗") : c.yellow("!")} [${f.severity}] ${f.message}${f.file ? c.dim(` — ${f.file}`) : ""}`);
+  }
+  console.log(r.ok ? c.green(`✓ ${r.slug} ${r.version}: cài được, không cần xác nhận rủi ro`) : c.red(`✗ ${r.slug ?? ""}: chưa đạt — sửa các lỗi trên`));
+  return r.ok;
+}

package/lib/env/Caddyfile

@@ -0,0 +1,58 @@
+# Một tên miền cho cả website, trang quản trị (/admin) và API.
+# SITE_ADDRESS là tên miền (vd example.com) → Caddy tự xin và gia hạn chứng chỉ HTTPS (Let's Encrypt).
+# Mặc định ":80" → HTTP thường: chạy thử trên máy, hoặc đứng sau một proxy khác lo HTTPS (Coolify, Cloudflare…).
+#
+# TRUSTED_PROXIES: dải IP của proxy đứng TRƯỚC Caddy (vd "private_ranges" trên Coolify, hoặc dải IP của Cloudflare).
+# Chỉ khi request đến từ các dải này Caddy mới tin X-Forwarded-For / X-Forwarded-Proto mà proxy đó gửi.
+# Mặc định chỉ tin chính máy (127.0.0.1) = Caddy đứng trực tiếp ngoài Internet.
+{
+	servers {
+		trusted_proxies static {$TRUSTED_PROXIES:127.0.0.1/32}
+		# Đọc X-Forwarded-For từ phải sang trái, bỏ qua các proxy tin cậy → không giả được IP bằng cách tự gửi header
+		trusted_proxies_strict
+		client_ip_headers X-Forwarded-For
+	}
+}
+
+{$SITE_ADDRESS::80} {
+	encode zstd gzip
+
+	# Kênh nội bộ giữa Builder và API (callback build, tải mã theme/plugin) — không mở ra Internet.
+	# Phải là một khối handle đứng trước: Caddy xếp "handle" trước "respond", nên "respond" đứng riêng sẽ không có tác dụng.
+	@internal path /api/internal /api/internal/*
+	handle @internal {
+		respond 404
+	}
+
+	# Route API của website Next.js (bình luận, proxy plugin, xem trước, xoá cache)
+	@frontend_api path /api/cms/* /api/revalidate /api/preview /api/preview/*
+	handle @frontend_api {
+		reverse_proxy builder:3000 {
+			header_up X-Forwarded-For {client_ip}
+		}
+	}
+
+	# CMS API, trang quản trị, file media, file tĩnh của extension, SignalR
+	@cms path /api/* /admin /admin/* /uploads/* /extensions/* /hubs/* /health
+	handle @cms {
+		reverse_proxy api:8080 {
+			# IP thật của người dùng (một giá trị) — API/Builder dùng cho rate limit, chống dò mật khẩu, nhật ký
+			header_up X-Forwarded-For {client_ip}
+			# Bật/tắt plugin backend hoặc cập nhật → API khởi động lại vài giây.
+			# Caddy giữ request và thử kết nối lại thay vì trả lỗi 502: người dùng chỉ thấy chậm một chút.
+			lb_try_duration 45s
+			lb_try_interval 250ms
+		}
+	}
+
+	handle {
+		reverse_proxy builder:3000 {
+			header_up X-Forwarded-For {client_ip}
+		}
+	}
+
+	header {
+		Strict-Transport-Security "max-age=31536000"
+		-Server
+	}
+}

package/lib/env/init-secrets.sh

@@ -0,0 +1,31 @@
+#!/bin/sh
+# Chạy một lần mỗi khi khởi động stack: sinh secret còn thiếu vào volume /secrets (không ghi đè secret đã có).
+# Mỗi file là một khoá cấu hình của CMS (đọc bằng AddKeyPerFile), vd Jwt__Secret.
+# Builder chỉ nhận 3 secret nó cần (volume riêng /builder-secrets) — mã theme/plugin chạy trong Builder không đọc được
+# khoá ký phiên đăng nhập hay mật khẩu database.
+set -eu
+umask 077
+cd /secrets
+gen() { [ -s "$1" ] || head -c 64 /dev/urandom | base64 | tr -dc 'A-Za-z0-9' | head -c "$2" > "$1"; }
+gen db_password 32
+gen redis_password 32
+gen Jwt__Secret 64
+gen Frontend__RevalidateSecret 40
+gen Extensions__BuilderSecret 40
+gen Security__FrontendApiKey 48
+# Chuỗi kết nối DB, Redis dựng từ mật khẩu đã sinh
+printf 'Host=postgres;Database=cms;Username=cms;Password=%s;GSS Encryption Mode=Disable' "$(cat db_password)" > ConnectionStrings__Default
+printf 'redis:6379,password=%s' "$(cat redis_password)" > ConnectionStrings__Redis
+
+# API chạy bằng user "app" (uid 1654); Postgres (uid 70) cần đọc mật khẩu của nó; Redis đọc mật khẩu lúc khởi động (root)
+chown 1654:1654 /secrets/*
+chmod 600 /secrets/*
+chmod 644 db_password
+
+# Secret của Builder: chỉ tiến trình Builder (root) đọc được — mã theme/plugin chạy bằng user "node" thì không
+if [ -d /builder-secrets ]; then
+  for f in Extensions__BuilderSecret Frontend__RevalidateSecret Security__FrontendApiKey; do cp "$f" "/builder-secrets/$f"; done
+  chown 0:0 /builder-secrets/*
+  chmod 600 /builder-secrets/*
+fi
+echo "Secret đã sẵn sàng."

package/lib/env.mjs

@@ -0,0 +1,235 @@
+// Môi trường CMS chạy bằng Docker cho người làm theme/plugin — không cần mã nguồn CMS.
+//   create-cms env up      dựng CMS (Postgres, Redis, API, website, Caddy) + cài đặt sẵn, in tài khoản quản trị
+//   create-cms env status  trạng thái, địa chỉ, tài khoản
+//   create-cms env down    dừng (giữ dữ liệu)  ·  --purge: xoá luôn dữ liệu
+//   create-cms env logs [api|builder|…] [-f]   xem log
+//   --dev        website chạy `next dev`; theme/plugin trong thư mục hiện tại (và thư mục con) được gắn thẳng vào → sửa là thấy
+//   --build DIR  build image từ mã nguồn CMS ở DIR (khi chưa kéo được image dựng sẵn)
+// Tài khoản được lưu ở .cms-env/credentials.json → `create-cms deploy/dev` tự dùng, không cần --password.
+import { CLI } from "./npm.mjs";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { c, readJson, run, write } from "./util.mjs";
+
+const cliDir = path.dirname(fileURLToPath(import.meta.url));
+/** Image dựng sẵn của CMS (đổi bằng --api-image/--builder-image hoặc biến CMS_API_IMAGE/CMS_BUILDER_IMAGE). */
+const DEFAULT_IMAGES = { api: "ghcr.io/ecomcx-jsc/ecomcx-nexus-api:latest", builder: "ghcr.io/ecomcx-jsc/ecomcx-nexus-builder:latest" };
+
+/** Theme/plugin đang viết ở thư mục hiện tại và thư mục con (+ --mount) → gắn vào Builder khi chạy --dev. */
+export function devMounts(args) {
+  const roots = [process.cwd(), ...fs.readdirSync(process.cwd(), { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith(".") && d.name !== "node_modules").map((d) => path.resolve(d.name))];
+  for (const m of [args.mount ?? []].flat()) roots.push(path.resolve(m));
+  const mounts = [];
+  for (const dir of [...new Set(roots)]) {
+    const theme = readJson(path.join(dir, "theme.json"));
+    const plugin = readJson(path.join(dir, "plugin.json"));
+    if (theme?.slug) mounts.push({ kind: "theme", slug: theme.slug, dir, target: `/app/frontend/themes/${theme.slug}` });
+    else if (plugin?.slug && plugin.frontend?.entry) mounts.push({ kind: "plugin", slug: plugin.slug, dir, target: `/dev-plugins/${plugin.slug}` });
+  }
+  return mounts;
+}
+
+/** File cấu hình đi kèm gói (lib/env/) hoặc lấy từ thư mục deploy/ khi chạy trong repo CMS. */
+function asset(name) {
+  for (const p of [path.join(cliDir, "env", name), path.resolve(cliDir, "../../../deploy", name)]) if (fs.existsSync(p)) return fs.readFileSync(p, "utf8");
+  throw new Error(`Thiếu file ${name} của create-cms`);
+}
+
+/** Tìm .cms-env gần nhất (thư mục hiện tại hoặc thư mục cha) — dùng cho deploy/dev. */
+export function findEnv(start = process.cwd()) {
+  for (let dir = path.resolve(start); ; dir = path.dirname(dir)) {
+    const cred = readJson(path.join(dir, ".cms-env", "credentials.json"));
+    if (cred) return cred;
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+
+const compose = (o) => `
+# Sinh bởi create-cms env — môi trường thử cho theme/plugin. Không dùng cho website thật.
+name: ${o.project}
+services:
+  init:
+    image: alpine:3.20
+    command: ["/bin/sh", "/init-secrets.sh"]
+    volumes: [secrets:/secrets, ./init-secrets.sh:/init-secrets.sh:ro]
+    restart: "no"
+  postgres:
+    image: postgres:17-alpine
+    restart: unless-stopped
+    depends_on: { init: { condition: service_completed_successfully } }
+    environment: { POSTGRES_USER: cms, POSTGRES_DB: cms, POSTGRES_PASSWORD_FILE: /secrets/db_password }
+    volumes: [pgdata:/var/lib/postgresql/data, secrets:/secrets:ro]
+    healthcheck: { test: ["CMD-SHELL", "pg_isready -U cms"], interval: 3s, retries: 40 }
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    healthcheck: { test: ["CMD", "redis-cli", "ping"], interval: 3s, retries: 20 }
+  api:
+${o.buildDir ? `    build: { context: ${JSON.stringify(o.buildDir)}, dockerfile: backend/Dockerfile }\n    image: cms-env-api:local` : `    image: ${o.apiImage}`}
+    restart: unless-stopped
+    depends_on: { postgres: { condition: service_healthy }, redis: { condition: service_healthy } }
+    environment:
+      CMS_SECRETS_DIR: /secrets
+      ConnectionStrings__Redis: redis:6379
+      Storage__PublicMediaUrl: ${o.url}/uploads
+      Frontend__PublicUrl: ${o.url}
+      Frontend__RevalidateUrl: http://builder:3000/api/revalidate
+      Extensions__BuilderUrl: http://builder:4100
+      Extensions__CallbackBaseUrl: http://api:8080
+      Setup__AdminUrl: ${o.url}/admin
+      Security__TrustedProxyHosts__0: caddy
+      Cors__Origins__0: ${o.url}
+      Security__FrameAncestors__0: ${o.url}
+    volumes: [storage:/data, secrets:/secrets:ro]
+  builder:
+${o.buildDir ? `    build: { context: ${JSON.stringify(o.buildDir)}, dockerfile: builder/Dockerfile }\n    image: cms-env-builder:local` : `    image: ${o.builderImage}`}
+    restart: unless-stopped
+    depends_on: [api]
+    environment: { CMS_SECRETS_DIR: /secrets, CMS_API_URL: http://api:8080, ADMIN_ORIGINS: ${o.url}, WEB_WORKERS: "1", TRUSTED_PROXY_HOSTS: caddy${o.dev ? ", BUILDER_MODE: dev, BUILDER_DEV_SERVER: \"1\"" : ""} }
+    volumes: [storage:/data, secrets:/secrets:ro${(o.mounts ?? []).map((m) => `, ${JSON.stringify(`${m.dir}:${m.target}:ro`)}`).join("")}]
+  caddy:
+    image: caddy:2-alpine
+    restart: unless-stopped
+    depends_on: [api, builder]
+    environment: { SITE_ADDRESS: ":80" }
+    ports: ["${o.port}:80"]
+    volumes: [./Caddyfile:/etc/caddy/Caddyfile:ro]
+volumes: { pgdata: {}, storage: {}, secrets: {} }
+`;
+
+/** Cổng còn trống trên máy (Docker sẽ báo "port is already allocated" ở bước cuối, sau khi đã tạo container). */
+function portFree(port) {
+  return new Promise((resolve) => {
+    const srv = net.createServer().once("error", () => resolve(false)).once("listening", () => srv.close(() => resolve(true)));
+    srv.listen(port, "0.0.0.0");
+  });
+}
+
+async function waitFor(url, seconds) {
+  const until = Date.now() + seconds * 1000;
+  while (Date.now() < until) {
+    try { const r = await fetch(url, { signal: AbortSignal.timeout(3000) }); if (r.ok) return true; } catch { /* chưa sẵn sàng */ }
+    await new Promise((r) => setTimeout(r, 1500));
+  }
+  return false;
+}
+
+export async function env(action, args) {
+  const dir = path.resolve(args.dir ?? ".cms-env");
+  const credFile = path.join(dir, "credentials.json");
+  const saved = readJson(credFile);
+  const project = saved?.project ?? `cms-dev-${crypto.createHash("sha1").update(dir).digest("hex").slice(0, 6)}`;
+  const dc = (...a) => run("docker", ["compose", "-f", path.join(dir, "docker-compose.yml"), ...a], { quiet: true });
+
+  if (action === "up") {
+    const port = Number(args.port ?? saved?.port ?? 8080);
+    const url = `http://localhost:${port}`;
+    const apiImage = args["api-image"] ?? process.env.CMS_API_IMAGE ?? saved?.apiImage ?? DEFAULT_IMAGES.api;
+    const builderImage = args["builder-image"] ?? process.env.CMS_BUILDER_IMAGE ?? saved?.builderImage ?? DEFAULT_IMAGES.builder;
+    const dev = Boolean(args.dev ?? saved?.dev);
+    const buildDir = args.build ? path.resolve(args.build) : saved?.buildDir;
+    const mounts = dev ? devMounts(args) : [];
+    // Môi trường đang chạy dùng lại cổng của nó; môi trường mới thì cổng phải trống
+    if (!saved && !(await portFree(port))) throw new Error(`Cổng ${port} đang được dùng — chọn cổng khác: create-cms env up --port ${port + 1}`);
+    write(path.join(dir, "docker-compose.yml"), compose({ project, port, url, apiImage, builderImage, dev, buildDir, mounts }));
+    write(path.join(dir, "Caddyfile"), asset("Caddyfile"));
+    write(path.join(dir, "init-secrets.sh"), asset("init-secrets.sh"));
+    write(path.join(dir, ".gitignore"), "*\n"); // tài khoản & cấu hình máy, không đưa vào git
+    if (dev) {
+      console.log(c.cyan(`• Chế độ dev: website chạy next dev${mounts.length ? `, gắn ${mounts.map((m) => `${m.kind} ${m.slug}`).join(", ")}` : ""}`));
+      if (!mounts.length) console.log(c.yellow("  ! Không thấy theme.json/plugin.json (có phần website) trong thư mục này — chạy lệnh ở thư mục chứa theme/plugin hoặc dùng --mount"));
+    }
+    if (buildDir) {
+      console.log(c.cyan(`• Build image từ mã nguồn ${buildDir} (lần đầu vài phút)…`));
+      await dc("build");
+    } else {
+      const local = async (img) => run("docker", ["image", "inspect", img], { quiet: true }).then(() => true, () => false);
+      const missing = [];
+      for (const [svc, img] of [["api", apiImage], ["builder", builderImage]]) if (!(await local(img))) missing.push(svc);
+      if (missing.length) console.log(c.cyan(`• Kéo image ${apiImage}…`));
+      try { if (missing.length) await dc("pull", ...missing); }
+      catch (e) {
+        throw new Error(`Không kéo được image CMS (${apiImage}). Image có thể chưa được phát hành công khai.\n`
+          + `  Có mã nguồn CMS: create-cms env up --build <thư-mục-mã-nguồn>\n  Hoặc chỉ định image khác: --api-image … --builder-image …\n  Chi tiết: ${e.message.split("\n").slice(-2).join(" ")}`);
+      }
+    }
+    try { await dc("up", "-d"); }
+    catch (e) {
+      // Lần chạy đầu hỏng giữa chừng: gỡ container vừa tạo, không để lại stack mồ côi (chưa có credentials.json để env down)
+      if (!saved) await dc("down", "-v", "--remove-orphans").catch(() => {});
+      throw e;
+    }
+    if (!(await waitFor(`${url}/api/health`, 240))) throw new Error(`CMS chưa phản hồi ở ${url} — xem log: docker compose -f ${path.relative(process.cwd(), dir)}/docker-compose.yml logs api`);
+
+    // Lần đầu website được build (1–2 phút) — chờ xong để mở ra là dùng được ngay
+    console.log(c.cyan("• Chờ website sẵn sàng (lần đầu cần build)…"));
+    const until = Date.now() + 600_000;
+    for (;;) {
+      const st = await fetch(url, { signal: AbortSignal.timeout(20_000) }).then((r) => r.status, () => 0);
+      if (st && st !== 502 && st !== 503) break;
+      if (Date.now() > until) throw new Error("Website chưa build xong sau 10 phút — xem log: docker compose logs builder");
+      await new Promise((r) => setTimeout(r, 3000));
+    }
+
+    let cred = saved;
+    const setup = await (await fetch(`${url}/api/setup`)).json();
+    if (setup.needsSetup && args["no-setup"]) {
+      // Tự trải nghiệm màn hình cài đặt như người dùng cuối
+      const token = (await dc("exec", "-T", "api", "cat", "/data/state/setup-token")).trim();
+      write(credFile, JSON.stringify({ project, port, url, apiImage, builderImage }, null, 2) + "\n");
+      console.log(c.green("✓ CMS đã chạy, chưa cài đặt"));
+      console.log(`  Mở ${url}/admin — mã cài đặt: ${c.bold(token)}`);
+      return;
+    }
+    if (setup.needsSetup) {
+      // Cài đặt lần đầu bằng chính màn hình cài đặt của CMS (mã cài đặt đọc trong container)
+      const token = (await dc("exec", "-T", "api", "cat", "/data/state/setup-token")).trim();
+      const password = crypto.randomBytes(12).toString("base64url");
+      const res = await fetch(`${url}/api/setup`, {
+        method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify({ token, siteTitle: args.title ?? "Website thử", language: args.lang ?? "vi", timezone: "Asia/Ho_Chi_Minh",
+          adminUserName: "admin", adminEmail: "admin@example.com", adminPassword: password, sampleContent: true, discourageSearchEngines: true }),
+      });
+      if (!res.ok) throw new Error(`Cài đặt CMS thất bại: ${res.status} ${await res.text()}`);
+      cred = { url, user: "admin", password };
+    }
+    cred = { ...cred, project, port, url, apiImage, builderImage, dev, buildDir, mounts: mounts.map((m) => ({ kind: m.kind, slug: m.slug, dir: m.dir })) };
+    write(credFile, JSON.stringify(cred, null, 2) + "\n");
+    fs.chmodSync(credFile, 0o600);
+    console.log(c.green("✓ CMS đã sẵn sàng"));
+    printInfo(cred, dir);
+    return;
+  }
+  // env up hỏng trước khi lưu tài khoản: vẫn cho env down dọn theo docker-compose.yml đã ghi
+  if (!saved && !(action === "down" && fs.existsSync(path.join(dir, "docker-compose.yml"))))
+    throw new Error(`Chưa có môi trường ở ${dir} — chạy: npx ${CLI} env up`);
+  if (action === "down") {
+    await dc("down", ...(args.purge ? ["-v"] : []));
+    if (args.purge) fs.rmSync(dir, { recursive: true, force: true });
+    console.log(c.green(args.purge ? "✓ Đã dừng và xoá dữ liệu" : "✓ Đã dừng (dữ liệu được giữ — `env up` để chạy lại)"));
+    return;
+  }
+  if (action === "logs") {
+    const extra = (args._ ?? []).slice(2);
+    const service = extra.find((x) => !x.startsWith("-"));
+    const follow = args.follow || extra.includes("-f");
+    await run("docker", ["compose", "-f", path.join(dir, "docker-compose.yml"), "logs", "--tail", "200", ...(follow ? ["-f"] : []), ...(service ? [service] : [])], { quiet: false });
+    return;
+  }
+  if (action === "status") {
+    const up = await waitFor(`${saved.url}/api/health`, 2);
+    console.log((up ? c.green("● Đang chạy") : c.yellow("○ Đã dừng")) + (saved.dev ? c.dim(` · dev (${(saved.mounts ?? []).map((m) => m.slug).join(", ") || "không gắn thư mục"})`) : ""));
+    if (saved.password) printInfo(saved, dir); else console.log(`  Website     ${saved.url}  (chưa cài đặt hoặc tự cài bằng màn hình cài đặt)`);
+    return;
+  }
+  throw new Error("Dùng: create-cms env up [--dev] [--build DIR] | status | logs [dịch vụ] [-f] | down [--purge]");
+}
+
+function printInfo(cred, dir) {
+  console.log(`  Website     ${cred.url}`);
+  console.log(`  Quản trị    ${cred.url}/admin   (${cred.user} / ${cred.password})`);
+  console.log(c.dim(`  Tài khoản lưu ở ${path.relative(process.cwd(), path.join(dir, "credentials.json"))} — \`create-cms dev\` tự dùng.`));
+}

package/lib/npm.mjs

@@ -0,0 +1,9 @@
+import { readFileSync } from "node:fs";
+
+// Gói npm (org @ecomcx) — theme/plugin import đúng tên này
+export const THEME_SDK = "@ecomcx/nexus-theme-sdk", ADMIN_SDK = "@ecomcx/nexus-admin-sdk", CONTENT = "@ecomcx/nexus-content";
+export const CLI = "@ecomcx/create-nexus";
+/** Tên cũ (trước khi lên npm) → tên mới: core vẫn hiểu import cũ, validate nhắc đổi, upgrade giữ bí danh để code cũ còn chạy. */
+export const OLD_NAMES = { "@cms/theme-sdk": THEME_SDK, "@cms/admin-sdk": ADMIN_SDK, "@cms/content": CONTENT };
+/** Phiên bản của CLI = phiên bản SDK phát hành cùng đợt. */
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;