create-wakii-stack 0.0.0-stage → 0.1.1

package/stack-template/app/create-wakii-stack/src/scaffold.ts

@@ -0,0 +1,315 @@
+// scaffold — full-copy template → render placeholders (__STACK_NAME__/
+// __STACK_ORG__ — text files only, binary byte 0x00 bỏ qua) → PRUNE theo
+// manifest: xoá paths, prune khối compose theo indentation (block 2-space,
+// depends_on entry 6-space), dọn depends_on tham chiếu service đã bỏ, bỏ
+// volume pgdata khi postgres bỏ, lọc gateway conf theo marker, lọc .env theo
+// envKeys — cuối cùng sinh README.md (services + up + smoke + ports).
+// Toàn bộ thao tác compose/gateway/env là TEXT theo cấu trúc thụt dòng —
+// không YAML parser (0 deps).
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { StackManifest } from './manifest.js';
+import type { StackSelection } from './options.js';
+
+/** Template mặc định — publish kèm CLI (worker-compose sở hữu nội dung). */
+export const DEFAULT_TEMPLATE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../../stack-template');
+
+export interface StackScaffoldInput {
+  selection: StackSelection;
+  dest: string;
+  /** Ghi đè nguồn template + manifest (test trỏ fixture). */
+  templateRoot?: string;
+  log?: (message: string) => void;
+}
+
+export interface StackScaffoldResult {
+  files: string[];
+  prunedServices: string[];
+}
+
+const STACK_ORG = 'wakii';
+
+async function copyTree(srcDir: string, destDir: string, opts: { stackName: string; files: string[] }): Promise<void> {
+  await mkdir(destDir, { recursive: true });
+  for (const entry of await readdir(srcDir, { withFileTypes: true })) {
+    if (entry.name === '.DS_Store') continue;
+    const srcPath = join(srcDir, entry.name);
+    const destPath = join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      await copyTree(srcPath, destPath, opts);
+      continue;
+    }
+    const buffer = await readFile(srcPath);
+    if (buffer.includes(0)) {
+      await writeFile(destPath, buffer); // binary — nguyên bản
+    } else {
+      const text = buffer.toString('utf8').replaceAll('__STACK_NAME__', opts.stackName).replaceAll('__STACK_ORG__', STACK_ORG);
+      await writeFile(destPath, text);
+    }
+    opts.files.push(destPath);
+  }
+}
+
+/** Line category — phân luồng YAML 2-space của compose. */
+type LineKind = 'top-level' | 'service-block' | 'comment-2space' | 'deeper' | 'blank';
+
+function kindOf(line: string): LineKind {
+  if (line.trim() === '') return 'blank';
+  if (!line.startsWith(' ')) return 'top-level';
+  if (/^  [A-Za-z0-9_-]+:\s*$/.test(line)) return 'service-block';
+  if (/^ {2}#/.test(line)) return 'comment-2space';
+  return 'deeper';
+}
+
+/**
+ * Prune file compose theo TEXT:
+ * - bỏ block 2-space `  <name>:` của service không chọn (kèm comment/blank
+ *   thuộc block — comment 2-space gắn block TRƯỚC nó);
+ * - dọn `depends_on`: bỏ entry 6-space tham chiếu service đã prune (+ con sâu
+ *   hơn); depends_on rỗng → xoá luôn dòng;
+ * - bỏ volume `  pgdata:` khi postgres prune;
+ * - chèn 1 comment cảnh báo đầu section services liệt kê service đã cắt.
+ */
+export function pruneCompose(text: string, selected: ReadonlySet<string>, allServices: string[]): string {
+  const lines = text.split('\n');
+  const pruned = allServices.filter((s) => !selected.has(s));
+  const out: string[] = [];
+  let section = ''; // top-level key hiện tại
+  let keptService: string | null = null; // service block đang ghi (null = ngoài block/bị cắt)
+  let skippingService: string | null = null; // service block đang cắt
+  let inDependsOn = false;
+  const prunedInFile: string[] = [];
+
+  for (const line of lines) {
+    const kind = kindOf(line);
+    if (kind === 'top-level') {
+      section = line.replace(/:.*$/, '').trim();
+      keptService = null;
+      skippingService = null;
+      inDependsOn = false;
+      out.push(line);
+      if (section === 'services' && pruned.length > 0 && !textHasPruneNote(out)) {
+        out.push(`  # create-wakii-stack: pruned ${pruned.join(', ')} (không chọn khi scaffold)`);
+      }
+      continue;
+    }
+    if (section !== 'services') {
+      // volumes: pgdata bỏ khi postgres prune
+      if (section === 'volumes' && dropPgdata(selected, allServices) && /^  pgdata:/.test(line)) {
+        continue;
+      }
+      out.push(line);
+      continue;
+    }
+
+    if (kind === 'service-block') {
+      const name = line.trim().replace(/:$/, '');
+      keptService = selected.has(name) ? name : null;
+      if (!keptService) {
+        skippingService = name;
+        prunedInFile.push(name);
+      }
+      inDependsOn = false;
+      if (keptService) out.push(line);
+      continue;
+    }
+    // comment-2space/deeper/blank → thuộc block đang mở (hoặc nền section)
+    if (skippingService !== null) continue; // đang cắt block — bỏ line
+    if (keptService !== null) {
+      if (kind === 'deeper' && /^ {4}depends_on:\s*$/.test(line)) {
+        inDependsOn = true;
+        pendingDepends.push(line);
+        continue;
+      }
+      if (inDependsOn && kind === 'deeper') {
+        const entry = /^ {6}([A-Za-z0-9_-]+):/.exec(line);
+        if (entry) {
+          // entry mới — xả depends_on pending nếu còn entries
+          flushDepends(out, pruned);
+          currentDepends.push({ name: entry[1]!, line, deeper: [] });
+          continue;
+        }
+        // dòng con của entry hiện tại (condition: …)
+        currentDepends[currentDepends.length - 1]?.deeper.push(line);
+        continue;
+      }
+      if (inDependsOn) {
+        // thoát depends_on (comment 2-space / blank) — xả pending rồi ghi line
+        flushDepends(out, pruned);
+        inDependsOn = false;
+      }
+      out.push(line);
+      continue;
+    }
+    out.push(line); // nền section (comment section header…)
+  }
+  flushDepends(out, pruned);
+  return out.join('\n').replace(/\n{3,}/g, '\n\n');
+}
+
+// Trạng thái depends_on đang gom (giữ module-level cục bộ qua closure của 1 call
+// bằng biến function-scoped — dùng container để flushDepends đọc được).
+const pendingDepends: string[] = [];
+interface DependsEntry {
+  name: string;
+  line: string;
+  deeper: string[];
+}
+const currentDepends: DependsEntry[] = [];
+
+function flushDepends(out: string[], pruned: readonly string[]): void {
+  if (currentDepends.length === 0) {
+    if (pendingDepends.length > 0) out.push(pendingDepends[0]!); // depends_on rỗng
+    pendingDepends.length = 0;
+    return;
+  }
+  out.push(pendingDepends[0]!);
+  pendingDepends.length = 0;
+  for (const entry of currentDepends) {
+    if (pruned.includes(entry.name)) continue;
+    out.push(entry.line);
+    out.push(...entry.deeper);
+  }
+  currentDepends.length = 0;
+}
+
+function textHasPruneNote(out: string[]): boolean {
+  return out.some((l) => l.includes('create-wakii-stack: pruned'));
+}
+
+function dropPgdata(selected: ReadonlySet<string>, allServices: string[]): boolean {
+  return allServices.includes('postgres') && !selected.has('postgres');
+}
+
+/** Lọc gateway conf: xoá khối ngoặc chứa marker (brace-count từ dòng mở). */
+export function pruneGatewayConf(text: string, markers: string[]): string {
+  let lines = text.split('\n');
+  for (const marker of markers) {
+    const result: string[] = [];
+    let skipping = false;
+    let depth = 0;
+    for (const line of lines) {
+      if (!skipping && line.includes(marker)) {
+        // mở khối: đếm brace trên chính dòng mở
+        skipping = true;
+        depth = (line.match(/\{/g)?.length ?? 0) - (line.match(/\}/g)?.length ?? 0);
+        if (depth <= 0) skipping = false; // khối 1 dòng
+        continue;
+      }
+      if (skipping) {
+        depth += (line.match(/\{/g)?.length ?? 0) - (line.match(/\}/g)?.length ?? 0);
+        if (depth <= 0) skipping = false;
+        continue;
+      }
+      result.push(line);
+    }
+    lines = result;
+  }
+  return lines.join('\n').replace(/\n{3,}/g, '\n\n');
+}
+
+/** Lọc file env: bỏ dòng có key (KEY=…) thuộc danh sách bỏ. */
+export function pruneEnv(text: string, keys: string[]): string {
+  const keySet = new Set(keys);
+  return text
+    .split('\n')
+    .filter((line) => {
+      const match = /^([A-Za-z_][A-Za-z0-9_]*)=/.exec(line);
+      return !match || !keySet.has(match[1]!);
+    })
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n');
+}
+
+/** README.md sinh ở đỉnh dest — services chọn + up + smoke + ports. */
+export function renderReadme(manifest: StackManifest, selection: StackSelection): string {
+  const ports = Object.entries(manifest.ports ?? {})
+    .map(([name, url]) => `- ${name}: ${url}`)
+    .join('\n');
+  return `# ${selection.appName}
+
+Stack generated by \`create-wakii-stack\` (Hybrid C — full template pruned to your selection).
+
+## Services
+
+${selection.services.map((s) => `- ${s} _(${manifest.services[s]?.layer ?? '?'})_`).join('\n')}
+
+## Run
+
+\`\`\`bash
+cd ${selection.appName}
+cp platform/.env.example platform/.env   # điền secret trước khi up
+docker compose --env-file platform/.env up -d
+\`\`\`
+
+${manifest.smoke ? `## Smoke\n\n\`\`\`bash\n${manifest.smoke}\n\`\`\`\n` : ''}
+${ports ? `## URLs\n\n${ports}\n` : ''}
+Need a FE app (SPA) outside this stack? \`pnpm create wakii-app\`.
+`;
+}
+
+/** Scaffold 1 stack: full-copy → render → prune theo manifest → README. */
+export async function scaffold(input: StackScaffoldInput): Promise<StackScaffoldResult> {
+  const { selection, dest, log } = input;
+  const templateRoot = input.templateRoot ?? DEFAULT_TEMPLATE_ROOT;
+  const manifestPath = join(templateRoot, 'stack-manifest.json');
+  if (!existsSync(manifestPath)) throw new Error(`Không thấy stack-manifest.json tại ${templateRoot}`);
+  const { loadManifest } = await import('./manifest.js');
+  const manifest = loadManifest(manifestPath);
+
+  const files: string[] = [];
+  log?.(`Copy full template → ${dest}`);
+  await copyTree(templateRoot, dest, { stackName: selection.appName, files });
+
+  const allServices = Object.keys(manifest.services);
+  const pruned = allServices.filter((s) => !selection.services.includes(s));
+
+  // 1. xoá paths của service bị prune
+  for (const name of pruned) {
+    for (const relPath of manifest.services[name]!.paths ?? []) {
+      const target = join(dest, relPath);
+      if (existsSync(target)) {
+        await rm(target, { recursive: true, force: true });
+        log?.(`Pruned path: ${relPath}`);
+      }
+    }
+  }
+
+  // 2. prune compose (block + depends_on + pgdata + warning comment)
+  const composePath = join(dest, manifest.files.compose);
+  if (existsSync(composePath) && pruned.length > 0) {
+    const before = await readFile(composePath, 'utf8');
+    await writeFile(composePath, pruneCompose(before, new Set(selection.services), allServices));
+    log?.(`Pruned compose: -${pruned.join(', -')}`);
+  }
+
+  // 3. prune gateway conf theo gatewayBlocks của service bị prune
+  if (manifest.files.gatewayConf) {
+    const gatewayPath = join(dest, manifest.files.gatewayConf);
+    const markers = pruned.flatMap((name) => manifest.services[name]!.gatewayBlocks ?? []);
+    if (existsSync(gatewayPath) && markers.length > 0) {
+      const before = await readFile(gatewayPath, 'utf8');
+      await writeFile(gatewayPath, pruneGatewayConf(before, markers));
+      log?.(`Pruned gateway blocks: ${markers.length}`);
+    }
+  }
+
+  // 4. lọc env keys
+  if (manifest.files.env) {
+    const envPath = join(dest, manifest.files.env);
+    const keys = pruned.flatMap((name) => manifest.services[name]!.envKeys ?? []);
+    if (existsSync(envPath) && keys.length > 0) {
+      const before = await readFile(envPath, 'utf8');
+      await writeFile(envPath, pruneEnv(before, keys));
+      log?.(`Pruned env keys: ${keys.length}`);
+    }
+  }
+
+  // 5. README sinh ở đỉnh dest
+  await writeFile(join(dest, 'README.md'), renderReadme(manifest, selection));
+  files.push('README.md');
+
+  return { files: files.map((f) => f.slice(dest.length + 1)), prunedServices: pruned };
+}

package/stack-template/app/create-wakii-stack/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["src"]
+}

package/stack-template/app/create-wakii-stack/vitest.config.ts

@@ -0,0 +1,9 @@
+// Vitest — engine test Node thuần (fs tmp thật, KHÔNG network, KHÔNG DOM).
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+  },
+});

package/stack-template/app/remotes/activity/Dockerfile

@@ -0,0 +1,36 @@
+# Remote `activity` — MF remote static (SF-6). Multi-stage theo platform/conventions/01-dockerfile-pattern.md.
+# Build context = repo ROOT (compose: context .., dockerfile app/remotes/activity/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, spike/host, spike/remote, shell,
+# remotes/tasks, remotes/activity) — 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/
+COPY app/remotes/tasks/package.json app/remotes/tasks/
+COPY app/remotes/activity/package.json app/remotes/activity/
+RUN pnpm install --frozen-lockfile --filter @wakii/remote-activity...
+COPY app/shared app/shared
+COPY app/ui-kit app/ui-kit
+COPY app/remotes/activity app/remotes/activity
+# Build-time env (conventions/06+08): prod API base = '' (same-origin qua gateway),
+# publicPath = /remotes/activity/ (gateway /remotes/<name>/ — conventions/08)
+ENV API_BASE_URL="" \
+    REMOTE_PUBLIC_PATH="/remotes/activity/" \
+    NODE_ENV=production
+RUN pnpm --filter @wakii/remote-activity build
+
+# runtime stage — nginx serve static, port cố định 4002 (conventions/05)
+# Healthcheck KHÔNG khai ở đây (conventions/01 rule 4 — một nguồn duy nhất: compose entry remote-activity)
+FROM nginx:1.27-alpine AS runtime
+COPY app/remotes/activity/nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /repo/app/remotes/activity/dist /usr/share/nginx/html
+EXPOSE 4002

package/stack-template/app/remotes/activity/README.md

@@ -0,0 +1,59 @@
+# @wakii/remote-activity
+
+FE remote `activity` — MF REMOTE (Rspack + @module-federation/enhanced, React 19). Expose `./ActivityPage`, shell (MF host) mount vào route `/activity` theo remote registry [`platform/conventions/08-gateway-and-remotes.md`](../../../platform/conventions/08-gateway-and-remotes.md).
+
+Feed + stats qua gateway `/api/activity` (go-svc) — render **trực tiếp** user-display fields (`userName`, `taskTitle`) từ response (go-svc resolve, FE không tự bịa); JWT tự đính qua `@wakii/fe-shared` ApiClient; error envelope decode → banner (stats lỗi không che feed).
+
+## Chạy dev
+
+```bash
+# từ repo root — pnpm workspace
+pnpm install
+pnpm --filter @wakii/remote-activity dev   # http://localhost:4002
+```
+
+Remote thật sự dùng được khi load TRONG shell (`pnpm --filter @wakii/shell dev` với
+`REMOTE_ACTIVITY_URL=http://localhost:4002/remoteEntry.js`); standalone :4002 chỉ để debug UI
+(không token ở origin này → API 401 là đúng hành vi).
+
+## Env build-time (conventions/06)
+
+| Var | Default dev | Prod | Ý nghĩa |
+|-----|-------------|------|---------|
+| `API_BASE_URL` | `http://localhost:8082` | `''` | Base gọi API — dev native gọi thẳng go-svc (CORS dev mở, conventions/07); prod same-origin qua gateway |
+| `REMOTE_PUBLIC_PATH` | `http://localhost:4002/` | `/remotes/activity/` | publicPath chunk (absolute khi dev, relative qua gateway khi prod) |
+| `REMOTE_ACTIVITY_PORT` | `4002` | — | Port dev server (conventions/05) |
+
+## Test + build
+
+```bash
+pnpm --filter @wakii/remote-activity test        # vitest + testing-library
+pnpm --filter @wakii/remote-activity typecheck
+pnpm --filter @wakii/remote-activity build       # dist/ — Dockerfile nginx serve static
+```
+
+## Docker
+
+Build context = **repo root** (cần `app/shared` + lockfile):
+
+```bash
+docker build -f app/remotes/activity/Dockerfile -t boilerplate-remote-activity .
+docker run -p 4002:4002 boilerplate-remote-activity   # http://localhost:4002/remoteEntry.js
+```
+
+## Standalone-copy
+
+Copy thư mục này **KÈM `app/shared/` + `app/ui-kit/`** (+ root `pnpm-workspace.yaml`/`pnpm-lock.yaml`) — remote import `@wakii/fe-shared` qua `workspace:*`.
+
+## API contract
+
+`contracts/openapi/activity.yaml` — source of truth (feed/stats shape, user-display fields, error envelope).
+
+> Lưu ý: override `REMOTE_ACTIVITY_PORT` KHÔNG tự đổi publicPath (default vẫn :4002) — đặt kèm `REMOTE_PUBLIC_PATH` nếu đổi port dev.
+
+## Design system (từ `@wakii/ui-kit` — story VU-53, tách khỏi fe-shared ADR-0009)
+
+- **Trong shell**: KHÔNG import lại `base.css` — shell import global làm chủ; remote chỉ ăn **tokens** CSS vars (`--c-* --ink* --line* --accent* --st-* --sp-* --fs-* --r-*`) + scoped classes riêng (`act-*`), không element selector toàn cục.
+- **Standalone** (`src/standalone.tsx`): tự import `tokens.css` + `base.css` để trang debug có style đầy đủ.
+- **Primitives**: `import { Badge, EmptyState, Skeleton, Spinner } from '@wakii/ui-kit'` — badge action feed = `Badge variant created|updated|assigned|deleted|assignmentFailed` (mỗi action một màu chấm); loading stats/feed skeleton ĐỘC LẬP (giữ `Promise.allSettled`); empty = `EmptyState` hướng dẫn sang Tasks; nút *Làm mới* busy = `Spinner`.
+- 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/remotes/activity/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>Remote: activity (standalone debug)</title>
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/stack-template/app/remotes/activity/nginx.conf

@@ -0,0 +1,35 @@
+# Remote `activity` static — port cố định 4002 trong container (conventions/05, gateway /remotes/activity/)
+server {
+  listen 4002;
+  server_name _;
+  root /usr/share/nginx/html;
+  index index.html;
+
+  # Security headers baseline — CSP cho MF để SF-7 thiết kế (script-src origin shell)
+  add_header X-Content-Type-Options "nosniff" always;
+  add_header X-Frame-Options "DENY" always;
+  add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+
+  # remoteEntry.js — shell fetch mỗi lần boot; KHÔNG cache aggressive (deploy mới phải thấy ngay)
+  location = /remoteEntry.js {
+    add_header Cache-Control "no-cache";
+  }
+
+  # Static asset — contenthash nên cache được lâu
+  location /assets/ {
+    expires 30d;
+    add_header Cache-Control "public, immutable";
+  }
+
+  # Standalone :4002 (BUG-1 sf-5b): index.html + runtime chunk fetch dùng publicPath
+  # gateway-shaped (/remotes/activity/main.*.js — compile-time, cần cho in-shell qua
+  # gateway) → map prefix đó về root để cùng 1 dist phục vụ cả 2 đường, không đổi publicPath.
+  location /remotes/activity/ {
+    alias /usr/share/nginx/html/;
+  }
+
+  # Standalone debug index (index.html) — không router nên fallback đơn giản
+  location / {
+    try_files $uri $uri/ /index.html;
+  }
+}

package/stack-template/app/remotes/activity/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@wakii/remote-activity",
+  "version": "0.1.0",
+  "private": true,
+  "description": "FE remote `activity` (SF-6, FI-74) — MF remote expose ./ActivityPage, feed + stats qua /api/activity (go-svc qua gateway). Standalone-copy: copy KÈM app/shared (fe-shared).",
+  "type": "module",
+  "scripts": {
+    "dev": "rspack serve",
+    "build": "rspack build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "catalog:",
+    "@wakii/fe-shared": "workspace:*",
+    "@wakii/ui-kit": "workspace:*",
+    "motion": "^12",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "react-hook-form": "^7"
+  },
+  "devDependencies": {
+    "@module-federation/enhanced": "catalog:",
+    "@rspack/cli": "1.7.12",
+    "@rspack/core": "catalog:",
+    "@tailwindcss/postcss": "^4.3.3",
+    "@testing-library/jest-dom": "6.9.0",
+    "@testing-library/react": "16.3.0",
+    "@testing-library/user-event": "14.6.1",
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.3",
+    "jsdom": "27.0.0",
+    "postcss-loader": "^8.2.1",
+    "typescript": "^5.7.0",
+    "vitest": "3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}