Introduction¶

In the DSH plugin ecosystem, agents often need to process structured text. dsh-fmt is provided as a client plugin and addresses formatting and validation issues for JSON, YAML, TOML, and SQL text through the format_text tool.

What Is It?¶

This is a DSH plugin maintained by ZhijiangTang. It implements the format_text tool. It natively supports JSON, YAML, TOML, and SQL. It returns a normalized JSON value containing format, ok, output, and error. It is pure ESM, build-free, and has no native dependencies.

Install and Enable¶

First, run the following command to install the plugin into the specified profile:

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

Usage¶

Call the format_text tool. text and format are required. The other parameters are optional.

text: The text to format/validate (required).
format: The target format (required): json, yaml, toml, or sql.
indent: Indentation width. JSON/YAML use spaces; SQL uses tabs. Default is 2.
sqlDialect: SQL dialect. Default is standard.
keywordCase: SQL keyword case. Default is upper.

Return Value¶

The tool always returns a normalized JSON value:

{
  "format": "json",
  "ok": true,
  "output": "...",
  "error": {
    "message": "...",
    "line": 1,
    "column": 2
  }
}

If parsing succeeds, ok is true, and output contains the formatted text.
If parsing fails (for example, a JSON syntax error), ok is false, output is omitted, and error contains an error message and position information (when available). This does not interrupt the agent workflow.

Examples¶

JSON beautification
Input {"b":1,"a":[1,2]}, format=json, indent=2.

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

YAML validation and beautification
Input YAML, format=yaml. It first parses to validate, then serializes.
TOML validation and normalization
Input TOML, format=toml.
SQL formatting
Input 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

Notes¶

Pure ESM: The plugin has no build steps or native dependencies and can be loaded directly.
SQL behavior: The SQL branch itself does not perform active syntax validation. It passes the text directly to sql-formatter. If the text cannot be parsed, it returns ok:false instead of throwing an exception.
Error handling: Parsing failures do not interrupt the agent. It returns ok:false and an error object.

Conclusion¶

This tool addresses formatting and validation needs for DSH agents when processing structured data.

dsh-fmt: Formatting and Validating JSON, YAML, TOML, and SQL Text