polyforge-cli 0.1.0 → 0.1.1

package/README.md

@@ -63,3 +63,11 @@ npm publish
 - Vite dev server proxy routes `/api` -> backend API and `/bff` -> gateway-bff.
 - Frontend page includes demo requests for `/api/v1/ping` and `/bff/ping` with `X-Trace-Id`.
 - Frontend templates include `src/api/request.ts` (timeout/retry/error mapping), `src/api/services/*`, and `src/api/client.ts`.
+
+## Module Runtime Notes
+
+- `grpc-service`: includes runnable Go gRPC server skeleton and proto generation script.
+- `mq`: includes local broker compose (`kafka`, `rabbitmq`, `nats`) and producer/consumer sample scripts.
+- `cache-redis`: includes cache key convention and minimal cache client example.
+- `observability`: includes local compose (`otel-collector`, `prometheus`, `grafana`) and up/down scripts.
+- `auth-center`: includes JWT login/refresh/verify endpoints (minimal flow).

package/dist/core/installer.js

@@ -61,4 +61,10 @@ async function maybeInstallDeps(config) {
             }
         }
     }
+    if (config.extraModules.includes("mq")) {
+        const mqDir = path_1.default.join(config.targetDir, "apps", "mq-worker");
+        if ((0, fs_1.existsSync)(path_1.default.join(mqDir, "package.json"))) {
+            await run(config.packageManager, ["install"], mqDir);
+        }
+    }
 }

package/dist/core/renderer.js

@@ -119,6 +119,19 @@ function dockerServices(config) {
     if (config.extraModules.includes("auth-center")) {
         services.push(`  auth-center:\n    image: node:20-alpine\n    working_dir: /app\n    volumes:\n      - ../apps/auth-center:/app\n    command: node server.js\n    ports:\n      - "8081:8081"`);
     }
+    if (config.extraModules.includes("mq")) {
+        services.push(`  kafka:\n    image: bitnami/kafka:3.7\n    environment:\n      - KAFKA_CFG_NODE_ID=1\n      - KAFKA_CFG_PROCESS_ROLES=broker,controller\n      - KAFKA_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER\n      - KAFKA_CFG_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093\n      - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://kafka:9092\n      - KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT\n      - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=1@kafka:9093\n      - KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE=true\n    ports:\n      - "9092:9092"`);
+        services.push(`  rabbitmq:\n    image: rabbitmq:3-management\n    ports:\n      - "5672:5672"\n      - "15672:15672"`);
+        services.push(`  nats:\n    image: nats:2.10\n    ports:\n      - "4222:4222"`);
+    }
+    if (config.extraModules.includes("cache-redis") && !config.dataModules.includes("redis")) {
+        services.push(`  redis:\n    image: redis:7\n    ports:\n      - "6379:6379"`);
+    }
+    if (config.extraModules.includes("observability")) {
+        services.push(`  otel-collector:\n    image: otel/opentelemetry-collector:0.108.0\n    ports:\n      - "4317:4317"\n      - "4318:4318"`);
+        services.push(`  prometheus:\n    image: prom/prometheus:v2.54.1\n    ports:\n      - "9090:9090"`);
+        services.push(`  grafana:\n    image: grafana/grafana:11.1.5\n    ports:\n      - "3000:3000"`);
+    }
     return services.join("\n\n");
 }
 async function writeGeneratedReadme(config) {

package/dist/templates/base/infra/scripts/check.sh

@@ -55,4 +55,194 @@ if [[ -f apps/python-ai/app/main.py ]]; then
   fi
 fi
 
+if [[ -f contracts/proto/greeter.proto ]]; then
+  if command -v protoc >/dev/null 2>&1; then
+    echo "[check] protoc available for grpc-service"
+  else
+    echo "[check] protoc missing, grpc-service code generation unavailable"
+  fi
+fi
+
+if [[ -f infra/mq/docker-compose.yml ]]; then
+  if command -v docker >/dev/null 2>&1; then
+    docker compose -f infra/mq/docker-compose.yml config >/dev/null
+  else
+    echo "[check] docker missing, skip mq compose validation"
+  fi
+fi
+
+if [[ -f apps/mq-worker/package.json ]]; then
+  if command -v node >/dev/null 2>&1; then
+    node --check apps/mq-worker/scripts/producer.js
+    node --check apps/mq-worker/scripts/consumer.js
+    node --check apps/mq-worker/scripts/roundtrip.js
+  else
+    echo "[check] node missing, skip mq-worker syntax check"
+  fi
+fi
+
+if [[ -f infra/observability/docker-compose.yml ]]; then
+  if command -v docker >/dev/null 2>&1; then
+    docker compose -f infra/observability/docker-compose.yml config >/dev/null
+  else
+    echo "[check] docker missing, skip observability compose validation"
+  fi
+fi
+
+RUNTIME_SMOKE="${CHECK_RUNTIME_SMOKE:-1}"
+if [[ "$RUNTIME_SMOKE" == "1" ]]; then
+  echo "[check] runtime smoke enabled (set CHECK_RUNTIME_SMOKE=0 to disable)"
+
+  declare -a PIDS=()
+  TMP_NATS_CONTAINER=""
+  cleanup() {
+    for pid in "${PIDS[@]}"; do
+      if kill -0 "$pid" >/dev/null 2>&1; then
+        kill "$pid" >/dev/null 2>&1 || true
+        wait "$pid" >/dev/null 2>&1 || true
+      fi
+    done
+    if [[ -n "$TMP_NATS_CONTAINER" ]] && command -v docker >/dev/null 2>&1; then
+      docker rm -f "$TMP_NATS_CONTAINER" >/dev/null 2>&1 || true
+    fi
+  }
+  trap cleanup EXIT
+
+  wait_http() {
+    local url="$1"
+    local retries="$2"
+    local delay="$3"
+    for _ in $(seq 1 "$retries"); do
+      if curl -sf "$url" >/dev/null 2>&1; then
+        return 0
+      fi
+      sleep "$delay"
+    done
+    return 1
+  }
+
+  wait_tcp() {
+    local host="$1"
+    local port="$2"
+    local retries="$3"
+    local delay="$4"
+    if ! command -v nc >/dev/null 2>&1; then
+      return 1
+    fi
+    for _ in $(seq 1 "$retries"); do
+      if nc -z "$host" "$port" >/dev/null 2>&1; then
+        return 0
+      fi
+      sleep "$delay"
+    done
+    return 1
+  }
+
+  if [[ -f apps/api/go.mod ]] && command -v go >/dev/null 2>&1; then
+    (
+      cd apps/api
+      APP_PORT=18080 go run ./cmd/server
+    ) >/tmp/scaffold-check-api.log 2>&1 &
+    PIDS+=("$!")
+    if wait_http "http://127.0.0.1:18080/health" 25 1; then
+      echo "[check] runtime ok: apps/api /health"
+    else
+      echo "[check] runtime warn: apps/api health probe failed"
+      tail -n 30 /tmp/scaffold-check-api.log || true
+    fi
+  fi
+
+  if [[ -f apps/gateway-bff/server.js ]] && command -v node >/dev/null 2>&1; then
+    (
+      cd apps/gateway-bff
+      PORT=13001 node server.js
+    ) >/tmp/scaffold-check-bff.log 2>&1 &
+    PIDS+=("$!")
+    if wait_http "http://127.0.0.1:13001/health" 20 1; then
+      echo "[check] runtime ok: apps/gateway-bff /health"
+    else
+      echo "[check] runtime warn: gateway-bff health probe failed"
+      tail -n 30 /tmp/scaffold-check-bff.log || true
+    fi
+  fi
+
+  if [[ -f apps/auth-center/server.js ]] && command -v node >/dev/null 2>&1; then
+    (
+      cd apps/auth-center
+      PORT=18081 node server.js
+    ) >/tmp/scaffold-check-auth.log 2>&1 &
+    PIDS+=("$!")
+    if wait_http "http://127.0.0.1:18081/health" 20 1; then
+      echo "[check] runtime ok: apps/auth-center /health"
+    else
+      echo "[check] runtime warn: auth-center health probe failed"
+      tail -n 30 /tmp/scaffold-check-auth.log || true
+    fi
+  fi
+
+  if [[ -f apps/python-ai/app/main.py ]] && command -v python3 >/dev/null 2>&1; then
+    if python3 -c "import uvicorn" >/dev/null 2>&1; then
+      (
+        cd apps/python-ai
+        python3 -m uvicorn app.main:app --host 127.0.0.1 --port 18090
+      ) >/tmp/scaffold-check-python-ai.log 2>&1 &
+      PIDS+=("$!")
+      if wait_http "http://127.0.0.1:18090/health" 20 1; then
+        echo "[check] runtime ok: apps/python-ai /health"
+      else
+        echo "[check] runtime warn: python-ai health probe failed"
+        tail -n 30 /tmp/scaffold-check-python-ai.log || true
+      fi
+    else
+      echo "[check] runtime skip: python-ai needs uvicorn"
+    fi
+  fi
+
+  if [[ -f apps/grpc-service/cmd/server/main.go ]] && command -v go >/dev/null 2>&1; then
+    (
+      cd apps/grpc-service
+      go run ./cmd/server
+    ) >/tmp/scaffold-check-grpc.log 2>&1 &
+    PIDS+=("$!")
+    if wait_tcp "127.0.0.1" "9090" 20 1; then
+      echo "[check] runtime ok: apps/grpc-service :9090"
+    else
+      echo "[check] runtime warn: grpc-service port probe failed"
+      tail -n 30 /tmp/scaffold-check-grpc.log || true
+    fi
+  fi
+
+  if [[ -f apps/mq-worker/package.json ]] && command -v npm >/dev/null 2>&1; then
+    MQ_NATS_READY="0"
+    if ! wait_tcp "127.0.0.1" "4222" 2 1; then
+      if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then
+        TMP_NATS_CONTAINER="scaffold-mq-check-$(date +%s)"
+        if docker run -d --rm --name "$TMP_NATS_CONTAINER" -p 4222:4222 nats:2.10 >/dev/null 2>&1; then
+          echo "[check] runtime info: started temporary NATS container ($TMP_NATS_CONTAINER)"
+          wait_tcp "127.0.0.1" "4222" 10 1 || true
+        fi
+      fi
+    fi
+
+    if wait_tcp "127.0.0.1" "4222" 2 1; then
+      MQ_NATS_READY="1"
+      if [[ -d apps/mq-worker/node_modules ]]; then
+        (cd apps/mq-worker && npm run -s roundtrip) || echo "[check] runtime warn: mq-worker roundtrip failed"
+      else
+        echo "[check] runtime skip: mq-worker dependencies not installed"
+      fi
+    fi
+
+    if [[ "$MQ_NATS_READY" != "1" ]]; then
+      if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then
+        echo "[check] runtime skip: NATS port 4222 unavailable"
+      else
+        echo "[check] runtime skip: NATS 4222 unavailable and Docker daemon not ready"
+      fi
+    else
+      echo "[check] runtime ok: mq-worker roundtrip completed"
+    fi
+  fi
+fi
+
 echo "[check] done"

package/dist/templates/base/infra/scripts/dev.sh

@@ -30,3 +30,19 @@ fi
 if [[ -f apps/python-ai/app/main.py ]]; then
   echo "[dev] python-ai available at apps/python-ai"
 fi
+
+if [[ -f apps/auth-center/server.js ]]; then
+  echo "[dev] auth-center available at apps/auth-center"
+fi
+
+if [[ -f infra/mq/docker-compose.yml ]]; then
+  echo "[dev] mq stack available at infra/mq/docker-compose.yml"
+fi
+
+if [[ -f apps/mq-worker/package.json ]]; then
+  echo "[dev] mq-worker available at apps/mq-worker"
+fi
+
+if [[ -f infra/observability/docker-compose.yml ]]; then
+  echo "[dev] observability stack available at infra/observability/docker-compose.yml"
+fi

package/dist/templates/modules/auth-center/apps/auth-center/README.md

@@ -1,5 +1,9 @@
 # Auth Center Module
 
-- Purpose: centralize login/token/authorization
-- Includes JWT login placeholder endpoint
-- Add OAuth2 client configs before production
+- Endpoints:
+  - `POST /auth/login`
+  - `POST /auth/refresh`
+  - `GET /auth/verify`
+  - `GET /health`
+- Includes JWT access/refresh token minimal flow.
+- Configure `JWT_SECRET` and `JWT_REFRESH_SECRET` for production.

package/dist/templates/modules/auth-center/apps/auth-center/server.js

@@ -5,17 +5,80 @@ const app = express();
 app.use(express.json());
 
 const secret = process.env.JWT_SECRET || "change-me";
+const refreshSecret = process.env.JWT_REFRESH_SECRET || "change-refresh-me";
+
+function signAccessToken(subject) {
+  return jwt.sign({ sub: subject, role: "user" }, secret, { expiresIn: "1h" });
+}
+
+function signRefreshToken(subject) {
+  return jwt.sign({ sub: subject, type: "refresh" }, refreshSecret, { expiresIn: "7d" });
+}
 
 app.post("/auth/login", (req, res) => {
   const username = req.body?.username || "demo";
-  const token = jwt.sign({ sub: username, role: "user" }, secret, { expiresIn: "1h" });
-  res.json({ code: 0, message: "success", data: { accessToken: token }, traceId: req.header("X-Trace-Id") || "auth-trace", timestamp: new Date().toISOString() });
+  const accessToken = signAccessToken(username);
+  const refreshToken = signRefreshToken(username);
+
+  res.json({
+    code: 0,
+    message: "success",
+    data: { accessToken, refreshToken, tokenType: "Bearer", expiresIn: 3600 },
+    traceId: req.header("X-Trace-Id") || "auth-trace",
+    timestamp: new Date().toISOString(),
+  });
+});
+
+app.post("/auth/refresh", (req, res) => {
+  const token = req.body?.refreshToken;
+  if (!token) {
+    return res.status(400).json({ code: 10001, message: "refreshToken required", data: null, traceId: req.header("X-Trace-Id") || "auth-trace", timestamp: new Date().toISOString() });
+  }
+
+  try {
+    const decoded = jwt.verify(token, refreshSecret);
+    const accessToken = signAccessToken(decoded.sub);
+    return res.json({ code: 0, message: "success", data: { accessToken, tokenType: "Bearer", expiresIn: 3600 }, traceId: req.header("X-Trace-Id") || "auth-trace", timestamp: new Date().toISOString() });
+  } catch (_e) {
+    return res.status(401).json({ code: 10002, message: "invalid refresh token", data: null, traceId: req.header("X-Trace-Id") || "auth-trace", timestamp: new Date().toISOString() });
+  }
+});
+
+app.get("/auth/verify", (req, res) => {
+  const auth = req.header("Authorization") || "";
+  const token = auth.startsWith("Bearer ") ? auth.slice(7) : "";
+  if (!token) {
+    return res.status(401).json({ code: 10003, message: "missing bearer token", data: null, traceId: req.header("X-Trace-Id") || "auth-trace", timestamp: new Date().toISOString() });
+  }
+
+  try {
+    const decoded = jwt.verify(token, secret);
+    return res.json({ code: 0, message: "success", data: { subject: decoded.sub }, traceId: req.header("X-Trace-Id") || "auth-trace", timestamp: new Date().toISOString() });
+  } catch (_e) {
+    return res.status(401).json({ code: 10004, message: "invalid access token", data: null, traceId: req.header("X-Trace-Id") || "auth-trace", timestamp: new Date().toISOString() });
+  }
+});
+
+app.get("/auth/me", (req, res) => {
+  const auth = req.header("Authorization") || "";
+  const token = auth.startsWith("Bearer ") ? auth.slice(7) : "";
+  if (!token) {
+    return res.status(401).json({ code: 10003, message: "missing bearer token", data: null, traceId: req.header("X-Trace-Id") || "auth-trace", timestamp: new Date().toISOString() });
+  }
+
+  try {
+    const decoded = jwt.verify(token, secret);
+    return res.json({ code: 0, message: "success", data: { subject: decoded.sub, role: decoded.role }, traceId: req.header("X-Trace-Id") || "auth-trace", timestamp: new Date().toISOString() });
+  } catch (_e) {
+    return res.status(401).json({ code: 10004, message: "invalid access token", data: null, traceId: req.header("X-Trace-Id") || "auth-trace", timestamp: new Date().toISOString() });
+  }
 });
 
 app.get("/health", (req, res) => {
   res.json({ code: 0, message: "success", data: { status: "ok" }, traceId: req.header("X-Trace-Id") || "auth-trace", timestamp: new Date().toISOString() });
 });
 
-app.listen(8081, () => {
-  console.log("auth-center listening on :8081");
+const port = Number(process.env.PORT || 8081);
+app.listen(port, () => {
+  console.log(`auth-center listening on :${port}`);
 });

package/dist/templates/modules/cache-redis/infra/cache/examples/cache-client.js

@@ -0,0 +1,8 @@
+// Minimal cache client wrapper example
+// Replace with your runtime client (ioredis/go-redis/spring-data-redis).
+
+function buildCacheKey(domain, entity, id) {
+  return `app:${domain}:${entity}:${id}`;
+}
+
+module.exports = { buildCacheKey };

package/dist/templates/modules/cache-redis/infra/cache/examples/redis-key-convention.md

@@ -0,0 +1,5 @@
+# Redis Key Convention
+
+- user profile: `app:user:profile:{userId}`
+- auth session: `app:auth:session:{sessionId}`
+- rate limit: `app:rate:{route}:{userId}`

package/dist/templates/modules/gateway-bff/apps/gateway-bff/server.js

@@ -3,15 +3,72 @@ const express = require("express");
 const app = express();
 app.use(express.json());
 
+const API_BASE = process.env.API_BASE || "http://127.0.0.1:8080";
+const port = Number(process.env.PORT || 3001);
+
+const rateCounter = new Map();
+setInterval(() => rateCounter.clear(), 60 * 1000);
+
+function traceId(req) {
+  return req.header("X-Trace-Id") || "bff-trace";
+}
+
+function withMeta(req, data) {
+  return {
+    code: 0,
+    message: "success",
+    data,
+    traceId: traceId(req),
+    timestamp: new Date().toISOString(),
+  };
+}
+
+function authPassthrough(req, res, next) {
+  const token = req.header("Authorization");
+  if (!token) {
+    return res.status(401).json({ code: 10003, message: "missing Authorization header", data: null, traceId: traceId(req), timestamp: new Date().toISOString() });
+  }
+  return next();
+}
+
+function rateLimit(req, res, next) {
+  const key = `${req.ip}:${req.path}`;
+  const count = (rateCounter.get(key) || 0) + 1;
+  rateCounter.set(key, count);
+  if (count > 120) {
+    return res.status(429).json({ code: 10029, message: "rate limit exceeded", data: null, traceId: traceId(req), timestamp: new Date().toISOString() });
+  }
+  return next();
+}
+
 app.get("/health", (_req, res) => {
   res.json({ code: 0, message: "success", data: { status: "ok" }, traceId: "bff-trace", timestamp: new Date().toISOString() });
 });
 
 app.get("/bff/ping", (req, res) => {
-  const traceId = req.header("X-Trace-Id") || "bff-trace";
-  res.json({ code: 0, message: "success", data: { message: "bff pong" }, traceId, timestamp: new Date().toISOString() });
+  res.json(withMeta(req, { message: "bff pong" }));
+});
+
+app.get("/bff/aggregate", rateLimit, authPassthrough, async (req, res) => {
+  try {
+    const [healthResp, pingResp] = await Promise.all([
+      fetch(`${API_BASE}/health`, { headers: { "X-Trace-Id": traceId(req) } }),
+      fetch(`${API_BASE}/api/v1/ping`, { headers: { "X-Trace-Id": traceId(req) } }),
+    ]);
+
+    const [healthData, pingData] = await Promise.all([healthResp.json(), pingResp.json()]);
+    return res.json(withMeta(req, { health: healthData, ping: pingData }));
+  } catch (error) {
+    return res.status(502).json({
+      code: 10502,
+      message: error instanceof Error ? error.message : "upstream call failed",
+      data: null,
+      traceId: traceId(req),
+      timestamp: new Date().toISOString(),
+    });
+  }
 });
 
-app.listen(3001, () => {
-  console.log("gateway-bff listening on :3001");
+app.listen(port, () => {
+  console.log(`gateway-bff listening on :${port}`);
 });

package/dist/templates/modules/grpc-service/apps/grpc-service/README.md

@@ -1,5 +1,6 @@
 # gRPC Service Module
 
-- Purpose: stable multi-language internal contracts
-- Includes proto sample and generation script
-- Requires: protoc + language plugins
+- Runtime server: `go run ./cmd/server`
+- Contract: `contracts/proto/greeter.proto`
+- Generation: `bash infra/scripts/gen-proto.sh`
+- Requires `protoc`, `protoc-gen-go`, `protoc-gen-go-grpc`

package/dist/templates/modules/grpc-service/apps/grpc-service/cmd/server/main.go

@@ -0,0 +1,27 @@
+package main
+
+import (
+	"log"
+	"net"
+
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/health"
+	grpcHealth "google.golang.org/grpc/health/grpc_health_v1"
+)
+
+func main() {
+	lis, err := net.Listen("tcp", ":9090")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	srv := grpc.NewServer()
+	healthSrv := health.NewServer()
+	healthSrv.SetServingStatus("grpc-service", grpcHealth.HealthCheckResponse_SERVING)
+	grpcHealth.RegisterHealthServer(srv, healthSrv)
+
+	log.Println("grpc-service listening on :9090")
+	if err := srv.Serve(lis); err != nil {
+		log.Fatal(err)
+	}
+}

package/dist/templates/modules/grpc-service/apps/grpc-service/go.mod

@@ -0,0 +1,8 @@
+module {{PROJECT_NAME}}/apps/grpc-service
+
+go 1.22
+
+require (
+	google.golang.org/grpc v1.66.0
+	google.golang.org/protobuf v1.34.2
+)

package/dist/templates/modules/mq/apps/mq-worker/README.md

@@ -0,0 +1,6 @@
+# MQ Worker
+
+- Consumer: `npm run consume`
+- Producer: `npm run produce`
+- Roundtrip test: `npm run roundtrip`
+- Default NATS URL: `nats://127.0.0.1:4222`

package/dist/templates/modules/mq/apps/mq-worker/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "{{PROJECT_NAME}}-mq-worker",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "consume": "node scripts/consumer.js",
+    "produce": "node scripts/producer.js",
+    "roundtrip": "node scripts/roundtrip.js",
+    "build": "node -e \"console.log('mq-worker build placeholder')\"",
+    "test": "node scripts/roundtrip.js"
+  },
+  "dependencies": {
+    "nats": "^2.29.1"
+  }
+}

package/dist/templates/modules/mq/apps/mq-worker/scripts/consumer.js

@@ -0,0 +1,11 @@
+import { connect, StringCodec } from "nats";
+
+const nc = await connect({ servers: process.env.NATS_URL || "nats://127.0.0.1:4222" });
+const sc = StringCodec();
+
+const sub = nc.subscribe("app.task.created");
+console.log("[mq-worker] listening on subject app.task.created");
+
+for await (const msg of sub) {
+  console.log("[mq-worker] consumed", sc.decode(msg.data));
+}

package/dist/templates/modules/mq/apps/mq-worker/scripts/producer.js

@@ -0,0 +1,15 @@
+import { connect, StringCodec } from "nats";
+
+const nc = await connect({ servers: process.env.NATS_URL || "nats://127.0.0.1:4222" });
+const sc = StringCodec();
+
+const payload = {
+  id: `evt-${Date.now()}`,
+  type: "app.task.created",
+  timestamp: new Date().toISOString(),
+};
+
+nc.publish("app.task.created", sc.encode(JSON.stringify(payload)));
+console.log("[mq-worker] produced", payload);
+
+await nc.drain();

package/dist/templates/modules/mq/apps/mq-worker/scripts/roundtrip.js

@@ -0,0 +1,29 @@
+import { connect, StringCodec } from "nats";
+
+const nc = await connect({ servers: process.env.NATS_URL || "nats://127.0.0.1:4222" });
+const sc = StringCodec();
+
+const subject = "app.task.created";
+const sub = nc.subscribe(subject, { max: 1 });
+
+const payload = {
+  id: `evt-${Date.now()}`,
+  type: subject,
+  timestamp: new Date().toISOString(),
+};
+
+nc.publish(subject, sc.encode(JSON.stringify(payload)));
+
+const timeout = setTimeout(async () => {
+  console.error("[mq-worker] roundtrip timeout");
+  await nc.drain();
+  process.exit(1);
+}, 3000);
+
+for await (const msg of sub) {
+  const parsed = JSON.parse(sc.decode(msg.data));
+  clearTimeout(timeout);
+  console.log("[mq-worker] roundtrip ok", parsed.id);
+  await nc.drain();
+  process.exit(0);
+}

package/dist/templates/modules/mq/infra/mq/README.md

@@ -1,5 +1,6 @@
 # MQ Module
 
 - Purpose: async collaboration between Go/Java/Python services
-- Includes placeholders for Kafka, RabbitMQ, NATS
+- Local stack: Kafka + RabbitMQ + NATS (`infra/mq/docker-compose.yml`)
+- Runnable worker example: `apps/mq-worker`
 - Default capabilities: producer/consumer samples, retry + idempotency + DLQ placeholders

package/dist/templates/modules/mq/infra/mq/docker-compose.yml

@@ -0,0 +1,25 @@
+services:
+  kafka:
+    image: bitnami/kafka:3.7
+    environment:
+      - KAFKA_CFG_NODE_ID=1
+      - KAFKA_CFG_PROCESS_ROLES=broker,controller
+      - KAFKA_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER
+      - KAFKA_CFG_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093
+      - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://kafka:9092
+      - KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP=CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
+      - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=1@kafka:9093
+      - KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE=true
+    ports:
+      - "9092:9092"
+
+  rabbitmq:
+    image: rabbitmq:3-management
+    ports:
+      - "5672:5672"
+      - "15672:15672"
+
+  nats:
+    image: nats:2.10
+    ports:
+      - "4222:4222"

package/dist/templates/modules/mq/infra/mq/scripts/consumer-sample.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "[mq] consumer sample placeholder"
+echo "Consume event: app.task.created"

package/dist/templates/modules/mq/infra/mq/scripts/producer-sample.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "[mq] producer sample placeholder"
+echo "Publish event: app.task.created"

package/dist/templates/modules/observability/infra/observability/docker-compose.yml

@@ -0,0 +1,21 @@
+services:
+  otel-collector:
+    image: otel/opentelemetry-collector:0.108.0
+    command: ["--config=/etc/otel-collector.yaml"]
+    volumes:
+      - ./otel-collector.yaml:/etc/otel-collector.yaml
+    ports:
+      - "4317:4317"
+      - "4318:4318"
+
+  prometheus:
+    image: prom/prometheus:v2.54.1
+    volumes:
+      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
+    ports:
+      - "9090:9090"
+
+  grafana:
+    image: grafana/grafana:11.1.5
+    ports:
+      - "3000:3000"

package/dist/templates/modules/observability/infra/observability/scripts/down.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+docker compose -f infra/observability/docker-compose.yml down

package/dist/templates/modules/observability/infra/observability/scripts/up.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+docker compose -f infra/observability/docker-compose.yml up -d

package/dist/templates/modules/python-worker/apps/worker-python/tasks/sample_task.py

@@ -1,6 +1,17 @@
+import random
+from datetime import datetime, timezone
+
+
 def run_sample_task(payload: dict) -> dict:
+    if payload.get("force_fail"):
+        raise RuntimeError("forced failure")
+
+    if not payload.get("disable_random") and random.randint(1, 8) == 1:
+        raise RuntimeError("simulated intermittent failure")
+
     return {
         "status": "ok",
         "traceId": payload.get("traceId", "generated-trace-id"),
+        "timestamp": datetime.now(timezone.utc).isoformat(),
         "data": payload,
     }

package/dist/templates/modules/python-worker/apps/worker-python/tests/test_worker.py

@@ -5,7 +5,7 @@ from tasks.sample_task import run_sample_task
 
 class WorkerTestCase(unittest.TestCase):
     def test_sample_task(self) -> None:
-        output = run_sample_task({"x": 1})
+        output = run_sample_task({"x": 1, "disable_random": True})
         self.assertEqual(output["status"], "ok")
 
 

package/dist/templates/modules/python-worker/apps/worker-python/worker.py

@@ -1,9 +1,51 @@
+from datetime import datetime, timezone
 from tasks.sample_task import run_sample_task
 
 
+class WorkerState:
+    def __init__(self) -> None:
+        self.jobs = {}
+        self.dead_letters = {}
+
+
+STATE = WorkerState()
+
+
+def process_job(job_id: str, payload: dict, max_retry: int = 2) -> None:
+    for attempt in range(max_retry + 1):
+        try:
+            STATE.jobs[job_id] = {
+                "id": job_id,
+                "attempt": attempt + 1,
+                "status": "running",
+                "updatedAt": datetime.now(timezone.utc).isoformat(),
+            }
+            result = run_sample_task(payload)
+            STATE.jobs[job_id] = {
+                "id": job_id,
+                "attempt": attempt + 1,
+                "status": "success",
+                "result": result,
+                "updatedAt": datetime.now(timezone.utc).isoformat(),
+            }
+            print(f"[worker-python] success: {STATE.jobs[job_id]}")
+            return
+        except Exception as exc:
+            if attempt >= max_retry:
+                STATE.dead_letters[job_id] = {
+                    "id": job_id,
+                    "status": "dead-letter",
+                    "error": str(exc),
+                    "updatedAt": datetime.now(timezone.utc).isoformat(),
+                }
+                print(f"[worker-python] dead-letter: {STATE.dead_letters[job_id]}")
+                return
+
+
 def main() -> None:
-    result = run_sample_task({"input": "demo"})
-    print(f"worker result: {result}")
+    process_job("job-1", {"input": "demo"})
+    print(f"[worker-python] jobs={STATE.jobs}")
+    print(f"[worker-python] dead_letters={STATE.dead_letters}")
 
 
 if __name__ == "__main__":

package/dist/templates/modules/worker-go/apps/worker-go/cmd/worker/main.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"encoding/json"
 	"log"
 	"time"
 
@@ -11,6 +12,11 @@ func main() {
 	log.Println("worker-go started")
 	for {
 		tasks.RunHeartbeatTask()
+
+		jobs, _ := json.Marshal(tasks.ListJobs())
+		dlq, _ := json.Marshal(tasks.ListDeadLetters())
+		log.Printf("worker-go state jobs=%s dead_letters=%s", string(jobs), string(dlq))
+
 		time.Sleep(10 * time.Second)
 	}
 }

package/dist/templates/modules/worker-go/apps/worker-go/internal/tasks/heartbeat.go

@@ -1,7 +1,112 @@
 package tasks
 
-import "log"
+import (
+	"errors"
+	"fmt"
+	"log"
+	"sync"
+	"time"
+)
+
+type JobStatus string
+
+const (
+	StatusPending   JobStatus = "pending"
+	StatusRunning   JobStatus = "running"
+	StatusSuccess   JobStatus = "success"
+	StatusFailed    JobStatus = "failed"
+	StatusDeadLetter JobStatus = "dead-letter"
+)
+
+type Job struct {
+	ID        string
+	Name      string
+	Attempts  int
+	MaxRetry  int
+	Status    JobStatus
+	UpdatedAt time.Time
+}
+
+var (
+	mu         sync.Mutex
+	registry   = map[string]*Job{}
+	deadLetter = map[string]*Job{}
+)
+
+func RegisterJob(name string, maxRetry int) string {
+	mu.Lock()
+	defer mu.Unlock()
+	id := fmt.Sprintf("job-%d", time.Now().UnixNano())
+	registry[id] = &Job{ID: id, Name: name, MaxRetry: maxRetry, Status: StatusPending, UpdatedAt: time.Now()}
+	return id
+}
+
+func RunJob(id string, fn func() error) {
+	mu.Lock()
+	job, ok := registry[id]
+	mu.Unlock()
+	if !ok {
+		log.Printf("job not found: %s", id)
+		return
+	}
+
+	for attempt := 1; attempt <= job.MaxRetry+1; attempt++ {
+		updateStatus(job, StatusRunning)
+		err := fn()
+		if err == nil {
+			job.Attempts = attempt
+			updateStatus(job, StatusSuccess)
+			log.Printf("job=%s success attempts=%d", job.ID, attempt)
+			return
+		}
+
+		job.Attempts = attempt
+		log.Printf("job=%s failed attempts=%d err=%v", job.ID, attempt, err)
+		if attempt > job.MaxRetry {
+			updateStatus(job, StatusDeadLetter)
+			mu.Lock()
+			deadLetter[job.ID] = job
+			mu.Unlock()
+			return
+		}
+		time.Sleep(500 * time.Millisecond)
+	}
+}
+
+func updateStatus(job *Job, status JobStatus) {
+	mu.Lock()
+	defer mu.Unlock()
+	job.Status = status
+	job.UpdatedAt = time.Now()
+}
+
+func ListJobs() []Job {
+	mu.Lock()
+	defer mu.Unlock()
+	items := make([]Job, 0, len(registry))
+	for _, job := range registry {
+		items = append(items, *job)
+	}
+	return items
+}
+
+func ListDeadLetters() []Job {
+	mu.Lock()
+	defer mu.Unlock()
+	items := make([]Job, 0, len(deadLetter))
+	for _, job := range deadLetter {
+		items = append(items, *job)
+	}
+	return items
+}
 
 func RunHeartbeatTask() {
-	log.Println("worker-go heartbeat task executed")
+	jobID := RegisterJob("heartbeat", 2)
+	RunJob(jobID, func() error {
+		if time.Now().Unix()%5 == 0 {
+			return errors.New("simulated intermittent failure")
+		}
+		log.Println("worker-go heartbeat task executed")
+		return nil
+	})
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polyforge-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "PolyForge hybrid full-stack scaffold CLI for go-gin and springboot",
   "main": "dist/index.js",
   "files": [