oxframe

oxframe-cli

ステータス： oxframe は現在、非常に活発に開発されています。API はまだ安定しておらず、バージョンごとに変更される可能性があります。Cargo.toml では正確なバージョンを指定し、アップグレードする前に変更履歴を確認してください。

oxframeプロジェクト用の oxframe コマンドです。プロジェクトの作成、ホットリロードによるプレビュー、レンダリング、チェックを行います。

cargo install oxframe-cli          # or a prebuilt binary:
#   Linux, macOS:  curl -fsSL https://github.com/oxygenframe/oxframe-cli/releases/latest/download/install.sh | sh
#   Windows:       powershell -ExecutionPolicy Bypass -c "irm https://github.com/oxygenframe/oxframe-cli/releases/latest/download/install.ps1 | iex"
oxframe init hello && cd hello
oxframe dev --open                 # editor on http://127.0.0.1:3000/?token=…
oxframe render                     # out/hello.mp4
oxframe publish --title "Hello"    # upload to oxframe.dev, print a link with a player
oxframe check                      # compile, then storyboard + report.json
oxframe inspect --at 2.5           # scene tree at that time, as JSON (--graph adds passes)
oxframe snapshot --at 1.5          # one frame as PNG in out/snapshots/
oxframe agents                     # refresh AGENTS.md and the Claude Code skill
oxframe upgrade                    # move the project to this CLI's SDK version
oxframe doctor                     # Rust, a C linker, ffmpeg: what is missing and how to fix it

更新

cargo install oxframe-cli --force  # the CLI
oxframe upgrade                    # then, in each project: SDK pin, Cargo.lock, agent files

プロジェクトでは SDK のバージョンを固定しているため（oxframe = "=0.22.0"）、新しいリリースが既存のプロジェクトに影響することはありません。CLI は 1 日 1 回、バックグラウンドで crates.io を確認し（cargo search）、新しいバージョンがあれば通知します。無効にするには OXFRAME_NO_UPDATE_CHECK=1 を設定してください（CI では無効です）。

リファレンス全文：https://oxframe.dev/docs/cli

AI コーディングエージェント

oxframe init は、AGENTS.md、CLAUDE.md（@AGENTS.md）、および .claude/skills/oxframe/ 内のスキル（ワークフローと API のチートシート）を生成します。これらは、エージェントに対して oxframe check（ストーリーボードと report.json）で視覚的な変更を検証し、oxframe dev は決して実行しないよう指示します。 oxframe agents を実行すると、アップグレード後にこれらのファイルが更新されます。oxframe-agents マーカーのないファイル（手動で編集したファイル）は、--force を指定しない限り保持されます。

oxframe mcp は、標準入出力を介して check、inspect、 render_graph、render_frame、render、list_components、および docs_search を提供する MCP サーバーです。

{ "mcpServers": { "oxframe": { "command": "oxframe", "args": ["mcp"] } } }

• MCP Registry 名：mcp-name: io.github.oxygenframe/oxframe

oxframe dev の仕組み

browser ──WS──▶ oxframe dev (127.0.0.1:3000) ──WS──▶ <project> preview --port 0
                 serves the embedded editor           restarted on every change
                 watches src/, assets/, Cargo.toml → cargo build

• 変更があると（200 ms のデバウンス後）、cargo build が実行されます。エディターには Building… と表示され、その後、同じフレーム位置に戻って Reloaded と表示されるか、 ファイル名と行番号付きのコンパイラーエラーが表示されます。いずれの場合も、前のビルドは実行を続けます。
• 古いプロセスには Shutdown が送られ、2 秒間の猶予の後、強制終了されます（Windows ではプロセスツリーも対象です）。クラッシュした場合、プロジェクトは最大 3 回再起動されます。
• セキュリティ：ループバック接続のみを許可し、Origin をチェックし、URL 内のワンタイムトークンを使用します。CLI が実行するのは cargo とプロジェクトのみで、ネットワークリクエストは行いません。

終了コード：0 は正常、1 はビルドエラー、2 は環境エラー（ffmpeg、ポート）、3 はバージョン不一致です。

埋め込みエディター

ui/dist は、ui.lock で固定された editor-ui のリリース版です。rust-embed を使ってバイナリにパッケージ化されているため、build.rs や cargo install でネットワークにアクセスすることはありません。

./scripts/fetch-ui.sh             # download the pinned release
just build-ui ../oxframe-web       # or build it from a sibling checkout
oxframe dev --ui-dir ../oxframe-web/packages/editor-ui/dist   # develop the editor

ui/debug-client/ は、デバッグ用に保持されている、単一ファイルの最小限のプロトコルクライアントです。

開発

cargo test                                          # unit tests, ui.lock check
cargo test --test e2e -- --ignored --nocapture      # init → dev → reload → render (needs ../oxframe-sdk)

MIT または Apache-2.0 ライセンスの下でライセンスされています。

ライセンス

Apache License, Version 2.0（LICENSE-APACHE）または MIT license（LICENSE-MIT）のいずれかを選択して利用できます。