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

arc blocklet

arc blocklet は、blocklet パッケージとインスタンスのライフサイクルをカバーします：スキャフォールド、ビルド、チェック、一覧表示、単一の blocklet のデプロイ、またはフリート全体のデプロイです。

arc blocklet は、blocklet のライフサイクル全体をカバーします：新しいパッケージのスキャフォールド、ビルド、検証、そして単独で、あるいはフリートの一部としてのデプロイです。

arc 2.0.0-beta.50（commit a99fb2c37、main、2026-09-11）に対して取得したものです。dump をコピーする前に arc --version を実行してください。コマンド面を固定するのは commit です。

bash
arc blocklet <subcommand> [options]

グローバルフラグ（概要 を参照）：--json、--view、--instance / -i（どのローカル ARC インスタンスか；省略すると default）、および --home（インスタンスのルート；どのインスタンスにするかを選ぶには --instance を使う）。

スキャフォールド

arc blocklet create

新しい blocklet パッケージをスキャフォールドします。arc blocklet init という別名でも使えます（後方互換性のために維持されています）。

使用法

bash
arc blocklet create [dir] [options]
  • [dir]（省略可、デフォルトは現在のディレクトリ）：blocklet ディレクトリ
  • --name <name>：blocklet の名前（デフォルト：ディレクトリ名）
  • --recipe <name>（別名 --template）：スキャフォールドのレシピ。basic、blank、blog、agent、minimal-app、agent-workspace、support-community のいずれか（デフォルト basic）

--name は合法な blocklet 識別子を導出できるものでなければなりません —— これはディスクに何かが書き込まれる前にチェックされ、拒否されます:

bash
$ arc blocklet create bad-dir --name "Not A Valid Name!"
ERROR: Error: Cannot derive a blocklet DID from --name "Not A Valid Name!": a blocklet identifier allows alphanumeric, hyphen, underscore only. Pass a valid identifier instead, e.g. --name Not-A-Valid-Name.

bad-dir ディレクトリは作成されません。合法な名前であれば通常どおりスキャフォールドされ、パイプラインの次のステップを示す Next: ヒントが表示されます:

bash
$ arc blocklet create my-app --recipe basic
Created blocklet.yaml with did: "did:blocklet:my-app"
Next: arc blocklet build /path/to/my-app

Next: の連鎖は、そのレシピ自身の能力に従います：DSL を持つレシピ（minimal-app、agent-workspace、support-community、agent、blog）は、ビルドの前に arc dsl validate を挿入しますが、manifest のみのレシピ（basic、blank）は挿入しません:

bash
$ arc blocklet create my-agent --recipe minimal-app
Created minimal app blocklet "my-agent" with 18 file(s).
Next: arc dsl validate /path/to/my-agent

$ arc dsl validate /path/to/my-agent
Passed DSL validation
  path: /path/to/my-agent
  files: 16
Next: arc blocklet build /path/to/my-agent

$ arc blocklet build /path/to/my-agent
Published 20 file(s) → /path/to/my-agent/dist
  .afs/manifest.json  (http-mount protocol)
  blocklet.dist.json  (flat manifest)
  instance: requires /instance DID Space

Next: arc blocklet run /path/to/my-agent

Deploy to CF Pages:
  arc blocklet deploy /path/to/my-agent --project <project-name>

DSL を持つスキャフォールドの Next: ヒントは arc dsl validate であり、そのコマンドは新しい minimal-app では exit 0 になります。DSL チェックチェーンの残りは一様に緑ではありません。arc blocklet create . --recipe minimal-app のあと、無修正の状態では:

bash
$ arc dsl lint .
Passed DSL lint
  path: /path/to/my-agent
  files: 16

$ arc dsl format --check .
Would format 0 file(s) (dry-run) — nothing to change
  path: /path/to/my-agent
  files: 5

$ arc dsl generate --check .
ERROR: Failed DSL generate (dry-run) — would change 4 file(s)
  path: /path/to/my-agent
  files: 11
  changed: .aup/app.json, .aup/pages/agent.json, .aup/pages/home.json, .aup/wrapper.json

  WARNING missing_man_coverage .aup/man/home.yaml: page "home" declares node-bound action(s) but has no .aup/man/home.yaml coverage
  ERROR generated_changed .aup/app.json: Generated artifact is stale. Run arc dsl generate --write.
  ERROR generated_changed .aup/pages/agent.json: Generated artifact is stale. Run arc dsl generate --write.
  ERROR generated_changed .aup/pages/home.json: Generated artifact is stale. Run arc dsl generate --write.
  ERROR generated_changed .aup/wrapper.json: Generated artifact is stale. Run arc dsl generate --write.

$ arc dsl doctor .
ERROR: Failed DSL doctor
  path: /path/to/my-agent
  decompile step: failed (0 files, 0 changed)

lint と format --check は exit 0；generate --check と doctor は現在 exit 5 です。これはゼロ編集のスキャフォールドに対する CLI の現在の振る舞いであり、文書で言い繕うものではありません —— validate が通ったからといって、この 2 つのゲートを緑だと思わないでください。

arc blocklet recipe

利用可能なスキャフォールドレシピを確認します。

bash
arc blocklet recipe <subcommand>
  • arc blocklet recipe list：スキャフォールドレシピを一覧表示する
  • arc blocklet recipe explain <name>：1 つのレシピを説明する

例

bash
$ arc blocklet recipe list
Blocklet scaffold recipes:
  basic
    Create only a blocklet manifest.
    capabilities: manifest
    generated files: 1
  ...
  minimal-app
    Create a tiny complete app with one web page, one AUP app, one agent, and generated settings.
    capabilities: web, aup, agent, settings
    generated files: 18
    source files: 14
  ...

$ arc blocklet recipe explain basic
Recipe: basic
  Create only a blocklet manifest.
  capabilities: manifest
  generated files:
    blocklet.yaml
  AFS data:
    blocklet.yaml
  checks:
    arc blocklet check <dir>

ビルドと検証

このリポジトリ自身のビルド＆チェックのパターン（bun .claude/verify/config.ts）は、blocklets/arcblock に対して arc blocklet check を実行し、続けて arc blocklet build を実行するものです。

arc blocklet build

Pages にそのままデプロイできる dist/ をビルドします。ファイルをコピーし、.afs/manifest.json とフラットな manifest を書き出します。

使用法

bash
arc blocklet build [dir] [options]
  • [dir]（省略可、デフォルトは現在のディレクトリ）：blocklet ディレクトリ
  • --output <dir>：出力ディレクトリ（デフォルト <dir>/dist）
  • --dry-run：ファイルをコピーせず、ディスクにも書き込まずに manifest だけを計算する
  • --clean：書き込む前に出力ディレクトリをクリーンにする（デフォルト true）

成功時には Next: arc blocklet run <dir> ヒントに加えて Deploy to CF Pages: ヒントも表示します —— 全体の連鎖は上の arc blocklet create を参照してください。

arc blocklet check

recipe/profile の契約に対して blocklet を検証します。arc blocklet validate という別名でも使えます。

使用法

bash
arc blocklet check [dir] [options]
  • [dir]（省略可、デフォルトは現在のディレクトリ）：blocklet ディレクトリ
  • --profile <name>：検証プロファイル。basic、minimal-app、agent-workspace、support-community のいずれか（デフォルト basic）

create や build とは異なり、check は成功時に Next: ヒントを表示しません。

arc blocklet dev

blocklet ディレクトリの規約をスキャンし、結果を報告します。これは DSL の内容に対する lint（それは arc dsl lint の役目）ではなく、ディレクトリの形に対する lint です。

bash
arc blocklet dev [dir]

検視

arc blocklet list

ローカルの blocklet パッケージを一覧表示します：blocklet.yaml を発見し、公開状態を報告します。

bash
arc blocklet list [dir]

arc blocklet inspect

ローカルの blocklet パッケージの manifest とファイル一覧を表示します。

bash
arc blocklet inspect <ref>
  • ref（必須）：blocklet ディレクトリへのパス

実行とデプロイ

arc blocklet run

デーモン上で単一の blocklet を提供し、そのアクセス URL を表示します。

使用法

bash
arc blocklet run <path> [options]
  • path（必須）：提供する blocklet ディレクトリへのパス

デーモンの再起動をまたいでソースを保持するには、それを名前付きインスタンスに記録してください：arc service start --instance <name> --blocklet <path>。arc service を参照してください。

arc blocklet deploy

blocklet をローカルに公開し、続けて Cloudflare Pages にデプロイする、一連の操作をワンステップで行います。

使用法

bash
arc blocklet deploy [dir] [options]
  • [dir]（省略可、デフォルトは現在のディレクトリ）：blocklet ディレクトリ
  • --project <name>：Pages プロジェクト名（デフォルト：blocklet の id）；同じプロジェクトにデプロイされた複数の blocklet は、1 つの集約された http-mount ツリーを共有する
  • --domain <domain>：インスタンスを紐づけるドメイン
  • --cloud <cf|none>：cf は Cloudflare Pages にプッシュする、none は staging のみ（デフォルト cf）
  • --branch <name>：デプロイの git ブランチラベル（デフォルト main）
  • --staging-root <dir>：staging ディレクトリのルート（デフォルト ~/.afs/blocklets-staging）
  • --cf-account-id <id> / --cf-api-token <token>：wrangler へ転送される
  • --verify：--domain と併用した --cloud=cf の後、パッケージ、診断情報、実際のルートを検証する（デフォルト true）
  • --routes <list>：検証する実際のルート、スペースまたはカンマ区切り（デフォルト /）
  • --compare-local：対応するローカルのルートも取得し、状態/ヘルスを比較する
  • --local-port <n>：--compare-local と併用するローカルの Arc ポート（省略するとインスタンスレジストリを使う）
  • --timeout-ms <n>：リクエストごとの検証タイムアウト、ミリ秒（デフォルト 10000）

arc blocklet instance

blocklet のインスタンス、つまりデプロイメントを管理します。

bash
arc blocklet instance <subcommand> [options]
  • arc blocklet instance deploy <ref>：公開済みの dist/ をローカルの Pages にデプロイし、ドメインを紐づける。--cloud <fs|cf|none> がターゲットを選ぶ（デフォルト fs）；--pages-root <dir> は --cloud=fs 用のローカル Pages ストアのルートを設定する（デフォルト ~/.arc/pages）
  • arc blocklet instance list：デプロイ済みのインスタンス、つまり Pages プロジェクトを一覧表示する
  • arc blocklet instance inspect <id>：デプロイ済みインスタンスの詳細を表示する
  • arc blocklet instance destroy <id>：デプロイ済みインスタンスを取り壊し、すべてのデプロイメントとドメインを削除する；確認には --force が必要
  • arc blocklet instance logs <id>：Pages インスタンスのデプロイ履歴を表示する（ランタイムログは利用できない —— Pages にはランタイムログのストリームがない）。--follow は削除されました（以前は受け付けられて即座に「not supported」というエラーになっていましたが、今は未知の引数として即座に拒否されます、exit 5）

フリート

arc blocklet fleet は、複数の blocklet を 1 つの集約された Pages プロジェクトとしてデプロイします。これが、（このサイトのような）マルチドメインのサイトフリートが一緒にデプロイされる仕組みです。

bash
arc blocklet fleet <subcommand> [dir] [options]

fleet の各サブコマンドで共有されるオプション：--blocklets <list>（--fleet を上書きする）、--fleet <yaml>（デフォルトは <dir>/site-fleet.yaml または <dir>/fleet.yaml）、--deployment <id>（instances.json からフリート manifest のパスを解決する、--fleet と排他）、--project <name>（デフォルト afsd-blocklets）、--domain-root <domain>（デフォルト afsd.io）。

--deployment/--fleet は、4 つのサブコマンドすべてで宣言され強制される排他関係です（文書に書いてあるだけではありません）:

bash
$ arc blocklet fleet deploy --deployment foo --fleet bar.yaml
ERROR: Arguments deployment and fleet are mutually exclusive
...

2 つのフラグのどちらか一方だけを渡すと、この特定の検査を通過します —— その後、別の、予期された理由（この fleet manifest が存在しない）で失敗します。これが、このガードが何でも拒否するのではなく実際に判別していることを示す方法です:

bash
$ arc blocklet fleet deploy --fleet bar.yaml
ERROR: Error: Fleet manifest not found: /path/to/bar.yaml
  • arc blocklet fleet deploy [dir]：エイリアス、Web Provider のアセット、スモークチェックを伴って複数の blocklet を公開・デプロイする。--publish は staging の前にすべての blocklet に対して arc blocklet build を実行する（デフォルト true）；--web-library は Web Provider のテーマ/ウィジェットを /web/.library に stage する（デフォルト true）；--web-library-dir <dir> は stage 元となる Web Provider パッケージのディレクトリを指定する（デフォルト providers/runtime/web-device）
  • arc blocklet fleet verify [dir]：公開や変更のプッシュを行わずに、デプロイ済みのフリートを検証する
  • arc blocklet fleet doctor [dir]：フリートデプロイのローカルな前提条件をチェックする（--cloud cf のときの wrangler の利用可否、staging root など）
  • arc blocklet fleet rollback <deploymentId> [dir]：Cloudflare Pages のフリートプロジェクトを以前のデプロイメントへロールバックする