create-wakii-stack 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,385 @@
+#!/usr/bin/env node
+import {
+  loadManifest
+} from "./chunk-ON2WTGZH.js";
+
+// src/index.ts
+import * as p from "@clack/prompts";
+import { existsSync as existsSync2, readdirSync } from "fs";
+import { join as join2, resolve as resolve2 } from "path";
+
+// src/options.ts
+function parseServicesList(raw) {
+  return raw.split(",").map((s) => s.trim()).filter(Boolean);
+}
+function parseArgs(argv) {
+  const options = { all: false, yes: false, skipInstall: false };
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === "--all") {
+      options.all = true;
+    } else if (arg === "--yes") {
+      options.yes = true;
+    } else if (arg === "--skip-install") {
+      options.skipInstall = true;
+    } else if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else if (arg === "--services") {
+      const value = argv[i + 1];
+      i += 1;
+      if (!value) return { ok: false, message: "--services c\u1EA7n danh s\xE1ch ph\u1EA9y: --services node-svc,shell" };
+      options.services = parseServicesList(value);
+    } else if (arg?.startsWith("--services=")) {
+      options.services = parseServicesList(arg.slice("--services=".length));
+    } else if (arg?.startsWith("--")) {
+      return { ok: false, message: `Flag kh\xF4ng h\u1ED7 tr\u1EE3: ${arg} (xem --help)` };
+    } else if (arg !== void 0) {
+      if (options.appName !== void 0) return { ok: false, message: "Ch\u1EC9 nh\u1EADn M\u1ED8T t\xEAn stack (positional \u0111\u1EA7u ti\xEAn)" };
+      options.appName = arg;
+    }
+    i += 1;
+  }
+  return { ok: true, options };
+}
+function resolveOptions(options, ctx) {
+  let selected;
+  if (options.all) {
+    selected = [...ctx.validServices];
+  } else if (options.services === void 0 || options.services.length === 0) {
+    throw new Error("Ch\u1ECDn \xEDt nh\u1EA5t 1 service \u2014 d\xF9ng --all ho\u1EB7c --services node-svc,shell,\u2026");
+  } else {
+    const unknown = options.services.filter((s) => !ctx.validServices.includes(s));
+    if (unknown.length > 0) {
+      throw new Error(`Service kh\xF4ng c\xF3 trong manifest: ${unknown.join(", ")} \u2014 h\u1EE3p l\u1EC7: ${ctx.validServices.join(", ")}`);
+    }
+    selected = [...options.services];
+  }
+  const set = new Set(selected);
+  const hasLayer = (layer) => selected.some((s) => ctx.layerOf(s) === layer);
+  const add = (name) => {
+    if (ctx.validServices.includes(name)) set.add(name);
+  };
+  if (hasLayer("be")) {
+    for (const name of ["postgres", "kafka", "gateway", "auth-svc"]) add(name);
+  }
+  if (hasLayer("fe")) add("gateway");
+  for (let changed = true; changed; ) {
+    changed = false;
+    for (const name of [...set]) {
+      for (const dep of ctx.requiresOf?.(name) ?? []) {
+        if (ctx.validServices.includes(dep) && !set.has(dep)) {
+          set.add(dep);
+          changed = true;
+        }
+      }
+    }
+  }
+  const rawName = options.appName ?? "my-wakii-stack";
+  const appName = /[\\/]/.test(rawName) ? rawName.split(/[\\/]/).pop() ?? "my-wakii-stack" : rawName;
+  return { appName, services: [...set].sort(), skipInstall: options.skipInstall };
+}
+
+// src/scaffold.ts
+import { mkdir, readFile, readdir, rm, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { parseDocument } from "yaml";
+var DEFAULT_TEMPLATE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../../stack-template");
+var STACK_ORG = "wakii";
+async function copyTree(srcDir, destDir, opts) {
+  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);
+    } else {
+      const text = buffer.toString("utf8").replaceAll("__STACK_NAME__", opts.stackName).replaceAll("__STACK_ORG__", STACK_ORG);
+      await writeFile(destPath, text);
+    }
+    opts.files.push(destPath);
+  }
+}
+function pruneCompose(text, selected, allServices) {
+  const doc = parseDocument(text);
+  const pruned = allServices.filter((name) => !selected.has(name));
+  if (pruned.length === 0) return text;
+  const services = doc.get("services");
+  if (services) {
+    for (const name of pruned) services.delete(name);
+    for (const item of services.items) {
+      const svcName = String(item.key?.value ?? "");
+      const depends = doc.getIn(["services", svcName, "depends_on"], true);
+      if (!depends || typeof depends !== "object") continue;
+      if (depends.items) {
+        const asMap = depends;
+        let removed = false;
+        for (const dep of [...asMap.items]) {
+          const depName = String(dep.key?.value ?? "");
+          if (pruned.includes(depName)) {
+            asMap.delete(depName);
+            removed = true;
+          }
+        }
+        if (asMap.items.length === 0) {
+          const svcMap = doc.getIn(["services", svcName], true);
+          svcMap.delete("depends_on");
+        } else if (removed) {
+          doc.setIn(["services", svcName, "depends_on"], asMap);
+        }
+      }
+    }
+  }
+  if (allServices.includes("postgres") && !selected.has("postgres")) {
+    const volumes = doc.get("volumes");
+    volumes?.delete("pgdata");
+  }
+  let out = doc.toString({ lineWidth: 0 });
+  out = out.replace(/^services:\n/, `services:
+  # create-wakii-stack: pruned ${pruned.join(", ")} (kh\xF4ng ch\u1ECDn khi scaffold)
+`);
+  return out;
+}
+function pruneGatewayConf(text, markers) {
+  let lines = text.split("\n");
+  for (const marker of markers) {
+    const result = [];
+    let skipping = false;
+    let depth = 0;
+    for (const line of lines) {
+      if (!skipping && line.includes(marker)) {
+        skipping = true;
+        depth = (line.match(/\{/g)?.length ?? 0) - (line.match(/\}/g)?.length ?? 0);
+        if (depth <= 0) skipping = false;
+        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");
+}
+function pruneEnv(text, keys) {
+  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");
+}
+function renderReadme(manifest, selection) {
+  const ports = Object.entries(manifest.ports ?? {}).map(([name, url]) => `- ${name}: ${url}`).join("\n");
+  return `# ${selection.appName}
+
+Stack generated by \`create-wakii-stack\` (Hybrid C \u2014 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   # \u0111i\u1EC1n secret tr\u01B0\u1EDBc khi up
+docker compose --env-file platform/.env up -d
+\`\`\`
+
+${manifest.smoke ? `## Smoke
+
+\`\`\`bash
+${manifest.smoke}
+\`\`\`
+` : ""}
+${ports ? `## URLs
+
+${ports}
+` : ""}
+Need a FE app (SPA) outside this stack? \`pnpm create wakii-app\`.
+`;
+}
+async function scaffold(input) {
+  const { selection, dest, log: log2 } = input;
+  const templateRoot = input.templateRoot ?? DEFAULT_TEMPLATE_ROOT;
+  const manifestPath = join(templateRoot, "stack-manifest.json");
+  if (!existsSync(manifestPath)) throw new Error(`Kh\xF4ng th\u1EA5y stack-manifest.json t\u1EA1i ${templateRoot}`);
+  const { loadManifest: loadManifest2 } = await import("./manifest-2JVLRMDB.js");
+  const manifest = loadManifest2(manifestPath);
+  const files = [];
+  log2?.(`Copy full template \u2192 ${dest}`);
+  await copyTree(templateRoot, dest, { stackName: selection.appName, files });
+  const allServices = Object.keys(manifest.services);
+  const pruned = allServices.filter((s) => !selection.services.includes(s));
+  for (const name of pruned) {
+    for (const rawPath of manifest.services[name].paths ?? []) {
+      const relPath = rawPath.endsWith("/**") ? rawPath.slice(0, -3) : rawPath;
+      const target = join(dest, relPath);
+      if (existsSync(target)) {
+        await rm(target, { recursive: true, force: true });
+        log2?.(`Pruned path: ${relPath}`);
+      }
+    }
+  }
+  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));
+    log2?.(`Pruned compose: -${pruned.join(", -")}`);
+  }
+  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));
+      log2?.(`Pruned gateway blocks: ${markers.length}`);
+    }
+  }
+  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));
+      log2?.(`Pruned env keys: ${keys.length}`);
+    }
+  }
+  await writeFile(join(dest, "README.md"), renderReadme(manifest, selection));
+  return { files: [...files.map((f) => f.slice(dest.length + 1)), "README.md"], prunedServices: pruned };
+}
+
+// src/index.ts
+var USAGE = `create-wakii-stack \u2014 scaffold full-stack FE+BE (Hybrid C: full-copy + prune)
+
+Usage: pnpm create wakii-stack [stackName] [flags]
+
+Flags:
+  --services <list>  Services ph\u1EA9y ng\u0103n c\xE1ch (vd node-svc,spring-svc,shell,tasks,activity,admin)
+  --all              Ch\u1ECDn m\u1ECDi service trong manifest
+  --yes              B\u1ECF confirm summary
+  --skip-install     B\u1ECF g\u1EE3i \xFD c\xE0i \u0111\u1EB7t \u1EDF next-steps
+  -h, --help         In h\u01B0\u1EDBng d\u1EABn
+
+Rules t\u1EA7ng 1: \u22651 BE t\u1EF1 k\xE8m postgres+kafka+gateway+auth-svc; \u22651 FE t\u1EF1 k\xE8m gateway.
+`;
+function printNextSteps(selection, templateRoot) {
+  const steps = [`cd ${selection.appName}`];
+  if (existsSync2(join2(templateRoot, "platform/.env.example")) || true) {
+    steps.push("cp platform/.env.example platform/.env   # \u0111i\u1EC1n secret tr\u01B0\u1EDBc khi up");
+  }
+  steps.push("docker compose --env-file platform/.env up -d");
+  if (!selection.skipInstall) steps.push("# FE apps: pnpm install trong t\u1EEBng app mu\u1ED1n ch\u1EA1y build c\u1EE5c b\u1ED9");
+  p.log.info("Next steps:");
+  for (const step of steps) p.log.step(`  ${step}`);
+  p.log.info("URLs: gateway http://localhost:8080 \xB7 shell http://localhost:3000 (n\u1EBFu ch\u1ECDn FE)");
+  p.log.info("FE-only SPA ngo\xE0i stack? pnpm create wakii-app");
+}
+async function main() {
+  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-stack \u2014 scaffold FE+BE stack");
+  let manifest;
+  try {
+    manifest = loadManifest(join2(DEFAULT_TEMPLATE_ROOT, "stack-manifest.json"));
+  } catch (err) {
+    p.log.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  const allServices = Object.keys(manifest.services);
+  let options = parsed.options;
+  if (!options.all && options.services === void 0) {
+    const chosen = await p.multiselect({
+      message: "Ch\u1ECDn services (space ch\u1ECDn/bo, enter x\xE1c nh\u1EADn)",
+      required: true,
+      options: allServices.map((name) => ({
+        value: name,
+        label: `${name} \u2014 ${manifest.services[name].layer}`
+      }))
+    });
+    if (p.isCancel(chosen)) {
+      p.cancel("Hu\u1EF7 \u2014 kh\xF4ng scaffold g\xEC.");
+      return;
+    }
+    options = { ...options, services: chosen };
+  }
+  if (!options.yes) {
+    const preview = resolveOptions(options, {
+      validServices: allServices,
+      layerOf: (name) => manifest.services[name]?.layer,
+      requiresOf: (name) => manifest.services[name]?.requires ?? []
+    });
+    const confirmed = await p.confirm({
+      message: `Scaffold '${preview.appName}' v\u1EDBi ${preview.services.length} services? (${preview.services.join(", ")})`,
+      initialValue: true
+    });
+    if (p.isCancel(confirmed) || !confirmed) {
+      p.cancel("Hu\u1EF7 \u2014 kh\xF4ng scaffold g\xEC.");
+      return;
+    }
+  }
+  let selection;
+  try {
+    selection = resolveOptions(options, {
+      validServices: allServices,
+      layerOf: (name) => manifest.services[name]?.layer,
+      requiresOf: (name) => manifest.services[name]?.requires ?? []
+    });
+  } catch (err) {
+    p.log.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  const rawName = process.argv[2] && !process.argv[2].startsWith("-") ? process.argv[2] : selection.appName;
+  const dest = /[\\/]/.test(rawName) ? resolve2(rawName) : resolve2(process.cwd(), rawName);
+  if (existsSync2(dest) && readdirSync(dest).length > 0) {
+    p.log.error(`Th\u01B0 m\u1EE5c \u0111\xEDch \u0111\xE3 t\u1ED3n t\u1EA1i v\xE0 kh\xF4ng r\u1ED7ng: ${dest}`);
+    process.exitCode = 1;
+    return;
+  }
+  const s = p.spinner();
+  s.start("Scaffolding stack\u2026");
+  try {
+    const result = await scaffold({
+      selection,
+      dest,
+      templateRoot: DEFAULT_TEMPLATE_ROOT,
+      log: (message) => {
+        s.message(message);
+      }
+    });
+    s.stop(`Xong \u2014 ${result.files.length} file \xB7 pruned: ${result.prunedServices.length} service`);
+  } catch (err) {
+    s.stop("Scaffold l\u1ED7i");
+    p.log.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+    return;
+  }
+  p.outro("Stack s\u1EB5n s\xE0ng! \u{1F389}");
+  printNextSteps(selection, DEFAULT_TEMPLATE_ROOT);
+}
+main().catch((err) => {
+  p.log.error(err instanceof Error ? err.message : String(err));
+  process.exitCode = 1;
+});

package/dist/manifest-2JVLRMDB.js

@@ -0,0 +1,10 @@
+import {
+  STACK_LAYERS,
+  loadManifest,
+  validateManifest
+} from "./chunk-ON2WTGZH.js";
+export {
+  STACK_LAYERS,
+  loadManifest,
+  validateManifest
+};

package/dist/manifest-O35TPW73.js

@@ -0,0 +1,10 @@
+import {
+  STACK_LAYERS,
+  loadManifest,
+  validateManifest
+} from "./chunk-AKPWS7FJ.js";
+export {
+  STACK_LAYERS,
+  loadManifest,
+  validateManifest
+};

package/dist/manifest-TXTY67BF.js

@@ -0,0 +1,10 @@
+import {
+  STACK_LAYERS,
+  loadManifest,
+  validateManifest
+} from "./chunk-7XGW4UJ5.js";
+export {
+  STACK_LAYERS,
+  loadManifest,
+  validateManifest
+};

package/dist/manifest-XWHR7Y3F.js

@@ -0,0 +1,10 @@
+import {
+  STACK_LAYERS,
+  loadManifest,
+  validateManifest
+} from "./chunk-ELM6GGC5.js";
+export {
+  STACK_LAYERS,
+  loadManifest,
+  validateManifest
+};

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "create-wakii-stack",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "CLI scaffold full-stack (FE+BE) dùng @wakii/ui-kit — full-copy + prune theo manifest (spec Hybrid C)",
+  "bin": {
+    "create-wakii-stack": "./dist/index.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "yaml": "^2.9.1"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "stack-template",
+    "README.md"
+  ]
+}

package/stack-template/.changeset/config.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "@changesets/cli/CHANGELOG.md",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "privatePackages": {
+    "version": true,
+    "tag": true
+  },
+  "ignore": []
+}

package/stack-template/.changeset/vu53-ui-redesign.md

@@ -0,0 +1,11 @@
+---
+'@wakii/ui-kit': minor
+---
+
+VU-53 UI redesign — đợt ship đầu tiên: 16 hooks native (spec usehooks.com) · Upload +
+UploadDropzone drag-drop · Field wrapper (react-hook-form + zod) · redesign Calendar,
+Carousel (swiper), Pagination, InputNumber, Alert, Select, Table filter, Skeleton shimmer
+· Icon system primeicons SVG · z-index token scale (dropdown→tooltip) · subpath exports
+heavy components (carousel/chart/schedule/editor — barrel không còn kéo CSS nặng) ·
+chuẩn bị publish npm: tsup dist (esm+cjs+dts, peer deps external), eslint flat config,
+changesets.

package/stack-template/.claude/agents/be-dev.md

@@ -0,0 +1,56 @@
+---
+name: be-dev
+description: Backend dev agent cho boilerplate — mọi việc trong services/ (node-svc Fastify+TS, spring-svc Boot 3, go-svc chi, auth-svc Fastify+TS). Dùng khi task đụng API, DB schema/migration, Kafka outbox/consumer/saga/DLQ, healthcheck, Dockerfile service.
+tools: Read, Grep, Glob, Bash, Edit, Write, NotebookEdit
+---
+
+Bạn là BE dev của boilerplate mixed-stack. Mỗi service một README — đọc README service đó TRƯỚC khi code.
+
+## Trước khi code — đọc
+
+1. `CLAUDE.md` + `orca.yaml` section `services:`
+2. `platform/conventions/` — 01 (Dockerfile), 02 (healthz/readyz), 03 (logging JSON), 04 (error envelope), 06 (env config). Đụng async → thêm 09 (Kafka lazy-connect + outbox + idempotent + retry/DLQ).
+3. Contract của miền: `contracts/openapi/<svc>.yaml`, `contracts/db/tasks-schema.sql` (canonical DDL), `contracts/events/task-events.md` + fixtures golden.
+
+## Ràng buộc cứng
+
+- **Contract-first**: sửa contract TRƯỚC rồi code theo — không code-before-spec. node-svc codegen: `pnpm --filter node-svc generate:types`. go-svc snapshot `internal/api/openapi/` phải **bit-identical** contract (CI drift-guard chặn).
+- **Schema ownership**: node-svc sở hữu `tasks`, spring-svc `users`+`teams`, go-svc `activity` (tự migrate). go-svc đọc-ONLY `tasks` qua role `go_readonly` — không bao giờ write chéo schema.
+- **Outbox, không REST fire-and-forget** (ADR-0008 supersede 0006): event đi node outbox → relay → Kafka `task-events` → go consumer idempotent, retry ×3 → DLQ; saga assign `svc-fail` → compensation `assignment_failed`. Consumer subscribe CHỈ sau khi topic tồn tại (race empty-assignment — conventions/09).
+- **Fail-closed** (ADR-0005): validate assignee với spring-svc unavailable = từ chối, không mở cửa.
+- Healthcheck: `/healthz` liveness + `/readyz` readiness theo conventions/02 — compose + CI boot-smoke phụ thuộc nó.
+- Error response LUÔN error envelope (conventions/04) — mirror đủ 4 OpenAPI specs.
+- Log JSON shape chung (conventions/03) — reqId, level string, không log secret/JWT.
+
+## Commands
+
+```bash
+# node-svc
+cd services/node-svc && pnpm install --frozen-lockfile --ignore-workspace   # standalone lockfile!
+pnpm test && pnpm build && pnpm dev    # vitest / tsc / tsx watch :3001
+# go-svc
+cd services/go-svc && go test ./... && go vet ./...
+# spring-svc
+cd services/spring-svc && ./mvnw test
+# auth-svc
+cd services/auth-svc && pnpm install --frozen-lockfile --ignore-workspace && pnpm test   # vitest
+```
+
+Chạy service local: env theo `platform/.env.example` + `docs/walkthrough.md` đường B.
+
+## Quy trình
+
+1. Đổi schema/contract → sửa `contracts/` cùng commit, nêu rõ trong PR/evidence.
+2. TDD: test RED trước với bug/feature — node-svc suite có pattern mock seam sẵn (app.test.ts 27 case làm mẫu).
+3. Đổi event envelope → fixtures golden (`contracts/events/fixtures/`) là test chung 2 đầu node/go — cập nhật CẢ HAI phía test.
+4. Xong = test service xanh + docker build được (`docker compose build <svc>`) + boot-smoke local nếu đụng startup/Kafka.
+
+## Đừng
+
+- Đừng bỏ qua `--ignore-workspace` khi install node-svc/auth-svc (standalone lockfile).
+- Đừng hardcode mật khẩu/secret — mọi config qua env (conventions/06), `.env` không commit.
+- Đừng thêm endpoint ngoài contract; đừng đổi id trong `contracts/auth/users.json` (seed spring phụ thuộc id cố định).
+- Đừng Để Kafka blocking startup — lazy-connect (conventions/09).
+
+## Team protocol (2026-10-18)
+Khi chạy trong terminal Orca dưới ZCode lead: xong việc → verify → BÁO CÁO → DỪNG chờ việc mới (không tự chuyển). Phạm vi file đúng đúng brief ("CHỈ <dir> — ngoài CẤM"). Ghi file dùng đường dẫn tuyệt đối từ `app/`. Chi tiết: section "Team protocol" trong CLAUDE.md + board docs/team/TEAM.md.

package/stack-template/.claude/agents/contracts-keeper.md

@@ -0,0 +1,51 @@
+---
+name: contracts-keeper
+description: Agent giữ contracts nhất quán — OpenAPI specs, canonical DDL, event envelope + fixtures golden, users fixture, JWT token contract. Dùng khi sửa contracts/, thêm endpoint/event field, đổi schema, hoặc review tính đồng bộ spec ↔ code 2 chiều (node codegen, go snapshot, spring seed).
+tools: Read, Grep, Glob, Bash
+---
+
+Bạn là keeper của `contracts/` — source of truth của repo (nguyên tắc vàng #1). Nhiệm vụ: mọi thay đổi contract nhất quán trên TẤT CẢ các bề mặt tiêu thụ, không có drift.
+
+## Bản đồ contracts
+
+| File | Ai tiêu thụ | Cơ chế bảo vệ |
+|---|---|---|
+| `openapi/tasks.yaml` | node-svc (codegen `generate:types`), FE api client | spectral CI + schemathesis |
+| `openapi/activity.yaml` | go-svc — snapshot `internal/api/openapi/` phải **bit-identical** | CI drift-guard + sync-check test |
+| `openapi/users.yaml` | spring-svc (displayName khớp User schema) | review |
+| `openapi/auth.yaml` | auth-svc | schemathesis CI |
+| `db/tasks-schema.sql` | node (Drizzle), go_readonly, outbox KHÔNG vào canonical | schema-diff test node-svc |
+| `events/task-events.md` + `fixtures/*.json` | node publish + go consume — golden envelope CHUNG 2 đầu | test 2 bên load cùng fixture |
+| `auth/users.json` | auth-svc seed + spring Flyway seed | **id UUID cố định** — thêm user = thêm entry, KHÔNG đổi id cũ |
+| `auth/token-contract.md` | auth-svc + mọi service verify JWT (`iss` pinned "auth-mock" — giá trị lịch sử) | review |
+
+## Quy trình chuẩn khi đổi contract
+
+1. Sửa spec/DDL/event contract trong `contracts/` — một commit có chủ đích, mô tả vì sao.
+2. `pnpm lint:contracts` (spectral) — phải sạch.
+3. Đẩy thay đổi xuống các bề mặt tiêu thụ CÙNG commit hoặc PR liền kề:
+   - node-svc: `pnpm --filter node-svc generate:types` + impl + test
+   - go-svc: copy spec vào `internal/api/openapi/activity.yaml` (bit-identical) + sync swagger copy `/api/activity/openapi.yaml`
+   - fixtures đổi → cập nhật test CẢ node (`app/relay/compensation`) VÀ go consumer
+   - users.json đổi → spring seed migration + auth-svc hiển thị (số user test auth-svc đếm THEO FIXTURE, không hard-code — bài học fix 2026-10-17)
+4. Error envelope (conventions/04) phải mirror đủ 4 specs khi đổi shape.
+5. Chạy chứng minh: test node + go + auth-svc xanh; nếu đụng runtime → `bash scripts/smoke/e2e.sh` PASS.
+
+## Kiểm tra drift định kỳ (khi review hoặc nghi ngờ)
+
+```bash
+diff contracts/openapi/activity.yaml services/go-svc/internal/api/openapi/activity.yaml   # phải rỗng
+pnpm --filter node-svc generate:types && git diff --stat                                  # types khớp spec?
+grep -rn "displayName" contracts/auth/users.json docs/ | head                             # seed nguồn sự thật
+pnpm lint:contracts
+```
+
+## Đừng
+
+- Đừng sửa contracts/ mà không nói rõ ai tiêu thụ và đã sync chưa — drift = bug im lặng nguy hiểm nhất của repo.
+- Đừng đổi id/uuid trong fixtures + users.json — chỉ thêm.
+- Đừng thêm field event mà bỏ qua bump `schemaVersion` + fixtures golden + test 2 đầu.
+- Đừng để contracts lệch với docs (`docs/walkthrough.md`, README service) — sửa cùng lúc.
+
+## Team protocol (2026-10-18)
+Khi chạy trong terminal Orca dưới ZCode lead: xong việc → verify → BÁO CÁO → DỪNG chờ việc mới (không tự chuyển). Phạm vi file đúng đúng brief ("CHỈ <dir> — ngoài CẤM"). Ghi file dùng đường dẫn tuyệt đối từ `app/`. Chi tiết: section "Team protocol" trong CLAUDE.md + board docs/team/TEAM.md.

package/stack-template/.claude/agents/e2e-runner.md

@@ -0,0 +1,61 @@
+---
+name: e2e-runner
+description: Agent vận hành + verify stack chạy thật — boot compose 10 services, tạo Kafka topic đúng thứ tự, chạy scripts/smoke/e2e.sh 2 chiều (happy + saga + DLQ assert), đọc log container khi fail, kiểm tra CI convergence. Dùng khi cần "chạy app", verify e2e, debug stack/compose/convergence CI.
+tools: Read, Grep, Glob, Bash
+---
+
+Bạn là agent vận hành stack demo. Mục tiêu: đưa stack lên sống, chứng minh chuỗi e2e 2 chiều, và khi fail — dump đúng chỗ để chẩn đoán, không đoán mò.
+
+## Chuẩn bị
+
+1. Đọc `CLAUDE.md` (run demo + gotchas) + `orca.yaml` section `run:`
+2. Docker daemon phải sống: `docker info` trước, không thì `open -a Docker` + chờ.
+3. `.env`: `cd platform && cp -n .env.example .env` — kiểm tra có JWT_SECRET + passwords.
+
+## Boot đúng thứ tự (race topic — bắt buộc)
+
+```bash
+cd platform && docker compose --env-file .env up -d postgres kafka
+# đợi kafka: loop exec kafka-broker-api-versions.sh ... && break
+for topic in task-events task-events.dlq; do
+  docker compose --env-file .env exec -T kafka /opt/kafka/bin/kafka-topics.sh \
+    --bootstrap-server localhost:9092 --create --if-not-exists --topic "$topic" \
+    --partitions 1 --replication-factor 1
+done
+docker compose --env-file .env up -d --build        # 10 services, health-gated chain
+```
+
+Vì sao: consumer subscribe TRƯỚC topic tồn tại → kẹt empty-assignment im lặng; relay publish trước topic → DLQ Unknown Topic. Topic tạo tường minh là bước, không phải depends_on (conventions/09).
+
+## Verify
+
+```bash
+# gateway ready (gateway không có /readyz riêng — poll qua auth-svc)
+curl -sf http://localhost:8080/api/auth/readyz | grep '"status":"ok"'
+# e2e 2 chiều từ repo root
+bash scripts/smoke/e2e.sh                # PASS = 15 bước: login → task → feed QUA KAFKA + auth-real (register/refresh/RBAC) + saga → assignment_failed → DLQ
+```
+
+UI: http://localhost:8080 — `alice@demo.local` / `demo-password`; saga demo assign cho `fail@demo.local`.
+
+## Khi fail — dump theo lớp (đừng skip lớp nào)
+
+1. `docker compose --env-file .env ps -a` — ai exit/ unhealthy?
+2. `docker compose --env-file .env logs --tail=100` → khoá vào service nghi: `logs node-svc go-svc` (relay/compensation/consumer).
+3. Kafka state: `kafka-get-offsets.sh --topic task-events` (relay publish chưa?) + console-consumer đọc topic/DLQ.
+4. Gateway chain: poll lại `/api/auth/readyz`; chain auth→spring→node theo health-gate compose.
+5. Saga fail ở auth/validate trên máy cũ → nghi pgdata volume cũ thiếu svc-fail/svc-activity (Flyway V2 seed chỉ chạy volume mới) → `docker compose down -v` rồi up lại (hỏi owner trước khi -v nếu máy dùng chung).
+
+## Mẫu tham chiếu
+
+CI làm đúng chuỗi này mỗi push: `.github/workflows/convergence.yml` job `e2e-smoke` (kèm DLQ assert bằng kafka-get-offsets + console-consumer, dump-on-fail). Debug convergence CI fail → đọc run: `gh run view <id> --log-failed`.
+
+## Đừng
+
+- Đừng boot full stack trước khi tạo topic.
+- Đừng `down -v` tùy tiện — xoá data demo + phải re-seed; chỉ khi nghi volume cũ.
+- Đừng dùng `docker compose` thiếu `--env-file platform/.env` — interpolation ẩn lỗi thật.
+- Đừng claim "stack chạy" khi chưa PASS e2e.sh — boot xanh ≠ chuỗi sống.
+
+## Team protocol (2026-10-18)
+Khi chạy trong terminal Orca dưới ZCode lead: xong việc → verify → BÁO CÁO → DỪNG chờ việc mới (không tự chuyển). Phạm vi file đúng đúng brief ("CHỈ <dir> — ngoài CẤM"). Ghi file dùng đường dẫn tuyệt đối từ `app/`. Chi tiết: section "Team protocol" trong CLAUDE.md + board docs/team/TEAM.md.