create-wakii-stack 0.0.0-stage → 0.1.1

package/stack-template/app/admin/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "types": ["vite/client", "vitest/globals", "@testing-library/jest-dom"]
+  },
+  "include": ["src", "vite.config.ts", "vitest.config.ts"]
+}

package/stack-template/app/admin/vite.config.ts

@@ -0,0 +1,11 @@
+// Vite config — app admin (batch ⑦): React SPA showcase ui-kit, port 5173 (storybook
+// ui-kit giữ 6006). Tailwind v4 qua @tailwindcss/vite — theme/utilities đến từ
+// ui-kit/styles/tailwind.css (xem src/styles.css: @source qua symlink node_modules).
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  server: { port: 5173 },
+});

package/stack-template/app/admin/vitest.config.ts

@@ -0,0 +1,14 @@
+// Vitest — admin tests (routing render + form zod). jsdom + globals, cùng pattern ui-kit.
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  esbuild: {
+    // JSX automatic runtime — không thì "React is not defined" lúc render
+    jsx: 'automatic',
+  },
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['./src/tests/setup.ts'],
+  },
+});

package/stack-template/app/create-wakii-app/README.md

@@ -0,0 +1,71 @@
+# create-wakii-app
+
+[![npm](https://img.shields.io/npm/v/create-wakii-app?logo=npm&label=create-wakii-app)](https://www.npmjs.com/package/create-wakii-app)
+
+Scaffold a React app wired with [@wakii/ui-kit](https://www.npmjs.com/package/@wakii/ui-kit) — CRA-style: interactive prompts, non-interactive flags. **Published as [`create-wakii-app@0.1.0`](https://www.npmjs.com/package/create-wakii-app) on npmjs.org.**
+
+## Usage
+
+```bash
+npm create wakii-app@latest my-app     # official
+npx create-wakii-app my-app            # npx
+pnpm create wakii-app my-app           # pnpm
+yarn create wakii-app my-app           # yarn
+```
+
+Interactive flow — you are only prompted for what's missing (project name → react-router? → extras multiselect → confirm → scaffold), then it prints the next steps:
+
+```
+cd my-app
+pnpm install
+pnpm dev
+```
+
+Non-interactive:
+
+```bash
+pnpm create wakii-app my-app --yes                                  # all defaults (ts + router, no extras)
+pnpm create wakii-app my-app --yes --extras chart                   # defaults + a chart demo route
+pnpm create wakii-app ~/code/my-app --lang js --skip-install        # path + JavaScript, skip the install hint
+```
+
+## Flags
+
+| Flag | Meaning | Default |
+|---|---|---|
+| `[appName]` (positional) | A name **or a path**: `my-app` → `./my-app`; `/a/b/my-app` → target `/a/b/my-app`. The package name is always the **basename** (a path never leaks into package.json) | prompt (`my-wakii-app`) |
+| `--lang ts\|js` | TypeScript / JavaScript (also accepts `--lang=js`) | `ts` |
+| `--router` / `--no-router` | react-router v7 (prompted when missing — unless `--yes`) | on |
+| `--extras <list>` | demo subpaths: `chart · carousel · schedule · editor` (also accepts `--extras=a`). Extras **imply the router** (each demo subpath is its own route) | none |
+| `--yes` | skip prompts, take all defaults | — |
+| `--skip-install` | omit `pnpm install` from the next steps | — |
+| `-h`, `--help` | print usage | — |
+
+Intentional error: `--no-router` together with `--extras` is a conflict → the CLI reports it clearly and exits (drop one of the two). The CLI **never installs** anything — it only prints next steps (`cd` to the exact target it created, even when you passed a path).
+
+## What's in the template
+
+Base (ts/js) — a demo app dogfooding **`@wakii/ui-kit` ^0.5.0** (pinned: the first version with dist exports):
+
+- **A working dark toggle** — `useAppTheme` (src/theme) persists to `localStorage` and sets `data-bp-theme` on `<html>`; every kit component cascades, no re-render.
+- **Demo components**: wash hero + Tag/Title/Text + 3 Buttons · a 3-column Table (Badge statuses) · Alert ×4 · CountUp Statistic · a "What's inside" Card (Storybook + npm links).
+- **Tokens-first**: a single styles.css (kit tokens + base + Tailwind v4 + the kit `@source`) — zero hex in the app.
+
+Router (on by default, react-router v7): a `/` demo route plus `/about` introducing the kit (NavLink). Extras: each extra adds one demo route using the matching subpath (`@wakii/ui-kit/chart`, `./carousel`, `./schedule`, `./editor`) and writes its peer dependency into package.json.
+
+## Architecture (repo)
+
+- `src/options.ts` — hand-rolled flag parser (zero parser dependencies) + defaults + validation (`--no-router` × `--extras` throws)
+- `src/scaffold.ts` — recursive template copy → renders the `{{appName}}` placeholder (binaries skipped) → applies the `router` / `extras/<name>` overlays → merges dependencies into package.json
+- `src/index.ts` — the `@clack/prompts` flow + logging + next steps (UI wiring only)
+
+Template sources: `app/starter-templates/vite-ts|vite-js` + `template-feats/` (owned by a separate worker). JS-variant overlays must be type-free (the engine only renames `.tsx→.jsx`); if an overlay ships its own `vite-js/` directory, that directory is used as-is.
+
+## Development
+
+```bash
+pnpm --filter create-wakii-app typecheck
+pnpm --filter create-wakii-app test      # fixture templates in tmp — no network
+```
+
+Publishing to npmjs: `./scripts/publish-npm.sh` — builds (tsup), then bundles `dist` + **`starter-templates/`** (vite-ts + vite-js) into the package (`files` field — npm rejects parent paths like `../`), sets `publishConfig` to public, and publishes using `NPM_TOKEN` (env) or an existing `_authToken` in `~/.npmrc`.

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

@@ -0,0 +1,27 @@
+{
+  "name": "create-wakii-app",
+  "version": "0.1.2",
+  "private": true,
+  "type": "module",
+  "description": "CLI scaffold app React + @wakii/ui-kit — pnpm create wakii-app my-app (spec: /tmp/starter-spec.md → docs khi publish)",
+  "bin": {
+    "create-wakii-app": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "tsup": "^9.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/stack-template/app/create-wakii-app/scripts/publish-npm.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Publish create-wakii-app lên npmjs.org — bundle starter-templates VÀO package
+# (npm files không nhận path cha '../' — engine resolve <pkg>/starter-templates).
+# Auth: env NPM_TOKEN hoặc ~/.npmrc đã có token wakii (mirror ui-kit script).
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+NPMRC_AUTH="$(grep -s '^//registry\.npmjs\.org/:_authToken=' "${NPM_CONFIG_USERCONFIG:-$HOME/.npmrc}" | head -1 || true)"
+if [ -z "${NPM_TOKEN:-}" ] && [ -z "$NPMRC_AUTH" ]; then
+  echo "✗ Thiếu NPM_TOKEN (env) hoặc _authToken npmjs trong ~/.npmrc"; exit 1
+fi
+
+echo "▶ Build (tsup)..."
+pnpm build
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+cp -r dist README.md package.json "$TMP/"
+mkdir -p "$TMP/starter-templates"
+cp -r ../starter-templates/. "$TMP/starter-templates/"
+[ -f "$TMP/starter-templates/vite-ts/package.json" ] || { echo "✗ thiếu template vite-ts sau copy"; exit 1; }
+
+python3 - "$TMP" << 'PY'
+import json, sys
+p = json.load(open(f'{sys.argv[1]}/package.json'))
+p['publishConfig'] = {'registry': 'https://registry.npmjs.org', 'access': 'public'}
+p['files'] = ['dist', 'starter-templates', 'README.md']
+for k in ('devDependencies', 'scripts', 'private'): p.pop(k, None)
+json.dump(p, open(f'{sys.argv[1]}/package.json', 'w'), indent=2, ensure_ascii=False)
+open(f'{sys.argv[1]}/package.json', 'a').write('\n')
+PY
+
+if [ -n "${NPM_TOKEN:-}" ]; then
+  printf '//registry.npmjs.org/:_authToken=%s\n' "$NPM_TOKEN" > "$TMP/.npmrc"
+fi
+cd "$TMP"
+npm publish --registry=https://registry.npmjs.org --access public
+echo "✓ create-wakii-app published (npmjs.org)"

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

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// create-wakii-app — CLI scaffold app React + @wakii/ui-kit (spec starter-spec).
+// Flow: parse flags → prompt phần thiếu (@clack) → confirm → scaffold → next-steps.
+// Engine logic nằm ở options.ts/scaffold.ts (test được) — file này chỉ wire UI.
+import * as p from '@clack/prompts';
+import { existsSync, readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { EXTRAS, parseArgs, resolveOptions, type ScaffoldPlan } from './options.js';
+import { scaffold } from './scaffold.js';
+
+const USAGE = `create-wakii-app — scaffold app React + @wakii/ui-kit
+
+Usage: pnpm create wakii-app [appName] [flags]
+
+Flags:
+  --lang ts|js        Ngôn ngữ (default: ts)
+  --router/--no-router  react-router v7 (default: có)
+  --extras <list>     Extras phẩy ngăn cách: chart,carousel,schedule,editor (default: none)
+  --yes               Lấy toàn bộ default, không prompt
+  --skip-install      Bỏ gợi ý 'pnpm install' ở next-steps
+  -h, --help          In hướng dẫn
+
+Ví dụ: pnpm create wakii-app my-app --lang ts --router --extras chart,carousel
+`;
+
+function printNextSteps(plan: ScaffoldPlan): void {
+  const steps = [`cd ${plan.appName}`];
+  if (!plan.skipInstall) steps.push('pnpm install');
+  steps.push('pnpm dev');
+  p.log.info('Next steps:');
+  for (const step of steps) p.log.step(`  ${step}`);
+}
+
+async function main(): Promise<void> {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (!parsed.ok) {
+    p.log.error(parsed.message);
+    console.error(USAGE);
+    process.exitCode = 1;
+    return;
+  }
+  if (parsed.options.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  p.intro('create-wakii-app — scaffold React + @wakii/ui-kit');
+
+  let options = parsed.options;
+  if (options.appName === undefined) {
+    const name = await p.text({ message: 'Tên project?', placeholder: 'my-wakii-app', defaultValue: 'my-wakii-app' });
+    if (p.isCancel(name)) {
+      p.cancel('Huỷ — không scaffold gì.');
+      return;
+    }
+    options = { ...options, appName: name.trim() };
+  }
+  if (options.router === undefined && options.extras.length === 0 && !options.yes) {
+    const withRouter = await p.confirm({ message: 'Thêm react-router v7?', initialValue: true });
+    if (p.isCancel(withRouter)) {
+      p.cancel('Huỷ — không scaffold gì.');
+      return;
+    }
+    options = { ...options, router: withRouter };
+  }
+  if (!options.yes && !options.extrasProvided) {
+    const chosen = await p.multiselect({
+      message: 'Extras (tuỳ chọn — demo subpath component nặng)',
+      options: EXTRAS.map((value) => ({ value, label: value })),
+      required: false,
+    });
+    if (p.isCancel(chosen)) {
+      p.cancel('Huỷ — không scaffold gì.');
+      return;
+    }
+    options = { ...options, extras: chosen };
+  }
+
+  let plan: ReturnType<typeof resolveOptions>;
+  try {
+    plan = resolveOptions(options);
+  } catch (err) {
+    p.log.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  // Positional nhận TÊN hoặc ĐƯỜNG DẪN (CRA style): 'my-app' → ./my-app;
+  // '/a/b/my-app' → dest /a/b/my-app. Package name luôn lấy basename — path
+  // tuyệt đối không lọt vào package.json (bug gate 2026-10-24).
+  const nameIsPath = /[\\/]/.test(plan.appName);
+  const dest = nameIsPath ? resolve(plan.appName) : resolve(process.cwd(), plan.appName);
+  const finalPlan = nameIsPath
+    ? { ...plan, appName: dest.split(/[\\/]/).pop() ?? 'my-wakii-app' }
+    : plan;
+  if (existsSync(dest) && readdirSync(dest).length > 0) {
+    p.log.error(`Thư mục đích đã tồn tại và không rỗng: ${dest}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const s = p.spinner();
+  s.start('Scaffolding…');
+  try {
+    const result = await scaffold({
+      plan: finalPlan,
+      dest,
+      log: (message) => {
+        s.message(message);
+      },
+    });
+    s.stop(`Xong — ${result.files.length} file ghi vào ${dest}`);
+  } catch (err) {
+    s.stop('Scaffold lỗi');
+    p.log.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+
+  p.outro('Sẵn sàng! 🎉');
+  // next-steps cd theo ĐÚNG đường dẫn đã tạo (path hoặc ./name)
+  printNextSteps(nameIsPath ? { ...finalPlan, appName: dest } : finalPlan);
+}
+
+main().catch((err: unknown) => {
+  p.log.error(err instanceof Error ? err.message : String(err));
+  process.exitCode = 1;
+});

package/stack-template/app/create-wakii-app/src/options.test.ts

@@ -0,0 +1,80 @@
+// Tests options — flags + defaults + invalid (spec: parse flags, defaults, invalid).
+import { describe, expect, it } from 'vitest';
+import { parseArgs, resolveOptions } from './options.js';
+
+describe('parseArgs', () => {
+  it('rỗng → defaults (lang ts, extras [], router/appName undefined để prompt)', () => {
+    const r = parseArgs([]);
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.options).toMatchObject({ lang: 'ts', extras: [], yes: false, skipInstall: false });
+      expect(r.options.appName).toBeUndefined();
+      expect(r.options.router).toBeUndefined();
+    }
+  });
+
+  it('positional → appName; --yes → yes', () => {
+    const r = parseArgs(['my-app', '--yes']);
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.options.appName).toBe('my-app');
+      expect(r.options.yes).toBe(true);
+    }
+  });
+
+  it('--lang js (dạng tách) và --lang=js (dấu =) đều nhận', () => {
+    expect(parseArgs(['--lang', 'js'])).toMatchObject({ ok: true, options: { lang: 'js' } });
+    expect(parseArgs(['--lang=js'])).toMatchObject({ ok: true, options: { lang: 'js' } });
+  });
+
+  it('--lang py → lỗi rõ', () => {
+    const r = parseArgs(['--lang', 'py']);
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.message).toContain("--lang chỉ nhận 'ts' | 'js'");
+  });
+
+  it('--router / --no-router set tri-state', () => {
+    expect(parseArgs(['--router'])).toMatchObject({ ok: true, options: { router: true } });
+    expect(parseArgs(['--no-router'])).toMatchObject({ ok: true, options: { router: false } });
+  });
+
+  it('--extras chart,carousel → parse + dedupe; --extras=chart dạng =; extra lạ → lỗi', () => {
+    expect(parseArgs(['--extras', 'chart,carousel'])).toMatchObject({
+      ok: true,
+      options: { extras: ['chart', 'carousel'], extrasProvided: true },
+    });
+    expect(parseArgs(['--extras=chart,chart'])).toMatchObject({
+      ok: true,
+      options: { extras: ['chart'] },
+    });
+    const bad = parseArgs(['--extras', 'redux']);
+    expect(bad.ok).toBe(false);
+    if (!bad.ok) expect(bad.message).toContain("Extra không hỗ trợ: 'redux'");
+  });
+
+  it('flag lạ → lỗi; 2 positional → lỗi; --skip-install + -h nhận', () => {
+    expect(parseArgs(['--bogus']).ok).toBe(false);
+    expect(parseArgs(['a', 'b']).ok).toBe(false);
+    expect(parseArgs(['--skip-install', '-h'])).toMatchObject({
+      ok: true,
+      options: { skipInstall: true, help: true },
+    });
+  });
+});
+
+describe('resolveOptions', () => {
+  it('đổ default: appName my-wakii-app, router true; giá trị chỉ định thắng', () => {
+    expect(resolveOptions({ lang: 'ts', extras: [], yes: true, skipInstall: false })).toEqual({
+      appName: 'my-wakii-app',
+      lang: 'ts',
+      router: true,
+      extras: [],
+      skipInstall: false,
+    });
+    // extras kéo theo router; tắt router tường minh + extras → lỗi rõ
+    expect(resolveOptions({ appName: 'x', lang: 'js', router: true, extras: ['chart'], yes: false, skipInstall: true })).toEqual({
+      appName: 'x', lang: 'js', router: true, extras: ['chart'], skipInstall: true,
+    });
+    expect(() => resolveOptions({ lang: 'ts', router: false, extras: ['chart'], yes: true, skipInstall: false })).toThrow(/mâu thuẫn/);
+  });
+});

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

@@ -0,0 +1,117 @@
+// options — parse argv tự viết (0 dep parser, spec engine): flag đơn giản +
+// defaults + validate. `router`/`appName` có thể undefined = CHƯA chỉ định →
+// CLI flow prompt; `--yes` lấy default qua resolveOptions.
+export const EXTRAS = ['chart', 'carousel', 'schedule', 'editor'] as const;
+export type Extra = (typeof EXTRAS)[number];
+export type Lang = 'ts' | 'js';
+
+export interface CliOptions {
+  /** Positional đầu tiên — undefined → CLI prompt (default 'my-wakii-app'). */
+  appName?: string;
+  lang: Lang;
+  /** undefined = chưa chỉ định (prompt); true/false = --router/--no-router. */
+  router?: boolean;
+  extras: Extra[];
+  yes: boolean;
+  skipInstall: boolean;
+  /** --help — index.ts in usage (options không tự in). */
+  help?: boolean;
+  /** --extras có mặt trên argv — CLI flow dùng để bỏ prompt multiselect. */
+  extrasProvided?: boolean;
+}
+
+export type ParseResult = { ok: true; options: CliOptions } | { ok: false; message: string };
+
+/** Plan hoàn chỉnh sau khi đổ default — đầu vào của scaffold(). */
+export interface ScaffoldPlan {
+  appName: string;
+  lang: Lang;
+  router: boolean;
+  extras: Extra[];
+  skipInstall: boolean;
+}
+
+function parseExtrasList(raw: string): { ok: true; extras: Extra[] } | { ok: false; message: string } {
+  const names = raw
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const extras: Extra[] = [];
+  for (const name of names) {
+    if (!(EXTRAS as readonly string[]).includes(name)) {
+      return { ok: false, message: `Extra không hỗ trợ: '${name}' — hợp lệ: ${EXTRAS.join(', ')}` };
+    }
+    if (!extras.includes(name as Extra)) extras.push(name as Extra);
+  }
+  return { ok: true, extras };
+}
+
+/** Parse argv (đã cắt program name) — lỗi đầu tiên trả ngay (không gom). */
+export function parseArgs(argv: readonly string[]): ParseResult {
+  const options: CliOptions = { lang: 'ts', extras: [], yes: false, skipInstall: false };
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === '--yes') {
+      options.yes = true;
+    } else if (arg === '--skip-install') {
+      options.skipInstall = true;
+    } else if (arg === '--router') {
+      options.router = true;
+    } else if (arg === '--no-router') {
+      options.router = false;
+    } else if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--lang') {
+      const value = argv[i + 1];
+      i += 1;
+      if (value !== 'ts' && value !== 'js') {
+        return { ok: false, message: `--lang chỉ nhận 'ts' | 'js' — nhận: ${value ?? '(thiếu giá trị)'}` };
+      }
+      options.lang = value;
+    } else if (arg?.startsWith('--lang=')) {
+      const value = arg.slice('--lang='.length);
+      if (value !== 'ts' && value !== 'js') {
+        return { ok: false, message: `--lang chỉ nhận 'ts' | 'js' — nhận: ${value}` };
+      }
+      options.lang = value;
+    } else if (arg === '--extras') {
+      const value = argv[i + 1];
+      i += 1;
+      if (!value) return { ok: false, message: '--extras cần danh sách phẩy: --extras chart,carousel' };
+      const parsed = parseExtrasList(value);
+      if (!parsed.ok) return parsed;
+      options.extras = parsed.extras;
+      options.extrasProvided = true;
+    } else if (arg?.startsWith('--extras=')) {
+      const parsed = parseExtrasList(arg.slice('--extras='.length));
+      if (!parsed.ok) return parsed;
+      options.extras = parsed.extras;
+      options.extrasProvided = true;
+    } else if (arg?.startsWith('--')) {
+      return { ok: false, message: `Flag không hỗ trợ: ${arg} (xem --help)` };
+    } else if (arg !== undefined) {
+      if (options.appName !== undefined) return { ok: false, message: 'Chỉ nhận MỘT tên project (positioned đầu tiên)' };
+      options.appName = arg;
+    }
+    i += 1;
+  }
+  return { ok: true, options };
+}
+
+/** Đổ default cho các field chưa chỉ định — dùng khi `--yes` hoặc sau prompts.
+ * Extras cần router (demo subpath là route riêng — quyết định thiết kế
+ * 2026-10-24: copy-overlay không thể mở route khi thiếu BrowserRouter):
+ * có extras mà router bị TẮT TƯỜNG MINH → lỗi rõ cho user bỏ một trong hai. */
+export function resolveOptions(options: CliOptions): ScaffoldPlan {
+  if (options.extras.length > 0 && options.router === false) {
+    throw new Error('--no-router mâu thuẫn với --extras (demo subpath cần route để mở) — bỏ --no-router hoặc bỏ extras');
+  }
+  return {
+    appName: options.appName ?? 'my-wakii-app',
+    lang: options.lang,
+    router: options.extras.length > 0 ? true : (options.router ?? true),
+    extras: options.extras,
+    skipInstall: options.skipInstall,
+  };
+}

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

@@ -0,0 +1,143 @@
+// Tests scaffold — fixture templates GIẢ nhỏ trong tmp (không phụ thuộc worker
+// starter-templates): copy + render placeholder + skip .DS_Store + binary nguyên
+// bản + overlay router/extras + merge deps + JS variant (đổi đuôi overlay).
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { scaffold, type ScaffoldInput } from './scaffold.js';
+
+let root: string;
+let dest: string;
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'cwa-engine-'));
+  dest = join(root, 'dest');
+});
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+/** Dựng fixture template theo cấu trúc spec (đủ để test mọi nhánh engine). */
+async function makeTemplates(): Promise<string> {
+  const t = join(root, 'starter-templates');
+  // base TS
+  await mkdir(join(t, 'vite-ts', 'src'), { recursive: true });
+  await writeFile(join(t, 'vite-ts', 'package.json'), JSON.stringify({ name: '{{appName}}', dependencies: { react: '^19' } }));
+  await writeFile(join(t, 'vite-ts', 'vite.config.ts'), 'export default {}; // {{appName}}');
+  await writeFile(join(t, 'vite-ts', 'src', 'main.tsx'), "import './styles.css';\n// app {{appName}}");
+  await writeFile(join(t, 'vite-ts', '.DS_Store'), 'junk');
+  const binary = Buffer.from([0x00, 0x01, ...Buffer.from('{{appName}}')]);
+  await writeFile(join(t, 'vite-ts', 'logo.png'), binary);
+  // base JS
+  await mkdir(join(t, 'vite-js', 'src'), { recursive: true });
+  await writeFile(join(t, 'vite-js', 'package.json'), JSON.stringify({ name: '{{appName}}' }));
+  await writeFile(join(t, 'vite-js', 'src', 'main.jsx'), '// js app {{appName}}');
+  // overlay router (TS gốc) — overlay tree MIRROR cấu trúc dest (1:1):
+  // template-feats/router/src/App.tsx → dest/src/App.tsx
+  await mkdir(join(t, 'template-feats', 'router', 'src'), { recursive: true });
+  await writeFile(join(t, 'template-feats', 'router', 'src', 'App.tsx'), 'export default () => <h1>{{appName}} routed</h1>;');
+  await writeFile(join(t, 'template-feats', 'router', 'src', 'main.tsx'), '// router main {{appName}}');
+  // overlay extra chart + schedule + editor (schedule/editor: fixture cho test multi-deps)
+  await mkdir(join(t, 'template-feats', 'extras', 'chart', 'src'), { recursive: true });
+  await writeFile(join(t, 'template-feats', 'extras', 'chart', 'src', 'ChartPage.tsx'), '// chart page {{appName}}');
+  await mkdir(join(t, 'template-feats', 'extras', 'schedule', 'src'), { recursive: true });
+  await writeFile(join(t, 'template-feats', 'extras', 'schedule', 'src', 'SchedulePage.tsx'), '// schedule page {{appName}}');
+  await mkdir(join(t, 'template-feats', 'extras', 'editor', 'src'), { recursive: true });
+  await writeFile(join(t, 'template-feats', 'extras', 'editor', 'src', 'EditorPage.tsx'), '// editor page {{appName}}');
+  return t;
+}
+
+async function run(planOverrides: Partial<ScaffoldInput['plan']>, templatesRoot: string) {
+  const plan = { appName: 'my-app', lang: 'ts' as const, router: false, extras: [] as never[], skipInstall: false, ...planOverrides };
+  const log = vi.fn();
+  const result = await scaffold({ plan, dest, templatesRoot, log });
+  return { result, log };
+}
+
+describe('scaffold — base copy + render', () => {
+  it('copy đủ file, skip .DS_Store, render {{appName}} mọi file text', async () => {
+    const templatesRoot = await makeTemplates();
+    const { result } = await run({ appName: 'hop-quy' }, templatesRoot);
+
+    expect(existsSync(join(dest, 'package.json'))).toBe(true);
+    expect(existsSync(join(dest, 'vite.config.ts'))).toBe(true);
+    expect(existsSync(join(dest, 'src', 'main.tsx'))).toBe(true);
+    expect(existsSync(join(dest, '.DS_Store'))).toBe(false); // rác macOS bị bỏ
+
+    const pkg = JSON.parse(await readFile(join(dest, 'package.json'), 'utf8'));
+    expect(pkg.name).toBe('hop-quy'); // placeholder render trong JSON
+    expect(await readFile(join(dest, 'vite.config.ts'), 'utf8')).toContain('// hop-quy');
+    expect(await readFile(join(dest, 'src', 'main.tsx'), 'utf8')).toContain('app hop-quy');
+
+    // result.files là path tương đối dest
+    expect(result.files).toContain(join('src', 'main.tsx'));
+  });
+
+  it('file binary (có byte 0x00) copy NGUYÊN BẢN — không render placeholder', async () => {
+    const templatesRoot = await makeTemplates();
+    await run({ appName: 'bin-app' }, templatesRoot);
+    const buf = await readFile(join(dest, 'logo.png'));
+    expect(buf[0]).toBe(0x00);
+    expect(buf.toString('latin1')).toContain('{{appName}}'); // KHÔNG bị thay
+  });
+});
+
+describe('scaffold — overlays + deps', () => {
+  it('router=true → overlay ghi đè App/main; deps +react-router', async () => {
+    const templatesRoot = await makeTemplates();
+    const { log } = await run({ appName: 'r-app', router: true }, templatesRoot);
+
+    expect(await readFile(join(dest, 'src', 'App.tsx'), 'utf8')).toContain('r-app routed');
+    expect(await readFile(join(dest, 'src', 'main.tsx'), 'utf8')).toContain('router main r-app');
+    const pkg = JSON.parse(await readFile(join(dest, 'package.json'), 'utf8'));
+    expect(pkg.dependencies['react-router']).toBe('^7.9.0');
+    expect(log).toHaveBeenCalledWith('Apply overlay: router');
+  });
+
+  it('extras → overlay copy + deps tương ứng (chart → chart.js)', async () => {
+    const templatesRoot = await makeTemplates();
+    await run({ appName: 'c-app', extras: ['chart'] }, templatesRoot);
+
+    expect(await readFile(join(dest, 'src', 'ChartPage.tsx'), 'utf8')).toContain('chart page c-app');
+    const pkg = JSON.parse(await readFile(join(dest, 'package.json'), 'utf8'));
+    expect(pkg.dependencies['chart.js']).toBe('^4.5.1');
+    expect(pkg.dependencies['react-router']).toBeUndefined(); // router=false → không thêm
+  });
+
+  it('extra nhiều peer deps → merge đủ list (schedule 3 fullcalendar, editor 2 tiptap)', async () => {
+    const templatesRoot = await makeTemplates();
+    await run({ appName: 'm-app', extras: ['schedule', 'editor'] }, templatesRoot);
+
+    const pkg = JSON.parse(await readFile(join(dest, 'package.json'), 'utf8'));
+    expect(pkg.dependencies['@fullcalendar/core']).toBe('^6.1.22');
+    expect(pkg.dependencies['@fullcalendar/daygrid']).toBe('^6.1.22');
+    expect(pkg.dependencies['@fullcalendar/interaction']).toBe('^6.1.22');
+    expect(pkg.dependencies['@tiptap/react']).toBe('^3.32.0');
+    expect(pkg.dependencies['@tiptap/starter-kit']).toBe('^3.32.0');
+  });
+
+  it('overlay thiếu (extra không có trong template) → throw message rõ', async () => {
+    const templatesRoot = await makeTemplates();
+    // fixture giờ có chart/schedule/editor (test multi-deps) — carousel là extra
+    // duy nhất fixture KHÔNG tạo → dùng làm case thiếu overlay
+    await expect(run({ extras: ['carousel'] }, templatesRoot)).rejects.toThrow("Không thấy overlay extra 'carousel'");
+  });
+});
+
+describe('scaffold — JS variant', () => {
+  it('lang=js → base vite-js (.jsx); overlay TS đổi đuôi .tsx→.jsx', async () => {
+    const templatesRoot = await makeTemplates();
+    await run({ appName: 'js-app', lang: 'js', router: true }, templatesRoot);
+
+    expect(existsSync(join(dest, 'src', 'main.jsx'))).toBe(true);
+    expect(existsSync(join(dest, 'src', 'main.tsx'))).toBe(false); // không trộn variant
+    expect(await readFile(join(dest, 'src', 'App.jsx'), 'utf8')).toContain('js-app routed'); // rename + render
+    expect(await readFile(join(dest, 'src', 'main.jsx'), 'utf8')).toContain('router main js-app');
+    const pkg = JSON.parse(await readFile(join(dest, 'package.json'), 'utf8'));
+    expect(pkg.dependencies['react-router']).toBe('^7.9.0'); // deps merge vẫn chạy
+  });
+});