create-bubbles 0.1.22 → 0.1.24

package/template-vp-monorepo-react-hono/.vite-hooks/commit-msg

@@ -0,0 +1,2 @@
+#!/bin/bash
+vp dlx commitlint --edit "$1"

package/template-vp-monorepo-react-hono/.vite-hooks/pre-commit

@@ -0,0 +1,2 @@
+#!/bin/bash
+# vp staged

package/template-vp-monorepo-react-hono/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["VoidZero.vite-plus-extension-pack"]
+}

package/template-vp-monorepo-react-hono/.vscode/settings.json

@@ -0,0 +1,23 @@
+{
+  "prettier.enable": false,
+  "biome.enabled": false,
+
+  "editor.defaultFormatter": "oxc.oxc-vscode",
+  "editor.formatOnSave": true,
+
+  "editor.codeActionsOnSave": {
+    "source.organizeImports": "explicit",
+    "source.fixAll.oxc": "explicit"
+  },
+
+  "oxc.typeAware": false,
+  "oxc.lint.run": "onType",
+
+  "files.watcherExclude": {
+    "**/node_modules/**": true,
+    "**/.pnpm/**": true,
+    "**/dist/**": true,
+    "**/coverage/**": true,
+    "**/.vite/**": true
+  }
+}

package/template-vp-monorepo-react-hono/AGENTS.md

@@ -0,0 +1,16 @@
+<!--VITE PLUS START-->
+
+# Using Vite+, the Unified Toolchain for the Web
+
+This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called `vp`. Vite+ is distinct from Vite, and it invokes Vite through `vp dev` and `vp build`. Run `vp help` to print a list of commands and `vp <command> --help` for information about a specific command.
+
+Docs are local at `node_modules/vite-plus/docs` or online at https://viteplus.dev/guide/.
+
+## Review Checklist
+
+- [ ] Run `vp install` after pulling remote changes and before getting started.
+- [ ] Run `vp check` and `vp test` to format, lint, type check and test changes.
+- [ ] Check if there are `vite.config.ts` tasks or `package.json` scripts necessary for validation, run via `vp run <script>`.
+- [ ] If setup, runtime, or package-manager behavior looks wrong, run `vp env doctor` and include its output when asking for help.
+
+<!--VITE PLUS END-->

package/template-vp-monorepo-react-hono/README.md

@@ -0,0 +1,54 @@
+# Vite+ React + Hono Monorepo
+
+这个模板包含 React 前端、Hono API、Drizzle/PostgreSQL、Redis 与独立 BullMQ Worker。
+
+## 项目结构
+
+- `apps/web`: React 前端，开发端口 `9999`
+- `apps/server`: Hono API 与 BullMQ Worker，API 开发端口 `10000`
+- `packages/i18n`: 可复用的国际化包
+- `docker-compose.yml`: PostgreSQL、Redis 与 MinIO 本地基础设施
+
+## 首次启动
+
+```powershell
+vp install
+Copy-Item apps/server/.env.example apps/server/.env
+docker compose up -d postgres redis
+vp run --filter server db:migrate
+```
+
+分别启动应用与队列 Worker：
+
+```powershell
+# 终端 1：React + Hono API
+vp run dev
+
+# 终端 2：BullMQ Worker
+vp run dev:worker
+```
+
+也可以通过 Vite+ 选择后端运行时：
+
+```powershell
+# Node API / Worker
+vp run dev:server:node
+vp run dev:worker:node
+
+# Bun API / Worker
+vp run dev:server:bun
+vp run dev:worker:bun
+```
+
+前端的 `/api/*` 代理会移除 `/api` 前缀，因此：
+
+- 浏览器请求 `/api/health/live`，后端路由为 `/health/live`
+- 浏览器请求 `/api/v1/jobs/demo`，后端路由为 `/v1/jobs/demo`
+
+后端也同时挂载 `/api/health/*` 与 `/api/v1/jobs/*`，因此生产环境即使不配置 rewrite 也可直接使用前端的 `/api` 地址。
+
+## 验证
+
+```powershell
+vp run ready
+```

package/template-vp-monorepo-react-hono/apps/server/.env.example

@@ -0,0 +1,13 @@
+NODE_ENV=development
+APP_NAME=bubbles-server
+HOST=0.0.0.0
+PORT=10000
+CORS_ORIGINS=http://localhost:9999
+DATABASE_URL=postgresql://postgres:ml@localhost:5432/postgres
+DATABASE_POOL_MAX=10
+REDIS_URL=redis://:ml@localhost:6379/0
+REDIS_CONNECT_TIMEOUT_MS=5000
+JOB_QUEUE_NAME=jobs
+JOB_QUEUE_PREFIX=bubbles
+JOB_WORKER_CONCURRENCY=5
+SHUTDOWN_TIMEOUT_MS=10000

package/template-vp-monorepo-react-hono/apps/server/README.md

@@ -0,0 +1,75 @@
+# Server
+
+Hono 后端采用两个独立进程：HTTP API 负责接收请求与写入队列，BullMQ Worker 负责消费任务。数据库、Redis 和队列连接均按需创建，导入 `app.ts` 不会连接外部服务。
+
+## 分层
+
+```text
+src/
+├─ app.ts                         # Hono 应用、middleware、路由与错误处理
+├─ index.ts                       # HTTP 进程入口
+├─ worker.ts                      # BullMQ Worker 进程入口
+├─ config/                        # Zod 环境变量校验
+├─ common/                        # 错误、响应、日志
+├─ infrastructure/
+│  ├─ database/                   # pg Pool、Drizzle 与 schema
+│  ├─ redis/                      # 普通 Redis 客户端与连接参数
+│  └─ queue/                      # BullMQ 连接工厂
+├─ modules/
+│  ├─ health/                     # live / ready 健康检查
+│  └─ jobs/                       # 示例任务的 route/service/repository/worker
+└─ runtime/                       # 优雅关闭工具
+```
+
+## 常用命令
+
+```powershell
+# Node API / Worker（默认）
+vp run --filter server dev:node
+vp run --filter server dev:worker:node
+
+# Bun API / Worker
+vp run --filter server dev:bun
+vp run --filter server dev:worker:bun
+
+vp run --filter server build
+vp run --filter server test
+vp run --filter server db:generate
+vp run --filter server db:migrate
+vp run --filter server db:studio
+```
+
+生产构建同样通过 Vite+ 启动：
+
+```powershell
+vp run --filter server start:node
+vp run --filter server start:bun
+vp run --filter server start:worker:node
+vp run --filter server start:worker:bun
+```
+
+Node API 使用 `@hono/node-server`，Bun API 使用原生 `Bun.serve`，二者共用同一个 `app.ts`。Bun 命令使用 `--no-env-file`，统一交给 `dotenv/config` 加载 `.env`，避免两个运行时读取不同的环境文件。
+
+## 接口
+
+- `GET /health/live`: 进程存活检查，不访问外部依赖
+- `GET /health/ready`: 检查 PostgreSQL 与 Redis
+- `POST /v1/jobs/demo`: 写入 `job_runs` 并投递 BullMQ 示例任务
+- `GET /v1/jobs/:id`: 查询任务执行状态
+- 上述路由也同时挂载在 `/api/*`，可兼容没有 rewrite 的生产部署
+
+创建示例任务的请求体：
+
+```json
+{
+  "payload": {
+    "message": "hello"
+  }
+}
+```
+
+Redis 必须使用 `noeviction` 策略，HTTP Queue 与阻塞式 Worker 使用不同连接；Worker 连接的 `maxRetriesPerRequest` 固定为 `null`。
+
+BullMQ、ioredis 和 `pg` 主要以 Node 为生产目标，因此 Worker 默认推荐使用 Node。Bun Worker 可以用于开发与兼容性验证，但生产启用前应测试任务重试、延迟任务、锁续期、stalled recovery 和优雅关闭。
+
+示例 jobs 模块通过固定 `jobId` 和失败补偿降低重复与悬挂风险，但 PostgreSQL 写入和 Redis 入队仍不是同一个原子事务。对支付、通知等关键任务，应把创建任务改为 transactional outbox，并让独立 dispatcher 将 outbox 可靠投递到 BullMQ；具体业务处理器也必须保持幂等。

package/template-vp-monorepo-react-hono/apps/server/drizzle/0000_flaky_madame_masque.sql

@@ -0,0 +1,18 @@
+CREATE TYPE "public"."job_run_status" AS ENUM('queued', 'processing', 'completed', 'failed');--> statement-breakpoint
+CREATE TABLE "job_runs" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"queue_name" varchar(100) NOT NULL,
+	"job_name" varchar(100) NOT NULL,
+	"status" "job_run_status" DEFAULT 'queued' NOT NULL,
+	"payload" jsonb NOT NULL,
+	"result" jsonb,
+	"attempts" integer DEFAULT 0 NOT NULL,
+	"error" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"started_at" timestamp with time zone,
+	"finished_at" timestamp with time zone
+);
+--> statement-breakpoint
+CREATE INDEX "job_runs_status_created_at_idx" ON "job_runs" USING btree ("status","created_at");--> statement-breakpoint
+CREATE INDEX "job_runs_queue_name_idx" ON "job_runs" USING btree ("queue_name");

package/template-vp-monorepo-react-hono/apps/server/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,153 @@
+{
+  "id": "07916fda-3931-48b0-93df-ae9a88ba500c",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.job_runs": {
+      "name": "job_runs",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "queue_name": {
+          "name": "queue_name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "job_name": {
+          "name": "job_name",
+          "type": "varchar(100)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "job_run_status",
+          "typeSchema": "public",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'queued'"
+        },
+        "payload": {
+          "name": "payload",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "result": {
+          "name": "result",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "attempts": {
+          "name": "attempts",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "error": {
+          "name": "error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "finished_at": {
+          "name": "finished_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "job_runs_status_created_at_idx": {
+          "name": "job_runs_status_created_at_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "job_runs_queue_name_idx": {
+          "name": "job_runs_queue_name_idx",
+          "columns": [
+            {
+              "expression": "queue_name",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {
+    "public.job_run_status": {
+      "name": "job_run_status",
+      "schema": "public",
+      "values": ["queued", "processing", "completed", "failed"]
+    }
+  },
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/template-vp-monorepo-react-hono/apps/server/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1786180920930,
+      "tag": "0000_flaky_madame_masque",
+      "breakpoints": true
+    }
+  ]
+}

package/template-vp-monorepo-react-hono/apps/server/drizzle.config.ts

@@ -0,0 +1,19 @@
+import 'dotenv/config'
+import { defineConfig } from 'drizzle-kit'
+
+const databaseUrl = process.env.DATABASE_URL
+
+if (!databaseUrl) {
+  throw new Error('DATABASE_URL is required to run Drizzle commands')
+}
+
+export default defineConfig({
+  schema: './src/infrastructure/database/schema/index.ts',
+  out: './drizzle',
+  dialect: 'postgresql',
+  dbCredentials: {
+    url: databaseUrl,
+  },
+  strict: true,
+  verbose: true,
+})

package/template-vp-monorepo-react-hono/apps/server/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "server",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "dev:node": "tsx watch src/index.ts",
+    "dev:bun": "bun --no-env-file --watch src/index.bun.ts",
+    "dev:worker": "tsx watch src/worker.ts",
+    "dev:worker:node": "tsx watch src/worker.ts",
+    "dev:worker:bun": "bun --no-env-file --watch src/worker.ts",
+    "build": "vp pack",
+    "start": "node dist/index.mjs",
+    "start:node": "node dist/index.mjs",
+    "start:bun": "bun --no-env-file dist/index.bun.mjs",
+    "start:worker": "node dist/worker.mjs",
+    "start:worker:node": "node dist/worker.mjs",
+    "start:worker:bun": "bun --no-env-file dist/worker.mjs",
+    "test": "vp test run",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio"
+  },
+  "dependencies": {
+    "@hono/node-server": "catalog:",
+    "bullmq": "catalog:",
+    "dotenv": "catalog:",
+    "drizzle-orm": "catalog:",
+    "hono": "catalog:",
+    "ioredis": "catalog:",
+    "pg": "catalog:",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@types/bun": "catalog:",
+    "@types/node": "catalog:",
+    "@types/pg": "catalog:",
+    "drizzle-kit": "catalog:",
+    "tsx": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vite-plus": "catalog:"
+  }
+}

package/template-vp-monorepo-react-hono/apps/server/src/app.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vite-plus/test'
+import { createApp } from './app.js'
+
+describe('server app', () => {
+  const app = createApp()
+
+  it('returns liveness without connecting to infrastructure', async () => {
+    const response = await app.request('/health/live')
+    const body = await response.json()
+
+    expect(response.status).toBe(200)
+    expect(body).toMatchObject({
+      code: 200,
+      data: {
+        status: 'ok',
+      },
+      msg: '操作成功',
+    })
+  })
+
+  it('uses the frontend-compatible response envelope', async () => {
+    const response = await app.request('/')
+    const body = await response.json()
+
+    expect(response.status).toBe(200)
+    expect(body).toMatchObject({
+      code: 200,
+      data: {
+        health: '/health/live',
+      },
+      msg: '操作成功',
+    })
+  })
+
+  it('supports the production /api prefix without a rewrite proxy', async () => {
+    const response = await app.request('/api/health/live')
+
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toMatchObject({
+      code: 200,
+      data: {
+        status: 'ok',
+      },
+    })
+  })
+
+  it('returns a wrapped 404 response', async () => {
+    const response = await app.request('/missing')
+
+    expect(response.status).toBe(404)
+    await expect(response.json()).resolves.toEqual({
+      code: 404,
+      data: null,
+      msg: '接口不存在',
+    })
+  })
+})

package/template-vp-monorepo-react-hono/apps/server/src/app.ts

@@ -0,0 +1,68 @@
+import { cors } from 'hono/cors'
+import { Hono } from 'hono'
+import { logger } from 'hono/logger'
+import { requestId } from 'hono/request-id'
+import { secureHeaders } from 'hono/secure-headers'
+import { AppError } from './common/errors/app-error.js'
+import { apiFailure, apiSuccess } from './common/http/response.js'
+import { appLogger } from './common/logger.js'
+import { getEnv } from './config/env.js'
+import { healthRoutes } from './modules/health/health.routes.js'
+import { jobsRoutes } from './modules/jobs/jobs.routes.js'
+
+export function createApp() {
+  const env = getEnv()
+  const app = new Hono()
+  const allowEveryOrigin = env.CORS_ORIGINS.includes('*')
+
+  app.use('*', requestId())
+  app.use('*', secureHeaders())
+  app.use(
+    '*',
+    cors({
+      origin: (origin) => {
+        if (allowEveryOrigin) return '*'
+        return env.CORS_ORIGINS.includes(origin) ? origin : ''
+      },
+      credentials: !allowEveryOrigin,
+    }),
+  )
+
+  if (env.NODE_ENV !== 'test') {
+    app.use('*', logger())
+  }
+
+  app.get('/', (context) =>
+    context.json(
+      apiSuccess({
+        name: env.APP_NAME,
+        environment: env.NODE_ENV,
+        health: '/health/live',
+        apiHealth: '/api/health/live',
+      }),
+    ),
+  )
+  app.route('/health', healthRoutes)
+  app.route('/api/health', healthRoutes)
+  app.route('/v1/jobs', jobsRoutes)
+  app.route('/api/v1/jobs', jobsRoutes)
+
+  app.notFound((context) => context.json(apiFailure(404, '接口不存在'), 404))
+  app.onError((error, context) => {
+    if (error instanceof AppError) {
+      return context.json(apiFailure(error.code, error.message, error.details), error.status)
+    }
+
+    appLogger.error('Unhandled request error', {
+      method: context.req.method,
+      path: context.req.path,
+      error: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : undefined,
+    })
+
+    const message = env.NODE_ENV === 'production' ? '服务内部错误' : error.message
+    return context.json(apiFailure(500, message), 500)
+  })
+
+  return app
+}

package/template-vp-monorepo-react-hono/apps/server/src/common/errors/app-error.ts

@@ -0,0 +1,23 @@
+export type AppErrorStatus = 400 | 401 | 403 | 404 | 409 | 422 | 429 | 500 | 502 | 503
+
+interface AppErrorOptions {
+  status: AppErrorStatus
+  message: string
+  code?: number
+  details?: unknown
+  cause?: unknown
+}
+
+export class AppError extends Error {
+  readonly status: AppErrorStatus
+  readonly code: number
+  readonly details?: unknown
+
+  constructor(options: AppErrorOptions) {
+    super(options.message, { cause: options.cause })
+    this.name = 'AppError'
+    this.status = options.status
+    this.code = options.code ?? options.status
+    this.details = options.details
+  }
+}

package/template-vp-monorepo-react-hono/apps/server/src/common/http/response.ts

@@ -0,0 +1,21 @@
+export interface ApiResponse<T> {
+  code: number
+  data: T
+  msg: string
+}
+
+export function apiSuccess<T>(data: T, msg = '操作成功'): ApiResponse<T> {
+  return {
+    code: 200,
+    data,
+    msg,
+  }
+}
+
+export function apiFailure(code: number, msg: string, data: unknown = null): ApiResponse<unknown> {
+  return {
+    code,
+    data,
+    msg,
+  }
+}

package/template-vp-monorepo-react-hono/apps/server/src/common/logger.ts

@@ -0,0 +1,30 @@
+type LogContext = Record<string, unknown>
+
+function write(level: 'info' | 'warn' | 'error', message: string, context?: LogContext): void {
+  const entry = {
+    level,
+    time: new Date().toISOString(),
+    message,
+    ...context,
+  }
+
+  const serialized = JSON.stringify(entry)
+
+  if (level === 'error') {
+    console.error(serialized)
+    return
+  }
+
+  if (level === 'warn') {
+    console.warn(serialized)
+    return
+  }
+
+  console.info(serialized)
+}
+
+export const appLogger = {
+  info: (message: string, context?: LogContext) => write('info', message, context),
+  warn: (message: string, context?: LogContext) => write('warn', message, context),
+  error: (message: string, context?: LogContext) => write('error', message, context),
+}