create-wakii-stack 0.0.0-stage → 0.1.1

package/stack-template/app/remotes/tasks/vitest.config.ts

@@ -0,0 +1,34 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defineConfig } from 'vitest/config';
+
+// Windows-safe absolute path (URL.pathname cho ra /C:/... sai trên win32)
+const rootDir = path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  // Stub build-time env (rspack DefinePlugin) cho unit test — test mock fetch nên base rỗng
+  define: {
+    __API_BASE_URL__: "''",
+  },
+  resolve: {
+    // fe-shared src/ui (SF-1) import 'react' nhưng package không khai báo dep (giữ
+    // pnpm-lock.yaml) — vitest resolve từ file fe-shared không thấy react của tasks.
+    // Alias về node_modules của tasks: catalog 19.3.0 pinned giống hệt ×3 package.
+    // (Cùng cấu hình shell/vitest.config.ts — SF-3 render primitives lần đầu trong tests.)
+    alias: {
+      react: path.resolve(rootDir, 'node_modules/react'),
+      'react-dom': path.resolve(rootDir, 'node_modules/react-dom'),
+      'react/jsx-runtime': path.resolve(rootDir, 'node_modules/react/jsx-runtime'),
+    },
+  },
+  // JSX fe-shared (không tsconfig riêng) phải transform automatic runtime — không thì
+  // esbuild rơi về classic "React.createElement" → "React is not defined" lúc render
+  esbuild: {
+    jsx: 'automatic',
+  },
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['./tests/setup.ts'],
+  },
+});

package/stack-template/app/shared/README.md

@@ -0,0 +1,21 @@
+# @wakii/fe-shared — logic FE dùng chung
+
+4 file **logic** consumed qua source bởi shell + 2 remotes: `api-client` (ApiClient +
+timeout/envelope), `token-storage` (JWT storage + claims), `error-envelope` (decode
+chuẩn conventions/04), `mf-bootstrap` (MF runtime helper — loadRemoteModule/retry).
+
+> **Design system KHÔNG còn ở đây** — tách sang [`@wakii/ui-kit`](../ui-kit) 2026-10-17
+> (ADR-0009): tokens/base css + primitives Badge/EmptyState/Skeleton/Spinner + Storybook.
+
+## READ-LOCKED
+
+Cả 4 file `src/*.ts` + `package.json#mfToolkit` **cấm sửa ngoài epic được duyệt** —
+versions đã test thật (spike SF-1: MF host :3000 load remote :4001, evidence
+`docs/superpowers/evidence/sf-1-mf-spike-host.png`). Nâng cấp react/rspack/@module-federation
+= re-spike qua `app/spike` trước. Chi tiết: CLAUDE.md + `package.json#mfToolkit.$comment`.
+
+## Standalone-copy
+
+Remote/shell copy KÈM package này (Dockerfile COPY đủ importer); fe-shared khai
+`catalog:` → standalone cần mini workspace (mẫu: `.github/workflows/convergence.yml`
+step copy-dir). Typecheck standalone = flags CLI, không tsconfig trong package.

package/stack-template/app/shared/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@wakii/fe-shared",
+  "version": "0.1.0",
+  "private": true,
+  "description": "fe-shared — logic FE dùng chung: ApiClient + token-storage + error-envelope + mf-bootstrap (4 file READ-LOCKED — cấm sửa ngoài epic duyệt). Design system đã tách sang @wakii/ui-kit 2026-10-17 (ADR-0009). Consumed QUA SOURCE. Standalone-copy: remote/shell copy KÈM package này.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./api-client": "./src/api-client.ts",
+    "./token-storage": "./src/token-storage.ts",
+    "./error-envelope": "./src/error-envelope.ts",
+    "./mf-bootstrap": "./src/mf-bootstrap.ts"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@module-federation/enhanced": "catalog:"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "mfToolkit": {
+    "$comment": "Kết quả spike SF-1 (app/spike) — versions ĐÃ TEST THẬT host :3000 load được remote :4001 trên Rspack + React 19 (evidence: docs/superpowers/evidence/sf-1-mf-spike-host.png). SF-5/6 dùng ĐÚNG matrix này; nâng cấp phải re-spike. Learned trong spike: (1) host entry cần async boundary (import('./bootstrap') — không import shared tĩnh, tránh RUNTIME-006 loadShareSync); (2) JSX dùng automatic runtime (jsc.transform.react.runtime='automatic').",
+    "pinned": {
+      "react": "19.3.0",
+      "react-dom": "19.3.0",
+      "@rspack/core": "1.7.12",
+      "@rspack/cli": "1.7.12",
+      "@module-federation/enhanced": "0.21.6"
+    },
+    "spikePath": "app/spike",
+    "validatedDate": "2026-10-12"
+  }
+}

package/stack-template/app/shared/src/api-client.ts

@@ -0,0 +1,66 @@
+// API client wrapper — mọi call lên gateway :8080 (conventions/05: CỔNG DUY NHẤT).
+// Trách nhiệm: đính JWT từ TokenStorage + decode error envelope (conventions/04).
+import { decodeErrorEnvelope, ApiError } from './error-envelope.js';
+import type { TokenStorage } from './token-storage.js';
+
+export interface ApiClientOptions {
+  baseUrl: string; // vd "http://localhost:8080" (dev native) hoặc "" (đồng origin qua gateway)
+  tokenStorage: TokenStorage;
+  fetchImpl?: typeof fetch;
+}
+
+export class ApiClient {
+  private readonly baseUrl: string;
+  private readonly tokenStorage: TokenStorage;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(opts: ApiClientOptions) {
+    this.baseUrl = opts.baseUrl.replace(/\/$/, '');
+    this.tokenStorage = opts.tokenStorage;
+    this.fetchImpl = opts.fetchImpl ?? fetch.bind(globalThis);
+  }
+
+  async get<T>(path: string): Promise<T> {
+    return this.request<T>('GET', path);
+  }
+  async post<T>(path: string, body: unknown): Promise<T> {
+    return this.request<T>('POST', path, body);
+  }
+  async patch<T>(path: string, body: unknown): Promise<T> {
+    return this.request<T>('PATCH', path, body);
+  }
+  async delete(path: string): Promise<void> {
+    await this.request<void>('DELETE', path);
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const headers: Record<string, string> = {};
+    const token = this.tokenStorage.getToken();
+    if (token) {
+      headers['Authorization'] = `Bearer ${token}`;
+    }
+    if (body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+    }
+    const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    if (!res.ok) {
+      let raw: unknown = null;
+      try {
+        raw = await res.json();
+      } catch {
+        // body không phải JSON — giữ null, decodeErrorEnvelope fallback
+      }
+      throw decodeErrorEnvelope(res.status, raw);
+    }
+    if (res.status === 204) {
+      return undefined as T;
+    }
+    return (await res.json()) as T;
+  }
+}
+
+export { ApiError };

package/stack-template/app/shared/src/error-envelope.ts

@@ -0,0 +1,38 @@
+// Error envelope types — mirror của platform/conventions/04-error-envelope.md
+// và components.schemas.Error trong contracts/openapi/*.yaml.
+
+export interface ErrorEnvelope {
+  error: {
+    code: string;
+    message: string;
+    requestId: string | null;
+    details: unknown;
+  };
+}
+
+export class ApiError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly requestId: string | null;
+  readonly details: unknown;
+
+  constructor(status: number, envelope: ErrorEnvelope) {
+    super(envelope.error.message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.code = envelope.error.code;
+    this.requestId = envelope.error.requestId;
+    this.details = envelope.error.details;
+  }
+}
+
+/** Parse response body 4xx/5xx thành ApiError. Body không phải envelope → envelope tổng quát. */
+export function decodeErrorEnvelope(status: number, rawBody: unknown): ApiError {
+  const candidate = rawBody as Partial<ErrorEnvelope> | null;
+  if (candidate && typeof candidate === 'object' && candidate.error && typeof candidate.error.code === 'string') {
+    return new ApiError(status, candidate as ErrorEnvelope);
+  }
+  return new ApiError(status, {
+    error: { code: 'INTERNAL', message: `Unexpected error (HTTP ${status})`, requestId: null, details: rawBody },
+  });
+}

package/stack-template/app/shared/src/index.ts

@@ -0,0 +1,21 @@
+// fe-shared — barrel export (LOGIC ONLY — design system đã tách sang @wakii/ui-kit,
+// ADR-0009 2026-10-17: primitives + tokens/base css sống ở ui-kit, imports UI đổi thẳng)
+export { ApiClient, ApiError, type ApiClientOptions } from './api-client.js';
+export { decodeErrorEnvelope, type ErrorEnvelope } from './error-envelope.js';
+export { tokenStorage, readClaims, isExpired, type TokenStorage } from './token-storage.js';
+export {
+  createAuthClient,
+  REFRESH_STORAGE_KEY,
+  type AuthClient,
+  type AuthSession,
+  type AuthUser,
+  type TokenPair,
+} from './refresh-client.js';
+export {
+  loadRemoteModule,
+  resolveRemoteUrl,
+  REMOTE_NAMES,
+  type RemoteName,
+  type RemoteEntry,
+  type LoadRemoteModuleOptions,
+} from './mf-bootstrap.js';

package/stack-template/app/shared/src/mf-bootstrap.ts

@@ -0,0 +1,89 @@
+// MF bootstrap helper — chuẩn hoá việc load remote cho shell (SF-5) và remotes (SF-6).
+// Remote registry: platform/conventions/08-gateway-and-remotes.md — URL đọc từ env, KHÔNG hardcode.
+
+/** Tên remote hợp lệ trong registry — đổi danh sách = sửa conventions/08 cùng commit. */
+export const REMOTE_NAMES = ['tasks', 'activity'] as const;
+export type RemoteName = (typeof REMOTE_NAMES)[number];
+
+export interface RemoteEntry {
+  /** Module federation container name (khoá trong rspack remotes config) */
+  name: RemoteName;
+  /** URL remoteEntry.js — dev: env REMOTE_TASKS_URL/REMOTE_ACTIVITY_URL; prod: /remotes/<name>/remoteEntry.js */
+  url: string;
+}
+
+/** Đọc URL remote từ env — host app (SF-5) inject `__REMOTE_URLS__` lúc bootstrap
+ * (build-time env REMOTE_TASKS_URL/REMOTE_ACTIVITY_URL); fallback prod đi qua gateway
+ * (conventions/08 remote registry prod URL). Không import `process` — giữ side-effect-free. */
+export function resolveRemoteUrl(name: RemoteName): string {
+  const fromWindow = (globalThis as Record<string, unknown>)['__REMOTE_URLS__'] as
+    | Record<string, string>
+    | undefined;
+  if (fromWindow?.[name]) {
+    return fromWindow[name];
+  }
+  return `/remotes/${name}/remoteEntry.js`;
+}
+
+/** Options cho loadRemoteModule (BUG-2, sf-5b). */
+export interface LoadRemoteModuleOptions {
+  /**
+   * true khi đây là lần RETRY sau khi remote có thể đã sống lại — phá sticky rejection
+   * của MF runtime rồi mới load lại. Xem comment trong thân hàm.
+   */
+  retry?: boolean;
+}
+
+/**
+ * Load 1 exposed module từ remote. Wrapper mỏng quanh import() federation —
+ * bắt lỗi remote-down để shell render error boundary thay vì trắng trang (SF-5 task).
+ */
+export async function loadRemoteModule<T>(
+  remote: RemoteEntry,
+  exposedModule: string,
+  options: LoadRemoteModuleOptions = {},
+): Promise<T> {
+  // Runtime API loadRemote muốn 'tasks/TasksPage' (KHÔNG './') — registry conventions/08
+  // ghi exposes kiểu './TasksPage', chuẩn hoá tại đây để caller dùng nguyên văn registry.
+  const containerKey = `${remote.name}/${exposedModule.replace(/^\.\//, '')}`;
+  try {
+    // [FLAG coordinator duyệt — SF-6 sửa READ-ONLY file, REQUIREMENT-GAP FI-62] Dùng runtime
+    // API loadRemote thay native import(): dynamic import với specifier BIẾN không được
+    // bundler rewrite (critical dependency warning) và import() native không resolve được
+    // bare specifier — bug lộ khi SF-6 lần đầu load remote THẬT vào shell (trước đó shell
+    // chỉ test remote-down mock). loadRemote là pattern chuẩn MF 2.0.
+    const runtime = await import('@module-federation/enhanced/runtime');
+    if (options.retry) {
+      // BUG-2 (sf-5b): sticky rejection — runtime memoize load-promise remoteEntry trong
+      // globalLoading (window.__GLOBAL_LOADING_REMOTE_ENTRY__, runtime-core 0.21.6
+      // getRemoteEntry()) và promise REJECTED không bao giờ được clear → mọi loadRemote
+      // sau trả lại rejection cũ TỨC THÌ, 0 network request mới (khớp evidence: skeleton
+      // flash + 0 fetch mới; raw import() cùng URL vẫn FETCH được vì không đi layer này).
+      // registerRemotes({force:true}) → registerRemote force → removeRemote xoá
+      // globalLoading + manifestCache + moduleCache + container global — đường sanctioned
+      // duy nhất trong runtime để reset; loadRemote sau đó fetch lại remoteEntry thật.
+      // Def PHẢI khớp registration gốc của webpack runtime: type 'global' (classic
+      // remoteEntry = script + global var). type 'module' (ESM) làm runtime coi entry là
+      // module namespace không có init → RUNTIME_002 ngay sau fetch (đã bắt ở browser E2E).
+      // Bắn TRƯỚC loadRemote, không đợi (fire-and-forget đủ — removeRemote là sync
+      // theo pin 0.21.6; re-spike bump version phải kiểm tra lại tính sync này).
+      void runtime.registerRemotes(
+        [
+          {
+            name: remote.name,
+            entry: remote.url,
+            type: 'global',
+            shareScope: 'default',
+          },
+        ],
+        { force: true },
+      );
+    }
+    const { loadRemote } = runtime;
+    return (await loadRemote<T>(containerKey)) as T;
+  } catch (err) {
+    throw new Error(
+      `Remote "${remote.name}" load failed (${remote.url}). Remote có thể đang down — shell phải render fallback. Nguyên nhân gốc: ${String(err)}`,
+    );
+  }
+}

package/stack-template/app/shared/src/refresh-client.ts

@@ -0,0 +1,170 @@
+// Refresh-client wrapper — auth flows v2 của epic auth-real (SF-4, VU-63).
+// Hiệp ước: contracts/openapi/auth.yaml v2 + contracts/auth/token-contract.md v2 §2/§4 —
+// response shape {user, accessToken, refreshToken} (DROP tokenType/expiresIn).
+// File MỚI theo decision #5 (spec rev2): token-storage.ts READ-LOCKED không đụng —
+// access token vẫn đi qua tokenStorage API có sẵn; refresh token lưu
+// localStorage['bp.rt'] (key pin trong token-contract §2 — ĐỪNG đổi).
+// 401 → refresh single-flight (promise lock, đúng 1 lần cho mọi caller đồng thời —
+// giảm xác suất CAS-reuse strict 2 tab) → retry; refresh fail → clear cả 2 key +
+// ném lỗi 401 (session chết, UI thấy Unauthorized thay vì 401 im lặng).
+import { ApiClient, ApiError } from './api-client.js';
+import { tokenStorage } from './token-storage.js';
+
+/** Key localStorage cho refresh token — pin token-contract.md §2. */
+export const REFRESH_STORAGE_KEY = 'bp.rt';
+
+/** Mirror UserRef schema (auth.yaml v2). */
+export interface AuthUser {
+  id: string;
+  email: string;
+  displayName: string;
+  roles: string[];
+}
+
+/** Response chung login + register (AuthSession schema v2). */
+export interface AuthSession {
+  user: AuthUser;
+  accessToken: string;
+  refreshToken: string;
+}
+
+/** Response /refresh (TokenPair schema — không có user). */
+export interface TokenPair {
+  accessToken: string;
+  refreshToken: string;
+}
+
+export interface AuthClient {
+  login(email: string, password: string): Promise<AuthSession>;
+  register(email: string, password: string, displayName: string): Promise<AuthSession>;
+  /** Chạy fn với access token hiện tại; 401 → refresh đúng 1 lần → retry với token mới. */
+  withRefresh<T>(fn: (token: string) => Promise<T>): Promise<T>;
+  /** Revoke refresh token server-side (idempotent) + clear cả 2 key — không ném khi mạng chết. */
+  logout(): Promise<void>;
+}
+
+// localStorage có thể văng (SSR/storage bị chặn) — mirror fallback im lặng của
+// token-storage.ts (READ-LOCKED, không export helper riêng được).
+
+function readRefreshToken(): string | null {
+  try {
+    return window.localStorage.getItem(REFRESH_STORAGE_KEY);
+  } catch {
+    return null;
+  }
+}
+
+function writeRefreshToken(token: string): void {
+  try {
+    window.localStorage.setItem(REFRESH_STORAGE_KEY, token);
+  } catch {
+    // storage chặn — access vẫn dùng được đến khi hết hạn 30m, refresh sẽ 401 sau
+  }
+}
+
+function clearRefreshToken(): void {
+  try {
+    window.localStorage.removeItem(REFRESH_STORAGE_KEY);
+  } catch {
+    // không có gì để clear
+  }
+}
+
+function unauthorizedError(): ApiError {
+  return new ApiError(401, {
+    error: { code: 'UNAUTHORIZED', message: 'Phiên đăng nhập đã hết hạn.', requestId: null, details: null },
+  });
+}
+
+function isUnauthorized(err: unknown): err is ApiError {
+  return err instanceof ApiError && err.status === 401;
+}
+
+/** Tạo AuthClient gắn với một ApiClient (base URL + timeout fetch do caller cấu hình —
+ * shell inject instance của src/api.ts). Mỗi bundle tự tạo 1 instance, lock trong phạm vi đó. */
+export function createAuthClient(api: ApiClient): AuthClient {
+  // Single-flight promise lock: mọi 401 đồng thời share 1 promise /refresh —
+  // không đốt 2 refresh token (rotation CAS strict sẽ coi call sau là reuse, token-contract §3).
+  let refreshInFlight: Promise<TokenPair> | null = null;
+
+  function storeSession(session: { accessToken: string; refreshToken: string }): void {
+    tokenStorage.setToken(session.accessToken);
+    writeRefreshToken(session.refreshToken);
+  }
+
+  function clearSession(): void {
+    tokenStorage.clearToken();
+    clearRefreshToken();
+  }
+
+  function refreshOnce(): Promise<TokenPair> {
+    refreshInFlight ??= (async () => {
+      const rt = readRefreshToken();
+      if (!rt) {
+        throw unauthorizedError();
+      }
+      return api.post<TokenPair>('/api/auth/refresh', { refreshToken: rt });
+    })().finally(() => {
+      refreshInFlight = null;
+    });
+    return refreshInFlight;
+  }
+
+  return {
+    async login(email, password) {
+      const session = await api.post<AuthSession>('/api/auth/login', { email, password });
+      storeSession(session);
+      return session;
+    },
+
+    async register(email, password, displayName) {
+      const session = await api.post<AuthSession>('/api/auth/register', { email, password, displayName });
+      storeSession(session);
+      return session;
+    },
+
+    async withRefresh(fn) {
+      try {
+        return await fn(tokenStorage.getToken() ?? '');
+      } catch (err) {
+        if (!isUnauthorized(err)) {
+          throw err; // lỗi nghiệp vụ (409…) hay mạng — không phải việc của refresh
+        }
+      }
+
+      let pair: TokenPair;
+      try {
+        pair = await refreshOnce();
+      } catch (refreshErr) {
+        // refresh chết (401 reuse/hết hạn 7d, hết rt, mạng) — session không cứu được
+        clearSession();
+        throw refreshErr;
+      }
+      storeSession(pair);
+
+      try {
+        return await fn(pair.accessToken);
+      } catch (retryErr) {
+        // token mới mà vẫn 401 → session chết thật (user bị revoke…); lỗi khác giữ nguyên session
+        if (isUnauthorized(retryErr)) {
+          clearSession();
+        }
+        throw retryErr;
+      }
+    },
+
+    async logout() {
+      const rt = readRefreshToken();
+      try {
+        // 204 idempotent (token-contract §4); rt thiếu → không có gì revoke server-side
+        if (rt) {
+          await api.post<void>('/api/auth/logout', { refreshToken: rt });
+        }
+      } catch {
+        // mạng/endpoint chết — intent đăng xuất thắng: vẫn clear cục bộ, không ném
+      } finally {
+        clearSession();
+      }
+    },
+  };
+}

package/stack-template/app/shared/src/token-storage.ts

@@ -0,0 +1,57 @@
+// Token storage — lưu JWT cho shell/remotes (token-contract.md: TTL 8h, không refresh).
+// Mặc định localStorage (persist qua refresh); có thể inject storage khác (memory cho test).
+
+const STORAGE_KEY = 'bp.jwt';
+
+export interface TokenStorage {
+  getToken(): string | null;
+  setToken(token: string): void;
+  clearToken(): void;
+}
+
+function defaultStorage(): Storage | null {
+  try {
+    // SSR/next lớn: localStorage có thể văng — trả null, rơi về memory
+    return typeof window !== 'undefined' ? window.localStorage : null;
+  } catch {
+    return null;
+  }
+}
+
+let memoryToken: string | null = null;
+
+export const tokenStorage: TokenStorage = {
+  getToken(): string | null {
+    return defaultStorage()?.getItem(STORAGE_KEY) ?? memoryToken;
+  },
+  setToken(token: string): void {
+    memoryToken = token;
+    defaultStorage()?.setItem(STORAGE_KEY, token);
+  },
+  clearToken(): void {
+    memoryToken = null;
+    defaultStorage()?.removeItem(STORAGE_KEY);
+  },
+};
+
+/**
+ * Giải payload JWT (phần giữa) KHÔNG verify signature — chỉ đọc claims để hiển thị
+ * (vd user email trên nav). Verify signature là việc service BE (enforcement 2 lớp,
+ * token-contract.md §4). Token hết hạn phía FE: so exp < now → clear + redirect login.
+ */
+export function readClaims(token: string): { sub: string; email: string; roles: string[]; exp: number } | null {
+  try {
+    // base64url → base64: đổi alphabet + tự bổ sung padding (JWT segment không có '=')
+    let seg = token.split('.')[1].replace(/-/g, '+').replace(/_/g, '/');
+    seg += '='.repeat(seg.length % 4 === 0 ? 0 : 4 - (seg.length % 4));
+    const payload = JSON.parse(atob(seg));
+    return payload.sub ? payload : null;
+  } catch {
+    return null;
+  }
+}
+
+export function isExpired(token: string): boolean {
+  const claims = readClaims(token);
+  return !claims || claims.exp * 1000 < Date.now();
+}

package/stack-template/app/shell/Dockerfile

@@ -0,0 +1,37 @@
+# Shell — MF host static (SF-5). Multi-stage theo platform/conventions/01-dockerfile-pattern.md.
+# Build context = repo ROOT (compose: context .., dockerfile app/shell/Dockerfile) —
+# cần app/shared (workspace dep TS raw) + pnpm-workspace.yaml + lockfile.
+
+# build stage — cài + build rspack
+FROM node:22-alpine AS build
+WORKDIR /repo
+# Pin pnpm 9.15.9 = dev machine + lockfileVersion (corepack default sẽ tải pnpm 12 — lệch format)
+RUN corepack enable && corepack prepare pnpm@9.15.9 --activate
+# COPY đủ MỌI importer trong pnpm-lock.yaml (., shared, shell, spike/host, spike/remote) —
+# thiếu importer nào frozen-lockfile cũng fail
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
+COPY app/shared/package.json app/shared/
+COPY app/ui-kit/package.json app/ui-kit/
+COPY app/spike/host/package.json app/spike/host/
+COPY app/spike/remote/package.json app/spike/remote/
+COPY app/shell/package.json app/shell/
+RUN pnpm install --frozen-lockfile --filter @wakii/shell...
+COPY app/shared app/shared
+COPY app/ui-kit app/ui-kit
+COPY app/shell app/shell
+# Build-time env (conventions/08 — remote registry; mặc định đi qua gateway /remotes/*)
+ARG REMOTE_TASKS_URL=/remotes/tasks/remoteEntry.js
+ARG REMOTE_ACTIVITY_URL=/remotes/activity/remoteEntry.js
+# Prod API base = '' (same-origin qua gateway — conventions/07)
+ENV REMOTE_TASKS_URL=${REMOTE_TASKS_URL} \
+    REMOTE_ACTIVITY_URL=${REMOTE_ACTIVITY_URL} \
+    API_BASE_URL="" \
+    NODE_ENV=production
+RUN pnpm --filter @wakii/shell build
+
+# runtime stage — nginx serve static, port cố định 3000 (conventions/05)
+# Healthcheck KHÔNG khai ở đây (conventions/01 rule 4 — một nguồn duy nhất: compose entry `shell`)
+FROM nginx:1.27-alpine AS runtime
+COPY app/shell/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /repo/app/shell/dist /usr/share/nginx/html
+EXPOSE 3000

package/stack-template/app/shell/README.md

@@ -0,0 +1,79 @@
+# app/shell — MF host (SF-5)
+
+FE shell — Module Federation host (Rspack + `@module-federation/enhanced`), React 19 + TypeScript + pnpm. Cửa vào của demo: login mock JWT → nav → load remote `tasks` / `activity` (SF-6 impl) vào layout; remote down → error boundary fallback + retry, không trắng trang.
+
+## Chạy native dev (không cần Docker)
+
+```bash
+# từ repo root — pnpm workspace
+pnpm install
+pnpm --filter @wakii/shell dev     # dev server :3000 (conventions/05)
+```
+
+Login demo: `alice@demo.local` / `demo-password` (fixture `contracts/auth/users.json` + dev password chung `AUTH_DEV_PASSWORD`).
+
+Dev native cần auth-svc chạy ở `:8090`:
+
+```bash
+cd services/auth-svc && pnpm install --frozen-lockfile --ignore-workspace && pnpm dev
+```
+
+## Env (build-time — conventions/06 + 08)
+
+| Env | Dev native | Prod (compose) | Ý nghĩa |
+|-----|-----------|----------------|---------|
+| `SHELL_PORT` | 3000 | (compose side) | port dev server |
+| `API_BASE_URL` | `http://localhost:8090` (mặc định khi dev) | `''` (same-origin qua gateway) | base gọi API — dev gọi auth-svc trực tiếp (CORS dev mở, conventions/07), prod đi qua gateway |
+| `REMOTE_TASKS_URL` | `http://localhost:4001/remoteEntry.js` | `/remotes/tasks/remoteEntry.js` (mặc định) | remoteEntry remote tasks |
+| `REMOTE_ACTIVITY_URL` | `http://localhost:4002/remoteEntry.js` | `/remotes/activity/remoteEntry.js` (mặc định) | remoteEntry remote activity |
+
+Ví dụ dev có remote SF-6 chạy local:
+
+```bash
+REMOTE_TASKS_URL=http://localhost:4001/remoteEntry.js pnpm --filter @wakii/shell dev
+```
+
+## Tests + build
+
+```bash
+pnpm --filter @wakii/shell test        # vitest + testing-library (48 tests / 9 file: a11y, login, remote-down, api-timeout, integration, primitives, shell-chrome)
+pnpm --filter @wakii/shell typecheck
+pnpm --filter @wakii/shell build       # rspack production build → dist/
+```
+
+A11y baseline CÓ TEST: skip link (`Tới nội dung chính`) + route focus management (focus `<main>` mỗi route change).
+
+## Docker (verify qua CI — dev machine không có Docker)
+
+```bash
+# context = repo root (cần app/shared + workspace lockfile)
+docker build -f app/shell/Dockerfile -t shell .
+docker run -p 3000:3000 shell
+```
+
+Multi-stage: node:22-alpine build → nginx:1.27-alpine serve static `:3000`, SPA fallback, healthcheck.
+
+## Pin matrix (không tự nâng — re-spike trước khi đổi)
+
+`react`/`react-dom` 19.3.0 · `@rspack/core` 1.7.12 · `@module-federation/enhanced` 0.21.6 — single-source qua **pnpm catalog** (root `pnpm-workspace.yaml`, coordinator sở hữu). `@rspack/cli` pin 1.7.12 riêng (không có trong catalog).
+
+## Standalone-copy
+
+Copy thư mục này **KÈM `app/shared/`** (workspace dep `@wakii/fe-shared`) + root `pnpm-workspace.yaml` + `pnpm-lock.yaml`. Không copy = build fail ngay ở import fe-shared.
+
+## Kiến trúc nhanh
+
+- `src/index.tsx` → async boundary `import('./bootstrap')` (bắt buộc MF — tránh loadShareSync)
+- `src/bootstrap.tsx` — import global `@wakii/ui-kit/styles/tokens.css` + `base.css` + `themes/dark.css` + `./app.css` (shell LÀM CHỦ global base — remotes KHÔNG import lại base khi chạy trong shell)
+- `src/App.tsx` — routes `/`, `/tasks`, `/activity` (remote slots), `/login`
+- `src/components/RemoteSlot.tsx` — lazy remote + error boundary + retry (Suspense fallback = Skeleton primitive)
+- `src/api.ts` — ApiClient từ fe-shared, base `__API_BASE_URL__`
+- Login dùng `tokenStorage` + `ApiClient` từ `@wakii/fe-shared` (READ-ONLY — SF-1 sở hữu)
+- `src/app.css` — Tailwind v4 entry (import `@wakii/ui-kit/styles/tailwind.css`); shell style bằng Tailwind utilities + tokens CSS vars, không còn file css scoped riêng
+
+## Design system (từ `@wakii/ui-kit` — ADR-0009)
+
+- **Tokens**: `import '@wakii/ui-kit/styles/tokens.css'` — CSS vars `--c-*` (canvas `#f5f5f5`, khối trắng `#ffffff` — bậc bề mặt antd), `--ink*`, `--line*`, `--accent*` (`#1677ff` antd colorPrimary), `--st-*`, `--sp-*`, `--fs-*`, `--r-*` + motion/ease scale; shadow layered cho floating surfaces (`--shadow-pop/lift`, `--ele-1..3`).
+- **Base**: `import '@wakii/ui-kit/styles/base.css'` — reset mỏng + element defaults (`@layer reset,base`) — CHỈ shell import làm global.
+- **Primitives**: `import { Badge, Button, Table, … } from '@wakii/ui-kit'` — 90+ components (xem barrel `app/ui-kit/src/index.ts`) + hooks/utils/motion; catalog sống ở Storybook (`pnpm --filter @wakii/ui-kit storybook`). `Badge variant: todo|doing|done|failed|created|updated|assigned|deleted|assignmentFailed` (role="status").
+- Hướng visual: light antd-look mặc định (spec `docs/superpowers/specs/2026-10-17-antd-look-tokens.md`); dark là theme phụ qua `UiKitProvider` (`data-bp-theme` → `@wakii/ui-kit/styles/themes/dark.css`).

package/stack-template/app/shell/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="vi">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Boilerplate Shell</title>
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>