mvframe 1.0.80 → 1.0.82

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mvframe",
   "packageManager": "yarn@4.4.1",
-  "version": "1.0.80",
+  "version": "1.0.82",
   "author": "matt avis",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/scripts/install-codex-agents.js

@@ -18,67 +18,73 @@ const path = require("path");
 
 const BEGIN = "<!-- MVFRAME-CODEX-RULES:BEGIN -->";
 const END = "<!-- MVFRAME-CODEX-RULES:END -->";
+const STYLE_RULES_FILE = path.join(__dirname, "..", ".cursor", "rules", "style-system.mdc");
 
-function renderCodexAgentsSection() {
-  return `${BEGIN}
-# MVFrame Codex Rules
-
-This project uses MVFrame. When editing Vue, JS, TS, SCSS, or CSS in this host app, prefer the framework globals before adding local implementations.
+function stripFrontmatter(markdown) {
+  if (!markdown.startsWith("---")) {
+    return markdown;
+  }
+  const end = markdown.indexOf("\n---", 3);
+  if (end < 0) {
+    return markdown;
+  }
+  return markdown.slice(end + 4).replace(/^\s*\n/, "");
+}
 
-## Global Components
+function shiftMarkdownHeadings(markdown, level = 1) {
+  return markdown.replace(/^(#{1,6})\s+/gm, (_all, hashes) => {
+    const nextLevel = Math.min(6, hashes.length + level);
+    return `${"#".repeat(nextLevel)} `;
+  });
+}
 
-- Prefer MVFrame global components in templates without local imports: \`Frame\`, \`Page\`, \`Table\`, \`Form\`, \`Input\`, \`Textarea\`, \`Select\`, \`SelectV2\`, \`Tabs\`, \`BtnGroup\`, \`Icon\`, \`Loading\`, \`Drawer\`, \`DrawerArea\`, \`Login\`, \`Lang\`.
-- Do not rebuild an equivalent control with raw DOM, \`el-*\` combinations, or third-party components unless the MVFrame component cannot express the behavior.
-- For segmented controls, single-choice button groups, login forms, page shells, tables, drawers, loading masks, and framework navigation, check the MVFrame component first.
+function getSharedStyleRulesForCodex() {
+  const raw = fs.readFileSync(STYLE_RULES_FILE, "utf8");
+  const withoutFrontmatter = stripFrontmatter(raw).trim();
+  const withoutRootTitle = withoutFrontmatter.replace(/^#\s+mvframe\s+样式系统\s*\n*/i, "");
+  return shiftMarkdownHeadings(withoutRootTitle, 1).trim();
+}
 
-## Global Style Utilities
+function renderCodexAgentsSection() {
+  return `${BEGIN}
+# MVFrame Codex 规则
 
-- Before writing scoped CSS, inline \`:style\`, or new SCSS utility code, check whether MVFrame global classes already cover it.
-- MVFrame styles must be imported once from the app entry: \`import "mvframe/style"\` and \`import "mvframe/style/cpt"\`. If utility classes appear missing, fix the import before duplicating CSS.
-- Prefer utility classes in templates for common layout, spacing, sizing, typography, color, border, scroll, hover, radius, and positioning work.
+本项目使用 MVFrame。在该宿主项目中编辑 Vue、JS、TS、SCSS 或 CSS 时，新增本地实现前，优先检查并复用框架已有的全局能力。
 
-Common utility classes:
+## 全局组件
 
-| Need | Prefer |
-|------|--------|
-| flex layout | \`flexMode\`, \`flexV\`, \`flex1\`, \`flexGrow\`, \`noShrink\`, \`minw0\`, \`minh0\` |
-| flex alignment | \`hl\`, \`hc\`, \`hr\`, \`hb\`, \`ha\`, \`vl\`, \`vc\`, \`vr\`, \`vs\` |
-| wrapping / gaps | \`flexWrap\`, \`grid\`, \`g2\` ... \`g40\` |
-| spacing | \`p{N}\`, \`pt{N}\`, \`pr{N}\`, \`pb{N}\`, \`pl{N}\`, \`m{N}\`, \`mt{N}\`, \`mr{N}\`, \`mb{N}\`, \`ml{N}\` where N is one of \`0,2,4,6,8,10,12,16,20,24,30,32,36,40,48\` |
-| sizing | \`w{N}\`, \`h{N}\`, \`minw{N}\`, \`maxw{N}\`, \`minh{N}\`, \`maxh{N}\`, \`wp25\`, \`wp50\`, \`wp75\`, \`wp100\`, \`hp100\`, \`vh100\` |
-| text | \`fs{N}\`, \`lh{N}\`, \`fw300\`, \`fw500\`, \`fw700\`, \`txt-c\`, \`txt-r\`, \`txt-nowrap\`, \`txt-nowrap{N}\`, \`txt-wrap\`, \`txt-prewrap\` |
-| color / background | \`txt-h1\`, \`txt-h2\`, \`txt-p\`, \`txt-tip\`, \`txt-gray\`, \`txt-primary\`, \`bg-primary\`, \`bg-page-header\`, \`border\`, \`border-t\`, \`border-b\`, \`border-none\` |
-| positioning / effects | \`relative\`, \`abs\`, \`absFull\`, \`absCenter\`, \`sticky\`, \`z1\`, \`z2\`, \`z9\`, \`radius{N}\`, \`radiusP50\`, \`hover\`, \`trans-all\`, \`backdrop\` |
-| interaction / scroll | \`point\`, \`grab\`, \`yscroll\`, \`xscroll\`, \`nobar\`, \`noscroll\`, \`noselect\`, \`noevent\`, \`hide\` |
+- 模板内优先直接使用 MVFrame 全局组件，不要重复本地 import：\`Frame\`、\`Page\`、\`Table\`、\`Form\`、\`Input\`、\`Textarea\`、\`Select\`、\`SelectV2\`、\`Tabs\`、\`BtnGroup\`、\`Icon\`、\`Loading\`、\`Drawer\`、\`DrawerArea\`、\`Login\`、\`Lang\`。
+- 除非 MVFrame 组件确实无法表达该交互，否则不要用原生 DOM、\`el-*\` 组合或第三方组件去重造等价控件。
+- 遇到分段切换、单选按钮组、登录表单、页面外壳、表格、抽屉、加载遮罩、框架导航等场景，先检查 MVFrame 组件是否已经覆盖。
 
-Spacing rule: do not add odd-pixel \`margin\` or \`padding\` such as \`3px\`, \`5px\`, \`7px\`, \`9px\`, or \`11px\`. Use the MVFrame spacing classes or rem values aligned with the spacing scale.
+## 全局样式工具类
 
-Scoped styles are still allowed for component-specific behavior, complex selectors, custom brand visuals, third-party overrides, or values not covered by the utility system. Keep those scoped rules narrow and combine them with MVFrame classes.
+${getSharedStyleRulesForCodex()}
 
-## Global Methods
+## 全局方法
 
-- Prefer MVFrame globals instead of repeated imports or local helpers: \`globalThis.$d\`, \`$fa\`, \`$fu\`, \`$pm\`, \`$db\`, \`$copy\`, \`$deepClone\`, \`$getLang\`, \`$getImg\`, \`$sc\`, \`$c.info\`.
-- In templates, call global methods directly when they are provided through Vue globalProperties.
-- For ordinary JS modules, use \`globalThis.$xxx\` or the exported MVFrame subpath only when a direct import is explicitly needed.
+- 优先使用 MVFrame 全局方法，不要重复 import 或本地封装等价 helper：\`globalThis.$d\`、\`$fa\`、\`$fu\`、\`$pm\`、\`$db\`、\`$copy\`、\`$deepClone\`、\`$getLang\`、\`$getImg\`、\`$sc\`、\`$c.info\`。
+- 在模板里，如果这些方法已经通过 Vue globalProperties 注入，直接调用即可。
+- 对普通 JS 模块，优先使用 \`globalThis.$xxx\`；只有确实需要显式 import 时，再使用 MVFrame 的子路径导出。
 
-## Router, Store, And Maps
+## 路由、Store 与 Maps
 
-- Prefer route \`name\` navigation over raw \`path\` navigation.
-- Use the MVFrame store factory pattern already wired by the app: \`inject("store")\` in components or \`import { store, pinia } from "mvframe/store"\` in setup code and guards.
-- For MVFrame maps/i18n maps, prefer \`useMap\`, \`getMaps\`, \`patchMaps\`, \`mapLang\`, and \`mapLangPath\` from \`mvframe/maps\`.
+- 路由跳转优先使用 route \`name\`，不要优先写死 \`path\`。
+- 使用项目已经接好的 MVFrame store factory 模式：组件内用 \`inject("store")\`，setup 代码或守卫里用 \`import { store, pinia } from "mvframe/store"\`。
+- 涉及 MVFrame maps / i18n maps 时，优先使用 \`useMap\`、\`getMaps\`、\`patchMaps\`、\`mapLang\`、\`mapLangPath\`，来源为 \`mvframe/maps\`。
 
-## Editing Checklist
+## 编辑检查清单
 
-- Before adding markup, check whether a MVFrame global component fits.
-- Before adding CSS, check whether MVFrame utility classes fit.
-- Before importing a helper library, check whether a MVFrame global helper already exists.
-- If local CSS or a new helper is still needed, keep it small and specific to the component.
+- 新增结构前，先判断是否已有合适的 MVFrame 全局组件。
+- 新增 CSS 前，先判断是否已有合适的 MVFrame 工具类。
+- 引入新的 helper 库前，先判断 MVFrame 是否已经提供等价全局方法。
+- 如果最终仍需新增本地 CSS 或 helper，保持小而专，限定在当前组件范围内。
 
-## Completion Notify
+## 完成后通知
 
-- After every completed development task, send one concise completion notification from the host project root with \`yarn exec mvframe-notify --once --message "<project or module>: <what changed and current result>"\`.
-- Keep the notify message short and delivery-focused. Include the affected module or page, the main completed work, and the current verification result when available.
-- If \`.env.mvframe-notify\` is missing, DingTalk notify is not configured, or the notify command fails, do not fake success. Report that notify could not be sent in the final response.
+- 每次完成一个开发任务后，都要在宿主项目根目录发送一条简洁的完成通知：\`yarn exec mvframe-notify --once --message "<项目或模块>: <本次改动与当前结果>"\`。
+- notify 文案保持简短、可投递、可扫读；包含受影响模块或页面、本次完成的主要工作，以及当前验证结果（如果已有）。
+- 如果缺少 \`.env.mvframe-notify\`、钉钉 notify 未配置，或命令执行失败，不要伪造成功；需要在最终回复里明确说明通知未发送成功。
 ${END}
 `;
 }

package/scripts/scaffold-app.js

@@ -3,12 +3,14 @@
  * 在目标工程生成 MVFrame 推荐目录与雏形文件（views / component / api / pinia / router / config / assets）。
  *
  * 用法：
- *   node path/to/mvframe/scripts/scaffold-app.js [项目根] [--force]
+ *   node path/to/mvframe/scripts/scaffold-app.js [项目根] [--force|-f]
  *   yarn exec mvframe-init-app
  *
  * 环境变量：MVFRAME_SCAFFOLD_TARGET=/path/to/project
  *
- * 选项：--no-package-json  不读不写 package.json（仅生成源码与 Vite 配置）
+ * 选项：
+ *   --force, -f            覆盖已存在的脚手架文件
+ *   --no-package-json, -n  不读不写 package.json（仅生成源码与 Vite 配置）
  */
 
 const fs = require("fs");
@@ -16,10 +18,10 @@ const path = require("path");
 const { execFileSync } = require("child_process");
 const { upsertCodexAgents } = require("./install-codex-agents.js");
 
-const FORCE = process.argv.includes("--force");
-const NO_PKG = process.argv.includes("--no-package-json");
+const FORCE = process.argv.includes("--force") || process.argv.includes("-f");
+const NO_PKG = process.argv.includes("--no-package-json") || process.argv.includes("-n");
 const argPath = process.argv.find(
-  (a, i) => i >= 2 && a !== "--force" && !a.startsWith("--"),
+  (a, i) => i >= 2 && !a.startsWith("-"),
 );
 const target = path.resolve(
   process.env.MVFRAME_SCAFFOLD_TARGET || argPath || process.cwd(),
@@ -831,7 +833,7 @@ yarn dev
 yarn exec mvframe-d
 \`\`\`
 
-若需跳过对 \`package.json\` 的修改：\`node scripts/scaffold-app.js --no-package-json\`。
+若需跳过对 \`package.json\` 的修改：\`node scripts/scaffold-app.js --no-package-json\` 或 \`node scripts/scaffold-app.js -n\`。
 
 自动生成的 \`vite.config.js\` 已包含 \`unplugin-auto-import\`；\`dts: true\` 时类型默认写在项目根 \`auto-imports.d.ts\`。
 
@@ -934,7 +936,7 @@ yarn exec mvframe-install-codex-rules
 
 ## Cursor 规则（\`.cursor/rules\`）
 
-初始化脚本会把 **mvframe 包内**与仓库一致的 **\`*.mdc\`** 写入目标项目 **\`/.cursor/rules/\`**（\`component-hierarchy\`、\`script-setup\`、\`style-system\`、\`views\`、\`router\`、\`global-components\`、\`data\`、\`util\`）。若目录或文件已存在且未加 \`--force\`，则跳过对应文件。
+初始化脚本会把 **mvframe 包内**与仓库一致的 **\`*.mdc\`** 写入目标项目 **\`/.cursor/rules/\`**（\`component-hierarchy\`、\`script-setup\`、\`style-system\`、\`views\`、\`router\`、\`global-components\`、\`data\`、\`util\`）。若目录或文件已存在且未加 \`--force\` / \`-f\`，则跳过对应文件。
 
 npm 包需在 \`files\` 中包含 \`.cursor/rules\`；使用本地 \`file:\` / 源码链接时同样可用。