xmltool

xmltool là công cụ Node.js/TypeScript cho Windows, dùng để tìm kiếm, preview, replace và xóa dữ liệu trong XML mà không format lại toàn bộ tài liệu. Công cụ có CLI, TUI, JSON/NDJSON và MCP server cho agent.

• Tìm literal hoặc JavaScript regex trong element name, attribute name/value, text, CDATA, comment hoặc raw XML.
• Lọc bằng XPath 3.1, gồm namespace mapping.
• Tự nhận diện XML trong .xml, .xaml, .csproj, .props, .targets, .config, .svg, .xsd, .xslt, .resx và file có extension bất kỳ nhưng nội dung là XML hợp lệ. File đuôi XML đã biết vẫn được giữ lại để báo lỗi nếu nội dung bị hỏng; file đuôi lạ chỉ được nhận khi toàn bộ nội dung parse thành công.
• Rule YAML/JSON kết hợp điều kiện cấu trúc all, any, not.
• Mutation mặc định chỉ tạo preview/diff; cần --apply mới ghi file.
• SHA-256 precondition ngăn apply một plan đã stale.
• Validate kết quả, atomic write, backup và rollback batch khi ghi lỗi.
• TUI ba vùng cho file, match và context/diff.
• MCP tách preview và apply_plan để agent không ghi file ngoài ý muốn.

• Windows 10/11 x64.
• Node.js 24 trở lên.

Phát triển từ source:

pnpm install
pnpm build
pnpm link --global
xmltool --help

Chạy trực tiếp trong repo:

pnpm dev -- search . -p "Legacy" --scope text,attribute-value

Tìm literal:

xmltool search C:\Projects -p "Legacy.Api" --scope text,attribute-value

JavaScript regex, bao gồm lookbehind và capture group:

xmltool search . -p "(?<=version=)\d+" --regex --flags iu --scope attribute-value

Regex chạy trong Worker Thread có timeout. Điều chỉnh bằng --regex-timeout 5000 nếu cần.

XPath và namespace:

xmltool search . `
  -p "old" `
  --xpath "//msb:PackageReference" `
  --namespace "msb=http://schemas.microsoft.com/developer/msbuild/2003" `
  --scope attribute-value

Các scope:

Output cho script hoặc agent:

xmltool search . -p old --output json
xmltool search . -p old --output ndjson
xmltool capabilities --output json
xmltool schema rule

Stdout của JSON/NDJSON không chứa progress hoặc ANSI. Diagnostic được gửi qua stderr.

Khi chạy trong PowerShell/Windows Terminal, progress được bật tự động:

⠹ Discovering XML files… 2.4s | 1,250 checked | 43 XML | current.dat
⠼ Processing 342/1,250 files (27.4%) | 85 matches | 2 errors | 54.3 files/s | ETA 16.7s | current.xml
✓ Done 1,250/1,250 files (100%) | 301 matches | 2 errors | 23s

Các chế độ:

# Mặc định: hiện khi stderr là terminal tương tác
xmltool search . -p keyword --progress auto

# Luôn hiện, kể cả khi chạy trong CI hoặc redirect output
xmltool search . -p keyword --progress always

# Tắt hoàn toàn
xmltool search . -p keyword --progress never

Progress luôn được ghi vào stderr, vì vậy có thể redirect JSON an toàn:

xmltool search . -p keyword --output json --progress always > result.json

Preview replacement:

xmltool replace . -p "old-(\d+)" --regex --scope attribute-value --with 'new-$1'

Apply và tạo backup:

xmltool replace . -p old --scope text --with new --apply

Lưu plan để review/apply sau:

xmltool replace . -p old --scope text --with new --save-plan change-plan.json
xmltool apply change-plan.json

Nếu file thay đổi sau khi plan được tạo, apply trả conflict và không ghi bất kỳ file nào trong batch.

Xóa là thao tác tường minh; replacement rỗng không tự động mang nghĩa xóa:

xmltool delete . -p obsolete --scope attribute-value --target attribute
xmltool delete . -p DeprecatedSetting --scope element-name --target node --apply

Các target gồm match, value, attribute, node, và unwrap (bỏ tag nhưng giữ children).

Tắt backup khi thật sự cần:

xmltool replace file.xml -p old --with new --apply --no-backup

Rule cho phép chọn target bằng XPath rồi kiểm tra nhiều điều kiện trong cùng element được chọn:

version: 1
paths: [C:\Projects]
select:
  xpath: //item
  scopes: [text]
  pattern: deprecated
where:
  all:
    - scope: attribute-value
      attribute: status
      equals: old
    - any:
        - scope: text
          element: name
          keyword: Legacy
        - scope: text
          regex: unsupported|obsolete
          flags: i
    - not:
        scope: attribute-value
        attribute: keep
        equals: "true"
action:
  type: replace
  with: supported

Chạy preview hoặc apply:

xmltool run rule.yaml
xmltool run rule.yaml --apply

Xem rule mẫu và JSON Schema.

xmltool tui C:\Projects

Phím chính:

• Tab: đổi literal/regex tại màn hình search.
• ↑/↓: di chuyển match.
• Space: chọn/bỏ chọn match.
• r: nhập replacement và xem diff.
• d: preview xóa node chứa match.
• a: apply plan đang preview với backup.
• /: search mới; q: thoát.

Khởi động MCP stdio:

node C:\path\to\xml-tool\dist\cli\main.js mcp

Ví dụ cấu hình MCP client:

{
  "mcpServers": {
    "xmltool": {
      "command": "node",
      "args": ["C:\\path\\to\\xml-tool\\dist\\cli\\main.js", "mcp"]
    }
  }
}

Tools được cung cấp:

• xml_search
• xml_preview_replace
• xml_preview_delete
• xml_apply_plan
• xml_validate

Plan của MCP chỉ tồn tại trong process server, tối đa 50 plan gần nhất. xml_apply_plan cần đúng planId đã preview và tất cả SHA-256 phải còn khớp.

• Giữ nguyên UTF-8, UTF-8 BOM, UTF-16 LE/BE và CRLF/LF.
• No-op round-trip phải giống source theo byte.
• Chỉ field được chỉnh sửa mới được encode lại; markup khác giữ nguyên.
• XML kết quả luôn được parse lại trước khi ghi.
• External/general entity không được tải từ mạng hoặc filesystem.
• Không follow symlink mặc định.
• File lớn hơn 64 MiB bị bỏ qua mặc định; thay đổi bằng --max-file-size.

pnpm typecheck
pnpm test
pnpm build

Test suite bao gồm parser lossless, encoding, discovery, XPath namespace, regex Worker, structured rules, replace/delete, stale plan, backup, CLI, TUI render và MCP end-to-end.