@manohub/app-kit 0.1.0

package/dist/styles/farris-bridge.css

@@ -0,0 +1,129 @@
+/**
+ * farris 桥接层：单向令牌映射 + farris 覆盖白名单。
+ *
+ * - 品牌色注入 farris：全仓唯一一处，替代各 app 自建 --f-theme-* 覆盖块。
+ * - 覆盖白名单内的 `!important` 是全仓唯一允许出现 `!important` 的地方；
+ *   压过 farris 统一用 `.app-container .f-*` 两段式，不打 important 军备竞赛。
+ */
+
+/* 品牌色注入 farris 主题槽位（全仓唯一一处，替代各 app 自建的 --f-theme-* 覆盖块）。
+   槽位语义沿用 farris 主题变量：01/03 主色、02/04/06/07 渐变、05/08 浅主色；
+   aid-02/03/04 为浅底（表格选中行、悬停底色等）。取值一律由 --ui-primary 派生，
+   局部换主题只需在更深的容器上重设 --ui-primary。 */
+.app-container {
+  --f-theme-01: color-mix(in oklab, var(--ui-primary) 88%, black);
+  --f-theme-02: linear-gradient(135deg, var(--ui-primary), color-mix(in oklab, var(--ui-primary) 88%, black));
+  --f-theme-03: var(--ui-primary);
+  --f-theme-04: linear-gradient(135deg, color-mix(in oklab, var(--ui-primary) 85%, white), var(--ui-primary));
+  --f-theme-05: color-mix(in oklab, var(--ui-primary) 85%, white);
+  --f-theme-06: linear-gradient(135deg, color-mix(in oklab, var(--ui-primary) 85%, white), var(--ui-primary));
+  --f-theme-07: linear-gradient(214deg, var(--ui-primary), color-mix(in oklab, var(--ui-primary) 85%, white));
+  --f-theme-08: color-mix(in oklab, var(--ui-primary) 85%, white);
+  --f-aid-02: color-mix(in oklab, var(--ui-primary) 16%, white);
+  --f-aid-03: color-mix(in oklab, var(--ui-primary) 10%, white);
+  --f-aid-04: color-mix(in oklab, var(--ui-primary) 6%, white);
+
+  /* 文本控件高度（= farris `.form-control` 的规则原文 `height: calc(2px + 1.53574rem)`）：
+     rem ⇒ 高度随根字号变（门户里实测 ≈24px），所以本包任何「要与控件首行对齐」的地方
+     （AppForm 的 label 列）**必须复用它**，硬写 px 令牌（32）会当场对不齐。
+     取值与上游绑定的地方只此一处，由 app-form.spec.ts 锁住。 */
+  --ui-form-control-height: calc(2px + 1.53574rem);
+}
+
+/* ===== FNotify 位置修复 =====
+ * farris index.css 中第二个全局 .farris-notify 规则
+ * （display:flex; width:100%; left:0; top:0; ...）
+ * 覆盖了第一个规则（position:fixed; z-index:999999），导致 notify 通过 inline style
+ * 计算的 left/top/transform 定位失效。这里重置为默认值让 inline style 重新生效。
+ */
+.app-container .farris-notify {
+  width: auto;
+  display: block;
+  left: auto;
+  top: auto;
+}
+
+/* FPageHeader 自带 margin 0 .5rem，在壳层布局中由 AppShell.Header 控制间距 */
+.app-container .f-page-header {
+  margin: 0;
+  flex-shrink: 0;
+}
+
+/* farris 弹层（popover/modal teleport 到 body）不受 .app-container 作用域约束，须全局覆盖 */
+body > .popover.popover-fitcontent.bs-popover-top {
+  position: fixed !important;
+  /* 已用 position:fixed 修正包含块；下文「变量平移」是另一套互斥修法，此处显式关掉避免叠加 */
+  translate: none !important;
+}
+.popover.f-combo-list-wrapper.popover-limitmax .f-combo-list-container {
+  max-height: none !important;
+}
+
+/* FTooltip（AppTooltip）浮层在微前端下会因 farris 自身定位规则偏移，
+   原先 mcp / repository 各自在应用 style.css 里打补丁，现统一到桥接层白名单。 */
+.fv-tooltip.tooltip {
+  position: fixed !important;
+  translate: none !important;
+}
+
+/* ===== 微前端容器原点补偿（变量驱动，宿主应用写入、桥接层消费） =====
+ * 问题：farris 面板定位把 `host === "body"` 当成「包含块在文档原点 (0,0)」，这只有在
+ * 面板包含块正好是初始包含块时才成立。子应用被门户挂进带 `position: relative` 的容器时，
+ * 包含块变成那个容器 ⇒ 面板整体多平移一个「容器文档原点」（实测横竖各多 259/185）。
+ *
+ * 修法：宿主应用把容器原点偏差写进 body 上的 CSS 变量（`--ibp-popup-shift-x/y`，
+ * 见 vm 子应用的 `utils/app-host.ts`），这里只负责把变量施加到弹层上：
+ * `translate` 是独立于 `transform` 的属性，不会覆盖 farris 用来对齐箭头的行内 `transform`。
+ *
+ * 为什么放桥接层而不是应用侧：弹层 Teleport 到 body、不受 `.app-container` 作用域约束，
+ * 应用侧的 `.popover { … }` 会同时撞护栏的「选择器前缀」与「farris 内部类」两条红线
+ * （原先 vm 子应用就是靠应用侧规则绕过，属历史债）。
+ *
+ * 对未写该变量的应用是 **no-op**（默认 0px，等于不位移）；
+ * 与上面 `position: fixed` 的两条规则互斥，那两条已显式 `translate: none` 关掉本条。
+ */
+body > .popover,
+body > .fv-tooltip.tooltip {
+  translate: var(--ibp-popup-shift-x, 0px) var(--ibp-popup-shift-y, 0px);
+}
+
+/* ===== .ak-table（AppTable）表头高度（按需） =====
+ * AppTable 的 `headerHeight` 通过 `--ak-table-header-height` 下发并同时挂 `ak-table--custom-header`；
+ * farris 把表头高度按固定常量**内联**写到 `.fv-grid-header` 上，故必须用 `!important` 压过：
+ * 内联样式非 important，会被这里的 important 规则覆盖。
+ *
+ * 用途：`AppTableColumn.title` 传函数（双行表头）时装不下 32px 的默认表头。
+ * 不传 `headerHeight` 的应用不会挂这个类 ⇒ 本条完全不生效（对其余应用零影响）。
+ */
+.ak-table.ak-table--custom-header .fv-grid-header,
+.ak-table.ak-table--custom-header .fv-grid-header-columns,
+.ak-table.ak-table--custom-header .fv-grid-header-primary,
+.ak-table.ak-table--custom-header .fv-grid-header-cell {
+  height: var(--ak-table-header-height, 32px) !important;
+  align-items: stretch !important;
+}
+
+/* FDrower/FTabs 的 fill 模式在 1.8.4 下类名不生效（mcp 配置抽屉原先自带补丁） */
+.app-container .f-drawer-body {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
+/* ===== AppSteps 只读档（clickable=false）的光标 =====
+ * 上游 FStep 的 `clickable` prop 在 1.8.4 里**完全没被使用**，`li.clickable` 只由单个 step 的
+ * `disabled` 决定 ⇒ 整条只读时上游仍给非禁用项手型光标。拦截已由 AppSteps 的门控承担，
+ * 这里只把光标压回默认值（选择器两段式压过上榜单类规则，无需 !important）。 */
+.app-container .ak-steps--static .f-progress-step li.clickable {
+  cursor: default;
+}
+
+/* ===== 消息框（FMessageBox）正文按**文本**换行 =====
+ * `messageBox` 的口径是"用文本传消息"（见 services/message-box.ts）：换行用 `\n`。
+ * 上游这两行默认 `white-space: normal`，`\n` 会被折成空格 ⇒ 调用方只能拼 `<div>` 来分段。
+ * 这里放开换行，文本路才真正可用；已经带 HTML 标签的长文说明不受影响（块级标签照旧成段）。 */
+.toast-msg-title,
+.toast-msg-detail {
+  white-space: pre-line;
+}
+

package/dist/styles/index.css

@@ -0,0 +1,16 @@
+/**
+ * app-kit 样式汇总入口（apps 侧 `@import "@manohub/app-kit/styles.css"` 唯一入口）。
+ *
+ * 导入顺序即契约：farris CSS 最前（供内部封装件使用），随后令牌 → 桥接 → 组件样式。
+ * apps 侧 style.css 固定三行：
+ *   @import "@manohub/app-kit/reset.css";
+ *   @import "@manohub/app-kit/styles.css";
+ *   @import "./app.css";
+ */
+@import "@farris/ui-vue/index.css";
+@import "./tokens.css";
+@import "./farris-bridge.css";
+@import "../shell/shell.css";
+@import "../atoms/atoms.css";
+@import "../components/components.css";
+@import "./markdown.css";

package/dist/styles/markdown.css

@@ -0,0 +1,85 @@
+/**
+ * markdown 富文本预设：h1~h6 / 列表 / 代码块 / 引用的元素级排版。
+ *
+ * 业务侧禁止自写富文本元素排版（护栏禁 font-size / 裸元素选择器），
+ * markdown 容器统一挂 `.ak-markdown`，排版一次定型在这里。
+ */
+
+.ak-markdown {
+  font-size: var(--ui-font-body);
+  line-height: 1.7;
+  color: var(--ui-base-content);
+  word-break: break-word;
+}
+
+.ak-markdown h1 { font-size: 24px; font-weight: 600; margin: 16px 0 8px; }
+.ak-markdown h2 { font-size: 20px; font-weight: 600; margin: 14px 0 8px; }
+.ak-markdown h3 { font-size: 17px; font-weight: 600; margin: 12px 0 6px; }
+.ak-markdown h4 { font-size: 15px; font-weight: 600; margin: 12px 0 6px; }
+.ak-markdown h5,
+.ak-markdown h6 { font-size: 14px; font-weight: 600; margin: 10px 0 6px; }
+
+.ak-markdown p { margin: 8px 0; }
+
+.ak-markdown ul,
+.ak-markdown ol {
+  margin: 8px 0;
+  padding-left: 24px;
+}
+.ak-markdown ul { list-style: disc; }
+.ak-markdown ol { list-style: decimal; }
+.ak-markdown li { margin: 4px 0; }
+
+.ak-markdown blockquote {
+  margin: 8px 0;
+  padding: 8px 12px;
+  border-left: 3px solid var(--ui-primary);
+  background: var(--ui-base-200);
+  color: var(--ui-base-content-muted);
+}
+
+.ak-markdown code {
+  font-family: 'JetBrains Mono', Consolas, 'Courier New', monospace;
+  font-size: 13px;
+  background: var(--ui-base-200);
+  border-radius: var(--ui-radius-sm);
+  padding: 2px 4px;
+}
+
+.ak-markdown pre {
+  margin: 8px 0;
+  padding: 12px;
+  background: var(--ui-base-200);
+  border-radius: var(--ui-radius-md);
+  overflow-x: auto;
+}
+.ak-markdown pre code {
+  background: transparent;
+  padding: 0;
+}
+
+.ak-markdown a {
+  color: var(--ui-primary);
+  text-decoration: none;
+}
+.ak-markdown a:hover {
+  text-decoration: underline;
+}
+
+.ak-markdown table {
+  border-collapse: collapse;
+  margin: 8px 0;
+}
+.ak-markdown th,
+.ak-markdown td {
+  border: 1px solid var(--ui-base-300);
+  padding: 6px 10px;
+}
+.ak-markdown th {
+  background: var(--ui-base-200);
+  font-weight: 600;
+}
+
+.ak-markdown img {
+  max-width: 100%;
+}

package/dist/styles/reset.css

@@ -0,0 +1,74 @@
+/**
+ * 通用最小 reset（scope 到 .app-container）。
+ *
+ * 放在导入链最前（先于 farris CSS），让 farris 自己的 base 覆盖 reset，
+ * 从根上消除「全局 reset 压过 UI 库」的冲突。
+ *
+ * ⚠️ 作用域一律用 `:where(.app-container)` 包裹：
+ * `:where()` 特异性为 0，等价于 Tailwind preflight 的纯元素选择器（0,0,1），
+ * 而 `.app-container button`（0,1,1）会反压 farris 的 `.btn-primary`（0,1,0）——
+ * 曾导致主按钮文字变黑（farris 的 `color: var(--f-text-00)` 被 reset 的 `color: inherit` 覆盖）。
+ *
+ * 注意：
+ * - micro-app 的 scopecss 不作用域化 html/:root/body，因此任何全局选择器都要克制；
+ *   html/body/#app 的高度规则仅供独立运行场景，micro-app 下由宿主容器承担高度。
+ * - 不要加 `.app-container ul { list-style: none }`：markdown 富文本依赖 ul 圆点，
+ *   富文本排版统一走 app-kit 的 `.ak-markdown` 预设。
+ */
+
+:where(.app-container),
+:where(.app-container) *,
+:where(.app-container) *::before,
+:where(.app-container) *::after {
+  box-sizing: border-box;
+}
+
+.app-container {
+  font-family: 'Noto Sans SC', Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  font-size: 14px;
+  line-height: 1.5;
+  color: var(--ui-base-content);
+  background: var(--ui-base-100);
+  height: 100%;
+  min-width: 320px;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+:where(.app-container) h1,
+:where(.app-container) h2,
+:where(.app-container) h3,
+:where(.app-container) h4,
+:where(.app-container) h5,
+:where(.app-container) h6,
+:where(.app-container) p,
+:where(.app-container) figure {
+  margin: 0;
+}
+
+:where(.app-container) button,
+:where(.app-container) input,
+:where(.app-container) textarea,
+:where(.app-container) select {
+  font: inherit;
+  color: inherit;
+}
+
+/* 独立运行场景：子应用挂 #app 需要整链高度；micro-app 下此规则被宿主容器覆盖，无副作用 */
+html,
+body,
+#app {
+  margin: 0;
+  padding: 0;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+}
+body label {
+  margin-bottom: 0;
+}

package/dist/styles/tokens.css

@@ -0,0 +1,111 @@
+/**
+ * 令牌层 —— 全仓唯一视觉令牌定义处。
+ *
+ * 锚定 `.app-container` 而非 `:root`：micro-app 的 scopecss 不作用域化 `:root`，
+ * 定义在 `:root` 的变量会泄漏到宿主全局（多子应用互染、卸载残留）；
+ * `.app-container` 由 createSubApp 统一包裹，取值一致且作用域安全。
+ *
+ * 局部换主题 = 在更深的容器上重设变量，如 `.role-tree-pane { --ui-primary: #7C3AED; }`。
+ */
+
+.app-container {
+  /* 品牌槽位：全仓唯一一处定义 */
+  --ui-primary: #2660FF;
+  --ui-primary-content: #FFFFFF;
+  --ui-primary-hover: #1A4FE0;
+  --ui-primary-weak: rgba(38, 96, 255, 0.08);
+  --ui-primary-subtle: #F0F7FF;
+
+  /* 中性阶（收敛自批次 5 盘点的 55 种字面量灰/白色，禁止再自由取值） */
+  --ui-base-50: #FAFAFA;
+  --ui-base-100: #FFFFFF;
+  --ui-base-200: #F5F7FA;
+  --ui-base-300: #E6E6E6;
+  --ui-base-400: #DCDCDC;
+  --ui-base-content: #1A1A1A;
+  --ui-base-content-muted: #666666;
+  --ui-base-content-subtle: #999999;
+
+  /* 状态色：主色 + 浅底 + 描边三档（标签 / 提示块 / 校验态） */
+  --ui-info: #3B82F6;    --ui-info-content: #FFFFFF;
+  --ui-success: #22C55E; --ui-success-content: #FFFFFF;
+  --ui-warning: #F59E0B; --ui-warning-content: #1A1A1A;
+  --ui-error: #DC2626;   --ui-error-content: #FFFFFF;
+  --ui-info-weak: #EFF6FF;    --ui-info-border: #BFDBFE;
+  --ui-success-weak: #ECFDF5; --ui-success-border: #A7F3D0;
+  --ui-warning-weak: #FFFBEB; --ui-warning-border: #FDE68A;
+  --ui-error-weak: #FEF2F2;   --ui-error-border: #FECACA;
+  --ui-success-strong: #059669;
+  --ui-warning-strong: #B45309;
+
+  /* 密度档位（页头 18px/56px 条高依据 MH后台-0911 设计稿 node 0:3888） */
+  --ui-font-caption: 13px;
+  --ui-font-body: 14px;
+  --ui-font-heading: 16px;
+  --ui-font-title: 18px;
+  --ui-font-display: 20px;
+
+  --ui-line-caption: 20px;
+  --ui-line-body: 22px;
+  --ui-line-heading: 24px;
+  --ui-line-title: 28px;
+
+  --ui-weight-regular: 400;
+  --ui-weight-medium: 500;
+  --ui-weight-semibold: 600;
+
+  --ui-font-mono: Consolas, Monaco, 'Courier New', monospace;
+
+  --ui-radius-sm: 4px;
+  /* 控件档圆角 6px：对齐 @aihub/theme 的 --f-radius-control（树节点行 / 说明条 / 输入控件都用它） */
+  --ui-radius-control: 6px;
+  --ui-radius-md: 8px;
+  --ui-radius-full: 9999px;
+
+  /* 说明条 / 警告提示（AppNotice）：数值取自 @aihub/theme `components/alert.css` 实测
+     （高 42、投影 0 2 10 黑 8%、文案 15px、警示/错误底取 Alert 专页样张，与语义 03 档两说时以专页为准） */
+  --ui-notice-height: 42px;
+  --ui-notice-shadow: 0 2px 10px rgba(0, 0, 0, 0.08);
+  --ui-notice-font: 15px;
+  --ui-notice-warning-bg: #fdf4ea;
+  --ui-notice-error-bg: #fdecec;
+
+  /* 树节点行：对齐 @aihub/theme `components/tree.css` 实测
+     （行高 30、字号 13、缩进步进 10、箭头 8、点击瞬态 #F4F5F9、滑过 Ne11、选中 Au02+Th03） */
+  --ui-tree-row-height: 30px;
+  --ui-tree-row-height-compact: 28px;
+  --ui-tree-indent-base: 8px;
+  --ui-tree-indent-step: 10px;
+  --ui-tree-active-bg: #f4f5f9;
+  --ui-tree-caret-size: 8px;
+
+  --ui-space-1: 4px;  --ui-space-2: 8px;  --ui-space-3: 12px;
+  --ui-space-4: 16px; --ui-space-6: 24px;
+
+  --ui-control-height-sm: 28px;
+  --ui-control-height-md: 32px;
+  --ui-row-height: 32px;
+  --ui-header-height: 48px;
+
+  /* 表单 label 列宽（AppForm.Item）：120 与设计稿「标签 + 一行控件」的表单同名宽；
+     需要不同宽度时在表单上覆盖（组件只下发 --ak-form-label-width，不在消费方写 CSS） */
+  --ui-form-label-width: 120px;
+
+  /* 栅格单元最小宽度（AppLayout.Row）：比表单的 --ui-form-column-min(320) 窄一档 ——
+     表单字段要放下「label + 控件」，而栅格单元（卡片/内容块）可以更窄。
+     用于「列数上限 N + 最小列宽」公式里 track 的下限（实测：600px 仍排 2 列、500px 折成 1 列）。 */
+  --ui-grid-column-min: 260px;
+
+  /* 两列表单的列最小宽度（AppForm columns=2）：容器放不下两列时自动回落一列 —— 320 是
+     「label 120 + 一个还能用的输入框」的下限 */
+  --ui-form-column-min: 320px;
+
+  /* 阴影：细线 + 弹层投影（拟物重投影一律收敛到这里） */
+  --ui-shadow-card: 0 2px 20px rgba(3, 18, 51, 0.05);
+  --ui-shadow-elevated: 0 2px 20px rgba(3, 18, 51, 0.15);
+  --ui-shadow-popover: 0 6px 16px rgba(15, 23, 42, 0.08);
+  --ui-overlay-weak: rgba(15, 23, 42, 0.04);
+  --ui-overlay-strong: rgba(15, 23, 42, 0.06);
+  --ui-mask: rgba(0, 14, 51, 0.1);
+  --ui-mask-light: rgba(255, 255, 255, 0.6);
+}

package/lint/__tests__/fixtures/clean-src/styles.css

@@ -0,0 +1,14 @@
+/* 合规样本：只写布局属性、只用登记前缀、无 rem / !important / 视觉属性 */
+.other-page {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+}
+
+.other-page-body {
+  flex: 1;
+  min-height: 0;
+  padding: 8px;
+  overflow: auto;
+}

package/lint/__tests__/fixtures/clean-src/views/good-page.tsx

@@ -0,0 +1,15 @@
+// 合规样本：AppShell 骨架 + Header/body 契约 + 面板 toolbar 字段 ≤3 + 组件用法合规
+import { AppShell, AppPanel, AppTable, AppInput } from '@manohub/app-kit'
+
+export default function GoodPage() {
+  return (
+    <AppShell>
+      <AppShell.Header title="示例页面" />
+      <AppShell.Body mode="plain">
+        <AppPanel title="列表" toolbar={<AppInput />}>
+          <AppTable framed rows={[]} columns={[]} rowKey="id" />
+        </AppPanel>
+      </AppShell.Body>
+    </AppShell>
+  )
+}

package/lint/__tests__/fixtures/violations-src/styles.css

@@ -0,0 +1,18 @@
+/* 故意违规样本：样式护栏（前缀未登记 / 视觉属性 / rem / !important / 裸元素 / .ak- / 令牌 / Split 竖直边框） */
+.my-app-header {
+  color: #ffffff;
+  padding: 0.5rem;
+  border-radius: 8px;
+}
+
+button {
+  margin: 0 !important;
+}
+
+.ak-panel {
+  --my-token: 12px;
+}
+
+.my-side-pane {
+  border-right: 1px solid #cccccc;
+}

package/lint/__tests__/fixtures/violations-src/views/bad-page.tsx

@@ -0,0 +1,38 @@
+// 故意违规样本：组件使用 + 页面结构护栏
+import { FDataGrid } from '@farris/ui-vue'
+import { AppShell, AppPanel, AppInput, AppSearchBox, AppSelect, AppTextarea } from '@manohub/app-kit'
+
+export default function BadPage() {
+  return (
+    <AppShell>
+      <AppShell.Header />
+      <AppShell.Body>
+        <div class="my-page-header">自绘页头</div>
+        <button class="btn btn-primary">确定</button>
+        {/* 跨行写法：`<input` 与 class 分两行 —— 逐行正则会漏（S4 必须整段扫） */}
+        <input
+          type="text"
+          class="my-cell-input"
+          placeholder="跨行写法"
+        />
+        <a class="my-op-link" onClick={() => remove}>删除</a>
+        <a href="#help" class="my-help-link">帮助</a>
+        <div style="height: 100vh" />
+        <AppPanel
+          title="列表"
+          toolbar={
+            <>
+              <AppInput />
+              <AppSearchBox />
+              <AppSelect />
+              <AppTextarea />
+            </>
+          }
+        />
+        <AppShell.Split sidebar={{ width: 200 }} />
+        <FDataGrid valueField="a" textField="b" rowOption={{ height: 32 }} />
+        <span>{row.raw}</span>
+      </AppShell.Body>
+    </AppShell>
+  )
+}

package/lint/__tests__/fixtures/violations-src/views/no-shell-page.tsx

@@ -0,0 +1,4 @@
+// 故意违规样本：路由级页面未使用 AppShell（S1）
+export default function NoShellPage() {
+  return <div class="my-legacy-layout">没有骨架</div>
+}

package/lint/__tests__/guardrails.spec.mjs

@@ -0,0 +1,144 @@
+/**
+ * 护栏自测：**故意违规的样本必须被打回，且必须携带 correction（唯一改法 + 出处）**。
+ *
+ * 为什么用 `node:test` 而不是 vitest：三条护栏是零依赖的 Node 脚本，
+ * `node --test` 内置即可运行，消费方与本仓都不需要额外安装测试框架
+ * （组件级的 DOM 契约测试另行引入 vitest + jsdom）。
+ *
+ * 运行：`pnpm --filter @manohub/app-kit test:unit`
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { cpSync, mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const LINT = join(HERE, '..')
+const AUDITS = ['style-audit.mjs', 'component-audit.mjs', 'structure-audit.mjs']
+
+/** 造一个临时消费仓：<tmp>/app/src/... + appkit-guardrails.config.json */
+function makeConsumer(fixtureName) {
+  const root = mkdtempSync(join(tmpdir(), 'appkit-guardrails-'))
+  mkdirSync(join(root, 'app'), { recursive: true })
+  cpSync(join(HERE, 'fixtures', fixtureName), join(root, 'app', 'src'), { recursive: true })
+  writeFileSync(
+    join(root, 'appkit-guardrails.config.json'),
+    JSON.stringify({
+      apps: [{ dir: 'app', name: 'fixture-app', prefixes: ['other-'], pending: false }],
+      srcGlobs: ['src/**/*.ts', 'src/**/*.tsx'],
+      styleGlobs: ['src/**/*.css'],
+      ignore: ['node_modules', 'dist'],
+    }),
+  )
+  return root
+}
+
+function runAudit(script, cwd) {
+  const res = spawnSync(process.execPath, [join(LINT, script), '--cwd=' + cwd], { encoding: 'utf8' })
+  return { code: res.status, out: (res.stdout ?? '') + (res.stderr ?? '') }
+}
+
+test('glob：嵌套路径必须匹配（防「只扫顶层文件」的静默漏扫）', async () => {
+  const { globToRegExp } = await import('../shared.mjs')
+  const src = globToRegExp('src/**/*.tsx')
+  assert.ok(src.test('src/main.tsx'), '顶层文件应匹配')
+  assert.ok(src.test('src/views/page.tsx'), '一级嵌套应匹配')
+  assert.ok(src.test('src/a/b/c/page.tsx'), '多级嵌套应匹配')
+  assert.ok(!src.test('src/page.ts'), '扩展名不符不应匹配')
+  const css = globToRegExp('src/**/*.css')
+  assert.ok(css.test('src/features/x/y.css'), '深层 css 应匹配')
+})
+
+test('违规样本：三条护栏都必须报错，且每条违规都带 correction', () => {
+  const root = makeConsumer('violations-src')
+  try {
+    const expectations = {
+      'style-audit.mjs': ['style/prefix', 'style/visual', 'style/rem', 'style/important', 'style/bare-element', 'style/ak-selector', 'style/token'],
+      'component-audit.mjs': ['api/farris-import', 'api/legacy-prop'],
+      'structure-audit.mjs': [
+        'structure/no-shell',
+        'structure/header-title',
+        'structure/body-mode',
+        'structure/native-control',
+        'structure/viewport-height',
+        'structure/self-header',
+        'structure/toolbar-fields',
+        'structure/self-border',
+      ],
+    }
+    for (const script of AUDITS) {
+      const { code, out } = runAudit(script, root)
+      assert.equal(code, 1, `${script} 应当失败（有违规）`)
+      for (const rule of expectations[script]) {
+        assert.ok(out.includes(rule), `${script} 未报出规则 ${rule}`)
+      }
+      assert.ok(out.includes('改法：'), `${script} 的违规必须带唯一改法`)
+      assert.ok(out.includes('出处：CONTRACT.md'), `${script} 的违规必须带规范出处`)
+    }
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('S4：原生按钮、「无 href 的锚点」、跨行写法的原生输入都要打回，带 href 的真链接不误报', () => {
+  const root = makeConsumer('violations-src')
+  try {
+    const { out } = runAudit('structure-audit.mjs', root)
+    const hits = out.split('\n').filter((line) => line.includes('structure/native-control'))
+    // 三条：按钮、无 href 锚点、以及 `<input` 与 class= 分两行的输入框
+    // （第三条是防回归：S4 曾经是逐行正则，跨行写法能整条逃过）
+    assert.equal(hits.length, 3, `按钮 / 锚点 / 跨行输入各应命中一条，实际 ${hits.length} 条`)
+    assert.ok(!out.includes('my-help-link'), '带 href 的锚点是真链接，不应被判为原生控件')
+    assert.ok(
+      hits.some((line) => line.includes('bad-page.tsx:13')),
+      `跨行输入的命中行号应指向 <input 那一行，实际：${hits.join(' | ')}`,
+    )
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('合规样本：三条护栏必须全绿（不得误报）', () => {
+  const root = makeConsumer('clean-src')
+  try {
+    for (const script of AUDITS) {
+      const { code, out } = runAudit(script, root)
+      assert.equal(code, 0, `${script} 不应报错，实际输出：\n${out}`)
+    }
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('pending 应用：照常报告但不计入退出码', () => {
+  const root = makeConsumer('violations-src')
+  try {
+    writeFileSync(
+      join(root, 'appkit-guardrails.config.json'),
+      JSON.stringify({
+        apps: [{ dir: 'app', name: 'fixture-app', prefixes: ['other-'], pending: true }],
+        ignore: ['node_modules', 'dist'],
+      }),
+    )
+    for (const script of AUDITS) {
+      const { code, out } = runAudit(script, root)
+      assert.equal(code, 0, `${script}：pending 应用不应影响退出码`)
+      assert.ok(out.includes('存量挂起'), `${script}：应提示存在存量挂起`)
+    }
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('--changed：非 git 环境下不裁剪（宁可多检查）', () => {
+  const root = makeConsumer('violations-src')
+  try {
+    const { code } = runAudit('style-audit.mjs', root)
+    assert.equal(code, 1)
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+})