create-next-imagicma 0.0.1

package/README.md

@@ -0,0 +1,42 @@
+# create-next-imagicma
+
+一个极简的项目脚手架（类似 `create-next-app`），用于从本仓库模板快速生成新项目。
+
+## 使用
+
+```bash
+npm install -g create-next-imagicma
+create-next-imagicma <project-dir> [--port <1-65535>]
+```
+
+本地（未发布）使用示例：
+
+```bash
+cd /Users/alexliu/Project/nextjs-app
+node ./create-next-imagicma/bin/create-next-imagicma.mjs demo-5001 --port 5001
+```
+
+## 参数
+
+- `--port <number>`：设置新项目 `dev/start` 的默认端口（写入 `next ... -p <port>`）。
+- 运行时仍可覆盖，例如：`pnpm dev -- -p 6001` 或 `PORT=6001 pnpm start`
+
+## 依赖安装策略
+
+- 优先使用 `pnpm install`
+- 如果没有 `pnpm`，会尝试 `corepack pnpm install`
+- 如果依然不可用，会自动回退到 `npm install`
+
+## 维护模板
+
+在脚手架目录执行（默认从同级的 `../nextjs-app` 同步）：
+
+```bash
+pnpm run sync-template
+```
+
+可通过环境变量自定义源仓库路径：
+
+```bash
+SOURCE_REPO=/abs/path/to/source pnpm run sync-template
+```

package/bin/create-next-imagicma.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const TEMPLATE_DIR = path.resolve(__dirname, "..", "template");
+
+function printHelp() {
+  console.log(`create-next-imagicma <project-dir> [--port <1-65535>]
+
+参数：
+  --port <number>  设置新项目 dev/start 的默认端口（next ... -p）
+  -h, --help       显示帮助
+`);
+}
+
+function parsePort(raw) {
+  const port = Number(raw);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(
+      `--port 参数不合法：${JSON.stringify(raw)}（期望 1-65535 的整数）`,
+    );
+  }
+  return port;
+}
+
+function sanitizePackageName(raw) {
+  const normalized = raw
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/gu, "-")
+    .replace(/^-+|-+$/gu, "");
+  return normalized || "my-app";
+}
+
+function parseArgs(argv) {
+  let projectDir;
+  let port;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === "-h" || arg === "--help") {
+      return { help: true };
+    }
+
+    if (arg === "--port") {
+      const value = argv[i + 1];
+      if (!value) {
+        throw new Error("--port 缺少值：请使用 --port <number>");
+      }
+      port = parsePort(value);
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--port=")) {
+      port = parsePort(arg.slice("--port=".length));
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      throw new Error(`未知参数：${arg}`);
+    }
+
+    if (!projectDir) {
+      projectDir = arg;
+      continue;
+    }
+
+    throw new Error(`多余的参数：${arg}`);
+  }
+
+  if (!projectDir) {
+    throw new Error("缺少 <project-dir>：请指定要创建的项目目录名/路径");
+  }
+
+  return { projectDir, port, help: false };
+}
+
+async function ensureTargetDirEmpty(targetDir) {
+  try {
+    const stat = await fs.stat(targetDir);
+    if (!stat.isDirectory()) {
+      throw new Error(`目标路径已存在且不是目录：${targetDir}`);
+    }
+    const entries = await fs.readdir(targetDir);
+    if (entries.length > 0) {
+      throw new Error(`目标目录已存在且非空：${targetDir}`);
+    }
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+}
+
+async function updatePackageName(targetDir, port) {
+  const pkgPath = path.join(targetDir, "package.json");
+  const raw = await fs.readFile(pkgPath, "utf8");
+  const pkg = JSON.parse(raw);
+  const devScript = port === undefined ? "next dev" : `next dev -p ${port}`;
+  const startScript =
+    port === undefined ? "next start" : `next start -p ${port}`;
+
+  pkg.name = sanitizePackageName(path.basename(targetDir));
+  pkg.scripts = {
+    ...(pkg.scripts ?? {}),
+    dev: devScript,
+    start: startScript,
+  };
+  await fs.writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+function runCommand(command, args, options) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: "inherit", ...options });
+    child.on("error", reject);
+    child.on("close", (code) => resolve(code ?? 0));
+  });
+}
+
+function isCommandMissingError(error) {
+  return (
+    !!error &&
+    typeof error === "object" &&
+    "code" in error &&
+    error.code === "ENOENT"
+  );
+}
+
+async function installDependencies(targetDir) {
+  console.log("\n正在安装依赖（优先 pnpm）...\n");
+
+  try {
+    const pnpmCode = await runCommand("pnpm", ["install"], { cwd: targetDir });
+    if (pnpmCode === 0) return { ok: true, installer: "pnpm" };
+    return { ok: false, installer: "pnpm" };
+  } catch (error) {
+    if (!isCommandMissingError(error)) {
+      throw error;
+    }
+  }
+
+  console.log("未检测到全局 pnpm，尝试使用 corepack 调用 pnpm...\n");
+  try {
+    const corepackCode = await runCommand("corepack", ["pnpm", "install"], {
+      cwd: targetDir,
+    });
+    if (corepackCode === 0) return { ok: true, installer: "pnpm" };
+  } catch (error) {
+    if (!isCommandMissingError(error)) throw error;
+  }
+
+  console.log("将使用 npm 安装依赖。\n");
+
+  try {
+    const npmCode = await runCommand("npm", ["install"], { cwd: targetDir });
+    if (npmCode === 0) return { ok: true, installer: "npm" };
+    return { ok: false, installer: "npm" };
+  } catch (error) {
+    if (isCommandMissingError(error)) {
+      console.error("未检测到 npm，请先安装 Node.js/npm。");
+      return { ok: false, installer: null };
+    }
+    throw error;
+  }
+}
+
+async function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+
+  const { projectDir, port } = parsed;
+  const targetDir = path.resolve(process.cwd(), projectDir);
+
+  await ensureTargetDirEmpty(targetDir);
+  await fs.mkdir(targetDir, { recursive: true });
+
+  await fs.cp(TEMPLATE_DIR, targetDir, { recursive: true });
+  await updatePackageName(targetDir, port);
+
+  const installResult = await installDependencies(targetDir);
+  if (!installResult.ok) {
+    console.error("\n依赖安装失败（不会回滚已生成的项目）。你可以稍后手动重试：");
+    console.error(`  cd ${projectDir}`);
+    console.error("  pnpm install");
+    console.error("  npm install\n");
+    console.error("若你当前环境存在代理导致安装失败，可尝试清空代理环境变量后重试：");
+    console.error("  HTTP_PROXY= HTTPS_PROXY= pnpm install");
+    console.error("  HTTP_PROXY= HTTPS_PROXY= npm install\n");
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`\n✅ 项目已创建：${targetDir}`);
+  if (port !== undefined) {
+    console.log(`已设置默认端口：${port}（写入 dev/start 启动命令）`);
+  }
+  console.log("\n下一步：");
+  console.log(`  cd ${projectDir}`);
+  if (installResult.installer === "npm") {
+    console.log("  npm run dev\n");
+  } else {
+    console.log("  pnpm dev\n");
+  }
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`\n错误：${message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "create-next-imagicma",
+  "version": "0.0.1",
+  "type": "module",
+  "bin": {
+    "create-next-imagicma": "./bin/create-next-imagicma.mjs"
+  },
+  "files": [
+    "bin/**",
+    "template/**",
+    "README.md"
+  ],
+  "scripts": {
+    "sync-template": "node ./scripts/sync-template.mjs"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  }
+}

package/template/.env.example

@@ -0,0 +1,10 @@
+# 复制为 .env.local 并填入真实值（.env.local 不会被提交）
+#
+# Postgres 连接串（Drizzle + pg 使用）
+# 示例：
+# DATABASE_URL="postgres://user:pass@localhost:5432/mydb"
+DATABASE_URL=""
+
+# 可选：运行端口（某些平台/容器会要求读取 PORT，例如 Replit 默认 5000）
+# PORT=5000
+

package/template/AGENTS.md

@@ -0,0 +1,146 @@
+# 项目 Agent 指南（Next.js + Tailwind v4 + shadcn/ui + React Query + Drizzle）
+
+本文档用于指导（人类或 AI）在本仓库中进行一致、可维护的开发与迁移工作。**默认使用中文沟通与输出**（除非用户明确要求其他语言）。
+
+## 1) 技术栈与约束
+
+- **框架**：Next.js（App Router，目录为 `app/`）
+- **语言**：TypeScript（`strict: true`，`noEmit: true`）
+- **UI**：Tailwind CSS v4 + shadcn/ui（Radix UI 组件为基础）
+- **主题**：`next-themes`，采用 `darkMode: ["class"]`
+- **请求层**：`@tanstack/react-query` + `fetch` 封装
+- **契约**：`zod`（对 API 返回做 schema 校验）
+- **数据库**：Postgres + Drizzle ORM（`pg` + `drizzle-orm` + `drizzle-kit`）
+
+### 运行环境提示（重要）
+- `DATABASE_URL` 必须通过环境变量提供（建议放在 `.env.local`，不要提交到 Git）。
+- `server/*` 代码属于 **Node.js runtime**（依赖 `pg`），Next route handlers 需要 `export const runtime = "nodejs"`。
+
+## 2) 目录结构约定
+
+- `app/`
+  - Next.js 路由与页面（Server Component 默认）
+  - `app/providers.tsx`：全局 Provider（Theme + React Query + Tooltip + Toaster）
+  - `app/api/*`：Route Handlers（替代传统 Express）
+- `components/ui/`
+  - 从模板迁移的 shadcn/ui 组件（**统一为 Client Components**）
+  - 规则：文件顶部保持 `"use client";`，避免 RSC 边界问题
+- `hooks/`
+  - 可复用 hooks（例如 toast、mobile、请求 hook）
+  - 规则：一般也视为客户端使用，文件顶部带 `"use client";`
+- `lib/`
+  - 工具与客户端通用封装（例如 `lib/utils.ts` 的 `cn()`、`lib/queryClient.ts`）
+- `shared/`
+  - 共享契约与 schema（例如 `shared/routes.ts`、`shared/schema.ts`）
+  - 这些文件应当 **不依赖 Next/React**，以便在 client/server 两端共同使用
+- `server/`
+  - 服务端基础设施（例如 `server/db.ts`、`server/storage.ts`）
+  - 必须 `import "server-only";`，避免被客户端错误引用
+- `types/`
+  - 本地类型补丁（当网络/依赖限制导致无法安装 `@types/*` 时使用）
+
+## 3) 常用命令（pnpm）
+
+本项目**仅允许使用 pnpm** 安装依赖（见 `package.json` 的 `packageManager` / `engines` / `preinstall`）。
+
+以仓库根目录为工作目录：
+
+- 开发：`pnpm dev`
+- 构建：`pnpm build`（当前脚本使用 `next build --webpack`，避免 Turbopack 在部分受限环境下失败）
+- Lint：`pnpm lint`
+- 类型检查：`pnpm check`
+- DB 同步：`pnpm db:push`
+
+> 若安装依赖出现网络/代理问题，可临时在命令前清空代理环境变量：
+> `HTTP_PROXY= HTTPS_PROXY= pnpm install`
+
+## 4) 环境变量与数据库
+
+### 必需环境变量
+- `DATABASE_URL`：Postgres 连接串（例：`postgres://user:pass@host:5432/dbname`）
+
+### Drizzle
+- 配置：`drizzle.config.ts`
+- Schema：`shared/schema.ts`
+- 迁移输出目录（默认）：`migrations/`
+
+**开发流程建议**
+1. 配置 `.env.local` 的 `DATABASE_URL`
+2. 执行 `pnpm db:push` 初始化/同步表结构
+3. 启动 `pnpm dev`
+
+## 5) UI / Tailwind / 主题
+
+### Tailwind v4
+- 全局样式：`app/globals.css`（包含 shadcn 常用 CSS 变量）
+- Tailwind 配置：`tailwind.config.mjs`（通过 `app/globals.css` 顶部的 `@config` 指令加载）
+
+### 主题（dark mode）
+- 通过 `next-themes` 在 `<html class="dark">` 上切换
+- `app/layout.tsx` 中应包含 `suppressHydrationWarning` 以减少 hydration 警告
+
+### shadcn/ui 迁移注意事项
+- `components/ui/*` 大量依赖 Tailwind 主题 token（如 `bg-background`、`text-foreground` 等）
+- 这些 token 由 `tailwind.config.mjs` 的颜色映射 + `app/globals.css` 的 CSS 变量共同提供
+- 若新增组件：优先保持与现有 `components/ui` 同风格（使用 `cn()`、Radix、`cva()`）
+
+## 6) 请求层（React Query）
+
+- QueryClient 构建：`lib/queryClient.ts` 导出 `makeQueryClient()`
+- 全局挂载：`app/providers.tsx` 使用 `useState(() => makeQueryClient())`，避免跨请求共享单例
+- 推荐模式：
+  - 将 API 路径与响应 schema 放在 `shared/routes.ts`
+  - 客户端 hook（例如 `hooks/use-greeting.ts`）中调用 `fetch` 并用 Zod parse 校验返回
+
+## 7) API 设计与契约（shared/routes）
+
+- `shared/routes.ts` 是“唯一真相”（path/method/response schema）
+- Route Handler（`app/api/**/route.ts`）建议：
+  1. 调用 server 层（`server/*`）获取数据
+  2. `api.xxx.responses[200].parse(body)` 校验输出
+  3. `NextResponse.json(body)`
+
+## 8) 代码质量与规则
+
+- TypeScript：保持 `strict`，不使用 `any`（如因外部依赖类型缺失，优先在 `types/` 提供最小可用声明）
+- React：遵守 “components/hooks must be pure” 的 lint 规则（避免在 render 中调用 `Math.random()`、`Date.now()` 等）
+- Server-only：凡是 DB/私密逻辑一律放 `server/`，并显式 `import "server-only"`
+- 不提交敏感信息：不要提交 `.env.local`、密钥、数据库连接串
+
+## 9) Git/分支约定（可选）
+
+- 若需要新建分支，建议使用前缀：`codex/xxx`
+
+## 10) 给 AI/自动化的“无交互启动”清单
+
+当启动者不是开发者（例如 AI Agent、CI Runner、平台工作流）时，推荐按以下顺序执行：
+
+1) 安装依赖
+   - `pnpm install`（有 `pnpm-lock.yaml` 时优先）
+2) 准备环境变量（至少要有 `DATABASE_URL`）
+   - 方式 A：平台/Runner 注入 `DATABASE_URL`
+   - 方式 B：在仓库根目录写入 `.env.local`（不要提交）
+3) 初始化数据库结构（只需首次或 schema 变更后）
+   - `pnpm db:push`
+4) 启动
+   - 开发：`pnpm dev`
+   - 生产：`pnpm build` 然后 `pnpm start`
+
+> 说明：`drizzle.config.ts` 会尝试读取 `.env.local` / `.env` 来获取 `DATABASE_URL`，避免自动化环境仅写文件但未显式 `export` 导致 CLI 取不到。
+
+## 11) 迁移验证入口
+
+- API：`GET /api/greeting`（文件：`app/api/greeting/route.ts`）
+- Demo 页面：`/hello`（文件：`app/hello/page.tsx`）
+
+## 12) 常见问题排障
+
+- `DATABASE_URL 未设置`
+  - 确认 `.env.local` 里有 **未注释** 的 `DATABASE_URL="..."`，或 Runner 里已注入环境变量
+- `关系 "messages" 不存在` / `table does not exist`
+  - 先执行 `pnpm db:push`
+- UI 样式不生效 / 主题色不对
+  - 确认 `app/globals.css` 顶部包含 `@config "../tailwind.config.mjs";`
+  - 确认 `tailwind.config.mjs` 的 `content` 覆盖到了 `components/ui` 等目录
+- 构建报 Turbopack/受限环境问题
+  - 当前 `pnpm build` 已固定使用 `next build --webpack`（见 `package.json`）

package/template/README.md

@@ -0,0 +1,36 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.