# useShell

`fluxlay.yaml` で宣言されたシェルコマンドを実行し、オプションで xterm ターミナルに出力をレンダリングします。

## インポート

```tsx
import { useShell } from "@fluxlay/react";
```

## シグネチャ

```tsx
function useShell(commandId: string, options?: UseShellOptions): UseShellReturn;
```

## パラメータ

| パラメータ  | 型                | 説明                                                          |
| ----------- | ----------------- | ------------------------------------------------------------- |
| `commandId` | `string`          | `fluxlay.yaml` の `shell` セクションで宣言されたコマンド ID。 |
| `options`   | `UseShellOptions` | オプションの設定。                                            |

### UseShellOptions

| プロパティ        | 型                         | デフォルト  | 説明                                                              |
| ----------------- | -------------------------- | ----------- | ----------------------------------------------------------------- |
| `refreshInterval` | `number`                   | `30000`     | コマンドを再実行する間隔（ミリ秒）。                              |
| `showStdout`      | `boolean`                  | `true`      | 標準出力をターミナルに書き込む。                                  |
| `showStderr`      | `boolean`                  | `false`     | 標準エラーをターミナルに書き込む。                                |
| `terminal`        | `TerminalInstance \| null` | `undefined` | 出力をレンダリングする `useTerminal()` のターミナルインスタンス。 |
| `columns`         | `number`                   | —           | 擬似ターミナルの列幅。                                            |
| `lines`           | `number`                   | —           | 擬似ターミナルの行の高さ。                                        |

## 戻り値

| プロパティ  | 型                    | 説明                           |
| ----------- | --------------------- | ------------------------------ |
| `execute`   | `() => Promise<void>` | コマンドを手動で実行。         |
| `isRunning` | `boolean`             | コマンド実行中かどうか。       |
| `error`     | `string \| null`      | 実行失敗時のエラーメッセージ。 |
| `result`    | `ShellResult \| null` | 最後の実行結果。               |

### ShellResult

| プロパティ   | 型               | 説明                                                        |
| ------------ | ---------------- | ----------------------------------------------------------- |
| `success`    | `boolean`        | コマンドがステータス 0 で終了したか。                       |
| `stdout`     | `string`         | 標準出力。                                                  |
| `stderr`     | `string`         | 標準エラー。                                                |
| `statusCode` | `number \| null` | 終了ステータスコード。シグナルで終了した場合は `null`。     |
| `signal`     | `number \| null` | プロセスを終了させたシグナル番号。通常終了の場合は `null`。 |

## 使用例

### ターミナル付き

```tsx
const { terminalRef, instance } = useTerminal({
  theme: TerminalThemes.nord
});

const { error } = useShell("macchina", {
  terminal: instance,
  refreshInterval: 60000
});
```

### ターミナルなし

```tsx
const { result, isRunning } = useShell("fetch-ip", {
  refreshInterval: 10000
});

return <p>{result?.stdout}</p>;
```

## 動作

- マウント時に 1 回実行。
- `commandId` 変更時に再実行。
- `refreshInterval` が設定されている場合、その間隔で自動実行。
- `terminal` インスタンスが渡された場合、ANSI 対応で出力をターミナルに書き込み。