create-next-imagicma 0.1.10 → 0.1.12

package/README.md

@@ -4,7 +4,6 @@
 
 ## 模版源
 
-- `../nextjs-app`
 - `../hono-app`
 如果要修改模版，请修改源头，然后执行 `pnpm run sync-template` 同步到当前模版目录，切记不可直接修改当前模版目录。
 ## 使用
@@ -50,7 +49,6 @@ pnpm run sync-template
 
 默认同步：
 
-- `../nextjs-app` -> `template/`
 - `../hono-app` -> `template-hono/`
 
 可通过环境变量覆盖：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-next-imagicma",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "type": "module",
   "bin": {
     "create-next-imagicma": "./bin/create-next-imagicma.mjs"

package/template-hono/AGENTS.md

@@ -1,95 +1,53 @@
-# 项目 Agent 指南（Hono + Vite + React + Drizzle）
-
-默认使用中文沟通与输出（除非用户明确要求其他语言）。
-
-## 目标
-
-你需要一次性交付可运行、可预览、可验证、可演示的完整应用，而不是半成品。
-
-## 技术栈与约束
-
-- 框架：Hono（Node runtime）+ Vite（单进程开发）
-- 前端：React 19 + React Router + Tailwind v4 + shadcn/ui
-- 请求层：React Query + fetch
-- 契约：Zod（`shared/routes.ts`）
-- 数据库：SQLite + Drizzle（默认 `./.data/app.db`，无需 `DATABASE_URL`；可用 `DATABASE_FILE` 覆盖）
-
-## 目录约定
-
-- `client/index.html`：Vite 前端入口 HTML
-- `client/public/`：前端静态资源
-- `client/src/`：前端应用入口、页面、Provider、错误边界
-- `client/src/components/ui/`：shadcn/ui 组件
-- `client/src/hooks/`：客户端 hooks
-- `client/src/lib/`：通用工具
-- `server/`：Hono 入口、路由、存储、DB
-- `shared/`：前后端共享 schema/契约
-
-## 常用命令
-
-- `pnpm dev`：单进程开发（Vite + Hono dev middleware）
-- `pnpm build`：构建前端并编译 server
-- `pnpm start`：生产启动
-- `pnpm check`：类型检查
-- `pnpm lint`：ESLint
-- `pnpm db:push`：同步数据库结构
-
-## 执行硬规则
-
-- 不阻塞就不要问用户，直接推进到完成。
-- 不要要求用户发送“继续执行/不要停在总结”之类控制语句，把持续推进作为默认行为。
-- 进度反馈用自然里程碑播报，不使用突兀命令式话术。
-- 仅在真实阻塞时才提问，并附已尝试步骤与日志证据。
-- 未达到完成标准前，不得用“文档总结/状态总结”代替执行。
-- 不得只做前端占位，必须打通真实 API 与数据读写链路。
-- 每次代码改动后必须重启服务并验证页面/接口。
-- 关键改动后必须跑端到端验证（如 `run_test`）并检查日志。
-- 禁止递归调用测试代理或无限循环调用同一工具。
-- 如果 `run_test` 结果不是 `[run_test] ok`，必须视为未通过，继续修复。
-- `run_test` 卡住或无进展时要快速失败并给出证据，禁止长时间空转重试。
-- 不允许“口头完成”。完成声明必须有工具证据支撑。
-- SQLite 路径必须保持单一 schema 真相源，禁止手写临时 SQL 与 ORM schema 并行漂移。
-- 禁止修改 `scripts/` 下的受保护启动文件：`imagicma-common.mjs`、`imagicma-guard.mjs`、`imagicma-dev.mjs`、`imagicma-start.mjs`、`imagicma-runtime-logs.mjs`。
-- 禁止修改 `package.json` 中 `scripts.dev` 与 `scripts.start`（以及对应 `predev`、`prestart`）命令。
-- 禁止直接执行 `vite` 或 `node dist/server/index.js` 或 `pnpm dev` 或 `pnpm start` 启动项目；只能通过 `restart_workflow` 启动。
-- 禁止主动注入环境变量到 `process.env`。
-- 端口契约只允许使用大写 `PORT`。
-- 运行时端口读取顺序固定为：外部环境变量 `PORT` -> 项目内 `.imagicma/runtime.env`。
-- 禁止写入 `/.imagicma/port.json`，禁止在 `process-compose.yaml` 中固化端口真相源。
-
-## 状态文件写入规则
-
-- 若维护 `docs/project_state.json`，每次写入前先读取最新版本。
-- 若写入报冲突（文件已变更），必须重新读取后重试，不得忽略。
-- `quality_gates.typecheck=true` 仅在构建命令真实通过后设置。
-
-## UI 质量门禁（必须全部满足）
-
-- `/` 路由必须可访问并落到首页组件。
-- `client/src/pages/home.tsx` 不允许为空文件、空组件，或仅返回 `null` / 空白占位；首页必须渲染可见内容。
-- 接入真实业务时，应将 `/` 首页替换为真实业务内容，不要长期保留模板默认文案或空白首页。
-- 视觉风格必须明确：字体、颜色、间距、动效要统一。
-- 必须定义可复用设计 token（颜色、圆角、阴影、间距等级）。
-- 至少覆盖桌面与移动端关键断点，不允许内容溢出。
-- 交互状态完整：hover/focus/disabled/loading/error/success。
-- 在 `<Button>` 上使用自定义背景色类（如 `bg-*`）时，必须同时显式声明文本色类（如 `text-*`）；禁止只改背景不改文字色。
-- 优先复用 `Input/Button/Card/Checkbox/Select` 的默认视觉语言，必要时只做局部增强，不要重写整套样式。
-- 列表增删改状态建议加入轻量动效（如 `framer-motion` 的入场/退出），并提供失败反馈（toast 或 inline alert）。
-
-## 数据与安全
-
-- 服务端数据库逻辑放在 `server/`，不要泄漏到客户端。
-- API 响应必须经过 `shared/routes.ts` 的 Zod schema 校验。
-- 不提交 `.env.local`、数据库密钥。
-- 优先复用 `client/src/components/ui` 与 `client/src/hooks`，避免重复造轮子。
-
-## 完成标准
-
-只有以下全部满足才允许结束：
-
-- `pnpm build` 通过（无 pnpm 时 `npm run build` 通过）
-- 页面可在本地端口访问并完成核心流程
-- `/` 首页路由可访问（允许临时隐藏默认模板 DOM）
-- `run_test` 返回 `[run_test] ok`
-- 关键日志无阻塞级错误
-- UI 达到可演示级（非“功能可用但观感粗糙”）
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This is a `Hono + Vite + React` app. Keep browser code in `client/src`, server entrypoints in `server/`, and shared contracts in `shared/`.
+
+- `client/src/pages/`: route-level pages such as `home.tsx`
+- `client/src/components/`: reusable UI, with shadcn/ui primitives under `components/ui/`
+- `client/src/lib/` and `client/src/hooks/`: client utilities and hooks
+- `server/routes/`: Hono route modules
+- `shared/routes.ts` and `shared/schema.ts`: Zod-backed API contracts and shared schema
+- `scripts/`: guarded dev/start scripts; do not bypass them
+- `.data/`: local SQLite data; treat as runtime state, not source
+
+The homepage must never ship blank. `client/src/pages/home.tsx` should render visible, meaningful content on first load, not hidden placeholders or empty shells.
+
+## Build, Test, and Development Commands
+
+- `restart_workflow`: required agent entrypoint for restarting dev services; do not call `pnpm dev` directly
+- `pnpm build`: builds the client with Vite and compiles the server with `tsc`
+- `pnpm start`: runs the production server through the guarded startup script
+- `pnpm check`: TypeScript type-check for both client and server configs
+- `pnpm lint`: runs ESLint across the repository
+- `pnpm db:push`: applies Drizzle schema changes to the local SQLite database
+
+## Coding Style & Naming Conventions
+
+Use TypeScript and ESM throughout. Follow the existing style: 2-space indentation, double quotes, semicolons, and trailing commas. Prefer:
+
+- PascalCase for React components, for example `HelloClient.tsx`
+- kebab-case for route/page files, for example `not-found.tsx`
+- colocated logic in `hooks/`, `lib/`, and `routes/` before creating new top-level folders
+
+Reuse the `@/` import alias for client code where it improves readability.
+
+## Testing Guidelines
+
+This template does not currently ship with a committed automated test runner or `pnpm test` script. Before opening a PR, run `pnpm check` and `pnpm lint`, then manually verify the main page and `GET /api/greeting`.
+
+If you add tests, keep them as `*.test.ts` or `*.test.tsx`, or add a `tests/` folder and document the new command in `package.json`.
+
+## Commit & Pull Request Guidelines
+
+Recent history uses Conventional Commit prefixes such as `feat:`, `fix:`, and `chore:`; keep that format and write concise subjects. PRs should include:
+
+- a short description of behavior changes
+- linked issue or task when available
+- screenshots or recordings for UI changes
+- notes for env, port, or database-impacting changes
+
+## Runtime & Configuration Notes
+
+Agents must use `restart_workflow` instead of invoking `pnpm dev` manually. Do not pass a port on the command line or by prefixing `pnpm dev` with `PORT=...`; keep runtime port configuration in `.imagicma/runtime.env`. Database defaults to `./.data/app.db`, and overrides belong in `.env.local`, not committed secrets.

package/template-hono/README.md

@@ -1,6 +1,6 @@
 # hono-app
 
-基于 **Hono + Vite + React** 的全栈模板，目标是保留原 `nextjs-app` 的前端体验，同时降低服务端运行开销。
+基于 **Hono + Vite + React** 的全栈应用。
 
 ## 技术栈
 
@@ -23,7 +23,7 @@
 
 ```bash
 pnpm install
-pnpm dev
+start_app.sh
 ```
 
 启动时按以下顺序解析端口：
@@ -38,14 +38,7 @@ pnpm dev
 PORT=6424
 ```
 
-请勿直接执行 `vite` 启动，必须使用 `pnpm dev`。
-
-## 构建与运行
-
-```bash
-pnpm build
-pnpm start
-```
+请勿直接执行 `vite` 或 `pnpm dev` 启动，必须使用 `restart_workflow`。
 
 - `build` 产出：
   - 前端：`dist/client`
@@ -67,29 +60,8 @@ pnpm db:push
 ## 运行时文件
 
 - `.imagicma/runtime.env`：项目运行端口契约，只使用大写 `PORT`
-- `/.imagicma/port.json`：已废弃，不再使用
 
 ## 验证路径
 
 - API：`GET /api/greeting`
 - 页面：`/hello`
-
-## E2E 与 `run_test`
-
-- Playwright 配置位于 [`playwright.config.ts`](/Users/alexliu/Project/imagicma-all/imagicma-template/hono-app/playwright.config.ts)
-- 测试契约位于 [`hono-app/.imagicma/testing-manifest.json`](/Users/alexliu/Project/imagicma-all/imagicma-template/hono-app/.imagicma/testing-manifest.json)
-- 本地回归命令：
-
-```bash
-pnpm test:e2e
-```
-
-- `run_test` 驱动 Playwright 时会注入：
-  - `IMAGICMA_RUN_ID`
-  - `IMAGICMA_RUN_TEST_RUNTIME_ROOT`
-  - `IMAGICMA_RUN_TEST_SKIP_WEBSERVER`
-  - `BASE_URL`
-
-fixtures 约定：
-- `tests/e2e/fixtures/imagicma.ts` 必须把浏览器 warning/error、page errors、失败网络请求与 current URL 写入 `IMAGICMA_RUN_TEST_RUNTIME_ROOT`
-- `testing-manifest.json` 负责声明稳定页面、selectors、fixtures 与 auth profile，供 `run_test` 编译阶段使用

package/template-hono/client/index.html

@@ -5,9 +5,14 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>hono-app</title>
     <script src="/imagicma-picker-bridge.js"></script>
+    <script src="/imagicma-preview-feedback.js"></script>
   </head>
   <body class="antialiased">
     <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
+    <script type="module">
+      import("/src/main.tsx").catch((error) => {
+        window.__IMAGICMA_PREVIEW_FEEDBACK__?.reportModuleBootstrapError(error);
+      });
+    </script>
   </body>
 </html>