polyforge-cli 0.1.0

package/dist/templates/frontend/react/apps/web/src/api/request.ts

@@ -0,0 +1,104 @@
+export type ApiPayload<T = unknown> = {
+  code: number;
+  message: string;
+  data: T;
+  traceId: string;
+  timestamp: string;
+};
+
+export class ApiRequestError extends Error {
+  status: number;
+  code: number | null;
+  traceId: string | null;
+  retryable: boolean;
+
+  constructor(message: string, status: number, code: number | null, traceId: string | null, retryable: boolean) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.traceId = traceId;
+    this.retryable = retryable;
+  }
+}
+
+export type RequestOptions = {
+  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  body?: unknown;
+  headers?: Record<string, string>;
+  timeoutMs?: number;
+  retries?: number;
+};
+
+const DEFAULT_TIMEOUT_MS = 5000;
+
+function randomTraceId(): string {
+  return `web-${Math.random().toString(16).slice(2, 10)}`;
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function makeErrorMessage(status: number, payload: unknown): string {
+  if (payload && typeof payload === "object" && "message" in payload) {
+    const message = (payload as { message?: unknown }).message;
+    if (typeof message === "string" && message.trim()) return message;
+  }
+  return `HTTP ${status}`;
+}
+
+export async function requestJson<T = unknown>(url: string, options: RequestOptions = {}): Promise<ApiPayload<T>> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const retries = options.retries ?? 0;
+
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    const traceId = randomTraceId();
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+      const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+        "X-Trace-Id": traceId,
+        ...(options.headers ?? {}),
+      };
+
+      const response = await fetch(url, {
+        method: options.method ?? "GET",
+        headers,
+        body: options.body === undefined ? undefined : JSON.stringify(options.body),
+        signal: controller.signal,
+      });
+
+      const raw = (await response.json()) as unknown;
+      if (!response.ok) {
+        const retryable = response.status >= 500;
+        const code = typeof raw === "object" && raw && "code" in raw ? Number((raw as { code: unknown }).code) : null;
+        const respTraceId = typeof raw === "object" && raw && "traceId" in raw ? String((raw as { traceId: unknown }).traceId) : null;
+        const error = new ApiRequestError(makeErrorMessage(response.status, raw), response.status, code, respTraceId, retryable);
+        if (retryable && attempt < retries) {
+          await delay(200 * (attempt + 1));
+          continue;
+        }
+        throw error;
+      }
+
+      return raw as ApiPayload<T>;
+    } catch (error) {
+      const retryable = error instanceof ApiRequestError ? error.retryable : true;
+      if (attempt < retries && retryable) {
+        await delay(200 * (attempt + 1));
+        continue;
+      }
+      if (error instanceof ApiRequestError) throw error;
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new ApiRequestError("request timeout", 408, null, null, true);
+      }
+      throw new ApiRequestError(error instanceof Error ? error.message : String(error), 0, null, null, true);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  throw new ApiRequestError("request failed", 0, null, null, true);
+}

package/dist/templates/frontend/react/apps/web/src/api/services/api.ts

@@ -0,0 +1,15 @@
+import { requestJson, type ApiPayload } from "../request";
+
+const API_BASE = import.meta.env.VITE_API_BASE || "/api";
+
+export function getApiBase(): string {
+  return API_BASE;
+}
+
+export function pingApi(): Promise<ApiPayload<{ message: string }>> {
+  return requestJson<{ message: string }>(`${API_BASE}/v1/ping`, { retries: 1, timeoutMs: 5000 });
+}
+
+export function healthApi(): Promise<ApiPayload<{ status: string }>> {
+  return requestJson<{ status: string }>(`/health`, { retries: 0, timeoutMs: 3000 });
+}

package/dist/templates/frontend/react/apps/web/src/api/services/bff.ts

@@ -0,0 +1,11 @@
+import { requestJson, type ApiPayload } from "../request";
+
+const BFF_BASE = import.meta.env.VITE_BFF_BASE || "/bff";
+
+export function getBffBase(): string {
+  return BFF_BASE;
+}
+
+export function pingBff(): Promise<ApiPayload<{ message: string }>> {
+  return requestJson<{ message: string }>(`${BFF_BASE}/ping`, { retries: 1, timeoutMs: 5000 });
+}

package/dist/templates/frontend/react/apps/web/src/main.tsx

@@ -0,0 +1,9 @@
+import React from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+
+createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);

package/dist/templates/frontend/react/apps/web/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "types": ["vitest/globals"]
+  },
+  "include": ["src"]
+}

package/dist/templates/frontend/react/apps/web/vite.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig, loadEnv } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), "");
+
+  return {
+    plugins: [react()],
+    server: {
+      proxy: {
+        "/api": {
+          target: env.VITE_DEV_API_TARGET || "http://localhost:8080",
+          changeOrigin: true,
+        },
+        "/bff": {
+          target: env.VITE_DEV_BFF_TARGET || "http://localhost:3001",
+          changeOrigin: true,
+        },
+      },
+    },
+  };
+});

package/dist/templates/frontend/vue/apps/web/.env.example

@@ -0,0 +1,4 @@
+VITE_API_BASE=/api
+VITE_BFF_BASE=/bff
+VITE_DEV_API_TARGET=http://localhost:8080
+VITE_DEV_BFF_TARGET=http://localhost:3001

package/dist/templates/frontend/vue/apps/web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{PROJECT_NAME}} web</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/dist/templates/frontend/vue/apps/web/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "{{PROJECT_NAME}}-web",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "vue": "^3.5.10"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.1.4",
+    "typescript": "^5.9.2",
+    "vite": "^5.4.8",
+    "vitest": "^2.1.3"
+  }
+}

package/dist/templates/frontend/vue/apps/web/src/App.test.ts

@@ -0,0 +1,7 @@
+import { describe, expect, it } from "vitest";
+
+describe("app", () => {
+  it("basic assertion", () => {
+    expect(true).toBe(true);
+  });
+});

package/dist/templates/frontend/vue/apps/web/src/App.vue

@@ -0,0 +1,59 @@
+<script setup lang="ts">
+import { ref } from "vue";
+import {
+  availableServices,
+  getApiBase,
+  getBffBase,
+  hasBffEnabled,
+  pingApi,
+  pingBff,
+  type ApiPayload,
+} from "./api/client";
+
+const HAS_BFF = hasBffEnabled();
+
+const apiResult = ref<ApiPayload | null>(null);
+const bffResult = ref<ApiPayload | null>(null);
+const apiError = ref("");
+const bffError = ref("");
+
+async function callApi() {
+  apiError.value = "";
+  try {
+    apiResult.value = await pingApi();
+  } catch (error) {
+    apiError.value = error instanceof Error ? error.message : String(error);
+  }
+}
+
+async function callBff() {
+  if (!HAS_BFF) return;
+  bffError.value = "";
+  try {
+    bffResult.value = await pingBff();
+  } catch (error) {
+    bffError.value = error instanceof Error ? error.message : String(error);
+  }
+}
+</script>
+
+<template>
+  <main style="font-family: sans-serif; padding: 24px; max-width: 900px;">
+    <h1>{{PROJECT_NAME}} - Vue</h1>
+    <p>API base: <code>{{ getApiBase() }}</code> | BFF base: <code>{{ getBffBase() }}</code></p>
+    <p>Available services: <code>{{ availableServices.join(", ") }}</code></p>
+
+    <section style="margin-bottom: 20px;">
+      <button @click="callApi">Call API /api/v1/ping</button>
+      <p v-if="apiError" style="color: crimson;">{{ apiError }}</p>
+      <pre v-if="apiResult">{{ JSON.stringify(apiResult, null, 2) }}</pre>
+    </section>
+
+    <section>
+      <button @click="callBff" :disabled="!HAS_BFF">Call BFF /bff/ping</button>
+      <p v-if="!HAS_BFF">BFF module not selected. Enable <code>gateway-bff</code> to use this call.</p>
+      <p v-if="bffError" style="color: crimson;">{{ bffError }}</p>
+      <pre v-if="bffResult">{{ JSON.stringify(bffResult, null, 2) }}</pre>
+    </section>
+  </main>
+</template>

package/dist/templates/frontend/vue/apps/web/src/api/client.ts

@@ -0,0 +1,20 @@
+import { type ApiPayload } from "./request";
+import { getApiBase, healthApi, pingApi } from "./services/api";
+import { getBffBase, pingBff as pingBffService } from "./services/bff";
+
+const HAS_BFF = "{{HAS_GATEWAY_BFF}}" === "true";
+
+export { type ApiPayload, getApiBase, healthApi, pingApi, getBffBase };
+
+export const availableServices = HAS_BFF ? ["api", "bff"] as const : ["api"] as const;
+
+export async function pingBff(): Promise<ApiPayload<{ message: string }>> {
+  if (!HAS_BFF) {
+    throw new Error("gateway-bff module not enabled");
+  }
+  return pingBffService();
+}
+
+export function hasBffEnabled(): boolean {
+  return HAS_BFF;
+}

package/dist/templates/frontend/vue/apps/web/src/api/request.ts

@@ -0,0 +1,104 @@
+export type ApiPayload<T = unknown> = {
+  code: number;
+  message: string;
+  data: T;
+  traceId: string;
+  timestamp: string;
+};
+
+export class ApiRequestError extends Error {
+  status: number;
+  code: number | null;
+  traceId: string | null;
+  retryable: boolean;
+
+  constructor(message: string, status: number, code: number | null, traceId: string | null, retryable: boolean) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.traceId = traceId;
+    this.retryable = retryable;
+  }
+}
+
+export type RequestOptions = {
+  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  body?: unknown;
+  headers?: Record<string, string>;
+  timeoutMs?: number;
+  retries?: number;
+};
+
+const DEFAULT_TIMEOUT_MS = 5000;
+
+function randomTraceId(): string {
+  return `web-${Math.random().toString(16).slice(2, 10)}`;
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function makeErrorMessage(status: number, payload: unknown): string {
+  if (payload && typeof payload === "object" && "message" in payload) {
+    const message = (payload as { message?: unknown }).message;
+    if (typeof message === "string" && message.trim()) return message;
+  }
+  return `HTTP ${status}`;
+}
+
+export async function requestJson<T = unknown>(url: string, options: RequestOptions = {}): Promise<ApiPayload<T>> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const retries = options.retries ?? 0;
+
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    const traceId = randomTraceId();
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+      const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+        "X-Trace-Id": traceId,
+        ...(options.headers ?? {}),
+      };
+
+      const response = await fetch(url, {
+        method: options.method ?? "GET",
+        headers,
+        body: options.body === undefined ? undefined : JSON.stringify(options.body),
+        signal: controller.signal,
+      });
+
+      const raw = (await response.json()) as unknown;
+      if (!response.ok) {
+        const retryable = response.status >= 500;
+        const code = typeof raw === "object" && raw && "code" in raw ? Number((raw as { code: unknown }).code) : null;
+        const respTraceId = typeof raw === "object" && raw && "traceId" in raw ? String((raw as { traceId: unknown }).traceId) : null;
+        const error = new ApiRequestError(makeErrorMessage(response.status, raw), response.status, code, respTraceId, retryable);
+        if (retryable && attempt < retries) {
+          await delay(200 * (attempt + 1));
+          continue;
+        }
+        throw error;
+      }
+
+      return raw as ApiPayload<T>;
+    } catch (error) {
+      const retryable = error instanceof ApiRequestError ? error.retryable : true;
+      if (attempt < retries && retryable) {
+        await delay(200 * (attempt + 1));
+        continue;
+      }
+      if (error instanceof ApiRequestError) throw error;
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new ApiRequestError("request timeout", 408, null, null, true);
+      }
+      throw new ApiRequestError(error instanceof Error ? error.message : String(error), 0, null, null, true);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  throw new ApiRequestError("request failed", 0, null, null, true);
+}

package/dist/templates/frontend/vue/apps/web/src/api/services/api.ts

@@ -0,0 +1,15 @@
+import { requestJson, type ApiPayload } from "../request";
+
+const API_BASE = import.meta.env.VITE_API_BASE || "/api";
+
+export function getApiBase(): string {
+  return API_BASE;
+}
+
+export function pingApi(): Promise<ApiPayload<{ message: string }>> {
+  return requestJson<{ message: string }>(`${API_BASE}/v1/ping`, { retries: 1, timeoutMs: 5000 });
+}
+
+export function healthApi(): Promise<ApiPayload<{ status: string }>> {
+  return requestJson<{ status: string }>(`/health`, { retries: 0, timeoutMs: 3000 });
+}

package/dist/templates/frontend/vue/apps/web/src/api/services/bff.ts

@@ -0,0 +1,11 @@
+import { requestJson, type ApiPayload } from "../request";
+
+const BFF_BASE = import.meta.env.VITE_BFF_BASE || "/bff";
+
+export function getBffBase(): string {
+  return BFF_BASE;
+}
+
+export function pingBff(): Promise<ApiPayload<{ message: string }>> {
+  return requestJson<{ message: string }>(`${BFF_BASE}/ping`, { retries: 1, timeoutMs: 5000 });
+}

package/dist/templates/frontend/vue/apps/web/src/env.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="vite/client" />
+
+declare module "*.vue";

package/dist/templates/frontend/vue/apps/web/src/main.ts

@@ -0,0 +1,4 @@
+import { createApp } from "vue";
+import App from "./App.vue";
+
+createApp(App).mount("#app");

package/dist/templates/frontend/vue/apps/web/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "types": ["vitest/globals"]
+  },
+  "include": ["src", "src/**/*.vue", "src/env.d.ts"]
+}

package/dist/templates/frontend/vue/apps/web/vite.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig, loadEnv } from "vite";
+import vue from "@vitejs/plugin-vue";
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), "");
+
+  return {
+    plugins: [vue()],
+    server: {
+      proxy: {
+        "/api": {
+          target: env.VITE_DEV_API_TARGET || "http://localhost:8080",
+          changeOrigin: true,
+        },
+        "/bff": {
+          target: env.VITE_DEV_BFF_TARGET || "http://localhost:3001",
+          changeOrigin: true,
+        },
+      },
+    },
+  };
+});

package/dist/templates/modules/auth-center/apps/auth-center/.env.example

@@ -0,0 +1,3 @@
+JWT_SECRET=please-change-in-production
+OAUTH_CLIENT_ID=example-client
+OAUTH_CLIENT_SECRET=example-secret

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

@@ -0,0 +1,5 @@
+# Auth Center Module
+
+- Purpose: centralize login/token/authorization
+- Includes JWT login placeholder endpoint
+- Add OAuth2 client configs before production

package/dist/templates/modules/auth-center/apps/auth-center/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "{{PROJECT_NAME}}-auth-center",
+  "private": true,
+  "version": "0.1.0",
+  "scripts": {
+    "dev": "node server.js",
+    "build": "node -e \"console.log('auth-center build placeholder')\"",
+    "test": "node -e \"console.log('auth-center test placeholder')\""
+  },
+  "dependencies": {
+    "express": "^4.21.2",
+    "jsonwebtoken": "^9.0.2"
+  }
+}

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

@@ -0,0 +1,21 @@
+const express = require("express");
+const jwt = require("jsonwebtoken");
+
+const app = express();
+app.use(express.json());
+
+const secret = process.env.JWT_SECRET || "change-me";
+
+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() });
+});
+
+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");
+});

package/dist/templates/modules/cache-redis/infra/cache/README.md

@@ -0,0 +1,5 @@
+# Cache Redis Module
+
+- Purpose: shared caching conventions across services
+- Key naming sample: `app:{domain}:{entity}:{id}`
+- TTL policy placeholder and hot-key protection notes

package/dist/templates/modules/cache-redis/infra/cache/policies.md

@@ -0,0 +1,5 @@
+# Cache Policies
+
+- default TTL: 5m
+- user session TTL: 30m
+- protect hot keys with local fallback and jittered TTL

package/dist/templates/modules/gateway-bff/apps/gateway-bff/README.md

@@ -0,0 +1,5 @@
+# Gateway BFF
+
+- Purpose: API aggregation, auth pass-through, rate limit placeholder
+- Default endpoint: `/bff/ping`
+- Integrates between frontend and backend main API

package/dist/templates/modules/gateway-bff/apps/gateway-bff/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "{{PROJECT_NAME}}-gateway-bff",
+  "private": true,
+  "version": "0.1.0",
+  "scripts": {
+    "dev": "node server.js",
+    "build": "node -e \"console.log('gateway-bff build placeholder')\"",
+    "test": "node -e \"console.log('gateway-bff test placeholder')\""
+  },
+  "dependencies": {
+    "express": "^4.21.2"
+  }
+}

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

@@ -0,0 +1,17 @@
+const express = require("express");
+
+const app = express();
+app.use(express.json());
+
+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() });
+});
+
+app.listen(3001, () => {
+  console.log("gateway-bff listening on :3001");
+});

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

@@ -0,0 +1,5 @@
+# gRPC Service Module
+
+- Purpose: stable multi-language internal contracts
+- Includes proto sample and generation script
+- Requires: protoc + language plugins

package/dist/templates/modules/grpc-service/contracts/proto/greeter.proto

@@ -0,0 +1,17 @@
+syntax = "proto3";
+
+package scaffold.greeter.v1;
+
+option go_package = "{{PROJECT_NAME}}/contracts/proto;greeter";
+
+service GreeterService {
+  rpc SayHello(HelloRequest) returns (HelloReply);
+}
+
+message HelloRequest {
+  string name = 1;
+}
+
+message HelloReply {
+  string message = 1;
+}

package/dist/templates/modules/grpc-service/infra/scripts/gen-proto.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# placeholder generation command; adjust plugins/language as needed
+protoc \
+  --proto_path=contracts/proto \
+  --go_out=apps/grpc-service \
+  --go-grpc_out=apps/grpc-service \
+  contracts/proto/greeter.proto

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

@@ -0,0 +1,5 @@
+# MQ Module
+
+- Purpose: async collaboration between Go/Java/Python services
+- Includes placeholders for Kafka, RabbitMQ, NATS
+- Default capabilities: producer/consumer samples, retry + idempotency + DLQ placeholders

package/dist/templates/modules/mq/infra/mq/kafka-topics.md

@@ -0,0 +1,5 @@
+# Kafka Topics Placeholder
+
+- `app.task.created`
+- `app.task.retry`
+- `app.task.dlq`

package/dist/templates/modules/mq/infra/mq/nats-subjects.md

@@ -0,0 +1,4 @@
+# NATS Subjects Placeholder
+
+- `app.task.created`
+- `app.task.completed`

package/dist/templates/modules/mq/infra/mq/rabbitmq-exchanges.md

@@ -0,0 +1,5 @@
+# RabbitMQ Placeholder
+
+- exchange: `app.events`
+- queue: `app.task.worker`
+- dead-letter queue: `app.task.dlq`