CLI
install 済み binary は project script、pnpm exec oxiquill、npx oxiquill から実行します。project 作成には pnpm dlx oxiquill も使えます。
Global option
Section titled “Global option”| Option | 動作 |
|---|---|
--help, -h | global または command-specific usage を表示し、成功で終了します。 |
--version | install 済み Oxiquill package version を表示します。 |
--debug | error の cause/stack を表示します。通常の expected error は簡潔です。 |
--config <path> | すべての project command で指定 Astro/Oxiquill config を使います。 |
-- | 残りの対応 argument を underlying Astro command へ渡します。 |
unknown option、option value の欠落、unknown command、余分な positional argument は usage を表示して non-zero で終了し、project を変更しません。
Command
Section titled “Command”| Command | 動作 |
|---|---|
init [directory] | versioned static starter を作ります。default は current directory です。 |
dev | 必要な runtime を生成し、watcher と Astro development server を起動します。 |
dev:runtime | runtime/source watcher だけを起動します。 |
dev:astro | Astro development server だけを起動します。 |
build | 必要な runtime を生成し、check 後に static site を作ります。 |
preview | 既存 production build を preview します。 |
check-links | 既存のビルド出力のローカルルートとフラグメントを読み取り専用で検証します。 |
check | 必要な runtime、Astro type を同期し、Astro diagnostics を実行します。 |
docgen | manifest を同期し、--wasm dev | build で必要な runtime も build します。 |
clean | resolved Oxiquill-owned/generated path と設定済み Astro output だけを削除し、verified download cache は保持します。 |
test-rust | optional helper crate を test します。 |
test-rust-coverage | helper crate を 85% coverage threshold 付きで test します。 |
lint-rust | helper crate の書式を検査し、全 target に warning deny で Clippy を実行します。 |
doc-rust | dependency を除いて helper crate documentation を build します。 |
test-wasm | runtime を生成し、すべての generated Rust/Haskell cell を default input で実行します。 |
dev:runtime は source change の監視を始める前に、runtime を一度初回同期します。runtime が生成済みの場合は oxiquill dev:runtime --skip-initial を使います。この option は起動時に同期せず watcher を登録し、最初の関連 docs/crate event を待ちます。統合された dev command は明示的な起動時生成を一度だけ行い、内部でこの mode を使います。
dev、dev:astro、build、preview、check は documented Astro argument を受け取り、-- より後の値もそのまま渡します。
pnpm dev -- --host 0.0.0.0 --port 4321pnpm check -- --minimumSeverity warningProject runtime lock
Section titled “Project runtime lock”build、check、docgen、clean、test-wasm は、consumer project の <cacheDir>/runtime.lock にある process 間 lock を command 全体で保持します。build は runtime generation、Astro diagnostics、最終 Astro build まで保持します。単独の astro build も build-start hook から build 完了まで同じ lock を保持します。install 済み Oxiquill package には書き込みません。
この5つの CLI command は -- より前に --lock-timeout <seconds> を指定できます。既定は 1800 秒、0 は lock 保持中なら即座に失敗します。有限の非負数を指定してください。
pnpm exec oxiquill build --lock-timeout 60pnpm exec oxiquill clean --lock-timeout 0競合時は holder の command、PID、host、開始時刻、lock path を標準エラーに表示し、30秒ごとに待機中の旨を表示します。timeout 時は同じ詳細と設定値を表示して非ゼロ終了し、project file や generated artifact を変更しません。一時的な取得用 record は削除します。test-wasm --format json の標準出力は NDJSON のままです。
dev は初回生成と watcher の同期中だけ lock を保持します。watcher は timeout せず、待機中の変更をまとめ、取得後に最新の入力を一度同期します。check --watch は command 終了まで lock を保持します。
clean は cache directory、ownership marker、lock 調整用 file を残し、生成内容を削除します。正常終了と SIGINT/SIGTERM で自身の lock を解放します。同じ host で PID が存在しない場合だけ自動回収し、経過時間だけでは回収しません。owner が不明または別 host の場合は復旧手順を参照してください。
Incremental build と clean build
Section titled “Incremental build と clean build”Oxiquill repository の pnpm build は reusable package を incremental に build し、変更のない runtime artifact を再利用します。Astro は毎回 static output directory を作り直します。pnpm build:package は package だけを incremental に build し、pack は常に clean package build を行います。
repository の pnpm build:clean は verified download cache を保持しながら package、generated runtime、site を clean して再生成します。consumer project では oxiquill clean 後に oxiquill build を実行すると runtime/site を最初から再生成できます。
Rust と Haskell の rebuild は cacheDir/build-cache の compiler cache を再利用します。Haskell cache は mode と compiler version ごとに分離します。Wasm build と test の両方で明示した CARGO_TARGET_DIR を優先します。clean は Oxiquill-owned compiler cache を削除し、verified download と外部の user-owned Cargo target は保持します。published runtime file の再利用前には記録した size と SHA-256 hash を検証します。
oxiquill build --force が消去するのは Astro の content cache だけです。package の再ビルドを強制したり、Oxiquill runtime fingerprint を破棄したりはしません。
安全な project 作成
Section titled “安全な project 作成”pnpm dlx oxiquill init my-docscd my-docspnpm installpnpm checkpnpm buildpnpm previewinit が受け入れるのは存在しない target または既存の空 directory だけです。non-empty target を上書きせず、dependency install や Git init を行わず、force option もありません。npm package name は lowercase で安全な形に変換され、無効または空の basename は oxiquill-docs になります。作成失敗時は可能な限り partial output を除去し、recovery または次の手順を正確に表示します。
Runtime/tool failure
Section titled “Runtime/tool failure”strict command は必要な compiler、generated artifact、config、download dependency がないと失敗します。該当する場合、diagnostic は command/tool、page、fence line、cell ID、field/path を示します。dev は Haskell compiler/build failure を許容して docs server を維持しますが、再生成に成功するまで該当 cell に error を表示します。
復旧方法は トラブルシューティング を参照してください。
Declared Cell Testing
Section titled “Declared Cell Testing”pnpm exec oxiquill test-wasm --page ja/guides/validation.mdx --cell tested-square --case default --format json| オプション | 動作 |
|---|---|
--page <path> | docs からの相対 Markdown/MDX パス。複数指定可。区切り文字と . を正規化し、絶対パスと docs の外への移動を拒否します。 |
--cell <id> | スコープ付きセル id。複数指定可。--page が一つならページ内 id も指定できます。 |
--case <id> | default または名前付きケースを絞り込みます。複数指定可。テスト未指定のケースには --all-cases が必要です。 |
--all-cases | テスト未指定の全ケースもスモーク検証します。 |
--format human|json | 既定は人向けの表示。json は標準出力に NDJSON を出力し、コンパイラーと生成の進捗は標準エラーに出力します。 |
同じオプション内の値は選択肢として扱い、page、cell、case はすべての条件を満たす対象を選びます。各セレクターに一致が必要で、空の選択は使用方法エラーです。Rust 以外のセルを明示選択すると、その言語のケーステストが未対応であると表示します。フィルター指定時は従来の Haskell スモーク検証を省略します。
セレクターなしでは全 Rust 既定入力と宣言テストを実行します。セルとケースの組み合わせごとに一度実行し、宣言された期待値をスモーク検証の代わりに適用します。生成済み Wasm を一度コンパイルし、実行ごとに新しいインスタンスを初期化します。別のテストビルドは実行しません。
JSON の test イベントは page、line(フェンス行)、cell、case、status(pass / fail)、durationMs、failures を持ちます。各失敗は reason、fieldPath、location(line、column)、長さ制限付き文字列 actual と expected、該当時は path と artifact を持ちます。実行エラー、タイムアウト、ハーネスエラー、パスや artifact の欠落、比較失敗を区別します。致命的エラーは message を持つ diagnostic イベントです。最後の summary は total、passed、failed、exitStatus と、該当時は status と cellCount を持つ haskell を含みます。Haskell の件数は Rust テスト総数と別です。
{ "type": "test", "page": "ja/guides/validation.mdx", "line": 109, "cell": "ja__guides__validation__tested-square", "case": "default", "status": "pass", "durationMs": 1, "failures": []}{ "type": "summary", "total": 1, "passed": 1, "failed": 0, "exitStatus": 0 }すべて成功すれば終了ステータス 0、テスト失敗、タイムアウト、メタデータ不正、使用方法エラーは 1 です。フィルターなしのセルがないプロジェクトは成功しますが、不一致セレクターは必ずエラーです。期待値の形式は 検証 を参照してください。
ビルドの報告と Explain
Section titled “ビルドの報告と Explain”build、check、docgen は --format human|json(既定値 human)と --explain を受け付けます。
pnpm exec oxiquill build --explainpnpm exec oxiquill docgen --wasm dev --format jsonpnpm exec oxiquill check --explain --format jsonExplain は設定の解決、セルの検出と検証、通常ビルドと同じ計画の評価を行います。runtime lock を取得せず、書き込み、ダウンロード、生成、コンパイルを行いません。子プロセスはツールチェーンのバージョン確認だけです。build はリリース、check は開発モードを計画し、docgen --wasm dev|build は目的のモードを選びます。設定またはセルの検証失敗は非ゼロで終了します。利用できないツールは診断として報告します。--outDir、--watch、--force、--lock-timeout など実行専用のオプションとは併用できません。
Human 形式はフェーズ、計画理由、最後のフェーズ集計を表示し、子プロセスの出力をすぐに転送します。30 秒間出力がなければフェーズと言語・モジュールを示す heartbeat を表示し、無出力が続く間は 30 秒ごとに繰り返します。終了・失敗・キャンセルで停止します。進捗率や完了予測時間は表示しません。
JSON 形式は stdout に 1 行 1 イベントの NDJSON を出力します。子プロセス出力もイベントに包み、失敗時を含め最後は必ず summary です。
type | フィールド |
|---|---|
phase | phase、state、elapsedMs。該当時に language、module、cache(hit / miss)、reason。状態は start、success、failure、skipped。 |
plan | language、action、reasons。該当時に module、key、pages、target(source / public)。 |
heartbeat | phase、elapsedMs。該当時に language、module。 |
output | ツール名の source、stream(stdout / stderr)、line。 |
diagnostic | message。 |
summary | exitStatus と phases。各フェーズにつき phase、state、elapsedMs、cache: { hits, misses } の 1 行。 |
フェーズは discovery、validation、generation、compile、optimize、publish、astro-check、astro-build です。最適化イベントは Oxiquill 自身の処理境界から発行し、検証済み最適化キャッシュの再利用も報告します。集計の時間は同じフェーズの処理時間の合計です。
理由の code は source-changed(changes: [{ page, cell }])、helper-inputs-changed、toolchain-changed、build-options-changed(変更された variables の名前だけ)、generator-changed、package-changed、dependencies-changed、mode-upgrade、output-missing、integrity-mismatch、previous-build-failed、failure-unchanged、forced です。cache-hit は検証済み再利用、absent は言語の出力が既に不要な状態です。fingerprint や設定値は表示せず、telemetry やベンチマーク履歴は保存しません。
ビルド済みサイトのリンク検証
Section titled “ビルド済みサイトのリンク検証”pnpm exec oxiquill check-linkspnpm exec oxiquill check-links --format jsonpnpm exec oxiquill build --check-linkscheck-links は <cacheDir>/build-report.json と既存の HTML を読み込みます。ファイルへの書き込み、ランタイムロックの取得、ランタイムの再生成は行いません。レポートや出力がない場合は、先に oxiquill build を実行してください。レポートにはビルド完了時の出力先、サイト URL、base、末尾スラッシュの方針、ビルド形式、リダイレクトが記録されます。build --outDir で指定した出力先も次回の検証に使われます。
アンカーとイメージマップの area 要素の href を、ローカルページやアセットと照合します。フラグメントは実際の HTML の id またはアンカーの name と比較され、生成されたセルや ox-ref-* のアンカーも対象です。日本語などのパーセント符号化されたフラグメントはデコードします。空のフラグメントと #top は常に有効です。クエリ文字列はファイル検索に影響せず、HTML 以外のアセットは存在だけを確認します。
相対パスは参照元ページの URL を基準に解決します。設定されたサイトと base 内の絶対 URL は検証し、別ホストの URL と同一サイトでも base 外の絶対 URL はスキップします。相対パスやルート相対パスが base 外を指す場合は失敗です。外部リンクや mailto:、tel:、data:、javascript:、blob: へのネットワークアクセスは行いません。設定されたリダイレクトと HTML のリダイレクトをたどり、最終ページでフラグメントを検証します。
失敗理由は missing-page、missing-fragment、outside-base、redirect-loop、trailing-slash です。明示的な trailingSlash: 'always' と 'never' の設定をページルートに適用します。同じ解決先と理由の失敗はまとめ、発生回数と最大 5 ページの参照元および元の href を表示します。
--format human|json の既定値は human です。JSON は NDJSON 形式です。link-failure イベントには target、reason、count、examples(source と href を持つオブジェクト)が含まれます。最後の summary には exitStatus と linkCheck の集計値 pages、checked、skipped、failures(重複をまとめた件数)、occurrences(失敗したリンクの総数)が含まれます。入力エラーでは diagnostic とリンク集計のない最終 summary を出力します。
正常時の終了ステータスは 0、リンク切れや入力エラーは 1 です。build --check-links はビルド成功後に同じ検証を実行し、既存のビルド summary に集計を追加します。失敗時も生成済みの出力は残ります。通常の build はリンクを検証しません。--check-links と --explain は併用できません。