実行できて見栄えも良いMarkdown手順書で快適な運用ライフを送ろう！

実行できる手順書(LC4RI)ってのご存じでしょうか？

ドキュメントとコマンドが混じって書いてあって、コマンド部分は実行できて、
その実行結果が載っています。
なので、手順書として読めて、かつ実行した内容とその時の出力がエビデンスとしてとれるもので
運用作業者にとってはExcel手順書の置き換えにぴったしなんですね

そういう書き方が出来るツールとしてjupyter notebookが良く使われているんですけど、
これが運用してみるとドキュメントの並び替えとか、編集が意外と面倒だったりする。

もっと普通のエディタで書けたら・・そう思ってました。したらヒラめいた！

VSCodeのmarkdown編集機能を実行できるようにすれば良いんだ！！

つくってみたわ

VScodeのマーケットプレイスからインストールするならこちら

こっちGit。

つかいかた

基本は普通のmarkdownと同じ書きっぷりです。リストと水平線と番号リストで変わります。

VSCodeのカーソル位置から下にあるコマンドを実行していきます。
なので、実行したい部分までカーソルを持ってってこの拡張機能を動かしてください。
（ショートカットキーに拡張機能の実行を割り当てると超便利ですよ！）

リスト

実行したいコマンドを書きます。
タブでインデントをずらすとAND条件になります。
つまり、

• • ls existsfile.txt
    • - rm existsfile.txt

でexistsfile.txtが無ければ削除しない、みたいな書き方ができます。

水平線

コマンドの実行範囲を区切ります。区切らないとリスト表記のを上から順に実行しちゃいます。

番号リスト

変数をもてます。1.～9.の範囲で実行結果の出力を変数として格納します。
重いコマンドとか何度も実行したくないものは結果を格納して使いまわせます。

コンフィグファイル

以下のようなサンプルで設定ファイルを作れます（無ければ自動生成します）

{
  "timeout": 10000,
  "template": {
    "linux": "ssh user@192.168.0.1 {COMMAND}"
  },
  "changeWord": {
    "#HOME#": "/home/user"
  },
  "toutf8": true,
  "toterminal": true
}

timeout

タイムアウト時間です。実行する時間が長いものはタイムアウトするようになってます

template

OSの環境にあわせて各コマンドを実行するテンプレートを定義します。
例えばlinuxの環境だったら、全部SSH経由で実行するみたいな定義が出来ます

通常lsと書いた場合ローカルでlsコマンドを実行します
    - ls
ただ、定義をこのようにすると
    ssh user@192.168.0.1 "{COMMAND}"
全てSSH経由でリモート実行されるようになります
    ssh user@192.168.0.1 ls

chageWord

ワードで文字列変更します

元の文字がこうなってて
    - ls #HOME#
定義がこうなってると
    "#HOME#": "/home/user"
このように置き換えて実行されます
    ls /home/user

toutf8

デフォオン(true)で、falseにするとSJISのまま処理されるはずなんですが・・・なんか手元だとうまく動かないですね。。

toterminal

trueに設定するとターミナルで直接実行します。↑のオプションがうまく動かない時はこちらで・・・

v1.0: 大幅リファクタ — 新機能

1. CodeLens（コマンドラインの再実行ボタン）

リスト形式のコマンド行の左側に「▶ Run」「Dry-run」ボタンが表示されます。

- uname -a

カーソルを動かして全体実行を行わずに、そのコマンド行だけ実行したい時に便利です。"lc4ri.showCodeLens": falseで無効にできます。

2. settings.json対応（後方互換性あり）

拡張機能の設定がVS Codeのsettings.jsonから読み込まれるようになりました。従来の~/.code-lc4ri/config.jsonも引き続き使用可能です。

{
  "lc4ri.timeout": 15000,
  "lc4ri.profiles": {
    "prod-ssh": "ssh [e-mail] {COMMAND}",
    "docker":   "docker exec -i app sh -c \"{COMMAND}\""
  },
  "lc4ri.changeWord": { "#HOME#": "/home/user" },
  "lc4ri.outputFormat": "collapsible",
  "lc4ri.confirmDangerous": true,
  "lc4ri.showCodeLens": true
}

3. 危険なコマンドの自動警告

実行コマンドが危険なパターン（rm -rf /、dd if=など）に該当する場合、実行前に確認ダイアログが表示されます。

• lc4ri.dangerousPatterns：警告を表示するコマンドパターン（正規表現）
• lc4ri.denyList：実行を完全に禁止するコマンド
• lc4ri.allowList：指定したコマンドのみ実行を許可

すべての実行コマンドはcode-lc4riの出力チャネルに記録されます。

4. 名前付き変数と組み込み変数

従来の{1}～{9}に加えて、より柔軟な変数機能が追加されました。

構文	意味
1. コマンド → {変数名}	コマンドの出力を{1}と{変数名}の両方に格納
- コマンド → {変数名}	リスト形式のコマンド出力を名前付き変数に格納
{$PREV}	前のコマンドの標準出力
{$STATUS}	前のコマンドの終了コード
{$DATE}、{$CWD}、{$USER}、{$HOST}	実行時の環境値

5. アサーション機能（- assert: ...）

コマンドの出力や終了コードを検証できます。

- curl -s http://api.local/health
    - assert: contains "ok"
    - assert: status == 0
    - assert: regex /version: \d+/

アサーション結果は出力ブロックに「✓ pass」「✗ FAIL」として記録されます。失敗するとAND-chainが中断されます。

6. ステータスバーのプロファイルスイッチャー

ステータスバーの右側にlc4ri: <プロファイル名>が表示され、クリックしてプロファイル（SSH、Docker、kubectlなど）を切り替えられます。ドキュメントを編集せずに実行環境を変更できます。

7. 実行レポートのエクスポート

実行セッション全体のレポートを生成できます。

• code-lc4ri: Export execution report (HTML)：実行結果を✓/✗付きで整形したHTML形式
• code-lc4ri: Export execution report (Markdown)：Markdown形式

運用作業のエビデンスやCI成果物として活用できます。

8. CLIランナー（ヘッドレス実行・CI対応）

VSCode拡張なしにMarkdownを実行できるCLIツールが提供されます。

npx code-lc4ri run runbook.md
npx code-lc4ri run runbook.md --dry-run
npx code-lc4ri run runbook.md --profile prod-ssh --report report.html

コマンドが失敗した場合、終了コードは0以外になるため、CI環境に直接組み込めます。

v1.1: 新機能

1. コマンド実行プレフィックス

プロンプトの先頭に記号を付けることで、実行方式を制御できます。

プレフィックス	動作
& <メッセージ>	このターン内のBashコマンドをバックグラウンド実行
! <コマンド>	ユーザーのターミナルで直接実行（出力をキャプチャしない）
なし	通常のフォアグラウンド実行（デフォルト）

2. .envファイルの読み込み

手順書のどこかに環境ファイルを指定すると、その中の環境変数を全コマンドで使用できます。

# env: .env.prod
- echo {DB_HOST}

3. 手順書のインクルード

別のMarkdownファイルを埋め込んで実行できます。インクルードされたファイル内で定義された変数は親スコープに引き継がれます。

- include: setup.md
- echo セットアップ完了

4. 並列実行

[parallel]プレフィックスを付けたコマンド行は、グループ化されて同時実行されます。

- [parallel] ssh server1 uptime
- [parallel] ssh server2 uptime
- [parallel] ssh server3 uptime

全コマンドが成功してはじめてAND-chainが続きます。1つでも失敗すると中断されます。

5. ファイルオープンとターミナル送信

記法	動作
- ! path.md / - open: path.md	ファイルを新規タブで開く
- ! コマンド	アクティブなターミナルに送信（出力キャプチャなし）

6. インデント仕様の改善

DEFAULT_INDENT_SPACESが4から2スペースに変更されました。これにより、Markdown標準の2スペースインデントが正しくAND-chain深度にマップされます。

- echo a       ← 深度0：常に実行
  - echo b     ← 深度1：aが成功したら実行
    - echo c   ← 深度2：bが成功したら実行
- echo d       ← 深度0：常に実行

従来の4スペースインデントを使いたい場合は、"lc4ri.tabWidth": 4で復帰できます。

7. write:ディレクティブ

手順書からファイルに内容を直接書き込めます。

- write: output/config.yaml
  ```yaml
  database:
    host: localhost
    port: 5432
  ```

• フェンスブロック内のコンテンツが指定パスに書き込まれます
• ファイルパスに変数置換が適用されます
• 親ディレクトリが存在しない場合は自動作成されます
• AND-chain に参加するため、インデント内のwrite:は親コマンドの成功時のみ実行されます
• --dry-runで実際の書き込みをせずに解決後のパスと内容を確認できます

あとがき

VSCodeのエコシステムが使えるので文章校正とか他の拡張機能の恩恵も受けれますね！
これで運用作業ドキュメントも見栄え良く、使いやすくなるものと思います。