cli-to-js 將任何 CLI 工具自動轉換為強型別的 JavaScript API

cli-to-js 將任何 CLI 工具自動轉換為強型別的 JavaScript API。

cli-to-js 是一個實驗性專案，旨在透過自動解析 CLI 工具的 --help 輸出，將任何指令列介面轉換為具備強型別的 JavaScript API，讓開發者能以程式碼方式呼叫系統工具。該專案目前處於高度實驗階段，API 可能隨時變動，開發者需留意其穩定性。

核心運作機制
該工具的核心邏輯在於「自動化解析」，它透過讀取二進位檔案的 --help 資訊，將其轉化為結構化的 Schema，並回傳一個基於 Proxy 的 API。

• 子指令（Subcommands）被映射為 JavaScript 方法。
• 旗標（Flags）被映射為選項物件。
• 系統會自動處理參數轉換，例如將 { verbose: true } 轉換為 --verbose，或將陣列參數展開為多個旗標。
• 支援從二進位名稱直接轉換，也支援從現有的幫助文字字串（Help text string）進行轉換。

對 Agent 的重要性
對於 Agent 開發而言，此工具解決了與系統互動的結構化問題。Agent 通常需要呼叫 CLI 工具，但直接處理原始 Shell 字串既不安全也不穩定。

• 結構化介面：Agent 可以對系統上的任何二進位檔案進行內省（Introspection），取得強型別介面並安全地呼叫。
• 錯誤修正：內建的 $validate 功能可在產生處理程序（Process）之前捕捉虛構的旗標名稱，並回傳建議，讓 Agent 能在單次重試中自我修正。
• 串流處理：$spawn 回傳標準的非同步迭代器，讓串流與管道操作能透過 for await 迴圈輕鬆實現。

關鍵技術特性

• TypeScript 整合：API 開箱即用，具備完整型別定義，無需額外的程式碼生成。開發者可透過泛型傳遞子指令的選項型別，或使用 npx 指令產生 .d.ts 文件。
• 嚴格驗證：在執行指令前，可透過 $validate 檢查選項。系統會檢查未知旗標（並提供基於 Levenshtein 距離的建議）、型別不匹配（如布林值與數值混用）以及位置參數的數量錯誤。
• 輸出解析：每個指令回傳的 CommandPromise 支援多種輸出格式，包括 .text()（原始字串）、.lines()（字串陣列）以及 .json()（自動解析 JSON 輸出），大幅簡化了處理 CLI 輸出的繁瑣工作。
• 指令組合：透過 $command 可取得 Shell 字串而非直接執行，並可使用 script() 將多個指令組合成可執行的腳本，支援順序執行與失敗中斷。

執行與串流控制
cli-to-js 提供了細緻的執行控制能力，適合複雜的自動化場景：

• 串流回呼：支援 onStdout 與 onStderr 回呼，允許在接收緩衝結果的同時取得即時輸出。
• 非同步迭代：$spawn 允許開發者透過非同步迭代器逐行讀取輸出，適用於監控長時間運行的指令。
• 互動模式：透過設定 stdio: "inherit"，可將標準輸入輸出傳遞給父終端，支援需要互動的 CLI 工具。
• 執行配置：每個方法皆可接收第二個參數進行配置，包括 cwd（工作目錄）、env（環境變數）、timeout（逾時設定）以及 AbortSignal（中止訊號），確保執行環境的靈活性。

獨立性與部署
該專案強調生成的程式碼具有高度獨立性：

• 獨立執行：透過 npx cli-to-js 產生的 JS/TS 封裝器是獨立的，內嵌了輕量級的執行時（Runtime），對 cli-to-js 本身零依賴。
• 部署彈性：開發者可以將產生的程式碼直接放入任何專案中，無需擔心相依性問題，這對於需要將 CLI 工具整合至現有專案的開發者來說非常便利。

注意事項
由於 cli-to-js 仍處於實驗階段，其 API 介面可能在未經通知的情況下發生變更。在生產環境中使用時，建議對其產生的 Schema 與執行結果進行充分測試，並密切關注專案的更新動態。