nx-sk 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 本文件格式参考 [Keep a Changelog](https://keepachangelog.com/)，中文正文。
 
+## 0.29.0 (2026-11-10)
+
+**新增 `shortcut` 字段与 `peek` 三态外壳；`source` 迁到同一外壳。三种形态、焦点与 reduced-motion 均经真实浏览器走查（57 项断言全过，控制台/网络 0 错误）。**
+
+### Added
+
+- **快捷键字段（`shortcut`）**：值按「组 → 条目 → 按键」三层存；折叠条只报组数/条数，
+  点「详细」打开键位面板（默认全屏，可切侧边/居中）——左侧分组目录、右侧说明表、底部键盘图，
+  录入时直接按组合键、悬停条目点亮对应键。`combo` 存 `KeyboardEvent.code`，写入接受
+  `"Ctrl+R"` / `["Ctrl","R"]` / `[{code,label}]` 三种写法。
+- **`peek` 三态外壳**：同一份内容可在 side / center / fullpage 之间切换。center/fullpage 补遮罩、
+  `aria-modal`、焦点陷阱、Esc 关闭与 reduced-motion；side 保持原右侧栏的宽度、断点与动画不变。
+
+### Changed
+
+- 原始资料（`source`）迁移到 `peek` 外壳：默认仍是原来的右侧栏，视觉与交互不变，新增三态切换按钮。
+
+### 说明
+
+- 走查修掉三处问题：三态选择器与 JSX 类名不一致导致面板尺寸/定位全部失效；点遮罩关闭后焦点掉到
+  `body`（现先 `preventDefault` 再关）；窄栏下快捷键表格逐字换行、全屏下表格与键盘图之间留大片空洞。
+
+## 0.28.0 (2026-11-10)
+
+**全量 TypeScript 化：后端与前端源码统一为 `.ts/.tsx`；字段与模块改为注册表驱动。对外行为不变。**
+
+### Changed
+
+- **源码全量 TypeScript**：`src/**` 不再有 `.js/.jsx`；`pnpm build` 先用 `tsc -p tsconfig.build.json`
+  产出 `dist/**/*.js`（`.ts` 导入后缀在 emit 时改写），再把面板构建到 `dist/web/public`。
+- **字段收敛为穷举注册表**：服务端 `FIELD_BEHAVIOR` / `FIELD_SEAL`、前端 `FIELD_CONTROLS`
+  都是 `Record<FieldType, …>`；`FIELD_TYPES` 加一项而漏实现/漏控件，会直接编译失败。
+- **模块「目录即声明」**：`src/modules/<id>/index.ts` 自动装载，新增模块不再需要改注册表与 eslint 清单。
+- **前端只消费 `shared`**：类型与零依赖纯函数从 `src/shared/**` 引入，eslint 边界规则覆盖 `.ts/.tsx`，
+  继续拦住 `import '../../core/**'` 与 `import '../../modules/**'`。
+
+### Fixed
+
+- **导出 ZIP 时表格的敏感列按列定义解密**：此前 `plainValues` 只处理 `entrylist`，含敏感列的表格会带密文出包，
+  换机器后永久不可解（独立提交 `fc4b9e2`）。
+
+### 说明
+
+- 命令、HTTP 响应形状、面板文案与交互、`store.json` 格式均未变化；`engines.node` 仍是 `>=18.17`。
+- 贡献者：单测直接执行 `.ts` 需要 Node `>=22.18`；改了后端源码要重新 `pnpm build`。
+
 ## 0.27.0 (2026-11-08)
 
 **表格字段重做：列头 ⋮ 属性菜单、行列都有抓手、去掉了那一整块「列设置」表单。**

package/README.md

@@ -11,13 +11,26 @@ nx-sk serve          # 打开面板（http://127.0.0.1:7866）
 
 ## 安装
 
+**要求 Node.js >= 18.17。** 包内是构建好的 `dist/`（纯 JS），运行时不需要 TypeScript。
+
+```bash
+npm i -g nx-sk        # 命令名就是包名
+nx-sk version
+nx-sk serve           # 打开面板
+```
+
+## 开发
+
+**开发/测试需要 Node >= 22.18**（单测用 `node --test` 直接跑 `.ts`，依赖 Node 原生类型剥离）；
+运行 CLI 与面板仍只需 >= 18.17。改了后端要重新构建——`dist/` 是运行时唯一入口。
+
 命令名就是包名。**推荐做成全局垫片**（全局 node_modules 里是指向本项目的软链，
 改代码立刻生效，不用重新安装）：
 
 ```bash
 cd <本项目>
 pnpm install          # 只为构建面板；CLI 侧零依赖
-pnpm run build        # 产出 src/web/public，serve 才有面板可服务
+pnpm run build        # tsc → dist/**/*.js，vite → dist/web/public
 npm link              # → 全局多了 nx-sk / nx-sk.cmd / nx-sk.ps1
 nx-sk version         # 从任何目录都能跑
 nx-sk serve           # 打开面板
@@ -45,7 +58,7 @@ nx-sk serve           # 打开面板
 >
 > 别忘了 `chmod +x ~/.local/bin/nx-sk`。验证：`cd / && nx-sk version`。
 
-> 不想污染全局也行：`node bin/nx-sk.mjs <子命令>` 等价，或 `npx --no-install . <子命令>`。
+> 不想污染全局也行：先 `pnpm build`，再 `node bin/nx-sk.mjs <子命令>`，或 `npx --no-install . <子命令>`。
 
 ### skill：用**软链垫片**（推荐）
 
@@ -516,9 +529,9 @@ pnpm test        # = lint + build + 冒烟 + 单测
 | --- | --- |
 | `bin/nx-sk.mjs` | 唯一入口，只转发 argv + 兜异常 |
 | `src/core/` | 零业务语义：paths / errors / store / fsx / crypto / vault / fields / attachments / render / ids / open |
-| `src/modules/<域>/` | `index.js`(action 声明) + `service.js`(业务) + `view.jsx`(面板) |
+| `src/modules/<域>/` | `index.js`(action 声明) + `service.js`(业务)。**不声明视图** |
 | `src/runtime/` | registry / spec / cli / api / server —— 装配层，不写业务 |
-| `src/web/frontend/` | React 壳 + 组件 + 视图注册表 |
+| `src/web/frontend/` | React 壳 + 组件 + `modules/<域>/view.jsx` + 视图注册表（视图只住这里） |
 | `assets/nx-sk/` | 随包分发的 skill（SKILL.md + references/） |
 | `tests/unit/` · `tests/smoke.mjs` | 一致性断言 + 端到端冒烟 |
 
@@ -553,7 +566,7 @@ agent 手册** —— 它写在创建本项目的脚手架 skill `server-cli-web
 | 把打码值当成新值写回去 | 密钥字段被写成 `sk-1****cdef` 这串掩码，**原凭据永久丢失** | 写入前比对掩码：相等就当成「未改动」保留原密文；含 `******` 的值直接拒绝 |
 | 删条目/栏目没有留退路 | 误删即不可逆；这是用户的**唯一一份**个人信息 | 破坏性写操作一律先 `transfer export` 导出，导出的包就是唯一回退手段 —— 不另设本地备份模块 |
 | store.json 解析失败就当空库继续 | 下一次写入把用户数据永久覆盖 | 先把损坏文件改名为 `store.json.corrupt-<时间>.json`，再降级返回空结构 |
-| 前端 import 了 `node:*` 或 `core/` | Vite 把 Node 侧代码打进浏览器包，dev 模式白屏 | lint 的 `files` 同时覆盖 `view.jsx`，禁掉 `node:*` / `core` / `runtime` / `service.js` |
+| 前端 import 了 `node:*` 或 `core/` | Vite 把 Node 侧代码打进浏览器包，dev 模式白屏 | lint 的 `files` 覆盖整个 `src/web/frontend/**`（视图都在这里），禁掉 `node:*` / `core` / `runtime` / `service.js` |
 | 新增模块忘了往 eslint 互依禁列里补一行 | **静默**：新模块变成「谁都可以依赖」，且规则随模块数增加持续衰减 | 在禁列旁留注释说明它是**逐模块枚举**的、漏补是静默的；加模块前先读 `eslint.config.js` |
 | 代理前缀 `/api` 与前端源码目录 `api/` 撞车 | 只在 dev 模式整页白屏，报错却是 404 / ECONNREFUSED，离根因很远 | vite 代理加 `bypass`，按「是不是前端资源」分流；并用测试钉住 `shouldServeLocally` |
 | 把「上传 / 选择」放到附件中心，再让条目去引用 | 条目里看不到上传入口，用户不知道该在哪儿加文件；附件中心还被迫预定义分类与槽位，跟栏目脱节 | **上传 / 选择发生在栏目条目里**（`file` 字段的值 = 附件 id）；附件中心由栏目驱动、只做统一展示与库存管理，**不预定义分类、不做指派** |

package/assets/nx-sk/references/15-special-fields.md

@@ -3,7 +3,7 @@
 大多数字段的值是标量（一行字、一个数字、一个日期）。这一篇只讲**值不是标量**的字段，
 以及它们各自的规则、写入时的体检、空值与默认值怎么处理：
 
-`table`（表格）· `entrylist`（结构清单）· `md`（图文）· `file`（附件）· `source`（原始资料袋）· `secret`（密文）
+`table`（表格）· `entrylist`（结构清单）· `md`（图文）· `file`（附件）· `source`（原始资料袋）· `shortcut`（快捷键）· `secret`（密文）
 
 > 为什么要单独一篇：这些字段的**值形状**决定了怎么读、怎么写、怎么在面板上编。
 > 把它们当普通字符串塞进去，最常见的后果不是报错，而是「存进去了但面板看不见」——
@@ -18,6 +18,7 @@
 | `md` | 一段 markdown 字符串 | — | 图文编辑器（Ctrl+V 贴图） | `entry get`（图片还原成路径） |
 | `file` | `[附件id, …]` | 字段字典的 `kind` / `maxItems` | 附件选择器（上传 / 从库里选） | `entry get`（附件名 + 物理路径） |
 | `source` | `[{id, kind, name, text\|fileId\|url, addedAt, …}]` | 内置（每个栏目自带一个） | 底部折叠条 → 右侧侧边栏 | `source get` |
+| `shortcut` | `[{id, name, shortcuts:[{id, combo:[{code,label}], description, condition?}]}]` | 数据自己（组 → 条目 → 按键） | 折叠条只报组数/条数；`详细` 打开键位面板（默认全屏，可切侧边/居中） | `entry get` |
 | `secret` | 一个字符串（落盘是密文） | — | 输入框 | `key get` / `entry get` |
 
 共同点：**写入即校验**（不合法就整条拒绝，不会存半条）、**空值有明确语义**、
@@ -190,6 +191,29 @@
   普通文字本来就是合法 markdown，老数据不用迁移。
 - 不计完整度（`fill: optional`）；袋里是明文，**敏感内容不要进袋**。
 
+## `shortcut` 快捷键
+
+- 值 = **组 → 条目 → 按键**三层：`[{ name, shortcuts: [{ combo, description, condition? }] }]`。
+  组是目录，条目是「这条快捷键做什么」，`condition` 写生效范围（不写 = 全局）。
+- `combo` 存 `KeyboardEvent.code`（物理键位），不是 `key`——换键盘布局/输入法不会让快捷键错位。
+- 写入时三种写法等价（都会归一成同一种形状）：
+
+```bash
+# 1) 最省事的字符串
+nx-sk entry add --section demo --title 快捷键示例 \
+  --set 'keys=[{"name":"全局","shortcuts":[{"combo":"Ctrl+Shift+R","description":"刷新"}]}]'
+
+# 2) 键名数组
+--set 'keys=[{"name":"列表","shortcuts":[{"combo":["J"],"description":"下一条"}]}]'
+
+# 3) 面板存下来的按键对象（精确控制左右修饰键）
+--set 'keys=[{"name":"全局","shortcuts":[{"combo":[{"code":"ControlLeft","label":"Ctrl"},{"code":"KeyK","label":"K"}],"description":"命令面板"}]}]'
+```
+
+- 每条必须有 `description`；键位认不出（例如 `Ctrl+？`）会整条拒绝并指出是第几组第几条。
+- 面板里点 `详细` 打开键位图：悬停条目点亮对应键；`新增` 后直接按组合键即可录入。
+- 不能当表格列（`cell: false`）；不引用附件，没有子密文。
+
 ## `secret` 密文
 
 - 值是一个字符串，落盘 AES-256-GCM 密文；读出来默认原文，`--mask` 打码。

package/bin/nx-sk.mjs

@@ -1,7 +1,25 @@
 #!/usr/bin/env node
-// nx-sk 的唯一可执行入口：只做两件事——转发 argv、兜住未捕获的异常。
-// 所有命令分发都在 src/runtime/cli.js（那里才是命令表）。
-import { runCli } from '../src/runtime/cli.js';
+// nx-sk 的唯一可执行入口：转发 argv、兜住未捕获的异常。
+// 所有命令分发都在 dist/runtime/cli.js（那里才是命令表）——只跑构建产物，
+// 不在运行时做 TypeScript 类型剥离（Node 对 node_modules 下的 .ts 直接拒绝）。
+//
+// 首次从源码仓库直接跑、或改了后端还没构建时，dist 不存在：给一句能照做的提示，
+// 而不是把 ERR_MODULE_NOT_FOUND 的栈甩给用户。
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const cliUrl = new URL('../dist/runtime/cli.js', import.meta.url);
+
+if (!existsSync(fileURLToPath(cliUrl))) {
+  process.stderr.write(
+    'nx-sk: 找不到构建产物 dist/runtime/cli.js。\n'
+      + '源码仓库需要先构建：pnpm build（npm run build）——它会先 tsc 产出 dist，再构建面板。\n'
+      + '如果你是用 npm 全局安装的，这说明包不完整，请重装：npm i -g nx-sk。\n',
+  );
+  process.exit(1);
+}
+
+const { runCli } = await import(cliUrl.href);
 
 runCli(process.argv.slice(2)).catch((err) => {
   const message = err && err.message ? err.message : String(err);

package/{src → dist}/core/argsafe.js

@@ -12,8 +12,7 @@
 // 又会拦住用 --data 写入的合法 CRLF 多行值（高假阳性）；LF 截断后则与合法单行值
 // 完全不可区分。可靠的信号不存在，因此只能提供可靠通道 + 修好通道本身。
 import { readFileSync } from 'node:fs';
-import { badInput } from './errors.js';
-
+import { badInput } from "./errors.js";
 /**
  * `--data` 的值：JSON 字面量 / `@文件路径` / `-`（stdin）。
  *
@@ -21,33 +20,34 @@ import { badInput } from './errors.js';
  * 「读 stdin」因此不是一个无法测试的隐式依赖，也让本模块保持纯函数（不自己碰 fd 0）。
  */
 export function parseDataArg(raw, takeStdin) {
-  const s = String(raw ?? '').trim();
-  if (!s) throw badInput('--data 需要一个 JSON 字面量、@文件路径，或 -（从 stdin 读）');
-  if (s === '-' || s === '@-') return parseJson(takeStdin(), '-');
-  if (s.startsWith('@')) return parseJson(readText(s.slice(1)), s.slice(1));
-  return parseJson(s, '--data'); // 直接给的字面 JSON
+    const s = String(raw ?? '').trim();
+    if (!s)
+        throw badInput('--data 需要一个 JSON 字面量、@文件路径，或 -（从 stdin 读）');
+    if (s === '-' || s === '@-')
+        return parseJson(takeStdin(), '-');
+    if (s.startsWith('@'))
+        return parseJson(readText(s.slice(1)), s.slice(1));
+    return parseJson(s, '--data'); // 直接给的字面 JSON
 }
-
 /** 值本身走 stdin 的入口（`key set NAME -`）。true 表示「这个值来自 stdin」。 */
 export function parseStdinValue(raw) {
-  return String(raw ?? '').trim() === '-';
+    return String(raw ?? '').trim() === '-';
 }
-
 function parseJson(text, src) {
-  try {
-    return JSON.parse(text);
-  } catch (e) {
-    throw badInput(`--data 不是合法 JSON（${src}）: ${e.message}`);
-  }
+    try {
+        return JSON.parse(text);
+    }
+    catch (e) {
+        throw badInput(`--data 不是合法 JSON（${src}）: ${e.message}`);
+    }
 }
-
 function readText(p) {
-  try {
-    return readFileSync(p, 'utf8');
-  } catch (e) {
-    // 路径写法是最常见的坑：Git Bash 的 /tmp 在 node 侧看不到（真实事故 ENOENT），
-    // 所以错误里直接把 Windows 路径形式写出来，省掉一轮排查。
-    throw badInput(`读取文件失败: ${p}（${e.message}）—— Windows 上请用 C:/Users/... 形式的路径`);
-  }
+    try {
+        return readFileSync(p, 'utf8');
+    }
+    catch (e) {
+        // 路径写法是最常见的坑：Git Bash 的 /tmp 在 node 侧看不到（真实事故 ENOENT），
+        // 所以错误里直接把 Windows 路径形式写出来，省掉一轮排查。
+        throw badInput(`读取文件失败: ${p}（${e.message}）—— Windows 上请用 C:/Users/... 形式的路径`);
+    }
 }
-