スクリプティングおよび自動化ツールとしての Keleusma
本リファレンスは、devops および sysadmin の自動化を記述するために keleusma コマンドラインツールを使用する、オペレーター向けの説明を集約したものです。番号付きのガイド章は言語を教えます。本ドキュメントは、スクリプトをデプロイ可能なコマンド、ストリーミングフィルタ、または長時間稼働するデーモンへと変える要素を集め、その成果物を署名付きかつ任意で暗号化されたバイトコードとして配布する方法を説明します。
ここでの内容は、それぞれ 1 つの側面を扱う複数の章とリファレンスドキュメントから寄せ集められています。ある話題について他所でより充実した扱いがある場合、本ドキュメントはそれを再述するのではなくリンクします。
想定読者
ランタイムを Rust ホストへ組み込むのではなく、Keleusma プログラムをスタンドアロンなツールとして実行したいオペレーターおよびスクリプト作成者向けです。ランタイムを組み込みたい読者は、代わりに第31章から始めてください。
スクリプトを実行する 3 つの方法
ソーススクリプトは、3 つの相互に交換可能な形式で実行されます。3 つすべてが同じスクリプト引数を受け付けます。
| 形式 | コマンド | プラットフォーム |
|---|---|---|
| 明示的なサブコマンド | keleusma run script.kel | すべて |
| 拡張子による省略記法 | keleusma script.kel | すべて |
| シバンによる実行可能ファイル | chmod +x 後の ./script.kel | macOS および Linux |
シバン形式では、ソースの最初の行が #!/usr/bin/env keleusma である必要があります。レキサーはその行をスキップしますが、診断におけるソース行番号は保持するため、同じファイルは Windows でも引き続きコンパイル可能であり、そこでは keleusma run を通じて実行されます。第2章では、チュートリアルのペースでシバンを紹介します。コンパイル済みのバイトコードファイルもシバンを持つことができ、これは第25章で扱います。
スクリプト引数
スクリプトは shell バンドルを通じて自身の引数を読み取ります。shell::arg(0) はスクリプトパスを返し、shell::arg(1) 以降はランチャーがその後に渡した位置引数を返します。これは POSIX シェルの $0 および $1 の慣習を反映しています。shell::arg_count() は、引数ゼロを含めたエントリの数を報告します。
CLI は、keleusma run script.kel a b c とシバン形式の ./script.kel a b c の両方について位置引数を収集します。-- 終端子は CLI オプションの終わりを示し、それ以降のすべてのトークンは、ダッシュで始まる場合であってもスクリプト引数として扱われます。-- の前にある認識されない先頭ダッシュのトークンは、そのまま渡されるのではなく、フラグの入力ミスとして拒否されます。
./report.kel --since 2026-01-01 -- --raw
その呼び出しにおいて、CLI は認識しないものを一切消費せず、スクリプトは --since、2026-01-01、--raw を位置引数の1番目から3番目として受け取ります。
エントリ種別はデプロイ形態に対応します
スクリプトは3つのエントリ種別のうちの1つを宣言します。CLI はコンパイルされたエントリブロックを検査し、それに応じて駆動します。エントリ種別は、スクリプト作成者がデプロイ形態を決めるための主要なレバーです。第15章、第16章、第17章では言語のセマンティクスを扱います。以下の表は、それぞれを運用上の役割に対応付けます。
| エントリ種別 | 宣言 | 終了 | 運用形態 |
|---|---|---|---|
| アトミック | fn main() -> Word | 1回の呼び出しで完了まで実行されます | ワンショットコマンド。cron ジョブ、ビルドステップ、手動呼び出しに適しています。 |
| ステージド | yield main(tick: Word) -> Word | yield ではなく return します | ティックをまたいで一時停止と再開を行い、その後終了する協調的タスク。 |
| デーモン | loop main(tick: Word) -> Word | shell::exit または終了シグナルの場合のみ | 長時間稼働するサービス。return はエラーとして扱われます。 |
CLI が各種別をどのように駆動するかから、いくつかの運用上の帰結が生じます。
- アトミックな
fn mainは、その返り値が標準出力に表示されます。プロセスの終了ステータスは返り値から取得されません。特定の終了コードを必要とするスクリプトはshell::exit(code)を呼び出します。リポジトリのリンクチェッカーは、まさにこのパターンを使用しています。 loop mainデーモンは--tick-intervalによってレート制限されます。これは100ms、1s、1m、1h、1d、1wのような人間に読みやすい期間を、最大4週間まで受け付けます。ランタイムは反復と反復の間、実際にアイドル状態となるため、長い周期のデーモンは計算ではなくページフォールト回避のコストがかかります。メモリ常駐性の分析についてはMETRICS.mdを、デーモン周期に関する運用者向けガイドについてはSECURITY_POLICY.mdを参照してください。
シェルバンドルを通じた作業の委譲
ホスト登録のネイティブ関数がなければ、言語は純粋な全域関数と生産的発散ループのみを許容します。CLI は shell バンドルを登録し、これがオーケストレーションを可能にします。スクリプトは通常のコマンドラインプログラムに作業を委譲し、それぞれが返す Word の終了コードで分岐し、可変な private data セグメントに実行全体を通じて蓄積し、自身のプロセス終了ステータスを設定します。
| ネイティブ | 目的 |
|---|---|
shell::run(cmd) -> (Word, Text) | sh -c を通じてコマンドを実行します。終了コードと標準出力を返します。標準エラー出力は破棄されます。 |
shell::run_full(cmd) -> (Word, Text, Text) | 上記と同様ですが、終了コード、標準出力、標準エラー出力を返します。 |
shell::run_checked(cmd) -> Text | コマンドを実行します。非ゼロの終了でトラップします。 |
shell::run_timeout(cmd, ms) -> (Word, Text) | ウォールクロックの期限付きでコマンドを実行します。 |
shell::read_file、shell::write_file、shell::append_file | ファイルの入出力。 |
shell::writeln_err、shell::write_err | 標準エラー出力へのログ形式の出力。 |
shell::arg、shell::arg_count | スクリプト自身の引数。 |
shell::exit(code) | 終了ステータスとともにプロセスを終了します。 |
完全な一覧、シグネチャ、およびネイティブごとの契約は STANDARD_LIBRARY.md にあります。バンドルの機能評価とその現行の制限は SHELL_AUDIT.md にあります。
実践例: Markdown リンクチェッカー
リポジトリ自身の Markdown リンクチェッカーである scripts/check-md-links.kel は、オーケストレーターパターンの完全な実践例であり、継続的インテグレーションで実行されています。これは部分的なテキスト走査作業を shell::run を通じて POSIX ツールに委譲し、返された Word に基づいて制御フローを駆動し、第18章で説明する private data セグメントに失敗を蓄積し、shell::exit を通じて結果を伝播します。オーケストレーションを全域とする構成要素である部分演算ファミリーは、第23章で扱います。
署名および暗号化されたバイトコードとしてのスクリプト配布
完成したスクリプトはバイトコードにコンパイルし、改ざん検知が可能で、任意で機密性を持つアーティファクトとして配布できます。2つのポリシーは独立しています。いずれも無効、署名のみ、暗号化のみ、または両方が有効となり得ます。
| ステップ | コマンド |
|---|---|
| 署名鍵ペアの生成 | keleusma keygen --seed sign.seed --public sign.pub |
| 暗号化鍵ペアの生成 | keleusma keygen --kind encryption --seed dest.seed --public dest.pub |
| コンパイル、署名、暗号化 | keleusma compile script.kel --signing-key sign.seed --encryption-key dest.pub -o script.kel.bin |
| 検証および復号しての実行 | keleusma run script.kel.bin --verifying-key sign.pub --decryption-key dest.seed |
署名にはエントリ関数が signed 修飾子を持つことが必要です。そうでない場合、ツールチェーンは署名なしバイトコードを生成し、署名鍵を拒否します。暗号化は X25519 鍵合意を使用するため、成果物は受信者の公開鍵に対して封印され、対応する秘密シードで開かれます。署名と暗号化の設計は 第26章 で、ワイヤーフォーマットは WIRE_FORMAT.md で扱われています。
厳格モードの鍵ストア
管理されたホストでは、信頼に関する判断は運用者の手から取り上げられます。厳格署名モードでは、CLI はシステムディレクトリから信頼された公開鍵を読み込み、ソースファイル、署名なしのバイトコード、およびストア外の鍵で署名されたバイトコードを拒否します。--verifying-key 引数は拒否されるため、権限を持たない運用者がポリシーを緩めることはできません。厳格暗号化モードは、復号鍵ストアについて同様に振る舞います。ディレクトリ、環境変数、および脅威モデルは SECURITY_POLICY.md に文書化されています。
シバンも持つ署名および暗号化されたバイトコードアーティファクトは、改ざん検知が可能で機密性を保ちながら、オペレーティングシステムのシェルを通じて直接実行可能です。これは配布可能なランブックの配信形態であり、宅配便で配送されるメディアについて SECURITY_POLICY.md で説明されています。
複数のスクリプトを監視下で実行する
複数のスクリプトを必要とするワークロードのために、run-tasks サブコマンドは、イベントキュー、監視付き再起動、およびタスクごとの署名・暗号化ポリシーを備えた協調スケジューラを通じて、TOML マニフェストから一連のスクリプトを駆動します。これは examples/rtos/ の協調的 RTOS パターンをデスクトップおよびサーバーに引き上げるものです。
keleusma run-tasks fleet.toml --quiet
マニフェストはスケジューラのティック間隔、各スクリプトの名前・バイトコードパス・never／on_error／always のいずれかの再起動ポリシーを持つ [[task]] テーブル、およびオプションのイベントテーブルを宣言します。マニフェストの形式、検証規則、およびスケジューラのセマンティクスは RUN_TASKS.md に記載されています。
静的保証が成り立たない箇所
言語はそれ以外の場合、最悪実行時間またはメモリを静的に有界化できないプログラムを拒否します。オーケストレーションのネイティブ関数は、その保証が及ばない明示的な境界です。
shell::runおよびその兄弟を通じて生成されたサブプロセスは、検証器がモデル化できない時間とメモリを持ちます。静的な最悪ケース境界はこれらの呼び出しをまたぎません。shell::run_timeoutは呼び出しごとのウォールクロック時間に上限を設けますが、メモリには設けません。shell::read_fileおよび run 系のネイティブ関数は、スクリプトアリーナの予算の外側にあるホストヒープ上に出力バッファを割り当てます。- オーケストレーションのネイティブ関数は可変な外部状態を読み取るため、それらを使用するスクリプトは再現可能ではありません。
shell::exitはホストプロセスを直接終了します。
これらの性質は、言語ではなく、アンビエント権限を持つ shell バンドルに属します。封じ込めまたは証明された境界を必要とするデプロイメントは、完全なバンドルを信頼できないスクリプトに配布するのではなく、厳選されたサブセットまたは独自のより狭いネイティブ関数をカスタムホストに登録します。制約の完全なリストは SHELL_AUDIT.md にあります。