dsh-fmt

dsh-fmt

DSH 插件：格式化 / 校验文本，支持 JSON / YAML / TOML / SQL 四种格式。纯 ESM、无构建、无原生依赖。

安装

dsh plugin --profile <name> add file:./plugins/dsh-fmt

（发布到 npm 后：dsh plugin --profile <name> add dsh-fmt）

工具

• format_text —— 输入文本与目标格式，返回规范值 { format, ok, output, error? }。

参数

参数	类型	必填	默认	说明
text	string	是	-	要格式化 / 校验的文本
format	enum	是	-	json / yaml / toml / sql
indent	number	否	2	缩进宽度（JSON/YAML 美化；SQL 的 tab 宽度）
sqlDialect	enum	否	standard	standard / postgresql / mysql / sqlite，仅 SQL 使用
keywordCase	enum	否	upper	upper / lower / preserve，仅 SQL 使用

返回值

规范 JSON 值：

{
  "format": "json",       // 本次使用的格式
  "ok": true,             // 解析/格式化是否成功
  "output": "…",          // 格式化结果（ok=true）
  "error": {              // 仅 ok=false 时存在
    "message": "…",
    "line": 1,            // 可选
    "column": 2           // 可选
  }
}

解析失败不算工具失败：错误以 ok:false + error（尽力带 line/column 位置）返回，而不是抛出工具异常。

各格式示例

JSON

输入 {"b":1,"a":[1,2]}，format=json，indent=2：

{
  "b": 1,
  "a": [
    1,
    2
  ]
}

非法输入 {bad 返回 ok:false，error.message 含 Node 报错原文，line/column 从报错中的 position … (line L column C) 正则提取。

YAML

输入：

a:
  b: 1
c: [x, y]

format=yaml 先 parse 校验，再 stringify 美化（流式数组会展开为块式）。解析失败捕获 YAMLParseError，取 linePos[0] 作为位置。

TOML

输入：

title="demo"
[owner]
name="t"

format=toml 先 parse 校验再 stringify 规范化；解析失败取 TomlError 的 line / column。

SQL

输入 select a,b from t where x=1 order by b，format=sql、keywordCase=upper：

SELECT
  a,
  b
FROM
  t
WHERE
  x = 1
ORDER BY
  b

sqlDialect 映射到 sql-formatter 的 language：standard→sql、postgresql→postgresql、mysql→mysql、sqlite→sqlite。

SQL 不做语法校验的说明

format_text 的 SQL 分支本身不做主动语法校验：不先解析再格式化，直接把文本交给 sql-formatter 的 format()，多数可读 SQL 都能得到规范化输出。但 sql-formatter 底层是一个完整的 SQL 解析器，遇到根本无法解析的片段会抛错——此时同样遵循「解析失败不算工具失败」的约定，返回 ok:false + error.message，而不会让工具调用失败。

License

MIT