dsh-fmt

Readme

# dsh-fmt

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

## 安装

```sh
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 值：

```jsonc
{
  "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`：

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

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

### YAML

输入：

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

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

### TOML

输入：

```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`：

```sql
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