メインコンテンツへスキップ

6. CLI設計

6.1 実行ファイル名と基本形式

6.1.1 実行ファイル名

  • 実行ファイル名は create_skeleton.py とする。

6.1.2 基本コマンド形式

python create_skeleton.py -i path/to/input.yaml

6.2 引数仕様

6.2.1 オプション一覧

オプション 必須 値 説明
-i / --input 必須 ファイルパス 入力 YAML ファイルパス

6.2.2 入力ファイルパスの取り扱い

  • -i/--input は 必須。
  • 相対パス／絶対パスの両方を許容する。
  • ファイルが存在しない／読めない場合は 入力エラーとして扱う。

`-i` を省略した実行は「入力不足」ではなく、以降の処理全体が成立しないため 入力エラーとして即時終了する。

6.3 設定（環境変数）

BookStack API 接続情報は すべて環境変数で受け取る。

環境変数 必須 説明
BOOKSTACK_BASE_URL 必須 BookStack のベースURL（例：https://example.com）
BOOKSTACK_TOKEN_ID 必須 API Token ID
BOOKSTACK_TOKEN_SECRET 必須 API Token Secret

6.3.1 環境変数のバリデーション

  • 上記の必須環境変数が欠けている場合は 入力エラーとして即時終了する。

`BOOKSTACK_TOKEN_SECRET` などの秘匿情報を、ログや標準出力に 出力してはならない。 例外メッセージに含まれている可能性もあるため、出力時は必ずマスク／抑制する。

6.4 終了コード

終了コードは以下に固定する。

終了コード 意味
0 成功
1 APIエラー または 想定外エラー
2 入力エラー（引数不足・環境変数不足・YAML不正・バリデーション違反）

「入力エラー」と「実行時エラー(API/想定外)」を分離することで、 失敗時に 入力を直すべきか／通信やサーバ状況を疑うべきかを機械的に判定できる。

6.5 標準出力仕様

6.5.1 出力目的

  • 実行結果を人間が即座に把握できること
  • 次回実行時の再確認が容易なこと
  • ID（Book/Chapter/Page）に依存せず、YAMLと照合できること

6.5.2 出力形式

標準出力は行単位で、以下のいずれかのプレフィックスを持つ。

  • OK: <対象名>
  • SKIP: <対象名>
  • ERROR: <対象名> (<概要>) または ERROR: <概要>

例：

OK: ISO 26262 / 21434 とA-SPICEの役割分担
SKIP: A-SPICEを軸にした規格全体設計の考え方
ERROR: XXX（API error）

6.5.3 対象名の表現（スコープの扱い）

  • ページ名は YAML に記載されたタイトル（文字列）をそのまま使う（前後trim後）。
  • 章とページが同名になり得るため、必要に応じてスコープを明示する。

推奨フォーマット（例）：

  • Book直下ページ：<page_name>
  • 章：<chapter_name>
  • 章配下ページ：<chapter_name> / <page_name>

Book直下 `pages` と章配下 `pages` の同名は仕様上許容されるため、 ログの可読性のために 章配下ページはスコープ表記を推奨する。

6.6 ログ出力（標準出力との分離）

  • 標準出力：処理結果（OK/SKIP/ERROR）のみを簡潔に出す
  • ログ：デバッグや原因追跡に必要な情報を出す（例外スタックトレース含む）

標準出力に詳細（HTTPレスポンス全文、スタックトレース等）を混ぜると、 実行結果の把握が困難になる。詳細は ログ側に寄せる。

6.7 処理順とCLIの関係（期待される動作）

CLI は YAML を入力として受け取り、処理順は YAML 定義に従う。

  1. YAML ロード・バリデーション

  2. Book直下ページ一覧取得（SKIP判定）

  3. Book直下 pages を上から順に処理

  4. chapters を上から順に処理

    • 章の存在確認（なければ作成）
    • 章内ページ一覧取得（SKIP判定）
    • 章配下 pages を上から順に処理

処理順がYAMLの記載順と一致していることで、 人間が YAML を読めば挙動が完全に予測できる。

6.8 エラー時のCLI挙動（境界）

  • 入力エラー：API処理を開始せずに即時終了（終了コード 2）
  • APIエラー：対象の ERROR を出力し、即時終了（終了コード 1）
  • 想定外エラー：ERROR を出力し、即時終了（終了コード 1）

fail-fast を採用しているため、部分成功は仕様として追わない。 ただし既存は SKIP されるため、再実行により自然復旧できる。

上に戻る