create-next-imagicma 0.1.6 → 0.1.9

package/README.md

@@ -25,12 +25,15 @@ node ./create-next-imagicma/bin/create-next-imagicma.mjs demo-next --template ne
 ## 参数
 
 - `--template <hono|next>`：选择模板。默认 `hono`。
-- `--port <number>`：设置新项目默认端口。
-  - `next` 模板：写入 `next dev/start -p <port>`
-  - `hono` 模板：写入 `/.imagicma/port.json`，并同步 `process-compose.yaml` 的 `PORT`
+- `--port <number>`：写入项目运行时端口文件 `.imagicma/runtime.env`，内容为 `PORT=<number>`。
 - `--theme <name>`：设置默认主题（`quadratic`、`nomad`、`honey`、`zen-garden`、`highlighter`）。
 - `-v, --version`：显示版本号。
 
+说明：
+
+- `.imagicma/runtime.env` 是运行时文件，不是业务配置文件。
+- 脚手架不会写入 `port.json`，模板运行时只认大写 `PORT`。
+
 ## 依赖安装策略
 
 - 优先 `pnpm install`

package/bin/create-next-imagicma.mjs

@@ -40,7 +40,7 @@ function printHelp() {
 
 参数：
   --template <name>  选择模板（可选：${TEMPLATE_CHOICES.join("、")}，默认：${DEFAULT_TEMPLATE}）
-  --port <number>    设置新项目默认端口
+  --port <number>    写入项目运行时端口文件 .imagicma/runtime.env
   --theme <name>     设置默认主题（可选：${THEME_STYLES.join(", ")}）
   -h, --help         显示帮助
   -v, --version      显示版本号
@@ -202,7 +202,7 @@ async function ensureTargetDirReady(targetDir) {
   }
 }
 
-async function updatePackageName(targetDir, port, template) {
+async function updatePackageName(targetDir, template) {
   const pkgPath = path.join(targetDir, "package.json");
   const raw = await fs.readFile(pkgPath, "utf8");
   const pkg = JSON.parse(raw);
@@ -210,14 +210,10 @@ async function updatePackageName(targetDir, port, template) {
   pkg.name = sanitizePackageName(path.basename(targetDir));
 
   if (template === "next") {
-    const devScript = port === undefined ? "next dev" : `next dev -p ${port}`;
-    const startScript =
-      port === undefined ? "next start" : `next start -p ${port}`;
-
     pkg.scripts = {
       ...(pkg.scripts ?? {}),
-      dev: devScript,
-      start: startScript,
+      dev: "next dev",
+      start: "next start",
     };
   } else {
     pkg.scripts = {
@@ -228,57 +224,6 @@ async function updatePackageName(targetDir, port, template) {
 
   await fs.writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
 }
-
-async function updateProcessComposePort(targetDir, port) {
-  if (port === undefined) return;
-
-  const filePath = path.join(targetDir, "process-compose.yaml");
-
-  let raw;
-  try {
-    raw = await fs.readFile(filePath, "utf8");
-  } catch (error) {
-    if (error && typeof error === "object" && error.code === "ENOENT") {
-      return;
-    }
-    throw error;
-  }
-
-  const next = raw.replace(
-    /^(\s*-\s*["']?PORT=)\d+(["']?\s*)$/m,
-    `$1${port}$2`,
-  );
-  await fs.writeFile(filePath, next);
-}
-
-async function updateLockedPortFile(targetDir, port) {
-  if (port === undefined) return;
-
-  const filePath = path.join(targetDir, ".imagicma", "port.json");
-
-  let current = {};
-  try {
-    const raw = await fs.readFile(filePath, "utf8");
-    const parsed = JSON.parse(raw);
-    if (parsed && typeof parsed === "object") {
-      current = parsed;
-    }
-  } catch (error) {
-    if (!(error && typeof error === "object" && error.code === "ENOENT")) {
-      throw error;
-    }
-  }
-
-  const next = {
-    ...current,
-    port,
-    locked: true,
-    version: 1,
-  };
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
-  await fs.writeFile(filePath, `${JSON.stringify(next, null, 2)}\n`);
-}
-
 async function updateDefaultTheme(targetDir, theme) {
   if (theme === undefined) return;
 
@@ -296,6 +241,18 @@ async function updateDefaultTheme(targetDir, theme) {
   await fs.writeFile(filePath, next);
 }
 
+async function writeRuntimeEnv(targetDir, port) {
+  const runtimeEnvPath = path.join(targetDir, ".imagicma", "runtime.env");
+
+  if (port === undefined) {
+    await fs.rm(runtimeEnvPath, { force: true });
+    return;
+  }
+
+  await fs.mkdir(path.dirname(runtimeEnvPath), { recursive: true });
+  await fs.writeFile(runtimeEnvPath, `PORT=${port}\n`);
+}
+
 function runCommand(command, args, options) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, args, { stdio: "inherit", ...options });
@@ -417,12 +374,9 @@ async function main() {
     // ignore
   }
 
-  await updatePackageName(targetDir, port, template);
-  await updateProcessComposePort(targetDir, port);
-  if (template === "hono") {
-    await updateLockedPortFile(targetDir, port);
-  }
+  await updatePackageName(targetDir, template);
   await updateDefaultTheme(targetDir, theme);
+  await writeRuntimeEnv(targetDir, port);
 
   await initGit(targetDir);
 
@@ -442,7 +396,7 @@ async function main() {
   console.log(`\n✅ 项目已创建：${targetDir}`);
   console.log(`模板类型：${template}`);
   if (port !== undefined) {
-    console.log(`已设置默认端口：${port}`);
+    console.log(`已写入运行时端口文件：.imagicma/runtime.env (PORT=${port})`);
   }
   if (theme !== undefined) {
     console.log(`已设置默认主题：${theme}`);

package/package.json

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

package/template-hono/AGENTS.md

@@ -49,6 +49,13 @@
 - `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` 中固化端口真相源。
 
 ## 状态文件写入规则
 
@@ -59,7 +66,8 @@
 ## UI 质量门禁（必须全部满足）
 
 - `/` 路由必须可访问并落到首页组件。
-- 接入真实业务时，应将 `/` 首页替换为业务内容，不要长期保留模板默认文案。
+- `client/src/pages/home.tsx` 不允许为空文件、空组件，或仅返回 `null` / 空白占位；首页必须渲染可见内容。
+- 接入真实业务时，应将 `/` 首页替换为真实业务内容，不要长期保留模板默认文案或空白首页。
 - 视觉风格必须明确：字体、颜色、间距、动效要统一。
 - 必须定义可复用设计 token（颜色、圆角、阴影、间距等级）。
 - 至少覆盖桌面与移动端关键断点，不允许内容溢出。

package/template-hono/README.md

@@ -26,7 +26,18 @@ pnpm install
 pnpm dev
 ```
 
-默认端口由 `/.imagicma/port.json`。
+启动时按以下顺序解析端口：
+
+1. 显式环境变量 `PORT`
+2. 项目内 `.imagicma/runtime.env`
+
+如果两者都不存在，启动会直接失败。
+项目内唯一允许的端口文件是 `.imagicma/runtime.env`，内容示例：
+
+```bash
+PORT=6424
+```
+
 请勿直接执行 `vite` 启动，必须使用 `pnpm dev`。
 
 ## 构建与运行
@@ -40,7 +51,7 @@ pnpm start
   - 前端：`dist/client`
   - 后端：`dist/server`
 - `start`：由受保护脚本启动服务（禁止直接 `node dist/server/index.js`），并由 Hono 承载 API + 静态资源 + SPA fallback。
-- 生产端口同样由 `/.imagicma/port.json` 锁定，不接受 `PORT` 覆盖。
+- 生产启动同样按 `PORT -> .imagicma/runtime.env` 的顺序解析端口。
 
 ## 数据库
 
@@ -53,6 +64,11 @@ pnpm db:push
 - 默认数据库文件：`./.data/app.db`
 - 如需自定义位置，可复制 `.env.example` 为 `.env.local` 后设置 `DATABASE_FILE`
 
+## 运行时文件
+
+- `.imagicma/runtime.env`：项目运行端口契约，只使用大写 `PORT`
+- `/.imagicma/port.json`：已废弃，不再使用
+
 ## 验证路径
 
 - API：`GET /api/greeting`

package/template-hono/client/src/components/ui/button.tsx

@@ -7,14 +7,14 @@ import { cva, type VariantProps } from "class-variance-authority"
 import { cn } from "@/lib/utils"
 
 const buttonVariants = cva(
-  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-xl text-sm font-semibold tracking-[0.01em] transition-all duration-200 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40 focus-visible:ring-offset-1 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-xl text-sm font-semibold tracking-[0.01em] transition-all duration-200 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40 focus-visible:ring-offset-1 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 hover-elevate active-elevate-2",
   {
     variants: {
       variant: {
         default:
-          "bg-primary text-primary-foreground border border-primary/45 shadow-[0_10px_24px_hsl(var(--primary)/0.38)] hover:-translate-y-0.5 hover:shadow-[0_14px_30px_hsl(var(--primary)/0.46)] active:translate-y-0",
+          "bg-primary text-primary-foreground border border-primary/45",
         destructive:
-          "bg-destructive text-destructive-foreground border border-destructive/45 shadow-[0_10px_22px_hsl(var(--destructive)/0.3)] hover:brightness-105",
+          "bg-destructive text-destructive-foreground border border-destructive/45 hover:brightness-105",
         outline:
           "border border-input/80 bg-white/75 text-foreground shadow-[0_4px_12px_rgba(15,23,42,0.08)] hover:bg-white hover:border-ring/35",
         secondary: "border border-secondary-border bg-secondary/90 text-secondary-foreground shadow-sm hover:bg-secondary",

package/template-hono/client/src/components/ui/checkbox.tsx

@@ -13,7 +13,7 @@ const Checkbox = React.forwardRef<
   <CheckboxPrimitive.Root
     ref={ref}
     className={cn(
-      "peer h-5 w-5 shrink-0 rounded-full border-2 border-primary/45 bg-white shadow-[0_1px_3px_rgba(15,23,42,0.18)] ring-offset-background transition-[background-color,border-color,box-shadow] duration-200 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/35 focus-visible:ring-offset-1 disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground data-[state=checked]:shadow-[0_8px_16px_hsl(var(--primary)/0.35)]",
+      "peer h-5 w-5 shrink-0 rounded-full border-2 border-primary/45 bg-white shadow-[0_1px_3px_rgba(15,23,42,0.18)] ring-offset-background transition-[background-color,border-color,box-shadow] duration-200 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/35 focus-visible:ring-offset-1 disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:border-primary data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground data-[state=checked]:shadow-[0_8px_16px_rgba(15,23,42,0.18)]",
       className
     )}
     {...props}

package/template-hono/client/src/lib/imagicma-preview-bridge.ts

@@ -0,0 +1,55 @@
+const PROD_PARENT_ORIGINS = new Set(["https://agentma.cn", "https://imagicma.cn"]);
+const LOCAL_PARENT_RE = /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/i;
+const LOCAL_IMAGICMA_PARENT_RE = /^https?:\/\/([a-z0-9-]+\.)?local\.(agentma\.cn|imagicma\.cn)(:\d+)?$/i;
+
+type PreviewBridgeState = {
+  parentOrigin: string | null;
+};
+
+declare global {
+  interface Window {
+    __IMAGICMA_PREVIEW_BRIDGE__?: PreviewBridgeState;
+  }
+}
+
+function getBridgeState(): PreviewBridgeState {
+  if (typeof window === "undefined") {
+    return { parentOrigin: null };
+  }
+  if (!window.__IMAGICMA_PREVIEW_BRIDGE__) {
+    window.__IMAGICMA_PREVIEW_BRIDGE__ = {
+      parentOrigin: null,
+    };
+  }
+  return window.__IMAGICMA_PREVIEW_BRIDGE__;
+}
+
+export function isAllowedPreviewParentOrigin(origin: string): boolean {
+  if (!origin) return false;
+  return PROD_PARENT_ORIGINS.has(origin) || LOCAL_PARENT_RE.test(origin) || LOCAL_IMAGICMA_PARENT_RE.test(origin);
+}
+
+export function bindPreviewParentOrigin(origin: string | null): string | null {
+  const state = getBridgeState();
+  if (!origin) {
+    state.parentOrigin = null;
+    return state.parentOrigin;
+  }
+  if (!isAllowedPreviewParentOrigin(origin)) {
+    return state.parentOrigin;
+  }
+  state.parentOrigin = origin;
+  return state.parentOrigin;
+}
+
+export function getBoundPreviewParentOrigin(): string | null {
+  return getBridgeState().parentOrigin;
+}
+
+export function postToBoundPreviewParent(message: unknown): boolean {
+  if (typeof window === "undefined" || window.parent === window) return false;
+  const parentOrigin = getBoundPreviewParentOrigin();
+  if (!parentOrigin) return false;
+  window.parent.postMessage(message, parentOrigin);
+  return true;
+}