HIsheR
57 lines
7.2 KiB
JSON
57 lines
7.2 KiB
JSON
{
|
||
"name": "@ui-arch/cli",
|
||
"type": "tooling",
|
||
"description": "ua 命令行与 MCP 注册表服务：把各包 ua.manifest.json 汇总成机器可读索引（.ua/index.json）、Agent 全量文档（llms-full.txt）与人类文档站，并提供清单一致性门禁。",
|
||
"tags": [
|
||
"cli",
|
||
"tooling",
|
||
"mcp",
|
||
"docs",
|
||
"gate"
|
||
],
|
||
"api": {
|
||
"entry": "bin/ua.js",
|
||
"exports": [
|
||
"ua doctor：11 项环境与自洽预检（node / 依赖 / git 钩子与身份 / .ua 元数据可解析 / usage 串 ↔ dispatch 一致 / check 链覆盖全部门禁步骤 / CLI 清单声明的命令都有实现），任一失败退出码 1",
|
||
"ua index：扫描 packages/ 两层目录的 ua.manifest.json，生成 .ua/index.json 与 llms.txt",
|
||
"ua list：列出注册表内所有包与组件数；--json 输出「包 + 组件 id」结构化数组，--components 逐组件展开",
|
||
"ua info <包名|组件id>：包名返回摘要，组件 id 返回 props 表 + 步骤 + 示例；--json 输出原始清单，--md 直接给可粘贴的 Markdown 片段（标题 + 参数表 + 用法 + 示例）",
|
||
"ua tokens [关键词] [--json|--unused]：打印 --ua-* 令牌清单（颜色带暗色值）；--unused 反向列出皮肤包与令牌自身都没引用的令牌，用来收口令牌面",
|
||
"ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt",
|
||
"ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1",
|
||
"ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在 / 视觉回归抽查清单六组件各 ≥3 条且五维度齐全）",
|
||
"ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1",
|
||
"ua audit:visual [--json|--baseline]：视觉漂移门禁，统计皮肤包里各类硬编码视觉字面量（字号/动效时长/阴影/圆角/焦点环/内距/控件高度/字重/行高/层级/边框色）并与 .ua/visual-baseline.json 棘轮比对，超基线退出码 1；--baseline 重写基线，--json 出机器可读计数与每类命中行号（line / prop / value / hint，Agent 可直接定位）",
|
||
"ua audit:contrast [--json|--list]：对比度门禁，把令牌里 18 组「前景色 × 底色」配对按 WCAG 公式算成对比度（求值支持 var() 与 color-mix，半透明底先压到页面底色），亮/暗 × 常规/高对比四套分算，低于阈值（正文 7 / 常规 4.5 / 禁用 2.6 / 非文本 3）退出码 1；--json 出逐对明细，--list 只列配对表",
|
||
"ua audit:motion [--json]：动效兜底门禁，两类必查——① 带 infinite 的动画逐个核对是否在 prefers-reduced-motion 块里 animation: none；② 悬停 / 按压的位移（translate）是否在减少动效下归零（认 ua- 类通配的全局规则）。缺兜底退出码 1（--json 出逐条明细）",
|
||
"ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe；get_component 支持 format: md 直接取可粘贴的 Markdown 片段"
|
||
],
|
||
"keyTypes": [
|
||
"ua.manifest.json 清单结构",
|
||
"MCP tool 入参 schema"
|
||
]
|
||
},
|
||
"usage": "node packages/tools/cli/bin/ua.js <index|list|info <包名|组件id> [--json|--md]|docs|tokens [--json|--unused]|style|verify|commit-lint|audit:visual|audit:contrast|audit:motion|doctor|mcp>；仓库内等价于 npm run index / docs / style / verify / audit:visual / audit:contrast / audit:motion / doctor",
|
||
"conventions": [
|
||
"零依赖：只用 node 标准库，Node >= 18",
|
||
"清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 ua.manifest.json 派生",
|
||
"门禁只增不改：新增校验必须能被人手复现，报错要指出文件与字段"
|
||
],
|
||
"docs": {
|
||
"intro": "工程层工具包（private，不发布）。所有 Agent 与人都通过它读取组件库：清单驱动索引、文档、MCP 三件套，外加 style / verify 两道门禁。",
|
||
"steps": [
|
||
"接手先跑 ua doctor（11 项：node / 依赖 / git 钩子与身份 / 元数据 / 命令面三方一致 / 门禁链完整，秒级），再跑 npm run check 确认基线全绿（build → demo → style → typecheck → smoke → index → verify → lint-iterations → audit:visual → audit:contrast → audit:motion）",
|
||
"查组件：ua list 看全量，ua search <关键词> 按 id/标题/参数名/参数说明/步骤五层 + 配方三层（标题/配方组件/要点）模糊找（命中非 id 标题会标出命中字段，配方命中行直接给 ua recipes <编号> 指路；拼错会回相近 id），ua info <组件id> 看 props/步骤/示例（ua info <包名> 看单包 api 与约定，加 --json 出原始清单）；要给文档 / issue / 回复贴组件说明时加 --md，直接拿到标题 + 参数表 + 用法 + 示例的 Markdown 片段",
|
||
"查配方：ua recipes 列全量（编号 / 标题 / 用到的组件），ua recipes <编号> 看骨架代码与要点（--json 给脚本用；MCP 里对应 list_recipes / get_recipe）",
|
||
"查令牌：ua tokens 打印全部 --ua-* 变量（颜色带暗色值），--json 输出结构化数组；写样式前先查，禁止硬编码。令牌分十三组：颜色 / 混色浓度 / 圆角 / 间距 / 字号 / 字重行高 / 边框 / 阴影 / 动效 / 位移 / 焦点环 / 控件高度 / 层级，color-mix 混入浓度用 --ua-alpha-soft/tint/line/mid/strong/heavy，弹层阴影用 --ua-shadow-1..4，过渡用 --ua-duration-* + --ua-ease，transform 位移用 --ua-translate-*（负号 calc(-1 * var(...))），焦点环用 --ua-focus-ring(_inset)",
|
||
"收口令牌面用 ua tokens --unused：列出皮肤样式表与令牌自身都没引用的令牌（当前 3 个：surface-3 / text-secondary / font-size-xl），删之前先确认没有外部消费方在吃它们",
|
||
"改完清单跑 npm run docs：同时刷新人类文档站与 llms-full.txt（Agent 首选喂料）",
|
||
"改完样式跑 npm run audit:visual：各类硬编码计数不得高于 .ua/visual-baseline.json（棘轮只减不增）；字面量可用 npm run visual:migrate 幂等改写成令牌",
|
||
"改完颜色令牌跑 npm run audit:contrast：18 组前景/底色配对在亮/暗 × 常规/高对比四套主题下都必须达标（正文 7 / 常规 4.5 / 禁用 2.6 / 非文本 3），跌破即退出码 1——调一个色值就能让全站辅助文字掉到 4.4 或让焦点环糊进背景，人眼看不出但门禁看得出",
|
||
"改完动效跑 npm run audit:motion：带 infinite 的动画必须在 prefers-reduced-motion 块里被关掉，悬停 / 按压的位移（translate）必须归零，缺一条即退出码 1——循环动画漏兜底会把「减少动效」用户整页交给抖动，位移漏兜底则每次悬停都在推搡前庭",
|
||
"在 ~/.workbuddy/mcp.json 注册 ua mcp 后，Agent 可直接调 list_components / get_component / search_components / get_tokens / list_recipes / get_recipe；get_component 传 format: md 拿到与 ua info --md 同款的 Markdown 片段"
|
||
],
|
||
"components": []
|
||
}
|
||
}
|